Analysis Results

Orbitron keeps calculation results in program-neutral scene and task records. The desktop, TUI, CLI, and Python bridge read those same records, so a value does not acquire a different meaning when you change frontends. Availability still depends on what the source program printed.

Result	Parsed sources	Desktop	TUI	CLI	Python
Permanent dipole	Gaussian, NWChem, ORCA, Molcas/OpenMolcas, Molpro, DIRAC	Analysis → Overview	Analysis	`inspect`	`scene.dipole_moment()`
Per-atom forces	VASP, QMCPACK (`ACForce`)	Analysis → Overview, drawn as arrows	—	`analyze qmc`	—
Method, basis, and task kind	Gaussian, NWChem, ORCA, Molcas/OpenMolcas, Molpro, DIRAC, QE, CP2K	Analysis → Tasks	Analysis	`info` / `inspect`	`task_summaries(path)`
Implicit solvation	Gaussian, NWChem, ORCA, Molcas/OpenMolcas, DIRAC	Analysis → Tasks	Analysis	`info` / `inspect`	`task_summaries(path)`
SCF convergence	Gaussian, NWChem, ORCA, Molcas/OpenMolcas, Molpro, DIRAC, QE, CP2K, where the output reports iterations or status	Analysis → Tasks	Analysis	`info` / `inspect`, `plot scf`	`task_summaries(path)`
Per-atom charges and populations	See Data Support §2.5	Analysis → Charges	Analysis	`analyze populations`	`analyze_populations(scene)`
Computed bond orders	Gaussian Wiberg, NWChem Mayer, ORCA Mayer, Molcas/OpenMolcas natural, Molpro IAO Wiberg and IBBA renormalized, standalone NBO Wiberg	Analysis → Charges	Analysis	`analyze bond-orders`	`analyze_bond_orders(scene)`
NBO donor-acceptor (E(2)) interactions	Standalone NBO output (`.nbo`) and Gaussian logs run with `pop=nbo`, closed and open shell	—	—	`analyze nbo-e2`	`analyze_nbo(scene)["evidence"]["second_order"]`
Orbital energies and frontier gap	Any output with orbital energies	Analysis → Orbitals	Analysis	`analyze orbitals`, `plot levels`	`analyze_orbitals(scene)`
Vibrational modes and thermochemistry	Frequency runs	Analysis → Vibrations	Vibrations	`analyze vibrations`, `plot spectrum`	`analyze_vibrations(path)`
Excited-state contributions	Gaussian, NWChem, ORCA, Molcas/OpenMolcas, Molpro, DIRAC, depending on method	Analysis → Excited States	Analysis when available	`inspect`, `plot excited`	`scene.excited_states()`
Magnetic anisotropy (g tensors, crystal field, χT)	OpenMolcas SINGLE_ANISO	Analysis → Magnetism	—	`analyze magnetism`	`scene.magnetic_anisotropy()`
Solvent-accessible area	Any scene with elements the chosen radius table covers	—	—	`sasa`	`scene.accessible_area()`
Point group	Any molecular scene	Scene section	—	`analyze symmetry`	—
Structural validation	Protein models (PDB, mmCIF)	Sequence / Residues panel	—	`analyze validation`	—
Metal coordination sites	Any structure with metal centres	Scene Info → Coordination; Sequence / Residues → Metal sites, for structures with residues	—	`analyze metal-sites`	—
Bands, DOS, and first Brillouin zone	VASP, Quantum ESPRESSO, and CP2K (a `.bs` beside the output) when the calculation carries the required arrays and cell	Analysis → Periodic	Analysis	`inspect`, `pack periodic`, `plot bands`/`dos`/`bz`	`periodic_electronic_structure()`, `brillouin_zone()`

The table names data families rather than promising identical depth. For example, one SCF output may contain every iteration energy while another only states an iteration count and whether it converged. Orbitron preserves that difference instead of inventing points for a plot.

Molecular properties

Intended charge and multiplicity

