Terminal UI

Run through the CLI:

orbitron view fixtures/benzene.xyz --tui

A real session, recorded as an asciicast rather than a video — a few kilobytes where a GIF would be several megabytes, sharp at any zoom, and selectable, so a command can be copied straight out of it:

 Orbitron TUI · molecular scene
 ┌────────────────────────────────────┐
 │             H                      │
 │             │                      │
 │       H ─── C ─── H                │
 │             │                      │
 │             H                      │
 └────────────────────────────────────┘
 hjkl rotate · +/- zoom · m glyph · b bonds · r reset

The ASCII block above is a stand-in, shown only when this page is opened from disk rather than served.

Several outputs are read as one calculation — a job resubmitted after walltime, or unrelated runs looked at together. The task list spans all of them and names which file each task came from; see Several Files, One Calculation.

orbitron view jobA.out jobB.out --tui

Note: The binary requires an interactive terminal. If you see Terminal initialization failed: Device not configured, run the command directly in iTerm/Terminal rather than inside an IDE pane.

Before parsing a source or switching into raw terminal mode, the TUI estimates the load’s peak host memory from its file type, size, and any counts available in the first 64 KiB. A tight projection is shown in the ordinary terminal and defaults to cancellation unless you enter y. A configured max_memory cap refuses the load. To set a cap for one launch, use the CLI entry point:

orbitron --max-memory 8589934592 view calculation.out --tui

Use --allow-large with orbitron view --tui to skip an advisory confirmation after checking the risk. The flag cannot bypass a configured cap or a projection beyond physical memory and swap.

The TUI shares loader/analysis code with the CLI but renders via ratatui. It is keyboard-first and pane-focused: at any moment one pane is focused and owns the contextual keys, and Tab / Shift+Tab cycle focus between the panes that exist for the loaded file. A branded header bar shows the file, detected format, and atom/bond counts; a brief splash appears on launch. The panes:

View — ASCII shaded molecule viewport: arrow-key rotation, zoom, roll, glyph modes (element symbols → depth → density), and a toggleable bond overlay.
Atoms — navigable atom list with keyboard selection, filter-by-element, and geometry measurements (pick 2 atoms for a distance, 3 for an angle, 4 for a dihedral; the value shows in Properties).
Analysis: a geometry summary at the top (atom and bond counts, element and coordination-number distributions, bounding box, centre, span, dangling atoms and any loader warnings), then permanent dipole, excited states, chemical identifiers, charge / orbital / NBO highlights, computed bond orders, cross-program task provenance and SCF histories, and periodic band / first-Brillouin-zone summaries. The excited-states section names the method and state count, flags a response solver that did not converge, and gives the first five states with their energies, oscillator strengths, and — for a multireference run — the dominant configuration and the reference weight, which is what says whether a single-reference description held. Gaussian-stage and NWChem-task stepping use the same records as the CLI and desktop. A computed bond-order method displays at most 100 pair rows and 100 three-center rows, followed by the exact omitted count. Use orbitron analyze bond-orders FILE --json when you need the complete matrix. Calculation-task sections likewise display at most 100 tasks, 100 state energies per task, 100 SCF cycles per task, and 100 SCF task sections. Each truncated section gives its exact omitted count; use orbitron info FILE --json for the complete task records.
Properties (below the atom list) also reports a declared molecular charge and multiplicity, implied electron count, impossible spin parity, and a mismatch with the sum of atomic formal charges. The TUI displays this state; editing it is a desktop or Python workflow.
Sequence — read-only residue summaries (chains, gaps, components), trajectory frame playback with the periodic/centering/fitting views, and multi-stage/task stepping (appears when the file has residues, frames, stages, or tasks).
Vibrations — normal-mode selection and animation (appears for freq jobs).
Slice — a 2D orbital/density cross-section as a colored ASCII heatmap on the plane through the 3 atoms picked in the Atoms pane (appears when the scene has a basis set). Point at a cell, or move the probe with shift+arrows, to read its in-plane coordinates and the value there; the field is sampled at one value per character cell, so the number is a computed sample rather than an interpolation.

Inline image preview is available on Kitty/WezTerm-capable terminals (g).

A worked session

