Automation CLI

automation/cli bundles high-level workflows powered by OrbitronServices. All commands honour the global flags for logging, periodic boundary conditions, and data root. - The persisted file-size cap from config.toml is applied automatically. Override it per invocation with --max-file-size BYTES, or update the default via orbitron config set-thresholds --max-file-size-mb <value>. - Before each load the CLI projects the operation’s peak memory against available RAM. Warnings go to stderr, so JSON and piped data on stdout stay clean. Interactive launches prompt only when both stdin and stderr are terminals, with No as the default. In scripts, warning-band projections continue, critical projections fail, and impossible machine limits always fail. --allow-large permits a critical advisory projection after you have checked the risk. It cannot override --max-memory BYTES or an impossible machine limit. The default hard cap is 0, meaning unlimited.

4.0 Quickstart Workflow

  1. Inspect a molecule

    orbitron info io/pipelines/tests/fixtures/xyz/water.xyz --json

    This prints atoms, bonds, bounding box, and metadata.

  2. Measure a distance (atom indices are 1-based)

    orbitron measure io/pipelines/tests/fixtures/xyz/water.xyz --distance 1 2

  3. Render a PNG headlessly

    mkdir -p ~/scratch/orbitron-quickstart
orbitron render io/pipelines/tests/fixtures/xyz/water.xyz \
  -o ~/scratch/orbitron-quickstart/water.png
Command Purpose Highlights
info <file> Load a scene and print summary Optional --json, cell overrides, prints bounding box/elements/metadata, surfaces extras.molpro when Molpro data is present (with --molpro-task N / --molpro-kind freq filters), extras.molcas for Molcas/OpenMolcas runs, and a cross-program program_tasks block (DIRAC, QE, NWChem, etc.) sourced from canonical extras
resources <file> (alias resource) Estimate source-open memory without parsing Reads metadata plus at most 64 KiB of the source, reports bounded count hints, current host memory, the projected policy band, and any configured hard cap; optional --json and --mode scene\|trajectory\|indexed-trajectory
analyze geometry\|orbitals\|populations\|bond-orders\|vibrations Static and calculation analyses JSON or human output, --frontier, --top, --projected knobs; computed bond orders retain method, matrix coverage, print thresholds, and three-center terms. Human bond-order reports print at most 100 pair and 100 three-center rows per analysis unless --limit N or --all is supplied.
analyze md Bounded-memory trajectory analysis RMSD against a frame or separate structure, atom/residue RMSF, radius of gyration, geometry series, contact/interface occupancy, and explicit-H hydrogen-bond occupancy. Writes complete JSON or CSV only after the analysis finishes.
select <expr> [source] Evaluate a selection expression Reads an optional positional source file (-s/--source kept as a deprecated alias), prints atom IDs; supports element symbols, residue and alternate-location terms, within R of <sel>, and and/or/not
measure <file> Distance, angle, or dihedral measurement Reads a positional source file (-s/--source kept as a deprecated alias); accepts --distance a b, --angle a b c, or --dihedral a b c d (1-based atom indices)
from-smiles <text> -o <file> Build a molecule from supported SMILES Writes XYZ, PDB, GRO, MOL, SDF, or binary scene bytes; deterministic 3D by default, --no-3d keeps connection-table coordinates
convert Convert or extract frames Writes XYZ, PDB, GRO, MOL, SDF, or binary scene bytes. Formats are inferred from the output extension; use --frame for one trajectory frame or --trajectory for multiframe XYZ. GRO export is one frame only.
render Headless raster or vector render Writes PNG for 3D or 2D views; diagram mode also writes SVG, PDF, EPS, MOL, and SDF. Accepts --width, --height, --camera (legacy JSON), --appearance <bundle.json> (theme + lighting + camera + render flags from File ▸ Export Appearance Bundle), --diagram, --diagram-style, and --diagram-show-h. A periodic scene is refused a diagram: a cell’s contents drawn flat is a fragment cut where the box was, not a molecule. That is keyed on the scene declaring a cell, so a structure that carries one only because it was measured in a lattice (most PDB and mmCIF entries) is refused too, and draws as usual once the cell is dropped.
orbital Render an MO isosurface to PNG --mo, --spin alpha\|beta, --iso (default 0.02), --grid (default 80), --width/--height, -o; for NWChem supply the companion --movecs (auto-detects a sibling <stem>.movecs)
view Launch GUI or TUI from the CLI --freq, --select, --tui, --blank
inspect Dump run summaries Reports molecular dipoles; cross-program method, basis, solvation, and SCF provenance; band structure, band gap, DOS, and the exact first Brillouin-zone topology for periodic runs. It warns when a run did not finish or sampled a mesh rather than a k-path. Human trajectory reports show at most 100 frame rows; JSON keeps every frame. Task filters include --dirac-task N, --molpro-task N, --molpro-kind freq (alias --task freq/--task caspt2), and --molcas-task N
canonical export\|import\|cache Manage canonical bundles Export bundles with --pretty/--force/--skip-cache, import with --output/--id, cache commands: path/list/purge [digest]
pack periodic (alias pack vasp) Package a periodic run (VASP or Quantum ESPRESSO) Canonical JSON, band/fat-band/DOS/PDOS figures and CSVs, optional raw files (--skip-raw), optional volumetric grids (--include-volumetric), manifest with SHA-256 hashes
batch Execute a TOML job list Supports info, analyze, convert, render entries; --jobs N runs N jobs concurrently (one child process per job, renders still serialised), --only-job N runs just that 1-based entry, --keep-going finishes the list after a failure
fs list\|exists Inspect data roots fs list [<dir>] [--json] lists directory contents (the directory is positional, defaulting to .), fs exists <path> checks file existence
config set-thresholds Persist configuration settings --max-file-size <bytes> or --max-file-size-mb <mb> sets loader size cap, saved to ~/.config/Orbitron/config.toml (platform-dependent path)
completions <shell> Generate a shell completion script Prints a completion script for bash, zsh, fish, powershell, or elvish to stdout