MolecularElectronicState records the total charge and spin multiplicity intended for the current editable molecular structure. It is distinct from parsed electronic-structure evidence and from the sum of per-atom formal charges. The desktop Edit rail, TUI Properties pane, orbitron info, and Scene.molecular_electronic_state() report the same state and consistency checks.

Orbitron checks electron count and spin parity, but it does not decide which spin state is physically lowest. A warning that the atomic formal charges do not sum to the molecular charge is also diagnostic, not an automatic rewrite. Periodic scenes do not carry a molecular charge/multiplicity state.

Permanent dipole

The dipole is stored in Debye as a vector in the source coordinate system. Orbitron also reports its magnitude. Rotating the camera does not rotate or redefine the stored components.

In Python:

import orbitron

scene = orbitron.Orbitron().load("calculation.out")
dipole = scene.dipole_moment()
if dipole:
    print(dipole["vector_debye"])
    print(dipole["magnitude_debye"])

For scripts that should work without Python, orbitron inspect run.out --json places the same object under scene.electronic_structure.dipole_moment for a single-geometry file. A file with several frames, such as an optimisation, reports each frame instead, under frames[i].electronic_structure.dipole_moment.

NBO donor-acceptor interactions

A standalone NBO run, or a Gaussian log run with pop=nbo, prints the second-order perturbation theory analysis of the Fock matrix: for each donor (a lone pair, bond or core orbital) and acceptor (an antibond or Rydberg orbital) the stabilisation energy E(2) in kcal/mol, the energy gap and the Fock matrix element.

orbitron analyze nbo-e2 run.nbo
orbitron analyze nbo-e2 run.nbo --min 5 --limit 50
orbitron analyze nbo-e2 run.nbo --json

Rows come strongest first, with the donor and acceptor labels exactly as NBO printed them and the atom numbers they sit on (1-based). NBO prints only the rows above its own threshold (0.50 or 0.25 kcal/mol in the files here), so a pair that is missing has an E(2) below it, not zero; the threshold is part of the output. An open-shell run has an alpha table and a beta table, kept separate by channel. --min drops weaker rows from the output without changing the file’s count or threshold. The JSON and analyze_nbo() carry at most the 2,000 strongest rows and say so when they cut (truncated).

The scene-level warning an open-shell NBO file also prints, that only the alpha orbital table was read, concerns the orbital list. The E(2) tables are both read.

Computed bond orders

Computed bond orders are analysis results. They do not replace the scene’s connection table and do not silently change single, double, aromatic, or dative bonds used for rendering and editing.

orbitron analyze bond-orders run.out
orbitron analyze bond-orders run.out --json

The report names the method and uses 1-based atom numbers. A source may print a thresholded list rather than a complete matrix. In that case an omitted pair is unknown, not zero. Reports from complete Wiberg matrices set complete_pair_matrix: true; exact zeroes may then be omitted without losing meaning. Three-center orders are retained separately from pair orders.

The desktop shows these tables under Analysis → Charges, below the per-atom charges. The bond-order rows are read-only. Clicking a row in the per-atom charge tables above them highlights that atom. In Python, use Orbitron.analyze_bond_orders(scene).

Calculation provenance and convergence

Open Analysis → Tasks in the desktop, or the Analysis pane in the TUI, to see calculation stages in file order. Each task can carry:

program and task kind;
method and orbital basis;
implicit-solvent model, solvent name, and dielectric constant;
final energy;
SCF cycles, iteration counts, convergence status, and iteration energies;
program-specific diagnostics such as active-space details or optimisation profiles.

An optimisation contains multiple electronic SCF cycles. Orbitron keeps those cycles separate, so a convergence plot does not draw a false line between the last electronic iteration at one geometry and the first at the next.

orbitron inspect run.out
orbitron inspect run.out --json | jq '.program_tasks'

The Python equivalent parses the output document rather than only the active geometry:

