Quick Start

This page gets Orbitron installed, opened, and useful from the desktop, CLI, terminal UI, and Python. For platform-specific installation details, see Install.

1. Install Orbitron

Download the latest release for your platform:

  • macOS: Orbitron Viewer.dmg for the desktop viewer, and orbitron-macos.zip for the orbitron command-line program, which the .dmg does not include
  • Linux: the bare binaries orbitron-viewer-linux and orbitron-linux
  • Windows: orbitron-windows.zip
  • Python: the cp310-abi3 wheel for your platform

Releases are attached to the latest GitHub release.

Put the orbitron and orbitron-viewer binaries somewhere on your PATH if you want the CLI (including the terminal UI, via orbitron view --tui) or the desktop viewer available from any terminal.

2. Open a File in the Desktop Viewer

Launch the viewer directly (or open the file from within it via File > Open):

orbitron-viewer molecule.xyz

orbitron is a separate command-line program and does not link the desktop viewer. orbitron view molecule.xyz on its own just prints a text summary of the file; add --tui for an interactive view in the terminal instead (see “Use the Terminal UI” below).

The viewer can load common molecular and computational-chemistry formats, including XYZ, PDB, CIF, SDF, GROMACS GRO/XTC, VASP, Gaussian, NWChem, ORCA, Molpro, Molcas, DIRAC, CP2K, QMCPACK, Quantum ESPRESSO, Molden, TREXIO, CUBE, MRC/CCP4 maps, and NBO outputs. Data Support lists what each one gives you.

3. Inspect a File From the CLI

The commands below run against a small file from the Orbitron repository, water_two_stage.log. Download it into the directory you run them from, and you can paste them verbatim and compare what you get; any Gaussian log of your own works too. It is a two-stage Gaussian job: a B3LYP/6-31G(d) optimization of water, then a frequency calculation reading the same checkpoint.

orbitron info prints what the file holds:

orbitron info water_two_stage.log
File: water_two_stage.log
Format: gaussian
Program: Gaussian 16 Rev. C.02
Geometry: converged_final — step 2 of 2, the converged geometry
Atoms: 3    Bonds: 2
Elements:
    H x 2
    O x 1
Bounding box (Å):
  min   = (-0.0000, -0.7615, -0.4790)
  max   = (0.0000, 0.7615, 0.1197)
  span  = (0.0000, 1.5231, 0.5987)
  center= (0.0000, 0.0000, -0.1796)
Molecular electronic state:
  charge       = +0
  multiplicity = 1
  electrons    = 10
Metadata:
  Name   : water_two_stage
  Source : water_two_stage.log
Tags:
  gaussian:frame_count: 2
  gaussian:last_energy_hartree: -76.408953979200
  gaussian:route_line: #p B3LYP/6-31G(d) Freq Geom=Checkpoint
  gaussian:structure_origin: gaussian-log
  geometry:role: converged_final
  geometry:source: step 2 of 2, the converged geometry
  provenance:loader: gaussian-log
  run:outcome: success
  run:outcome_program: gaussian

Program tasks:
  [1] Gaussian · Optimization
      Kind: Optimization
      Method: B3LYP
      Basis: 6-31G(d)
      Energy: -76.40895398 Eh
      SCF convergence: 2 cycles, 15 iterations
        Cycle 1: 9 iteration(s), converged, -76.3308768436 -> -76.4089507635 Eh
        Cycle 2: 6 iteration(s), converged, -76.4089526327 -> -76.4089539792 Eh
  [2] Gaussian · Frequency
      Kind: Frequency
      Method: B3LYP
      Basis: 6-31G(d)
      Energy: -76.40895398 Eh
      SCF convergence: 1 cycle, 9 iterations
        Cycle 1: 9 iteration(s), converged, -76.3309214384 -> -76.4089539792 Eh

The two program tasks at the bottom are the point. Orbitron did not treat the log as one calculation with one energy; it found the boundary between the optimization and the frequency job, and the SCF cycle counts under each are the ones that run reported. run:outcome: success and geometry:role: converged_final are how it says the geometry you are looking at is the converged one rather than an intermediate step.

Add --json for the same content as a machine-readable object, with a schema and producer block so a script can tell which Orbitron wrote it:

orbitron info water_two_stage.log --json

inspect asks a different question — not what the scene is, but what the file contains and how it would load:

orbitron inspect water_two_stage.log
Inspecting: water_two_stage.log

[ok] Detected as TRAJECTORY (2 frames)

Frame 0: Step=1, Atoms=3, Bonds=2, Energy=-76.408951 Ha
  - System: charge 0 (neutral), multiplicity 1
Frame 1: Step=2, Atoms=3, Bonds=2, Energy=-76.408954 Ha
  - System: charge 0 (neutral), multiplicity 1
  - Molecular dipole: 2.0954 D (x=0.0000, y=0.0000, z=-2.0954)
  - Electronic Structure: 19 MOs
  - Mulliken population analysis: 3 atoms

[ok] Detected FREQUENCY DATA
  - 3 vibrational modes

Frame 1 carries the dipole, the orbitals and the populations and frame 0 does not, because Gaussian only prints them at convergence. The output continues with the same task overview info printed, which is why inspect is the command to reach for on a log whose stage boundaries you do not already know.

Several files, one calculation

An HPC job that outruns its walltime is resubmitted, and the run continues in a second output. Name the files in the order they ran and Orbitron reads them as one study — one task list spanning all of them, naming which file each task came from:

orbitron inspect part_1.out part_2.out part_3.out
import orbitron as orb

study = orb.open_study(["part_1.out", "part_2.out", "part_3.out"])

Nothing merges the structures: two members of a restart chain hold the same molecule at different points, and averaging them would produce a geometry that never existed. The same mechanism covers unrelated runs looked at together. See Several Files, One Calculation.

To start from a SMILES string instead of a file:

orbitron from-smiles 'CCO' -o ethanol.sdf

To build a molecule interactively instead, launch the desktop viewer with a blank session and use Edit, which provides atom, ring, fragment, SMILES, conformer, metal-complex, and residue-mutation workflows. See Viewer §3.7 for the supported chemistry and refusal conditions.

4. Use the Terminal UI

For SSH sessions or machines without a graphical desktop:

orbitron view calculation.out --tui

5. Use Python

Install the wheel from the release page, then load a file:

import orbitron as orb

scene = orb.load("calculation.out")
scene

In Jupyter, returning a Scene displays the inline viewer when the bundled viewer assets are available.

Export a self-contained HTML viewer:

orb.export_html(scene, "calculation.html")

That HTML file can be opened in a browser, embedded in slides, or archived with the calculation.

Next Steps

  • Graphical Viewer - controls, measurements, overlays, orbitals, vibrations, and sessions.
  • Automation CLI - scripting, JSON output, conversion, rendering, identifiers, and batch workflows.
  • Terminal UI - keyboard-first inspection over SSH.
  • Python Bridge - Jupyter, scripting, rendering, widgets, and HTML export.
  • Web Viewer Embedding - standalone HTML and web-component embedding.