Reading from stdin. Any command that loads a structure accepts - as the source to read from stdin, so you can pipe structures between tools: cat mol.xyz | orbitron identify -. Stdin has no file extension, so format detection uses --stdin-format <ext> (default xyz) — e.g. curl … | orbitron info - --stdin-format pdb.

resources is the exception. Its purpose is to inspect a local source without consuming or parsing it, so it rejects -. Use it before a large open:

orbitron resources calculation.out
orbitron resources trajectory.XDATCAR --mode trajectory --json
orbitron resources calculation.out --max-memory 17179869184 --json

The default mode is indexed-trajectory, matching the bounded-retention path when a format supports indexed access. Use trajectory when the planned command will retain every frame, or scene for a static open. The report describes the estimate, current memory snapshot, policy verdict, and configured --max-memory. A refusal verdict still exits successfully because the inspection completed; the later open is the operation that would be refused. Operational errors such as a missing file, directory, or stdin source return a failure status. JSON output uses schema orbitron.resources/1, and stderr stays empty for a successful JSON inspection.

When canonical metadata includes task summaries (e.g., QE or NWChem runs), orbitron info --json emits a program_tasks array. Each entry identifies the originating program, task kind (SCF, optimisation, DOS, etc.), optional energy values, and diagnostic extras such as QE relax profiles or NWChem basis/method hints. Human-readable info and inspect output prints at most 100 program tasks. Within each displayed task it also prints at most 100 state energies and 100 SCF cycles. Molpro’s detailed task, correlated-stage, multistate-energy, and XML-sidecar sections use the same limit. Molcas module, diagnostic, and root lists, plus specialized NWChem, DIRAC, and QE task summaries, are bounded independently. Omission lines give the exact hidden counts. JSON retains every record. Explicit Molpro, Molcas, and DIRAC task selectors can still address records beyond the display limit.