orb = orbitron.Orbitron()
for task in orb.task_summaries("run.out"):
    print(task["program"], task["kind"], task.get("method"))
    print(task.get("basis"), task.get("solvation"))
    print(task.get("scf_convergence", []))

Method, basis, and solvation are provenance. Orbitron reports the labels the program supplied and does not treat them as a basis-set registry or a cross-program method equivalence.

A CP2K output reports its method as the electronic-structure scheme and the functional, for example GPW · PBE, with its SCF convergence beside it.

An output that ran several tasks opens on one of them. To read another from the CLI, number it as the desktop’s Tasks list does: orbitron analyze --task 2 populations run.out reads NWChem or Molpro task 2, or Gaussian stage 2 (the frequency job of an Opt Freq run is its own stage), and --task 1:pop names one calculation inside a Gaussian stage. See the CLI guide for the subcommands that accept it.

Orbitals and multireference states

The Orbitals panel lists energies, occupations, symmetry labels, and the largest atomic-orbital coefficients when full coefficients are available. ORCA coefficients require the sibling .molden.input produced by orca_2mkl; NWChem coefficients require .movecs. See Data Support for the companion-file rules.

The Excited States panel retains method-specific contributions instead of flattening every state into a single transition:

single-excitation methods retain occupied-to-virtual contributions and signed amplitudes where printed;
ORCA CASSCF and MRCI retain configuration occupation patterns and weights;
MRCI also retains each state’s reference-space weight;
Molcas/OpenMolcas and DIRAC retain the state data their program summaries provide.

Python exposes the same records through scene.excited_states().

Magnetic anisotropy from a spin-orbit run

For a lanthanide, an actinide or a transition metal with unquenched orbital momentum, the magnetic properties come from a pseudospin analysis of the spin-orbit states: OpenMolcas’s &SINGLE_ANISO, run after &RASSI with SPIN and MEES (and ANGMom in &GATEWAY). Orbitron reads what it prints in the output: the spin-orbit energies; each pseudospin multiplet’s g tensor and main magnetic axes, with its zero-field splitting D and E when its effective spin is above 1/2; the crystal-field parameters of the ground atomic multiplet (CRYS); the decomposition of that multiplet’s states in functions of definite M_J; the powder χT against temperature; and the powder magnetization against field at each temperature asked for.

orbitron analyze magnetism cef3.out
orbitron analyze magnetism cef3.out --json

The example is CeF3, a Ce(III) 4f¹ ion in a C3v field: CASSCF(1,7) over the seven doublets with ANO-RCC, spin-orbit coupling in RASSI, and SINGLE_ANISO on the three Kramers doublets of J = 5/2 (io/pipelines/tests/corpus/molcas/cef3-aniso/).

Pseudospin analysis (OpenMolcas SINGLE_ANISO): 14 spin-orbit states, 3 multiplets

  #  S_eff  E (cm-1)       gX       gY       gZ   Zm to ground  main |M_J|
  1    1/2       0.0   2.4231   2.4231   0.8314             -  99% |±1/2>
  2    1/2     207.6   0.0000   0.0000   2.5819          0.0°  100% |±3/2>
  3    1/2    1372.1   0.0327   0.0327   4.6127          0.0°  99% |±5/2>

Crystal field of the ground multiplet J = 5/2 (extended Stevens operators, cm-1, quantized along the ground Zm; those under 0.001 left out):
  B(2,0) = 77.4297   B(4,-3) = -0.0385   B(4,0) = 0.9117   B(4,3) = 15.7716

Powder chi T: 0.3887 cm3 K mol-1 at 0.0001 K, 0.7058 at 300 K (31 temperatures)
Powder magnetization at 2 K: 1.0009 muB at 7 T (15 fields)
Powder magnetization at 5 K: 0.7687 muB at 7 T (15 fields)

