Automation CLI

automation/cli bundles high-level workflows powered by OrbitronServices. All commands honour the global flags for logging, periodic boundary conditions, data root, and remote endpoints. - 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>.

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 --source io/pipelines/tests/fixtures/xyz/water.xyz --distance 1 2

  3. Render a PNG headlessly

    orbitron render io/pipelines/tests/fixtures/xyz/water.xyz -o 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
analyze geometry\|orbitals\|populations\|vibrations Rich analyses JSON or human output, --frontier, --top, --projected knobs
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, within R of <sel>, and and/or/not
measure Distance, angle, or dihedral measurement Accepts --distance a b, --angle a b c, or --dihedral a b c d (1-based atom indices)
convert Convert or extract frames Formats inferred from extension, --frame or --trajectory options
render Headless PNG render -o/--output, --width, --height, --camera (legacy JSON), --appearance <bundle.json> (theme + lighting + camera + render flags from File ▸ Export Appearance Bundle), --diagram/--diagram-style/--diagram-show-h
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 Lists Gaussian stages, NWChem tasks, DIRAC task summaries (SCF/DFT/RESOLVE/TDDFT), Molpro task summaries (program, method, energies, diagnostics) with byte boundaries when available, and Molcas/OpenMolcas module summaries (modules, optimisation energy profiles, and frequency mode counts); accepts --dirac-task N, --molpro-task N, --molpro-kind freq (alias --task freq/--task caspt2), and --molcas-task N filters
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 vasp Package VASP outputs Assembles structured bundle with canonical JSON, DOS/band CSVs, PNG plots, 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
fs list\|exists Inspect data roots (local or remote) fs list [--path <dir>] [--json] lists directory contents, fs exists <path> checks file existence; add --remote [user@]host:/root to inspect a remote host over SFTP
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)

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.

When canonical metadata includes task summaries (e.g., QE or NWChem runs), orbitron info --json now 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 output prints the same section after the metadata/tags block.

4.1 List top charges from a Gaussian run

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

4.2 Convert the third frame of a trajectory to XYZ

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

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

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 §3.11.2 for complete documentation of 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 Inspect remote data over SSH/SFTP

orbitron --remote mycluster:/scratch/$USER/runs info benzene.out

4.5 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 >, >=, <, <=, ==, !=

Atom ids are 1-based.

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)
  • 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.6 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) but do not yet drive Tasks panel entries.

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

The command 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.7 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

# 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, viewer loads, and remote hydrations see identical metadata. When scripting, prefer canonical exports for reproducible automation — they preserve provenance, attachments, and program extras in a single portable directory.

4.8 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 remote configuration dialog also exposes this threshold setting and saves to the same config file.

4.9 VASP bundle packaging (pack vasp)

The pack vasp command assembles a structured directory from VASP calculation outputs, organizing raw files, canonical metadata, and derived data products into a portable bundle.

Basic usage:

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

Custom output directory:

orbitron pack vasp /path/to/vasp_dir --output my_bundle.orbitron

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

Bundle contents: - orbitron.json: Canonical document with structure, periodic electronic structure, DOS, bands - dos_total.csv: Total density of states (energy, DOS values) - bands_envelope.csv: Band structure envelope (k-points, energies) - dos_plot.png, bands_plot.png: Quick-look plots for reports - raw/: Copy of original VASP files (when --skip-raw not used) - volumetric/: Volumetric grid files (when --include-volumetric used) - manifest.json: SHA-256 hashes and export metadata

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

4.10 Filesystem inspection (fs)

The fs commands provide a unified interface for inspecting local and remote data sources; with --remote they run over the same SSH/SFTP backend the viewer uses.

List directory contents:

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

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

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

JSON output includes:

{
  "path": "calculations",
  "entries": [
    {"name": "opt.log", "kind": "file", "size": 1048576},
    {"name": "freq", "kind": "directory"}
  ]
}

Check file existence:

# Returns exit code 0 if exists, 1 if not
orbitron fs exists calculations/benzene.xyz

# With remote source
orbitron --remote hpc.example.org:/scratch/user fs exists data.log

The fs commands work identically for local and remote data sources—just add --remote [user@]host:/root to query a remote host over SFTP instead of the local filesystem. This is useful for scripts that need to check file availability before launching expensive operations.