Standalone NWChem .civecs inspection follows the same policy. Human output shows at most 100 excited-state rows and reports the exact omitted count; orbitron inspect FILE.civecs_singlet --json retains every state.

The 100-row human-output limit also covers metadata tags, element and coordination summaries, run reports, warning lists, and bond-order analyses. orbitron analyze bond-orders --all is the explicit escape hatch for complete human-readable bond-order output. Ordinary structure summaries report bond counts and statistics rather than listing every raw bond. JSON retains complete collections throughout.

Identifying a JSON response. orbitron info --json carries three fields for the benefit of anything parsing it programmatically:

  • schema — the response shape, orbitron.info/2. The major version changes only when a reader would break (a field removed, or an existing field’s meaning changed); new fields are added without a bump.
  • producer — {"name": "orbitron", "version": "<crate version>", "commit": "<short git sha>"}, so a stored response records which build wrote it. The version alone does not identify a build, since every commit between releases reports the same version; the commit carries a -dirty suffix when the working tree had uncommitted changes.
  • warnings — an array of {source, code, message?}. source is loader for a parser warning (the code is the parser’s own token, e.g. cif:ambiguous_space_group_setting:227:1|2) or cli for one raised while assembling the response. An empty array is a claim that nothing was suppressed.

The last of these closes a real gap: a file whose main structure parsed but whose task section did not used to report program_tasks: [] with the explanation going only to stderr, which a piped caller never sees. That case now also emits a program_tasks_unavailable warning in the response itself.

These fields are carried by info, resources, inspect, all six analyze subcommands, smiles, inchi, identify, and fs list, each with its own schema (orbitron.resources/1, orbitron.analyze.geometry/1, orbitron.analyze.bond-orders/1, orbitron.smiles/1, and so on). They are merged into the existing payload rather than wrapping it, so a consumer already reading the payload’s keys is unaffected.

Two commands deliberately do not carry them. measure --json emits one object per measurement, a JSONL-style stream where a per-line envelope would be noise and a single wrapper would change the shape. select --json streams its result rather than building it in memory, because a 200k-atom selection should not be materialised as a Value first.

4.1 List top charges from a Gaussian run

orbitron analyze populations fixtures/formamide.out --top 10

Computed bond orders have their own report because they are not the scene’s rendering connectivity:

orbitron analyze bond-orders calculation.out
orbitron analyze bond-orders calculation.out --limit 25
orbitron analyze bond-orders calculation.out --all
orbitron analyze bond-orders calculation.out --json

The default human report keeps the source order and prints at most 100 pair rows and 100 three-center rows for each method or state. An omission line gives the exact remaining count. --limit N changes that ceiling, while --all prints the complete human report. JSON is always complete and is the better choice when the result will be redirected or processed by another program.

For a cross-frontend description of dipoles, provenance, SCF histories, bond orders, and reciprocal-space output, see Analysis Results.

4.2 Convert the third frame of a trajectory to XYZ

orbitron convert traj.nw -o out.xyz --frame 2

Read a concatenated GROMACS GRO trajectory or export one selected frame:

orbitron info trajectory.gro --json
orbitron convert trajectory.gro -o trajectory.xyz --trajectory
orbitron convert trajectory.gro -o frame-101.gro --frame 100

GRO stores coordinates, optional velocities, residue/atom fields, and a box. It does not store bonds, force-field topology, formal charges, isotopes, or molecular charge and multiplicity. orbitron convert prints those losses to stderr. --trajectory with GRO output is refused because the current writer emits one structure; use multiframe XYZ when all frames are needed.

Read a compressed GROMACS XTC with an explicit topology:

orbitron info production.xtc --topology system.gro --frame 100 --json
orbitron convert production.xtc --topology system.gro --frame 100 -o frame-101.xyz
orbitron view production.xtc --topology system.gro