Each row is a multiplet: its energy, the main values of its g tensor, the angle between its main magnetic axis Zm and the ground doublet’s, and the |M_J| its states hold most of. The ground doublet here is easy-plane, |±1/2⟩ with g⊥ 2.42 and g∥ 0.83; the third is |±5/2⟩ with gZ 4.61 against 4.29 for a pure J = 5/2 state, the J = 7/2 multiplet 2,342 cm⁻¹ above mixing in. With the main axis along the C3 axis only B(k,0) and B(4,±3) survive; the rest are below 0.001 cm⁻¹, where the program prints what the symmetry forbids as numerical noise, and the JSON keeps every one. The JSON carries everything read under anisotropy beside the per-multiplet summary; Python’s scene.magnetic_anisotropy() returns the same, and the desktop shows the table and the χT curve under Analysis → Magnetism.

The blocking-barrier matrix elements and POLY_ANISO’s exchange coupling are not read.

Periodic electronic structure

For a periodic run, Analysis → Periodic shows the dispersion, density of states, band gap, and projections present in the source. Open 3D k-space view… adds the exact first Brillouin zone of the calculation cell, folds the sampled k-points into it, and splits a path where it crosses a zone boundary. The view can be saved as SVG or PNG.

The k-space view does not guess a standard path. It displays the samples and labels supplied by the calculation. A uniform SCF mesh is shown as points and must not be read as a band path.

periodic = scene.periodic_electronic_structure(include_projections=True)
zone = scene.brillouin_zone()

if zone:
    print(zone["zone"]["reciprocal_basis_inv_angstrom"])
    print(len(zone["zone"]["faces"]), "faces")

Reciprocal Cartesian coordinates use the physical 2π convention and units of Å⁻¹. Array indices returned by brillouin_zone() are zero-based so they can index periodic_electronic_structure() directly.

Structure checks

orbitron analyze validation checks a protein model rather than a calculation. It prints the experiment the file states (method and resolution), with a note when that falls outside the Top8000 reference of X-ray structures at 2.0 Å or better; Ramachandran and rotamer outliers against Top8000; steric clashes, where a pair whose occupancies sum to 1 or less is left out and counted; missing side-chain and backbone atoms, including those a PDB’s REMARK 470 or an mmCIF’s _pdbx_unobs_or_zero_occ_atoms states are missing; and the chain termini. See analyze validation.

orbitron analyze metal-sites reports each metal centre’s coordination number, closest reference polyhedron, donor distances, and the oxidation state it used, with where it came from (oxidation_state_source): the one given on the command line, the charge the file states, a formal charge on the metal, the ionic model (the usual source, from the file’s declared total charge), a bond-valence sum, a coordination-number prior, or the element’s one state. It also gives the d configuration, the valence electron count against the 18-electron rule (declined, or given as a range, where the geometry does not settle it), a trust grade for the state, and, for d1 to d9 centres, a σ-only ligand-field picture. The desktop’s Scene Info Coordination section shows the same readout. Two metals that share a bridging ligand are reported as one bridged site. The numbers behind each of these, and what is declined, are in Metal sites: accuracy and limits. See analyze metal-sites. The desktop’s Sequence / Residues panel has its own validation and Metal sites views; see the viewer guide.

Geometry and results remain distinct

When you edit a loaded calculation, the desktop keeps Orig and Edited views. Dipoles, orbitals, charges, bond orders, excited states, and energies belong to the geometry on which they were computed. Orbitron therefore shows them on Orig and does not imply that an edited geometry has been recalculated.

Trajectory cells belong to frames

Trajectory frames are complete scene snapshots. Quantum ESPRESSO relaxations and extended XYZ trajectories can therefore change lattice vectors from one frame to the next, or explicitly contain an aperiodic frame among periodic ones. The desktop camera and cell overlay update while stepping; the TUI Sequence pane reports the current cell; inspect --json places unit_cell on each frame; and Trajectory.frame(index).unit_cell() exposes it in Python.

XDATCAR carries this the same way. A single leading header applies to a constant-cell trajectory; a variable-cell run repeats the full header before a later configuration, and Orbitron applies that per-frame lattice to the frame that follows it.