Over SSH, on a frequency job that finished an hour ago. Tab cycles in a fixed order — View, Atoms, Analysis, then Sequence, Vibrations and Slice for whichever of them the file supports — so “round to” below may be more than one press.

orbitron view water-freq.out --tui

The View pane has focus. hjkl turns the molecule, +/- zooms, b draws the bonds, m cycles the glyphs from element symbols to depth shading to density. r puts it back.
Tab round to Vibrations — the pane is there because the file has modes. j walks down the list, which is mode number and frequency, with i marking an imaginary mode (drawn in red) and r a rigid-body one. Stop on the imaginary one if there is one; that is the first thing a freq job is opened to check.
space animates the selected mode in the viewport. + raises the amplitude until the motion is legible, which for a stiff O–H stretch takes a few presses.
Tab round to Atoms. / filters to an element — O leaves the oxygen alone. Arrow to an atom and space picks it; pick three and the angle appears in Properties below the list. c clears the picks.
Keep those three atoms picked and Tab round to Slice, which is present only when the run wrote a basis set. The plane through the three picks is the cross-section, drawn as a coloured ASCII heatmap. m toggles between the orbital and the total density; ↑/↓ step through the MOs, so walking up from the HOMO shows where the next orbitals put their amplitude.
Tab round to Analysis. The geometry summary and the dipole are already there; i adds the formula, InChI and SMILES, which is the fastest way to confirm the file holds the molecule you meant to submit.

A one-line key hint for the focused pane sits along the bottom of the screen, and ? opens the full key reference as an overlay — that overlay, not orbitron view --help (which shows CLI flags, not TUI keybindings), is the place to look it up:

Pane	Keys	Action
Global	`Tab` / `Shift+Tab`	Next / previous pane
	`?`	Toggle key reference
	`g`	Inline preview (Kitty / WezTerm)
	`q` / `Esc` / `Ctrl+C`	Quit
View	arrows / `h` `j` `k` `l`	Rotate
	`[` `]`	Roll (z-axis)
	`+` / `-`	Zoom in / out
	`m`	Cycle glyph mode (symbols → depth → density)
	`b`	Toggle bonds
	`r`	Reset view
Atoms	arrows / `j` `k`	Move selection
	`PgUp` / `PgDn`	Jump ±10
	`Home` / `End`	First / last atom
	`/`	Filter by element
	space	Add / remove atom for a measurement
	`c`	Clear measurement
	mouse click	Select atom
Analysis	arrows / `j` `k`	Move highlight cursor
	`PgUp` / `PgDn`	Scroll the readout ±5 lines
	`Enter`	Apply highlight
	`t`	Highlight largest \|charge\| atoms
	`o` / `b`	Cycle orbital / NBO contributors
	`c`	Clear highlights
	`i`	Compute chemical identifiers (formula / InChI / SMILES), with one line per metal: the oxidation state the identifiers carry, its source, and any conflict, ambiguity or alternative
	`{` `}`	Previous / next Gaussian stage
	`<` `>`	Previous / next NWChem task
Sequence	space	Play / pause
	`n` / `p` (or arrows)	Next / previous frame
	`u`	Cycle the MD periodic view
	`c`	Center MD on the picked atoms (the cursor atom if none are picked)
	`f`	Fit MD using 3 or more picked atoms
	`x`	Clear MD centering / fitting
	`{` `}`	Previous / next Gaussian stage
	`<` `>`	Previous / next NWChem task
Vibrations	arrows / `j` `k`	Select normal mode
	space / `Enter`	Play / pause animation
	`+` / `-`	Amplitude up / down
Slice	`m`	Toggle orbital / density
	`↑` / `k`	Next MO
	`↓` / `j`	Previous MO

5.1 First-run Mac Tips

The .app from GitHub releases is signed and notarized, so it opens on first launch without a Gatekeeper prompt.
The orbitron CLI binary (which the TUI is part of) doesn’t require this step; it runs fine from the command line after cargo build --release.

Status: the TUI is a keyboard-first interactive viewer that sits between the CLI and the desktop GUI. It renders in the terminal as ASCII, but supports keyboard atom selection, filter-by-element, geometry measurements, vibration animation, and 2D orbital/density slices.

See Analysis Results for the data each analysis section represents and the matching CLI, desktop, and Python entry points.