Orbitron refuses a missing topology or atom-count mismatch. When a topology describes a different frame, add --confirm-xtc-atom-order only after checking that its atom order is identical. The CLI prints a warning and records the count-only pairing in metadata.

Apply a named periodic view and optional centering or fitting at the shared trajectory-loading boundary:

orbitron info production.xtc --topology system.gro \
  --trajectory-pbc whole-molecules --frame 100 --json
orbitron convert production.xtc --topology system.gro \
  --trajectory-pbc no-jump --trajectory-center 'resname SOL' \
  --frame 100 -o centered.xyz
orbitron render production.xtc --topology system.gro \
  --trajectory-fit 'chain A and not element H' \
  --trajectory-fit-reference 20 --frame 100 -o fitted.png

--trajectory-pbc accepts as-stored, whole-molecules, and no-jump. --trajectory-center and --trajectory-fit accept the selection language described below and cannot be combined. Fit references and requested frames are zero-based. The flags also apply when view --tui or the desktop viewer loads the trajectory.

Chemical identifiers — InChI, InChIKey, SMILES, and molecular formula from a structure file (handles metal complexes / coordination compounds):

orbitron identify cisplatin.xyz            # formula + InChI + InChIKey + SMILES
orbitron identify cisplatin.xyz --json     # single JSON object (for scripting)
orbitron inchi metal.xyz --reconnected     # InChI with the RecMet layer for metals
orbitron smiles caffeine.xyz               # canonical SMILES

Build a new structure from supported SMILES:

orbitron from-smiles 'CCO' -o ethanol.sdf
orbitron from-smiles 'c1ccccc1' -o benzene.xyz --json
orbitron from-smiles '[NH4+].[Cl-]' -o salt.sdf --no-3d

If the output path has no extension, Orbitron adds .xyz. Existing files are protected unless --force is present. The reader supports atoms, isotopes, charges, aromatic atoms, branches, rings, disconnected components, tetrahedral @/@@, and directional non-ring alkene //\ stereochemistry. Stereochemical input requires 3D generation. Wildcards, atom maps, reactions, SMARTS, CXSMILES, ring-alkene stereo, and non-tetrahedral atom configurations are refused rather than simplified. Bracketed metal ions are accepted. With --no-3d, the output is marked as a 2D depiction rather than measurable molecular geometry.

orbitron info reports a declared molecular charge and multiplicity when the scene carries one, together with the implied electron count, spin-state parity, and whether it matches the sum of per-atom formal charges.

4.3 Render images with custom camera configurations

The render command supports the --camera <path.json> option to specify custom camera positions for reproducible rendering. See Viewer §3.10.3 for the JSON format and coordinate system.

Basic usage:

# Render with default camera (position: [0,0,10], target: [0,0,0], distance: 10.0)
orbitron render fixtures/benzene.xyz -o benzene_default.png

# Render with saved camera preset
orbitron render fixtures/benzene.xyz -o benzene_front.png --camera cameras/front.json

# Render with custom close-up view
orbitron render molecule.xyz -o closeup.png --camera cameras/closeup.json

Camera JSON format (all fields optional):

{
  "position": [x, y, z],    // Camera location (Ångströms), default: [0.0, 0.0, 10.0]
  "target": [x, y, z],      // Look-at point (Ångströms), default: [0.0, 0.0, 0.0]
  "distance": float         // Distance from target (Å, min 0.001), default: 10.0
}

Example camera configurations:

# cameras/front.json (standard front view)
{ "position": [0.0, 0.0, 10.0], "target": [0.0, 0.0, 0.0], "distance": 10.0 }

# cameras/side.json (90° rotation)
{ "position": [10.0, 0.0, 0.0], "target": [0.0, 0.0, 0.0], "distance": 10.0 }

# cameras/closeup.json (close-up view of specific region)
{ "position": [3.0, 4.0, 5.0], "target": [1.5, 2.0, 0.0], "distance": 3.0 }

Minimal JSON (override only what you need):

// Just change distance (use default position and target)
{ "distance": 15.0 }

// Just change target (use default position and distance)
{ "target": [5.0, 0.0, 0.0] }

Batch rendering with multiple camera angles:

# Render same molecule from three different angles
for cam in front side top; do
  orbitron render molecule.xyz -o "molecule_${cam}.png" --camera "cameras/${cam}.json"
done

Implementation: automation/cli/src/handlers/commands/convert.rs:14 (read_camera_config), core/services/src/renderer/types.rs (CameraConfig struct)

4.4 Selection expression cheat sheet

Selection expressions are made of primitive terms combined with boolean operators.

Primitive terms:

  • element O (or a bare symbol like Fe; case is normalised) — select by element
  • atomic_number == 6 — select by atomic number
  • within 5.0 of <selection> — atoms within a radius of any atom matched by a sub-selection (the anchors are included), e.g. within 5.0 of element O
  • within_atom(1, 3.0), within_atom_shell(1, 1.5, 3.0) — distance from a single anchor atom
  • within_point(0.0, 0.0, 0.0, 5.0), within_point_shell(0, 0, 0, 1, 4) — distance from a point
  • bonded_to(7) — atoms bonded to an anchor
  • nearest_atoms(1, 5), nearest_point(0, 0, 0, 5) — the k nearest
  • within_atom_angle(vertex, ref, min, max) — angular filter around a vertex
  • property("partial_charge") > 0.25 — registered atom property compared to a threshold; the operator is one of >, >=, <, <=, ==, !=
  • chain A, resname HIS, resid 42 — residue terms, for structures that carry PDB/mmCIF annotation. Names and chain ids compare case-insensitively
  • altloc B — atoms in retained alternate location B. Blank/shared atoms do not match this term; combine it with another term when both are wanted

Atom ids are 1-based.

Naming one residue takes more than one term. A sequence number is only unique within a chain, and a residue name is not unique at all, so chain B and resname HIS and resid 42 is what picks out a single residue. On a scene with no residue annotation — an XYZ file, say — all three match nothing rather than everything.

Boolean operators combine terms: and, or, not, with parentheses for grouping. not binds tightest, then and, then or, so element C or element O and within_atom(1, 3.0) reads as element C or (element O and within_atom(1, 3.0)). The within <R> of operator binds the term that immediately follows it (use parentheses for a compound sub-selection). Examples:

  • element O and bonded_to(7)
  • within 5.0 of (element O or element N)
  • resname CYS and S — every cysteine sulfur, which is what you want before looking for disulfides
  • within 5.0 of (chain A and resid 42) — the environment of one residue
  • within_atom(1, 5.0) and not element H
  • property("partial_charge") < -0.3 and not element O

See the Developer Guide (§4.2 Query & Selection Engine) for the AST and evaluator details, and run orbitron select --help for the DSL overview.

4.5 Inspect stage/task boundaries

Use inspect to review the stages or tasks detected in Gaussian, NWChem, DIRAC, Molpro, and Molcas/OpenMolcas outputs and to obtain the byte ranges accepted by the boundary loaders documented in §2.1. Molpro logs print task kind, program banner, method/basis hints, correlated energies (when present), and any attached XML sidecar summaries. When Molpro metadata is available you can pass --dirac-task N (1-based index) or --molpro-task N (1-based index) or --molpro-kind freq (--task freq, --task caspt2, etc.) to restrict output to a single task or to all tasks of the same kind, and the correlated energy section respects the same filters. Molcas/OpenMolcas outputs are parsed into canonical documents that expose extras.molcas (geometry, module-based task list, optimisation energy profiles, and frequency mode counts), and the desktop Tasks panel renders the same module records.

orbitron inspect io/pipelines/tests/fixtures/gaussian/water_two_stage.log

Machine-readable triage (--json). orbitron inspect <file> --json emits the same findings in a shape a script can branch on, carrying the schema / producer / warnings fields described above (orbitron.inspect/2). The subject field says what kind of file was read:

  • output — anything that parses into a canonical document. Carries program (which program wrote it, named even when no tasks were extracted — format says only out for Molcas, DIRAC and NWChem alike), detected (trajectory, scene, or unparsed), capabilities, frames[] (index, step, atoms, bonds, energy, electronic-structure presence), scene for a single geometry, frequency.modes, program_tasks[] in the same shape info --json emits, and molpro. Machine-facing enum values are snake_case ("qe", "single_point"); they were respelled from the Rust spelling when the schemas went to /2.
  • movecs, hessian, molden, civecs, dirac_checkpoint — the companion files, which never become canonical documents and each carry their own fields.

Electronic structure is reported as presence plus counts, not as the data itself: inspect is triage, and analyze returns the bands, DOS and gaps themselves. One field worth branching on is band_structure.sampling (path or mesh); a mesh run also raises the band_eigenvalues_from_mesh warning, because those eigenvalues are stored in grid order and plotting them as a dispersion is an artefact.

An unparseable file is reported as detected: "unparsed" with a parse_error, and still exits 0 — “this file is not readable” is a triage answer, not a command failure. Selector errors are not: --molpro-task 999 fails the same way it does under info, since both use the same selection code.

orbitron inspect run.out --json | jq -r '.detected, (.frames | length)'

The human output prints a table of stages with their classification, energies, and (start_byte, end_byte) pairs. Pass these byte ranges to helpers such as gaussian_stage_scene_by_boundary or nwchem_task_scene_by_boundary to load just the portion of interest without reparsing the full log. Molpro canonical helpers currently operate on entire documents; the CLI’s summary still surfaces correlated energies, population data, and XML attachments so you can script around the structured extras.

4.6 Canonical bundles & cache management

Use the canonical subcommands to decouple heavy program logs from day-to-day analysis. Bundles record every attachment (raw source, MO coefficients, trajectories, volumetric grids) plus SHA-256 hashes so the viewer and CLI can hydrate caches without rereading gigabyte-scale logs.

# Export manifest + attachments for a run
orbitron canonical export fixtures/gaussian/benzene.log --output benzene.orbpack --pretty

# Emit a verified record for batch automation; failures still exit nonzero
orbitron canonical export run.out --output run.orbpack --json > run.export.json

# Restore the raw source (and hydrate the cache if needed)
orbitron canonical import benzene.orbpack --output benzene.log

# Inspect cache location, contents, or purge entries
orbitron canonical cache path
orbitron canonical cache list
orbitron canonical cache purge

The cache lives under the platform-default directory unless ORBITRON_CANONICAL_CACHE is set. Both CLI and GUI share this path, so exporting a bundle immediately benefits viewer loads and vice versa. Helper crates register attachment references through the shared register_attachment_refs / outcome_with_attachments utilities, guaranteeing that CLI exports and viewer loads see identical metadata. When scripting, prefer canonical exports for reproducible automation because they preserve provenance, attachments, and program extras in a single portable file. --json emits the versioned orbitron.canonical.export/1 record with hashes, counts, byte sizes, elapsed time, observed peak RSS, status, and error fields.

4.7 Configuration management (config)

Orbitron persists settings to a platform-specific configuration file (~/.config/Orbitron/config.toml on Linux/macOS, %APPDATA%\Orbitron\config.toml on Windows). Use the config command to update thresholds without manually editing the file.

Set maximum file size:

# Set limit in bytes
orbitron config set-thresholds --max-file-size 2147483648  # 2 GB

# Or use megabytes for convenience
orbitron config set-thresholds --max-file-size-mb 2048  # 2048 MB = 2 GB

# Unlimited loading (use with caution on large files)
orbitron config set-thresholds --max-file-size 0

The saved threshold applies to all subsequent CLI and GUI operations unless overridden with --max-file-size on a per-command basis. This prevents accidentally loading multi-gigabyte files that could exhaust memory. The viewer’s Preferences dialog also exposes this threshold setting and saves to the same config file.

4.8 Periodic bundle packaging (pack periodic)

pack periodic assembles a portable directory from a periodic calculation: the canonical document, every figure and CSV the run supports, and optionally the raw files. The exporters read the canonical electronic structure rather than anything program-specific, so a Quantum ESPRESSO output works as well as a VASP one.

The command was called pack vasp when it only handled VASP, and that name still works as an alias.

Basic usage:

orbitron pack periodic vasprun.xml
# Creates: vasprun.orbitron/

orbitron pack periodic pw.bands.silicon.out    # Quantum ESPRESSO
orbitron pack periodic /path/to/vasp_dir --output my_bundle.orbitron

Options: - --force: Overwrite existing bundle directory - --skip-raw: Omit raw input/output files (smaller bundle, canonical only) - --include-volumetric: Include volumetric grids (CHGCAR, LOCPOT, AECCAR, PARCHG)

Bundle contents. Filenames are prefixed with the source stem, and each product is written only when the run carries the data for it:

File Contents
orbitron.json Canonical document: structure, band structure, DOS, projections, band gap
exports/<stem>_bands.csv One row per (k-point, band) sample, plus a weight column per shell when a PROCAR supplied projections
exports/<stem>_bands.png Band structure, one curve per band, with high-symmetry corners labelled
exports/<stem>_fatbands_<shell>.png Projected (“fat”) bands: marker area proportional to s/p/d/f character. One figure per shell the run projects onto
exports/<stem>_dos.csv, _dos.png Total density of states
exports/<stem>_pdos.csv, _pdos.png Site- and shell-resolved DOS from a LORBIT >= 10 DOSCAR, grouped per element (Ni d, O p)
exports/<stem>_band_envelope.csv, _band.png Valence/conduction envelope. This is not a dispersion — see the note below
raw/ Copy of the original files (unless --skip-raw)
volumetric/ Grid files (with --include-volumetric)
manifest.json SHA-256 hashes and export metadata
Plot the bands, not the envelope

_band_envelope.csv reduces each k-point to max(E ≤ E_F) and min(E > E_F). That quantity steps to the next band down wherever a band crosses the Fermi level, so it is discontinuous by construction even when every eigenvalue is smooth. For a band-structure figure use _bands.csv / _bands.png.

A k-point mesh is not a band path

If the run sampled a Brillouin-zone grid (Monkhorst-Pack, Gamma) rather than a line-mode path, its eigenvalues are stored in grid order — consecutive samples are not neighbours in reciprocal space, and plotting them as a dispersion draws a jagged trace that is an artefact of the ordering. Orbitron detects this and captions the figure SCF MESH, NOT A K-PATH; orbitron inspect warns as well. Re-run with a line-mode KPOINTS for a publishable band figure.

The opposite holds for the band gap: a mesh gives a better gap than a path, because a path visits high-symmetry lines and can miss an extremum lying off them.

Use this command for archival, sharing results without raw files, or preparing datasets for downstream analysis. The GUI’s export dialog includes “Save VASP bundle…”, which uses the same packer.

4.9 Filesystem inspection (fs)

The fs commands inspect the local data root.

List directory contents:

# List current directory (or --data-root if set)
orbitron fs list

# List specific directory
orbitron fs list /data/projects/benzene

# JSON output for scripting
orbitron fs list calculations --json

JSON output includes:

{
  "path": "calculations",
  "entries": [
    {"name": "opt.log", "is_dir": false, "size": 1048576, "extension": "log"},
    {"name": "freq", "is_dir": true, "size": 0, "extension": null}
  ]
}

Check file existence:

# Prints "<path> => exists" or "<path> => missing", and exits 0 or 1 so it can
# be used in a shell conditional:
#   if orbitron fs exists calculations/benzene.xyz; then ...
orbitron fs exists calculations/benzene.xyz