Data Support

Orbitron’s io/pipelines crate provides a unified loader (load_scene, load_trajectory, load_frequency_data) that automatically selects the correct parser. The table summarises formats tested in production:

Format Extensions Highlights
XYZ .xyz Multi-frame trajectories, streamed via canonical helpers, attaches final-frame structure plus optional positions attachment
GROMACS GRO / XTC .gro, .xtc GRO reads fixed-width structures and concatenated short trajectories and writes one structure. XTC reads positions, time/step, precision, and orthorhombic or triclinic boxes lazily; it requires an explicit topology-bearing structure and is read-only. Coordinates are converted from nm to Å once. TPR, TRR, TOP, and ITP are not supported. Use gmx editconf -f topol.tpr -o topol.gro for a coordinate-only TPR conversion; it does not preserve force-field topology.
Gaussian LOG/FCHK/CUBE .log, .fchk, .cube, .gjf, .com Optimization trajectories, vibrational modes, orbital/NBO metadata, stage summaries + boundary loaders, canonical bundles capture MO and vibrational attachments
NWChem OUT/NW + companions .out, .nw, .movecs, .hess, .cube Multi-task support (OPT/FREQ/SP), byte-ranged loaders, canonical extras summarise tasks and attach MO coefficients/trajectory shards. Sources tab also loads .movecs (Fortran-binary MO coefficients) for full nbf × nmo coverage and .hess (Cartesian Hessian) for follow-up frequency synthesis when the .out doesn’t already carry the freq block. NWChem .out extracts the basis-set definition into a GaussianBasisSet, so .out + .movecs together render molecular orbitals as 3D isosurfaces in the Surfaces tab.
ORCA OUT .out Geometry and geometry-optimisation trajectories with per-cycle energies; vibrational modes with IR intensities and animated displacements; thermochemistry (ZPE, enthalpy, Gibbs, entropy components). Detected by ORCA’s own banner, so it coexists with the other programs that use .out. All 3N modes are kept, including the six near-zero translations and rotations, because ORCA’s IR table indexes into that numbering. Orbital energies and occupations, spin-resolved for unrestricted references, and Mulliken charges with spin populations are taken from the last SCF. Full orbital coefficients load from ORCA’s converted .molden.input companion, described below. IRC reaction paths are read from the IRC PATH SUMMARY table and the _IRC_Full_trj.xyz companion. TD-DFT/TDA excited states include orbital transitions and oscillator strengths in both gauges. EOM-CCSD includes signed single and double excitation amplitudes and uses the left-right spectrum for intensities. CASSCF and MRCI states retain their printed configuration occupation patterns and weights; MRCI also retains each state’s reference-space weight.
Molpro OUT (+ XML) .out, optional XML sidecars Task summaries (SCF/OPT/FREQ/CASPT2/CI/MRCC/MP2), correlated-energy capture, canonical extras seeded from XML manifests
Molcas/OpenMolcas OUT + companions .out, .molden Canonical documents expose module tasks (extras.molcas.tasks), optimisation energy profiles, frequency mode counts, RASSCF/CASPT2 diagnostics. Sources tab loads .molden siblings (SCF / RASSCF / Guess / MP2 flavors) and renders MOs as 3D isosurfaces in the Surfaces tab — the MOLDEN file ships geometry, basis, and coefficients in one file so no extra companion is needed. Sibling matching auto-detects Molcas-style task suffixes (acrolein.scf.molden matches acrolein.out).
MOLDEN .molden, .molden.input Self-contained geometry, Gaussian basis, MO energies, occupations, spin channels, and coefficients. Opens directly or enriches an ORCA/Molcas scene through Sources.
TREXIO (HDF5 backend) .h5, .trexio.h5 Content-detected HDF5 wavefunction container. Reads geometry, electron counts, optional periodic cell, ECP-aware atomic identity, Gaussian basis, and MO energies/occupations/coefficients. Coordinates and cells are converted from bohr to Å. Cartesian AOs, non-Gaussian bases, non-unit AO normalization, determinants, RDMs, CSFs, amplitudes, and integral groups are refused or outside the current reader.
DIRAC .out (+ HDF5 checkpoint) Relativistic QC output — geometry and run/energy summary; MO coefficients load from the companion HDF5 checkpoint via Analysis → Sources for orbital isosurfaces. Content-detected (no fixed extension).
Quantum ESPRESSO .out, .in, .xml, .xsf, .dos, .pdos_*, .bands, .UPF Periodic structures from .out text output, .in input decks, structured data-file-schema.xml (eigenvalues, occupations, fermi level), Cube-formatted .xsf densities (pp.x output_format=6) and proper XSF, DOS/PDOS/bands plot summaries under extras.qe, relax energy profiles, inline band samples
VASP vasprun.xml, POSCAR, CONTCAR, OUTCAR, INCAR, KPOINTS, POTCAR, DOSCAR, EIGENVAL, PROCAR, CHGCAR/CHG/PARCHG, XDATCAR, DYNMAT, ACF.dat Open any canonical filename (no extension required); auto-switches to Analysis → Sources showing the rest of the directory. Periodic geometry + DOS/band/forces/magmom/Bader, band gap (value, direct/indirect, and the k-points it occurs at), orbital projections from PROCAR (projected “fat” bands), site- and shell-resolved DOS from a LORBIT >= 10 DOSCAR, and high-symmetry corner labels read from KPOINTS. CHGCAR exposes total + spin-density isosurfaces. XDATCAR loads as multi-frame trajectory. POSCAR ↔︎ CONTCAR Compare overlay shows relaxation. Sources retired the old .zip/.tar archive-import flow.
CIF .cif Symmetry + periodic unit cells with provenance tags, plus mmCIF chain/residue identity, declared and unresolved polymer sequence, alternate locations, source connections, biological assemblies, secondary structure, and chemical-component type/name/formula/mass/parent metadata. Multi-model mmCIF files open as a model collection with source model numbers and no invented time steps; reordered rows are aligned by atom identity, while inconsistent models are reported and left first-model-only. The wwPDB 1 Å P1 placeholder used by non-crystallographic structures is not treated as a periodic cell. The asymmetric unit is expanded on load, tagged cif:expanded_asymmetric_unit:<from>:<to>, using the file’s symop loop or, when it has none, the space group it names (tagged cif:space_group_from_table:<number>:<hall>). Where the symbol leaves the origin choice open, the listed coordinates decide it (an expansion that puts atoms impossibly close, or that scatters a site across a lower-symmetry position, is the wrong one), tagged cif:space_group_setting_from_sites:<number>:<choice>:<hall>. If nothing distinguishes them the file is left unexpanded and warns cif:ambiguous_space_group_setting:<number>:<choices>, since the wrong setting moves atoms silently; add :1/:2 or :H/:R to the symbol, or a _space_group_name_Hall line, to say which
PDB .pdb, .ent, .brk, .pdb1 Biomolecular chains/residues, declared sequence and missing residues, alternate locations, source connections and inferred bonds, biological assemblies, and secondary structure. Multi-model ensembles open as a model collection with source MODEL numbers rather than time steps; models with different atom identities cannot be combined and are reported. The wwPDB 1 Å P1 placeholder used by non-crystallographic structures is not treated as a periodic cell
SDF/MOL .sdf, .mol V2000 and V3000 connection tables, bond orders including dative (V3000 type 9, see §2.6), canonical structure + raw-source attachments. A multi-record file loads every record as a trajectory tagged trajectory:kind = "records", so the UI steps it as “Record N of M” and any unreadable record is counted in sdf:unreadable_records:N. The single-scene path takes only the first record and reports the rest as sdf:skipped_records:N in io:warnings
Standalone NBO summaries .nbo + optional .47 (FILE47) Natural population tables and the full natural bond orbital table — bonding (BD), antibonding (BD*), core (CR), lone pair (LP), lone vacancy (LV) and Rydberg (RY), each with its bond order and per-atom contributions. Optional FILE47 geometry/basis metadata for NBO7; canonical documents capture population extras and raw logs. An open-shell run prints one orbital table per spin and only the alpha table is read, reported as nbo:extra_spin_tables_not_parsed:N in io:warnings
Volumetric CUBE files .cube Single grids with metadata + volumetric attachments
Volumetric directories directory of .cube files Ensures all cubes share a geometry, emits per-grid attachments and dataset metadata
MRC2014 / CCP4 maps .mrc, .map, .ccp4 Scalar experimental-density maps with endian-aware voxel decoding, nonstandard axis permutation, nonzero origins or start indices, skewed crystallographic cells, header statistics, and registered Cartesian placement. Ordinary maps open positive-only at the header-derived contour; signed difference maps can enable a separately colored negative contour. Uncompressed scalar modes are supported. Complex modes and volume stacks are refused, and compressed .map.gz files must be decompressed first.

ORCA orbital isosurfaces need one conversion step. ORCA keeps its basis set and MO coefficients in .gbw, a binary with no published layout whose header carries a build identifier, so Orbitron does not read it. Use ORCA’s converter:

orca_2mkl <basename> -molden

This writes <basename>.molden.input, an ordinary MOLDEN file that Orbitron reads in the desktop, CLI, and Python. Put it beside the output and load it under Sources. Orbitron checks atom identities and coordinates before it attaches the basis and coefficients to the active ORCA scene.

Loaders apply provenance tags, infer covalent bonds (SceneBuilder::infer_covalent_bonds), and attach task metadata.

Biological identity when exporting

Choose an export by the identity it can carry:

Export Biological identity retained
Orbitron bundle/session The complete scene: stable atom IDs, atom and bond properties, component definitions, and source metadata.
PDB Author chain, residue name and number, insertion code, atom name, alternate location, record kind, element, and active SSBOND records. Atom serials are local to the written file. General mmCIF label identifiers, chemical-component definitions, and _struct_conn rows do not fit PDB.
GRO Residue number/name and atom name/number, within the format’s five-column limits. Chain, insertion-code, alternate-location, mmCIF label, component-definition, and source-connection identity are absent from GRO; Orbitron reports each applicable loss after export.
MOL/SDF Element, formal charge, isotope, stereochemistry, and explicit connectivity. Chain and residue identity are absent.
XYZ Element and coordinates only.

Keep an Orbitron bundle beside a PDB, GRO, MOL/SDF, or XYZ export when the full edited scene must reopen without format loss.

GROMACS GRO structures and short trajectories

Orbitron treats .gro as a coordinate format. A single frame opens as a structure. Concatenated frames open as a trajectory in the desktop, TUI, CLI, Rust SDK, and Python bridge. The parser accepts the format’s variable coordinate precision, optional velocity columns, title times, and three- or nine-value box records. Source residue and atom numbers are retained even when their five-column fields wrap.

GRO does not contain bonds, atom charges, isotopes, force-field parameters, chain IDs, insertion codes, alternate locations, mmCIF label identifiers, chemical-component definitions, or source connections. Orbitron may infer bonds for display and analysis, but writing GRO cannot store these fields. The desktop, CLI, and SDK exporter report each applicable loss. Use an Orbitron bundle when those fields must survive, or keep the original GROMACS topology beside the coordinate file.

See GROMACS and MD trajectories for frontend examples and the current XTC/topology boundary.

Experimental density maps

Open an MRC2014 or CCP4 map directly to inspect its cell and density, or open the matching PDB/mmCIF model first and use Analysis → Surfaces → Add volume… to place both in the source Cartesian frame. Orbitron applies MAPC, MAPR, and MAPS, the origin or start indices, cell sampling, and cell angles when it builds the grid transform. It does not fit or translate a model to a map by guesswork.

Experimental density starts at the header-derived recommended contour and draws only the positive surface. Expand the row to change the contour, opacity, or color. Enable Negative contour for a signed difference-density map. These choices are stored in sessions and Orbitron bundles, and are replayed by desktop, CLI, and Web View rendering.

MRC volume stacks (ISPG 401 through 630) and complex Fourier modes are not scalar maps, so Orbitron rejects them. Large maps pass through the same resource preflight as CUBE and XSF files; the header contributes exact stored grid dimensions before voxel decoding begins.

When atoms are selected, a volume row offers Clip to selection. Orbitron captures their Cartesian bounds with 4 Å of padding, adjustable from 0 to 20 Å. The captured region stays fixed if the live selection changes; use Replace from selection to capture new bounds or Show full map to remove the clip. Cropping runs before the surface memory gate, decimation, and marching-cubes step, including for skewed grids. It lowers mesh-generation work, but it does not lower the cost of parsing or retaining the map. Sessions, bundles, CLI renders, and Web View exports retain the clip.

XTC is a coordinate stream rather than a topology. Its indexed service source keeps topology identity and bonds stable while decoding requested frames into a three-frame cache. Atom count must match on every frame. First-frame coordinate agreement verifies order; otherwise a caller must explicitly confirm order and Orbitron records the pair as unverified.

Construction input: SMILES

SMILES is a builder input rather than a file loader. Use Edit → SMILES, orbitron from-smiles, or Scene.from_smiles(). The supported subset covers atoms, bracket atoms, isotopes, formal charges, aromatic atoms, branches, ring closures, disconnected components, tetrahedral @/@@, and non-ring alkene //\ stereochemistry. Orbitron adds explicit hydrogens and can generate deterministic 3D coordinates.

Stereo requires 3D generation. Wildcards, atom maps, reactions, SMARTS, CXSMILES, ring-alkene stereo, and non-tetrahedral atom configurations are refused. Bracketed metal ions are accepted, but Orbitron’s deterministic 3D embedding is a starting geometry rather than a metal-complex structure prediction. Import MOL or SDF from a chemistry toolkit when unsupported SMILES features matter. See Viewer §3.7.12.

The format table describes what can enter the canonical document. The Analysis Results guide shows where dipoles, computed bond orders, method and basis provenance, implicit solvation, SCF histories, multireference contributions, and periodic electronic structure appear in the desktop, TUI, CLI, and Python bridge.

Interested in adding a new format? See the checklist in the Developer Guide (§5.1 Adding a New Chemistry Format) for a turnkey parser skeleton, naming conventions, and test scaffolding.

2.1 Quantum ESPRESSO support

Orbitron’s QE ingestion handles the full file zoo a typical QE project carries:

  • SCF / relax / nscf outputs (*.out): periodic structures + unit cells, SCF energetics, relax profiles, and task summaries (extras.qe).
  • Input decks (*.in): parses &CONTROL, &SYSTEM, ATOMIC_SPECIES, ATOMIC_POSITIONS, and CELL_PARAMETERS sections; derives the lattice from ibrav (0–14, including centred orthorhombic / monoclinic / triclinic variants) + celldm(1..6), or from explicit CELL_PARAMETERS for ibrav=0. Atom positions handled in alat / bohr / angstrom / crystal units. Open a .in directly to view the structure before running the calculation.
  • Structured XML output (<prefix>.xml / <prefix>.save/data-file-schema.xml): parsed via roxmltree. Surfaces atomic_structure, per-k-point eigenvalues + occupations, Fermi level, total energy, convergence status, exit status, and spin / SOC flags. More reliable than scraping .out because the schema is version-stable.
  • XSF volumetric (*.xsf): handles both proper XSF (CRYSTAL / MOLECULE / ATOMS) and QE’s “Cube-as-xsf” flavour (pp.x output_format=6 writes Gaussian Cube content with an .xsf extension). Cube-formatted XSF routes through the existing cube parser so pp.x densities, individual orbitals, and transition densities flow through the orbital-dataset registry alongside native .cube files.
  • DOS / PDOS / bands (*.dos, *.pdos_tot, *.pdos_atm#*, *.bands, *.bands.gnu): parsed into canonical-document extras.qe blocks with metadata for atom / WFC / orbital labels. The Sources panel surfaces each file as its own role.

Current limitations:

  • A dedicated QE Spectra panel that plots DOS / PDOS / band structure (mirroring the VASP equivalent) is future work — the parsers and Sources Load are in place but the plotting UI is not yet wired.
  • .UPF pseudopotentials are surfaced informationally in Sources but not parsed (no viewer feature consumes them today).
  • atomic_proj.xml (projwfc.x output) and the <prefix>.save/ binary checkpoint hierarchy are not parsed.
  • ibrav values are derived to a primitive cell; the -12 / ±13 monoclinic centred variants are treated as primitive with a warning that the centring isn’t expanded.

2.2 NBO FILE47 support

Orbitron can enrich standalone .nbo summaries with optional FILE47 (.47) sidecars. When a .47 file is present next to the .nbo log, Orbitron uses it to reconstruct the NBO7 basis/geometry payload so orbital and population views align with the original analysis. If the .47 file is missing or malformed, Orbitron still loads the .nbo summary — the populations and the orbital table both come from the .nbo text itself, so only the geometry falls back to synthetic positions (tagged nbo:synthetic_geometry).

The orbital table is read by the same parser whether it arrives standalone or embedded in a Gaussian log, so analyze_nbo() (Python) and the NBO tab return the same shape for both. Two things about it are worth knowing:

  • Antibonding orbitals are their own kind. BD* is not folded into BD; they are the donor and acceptor halves of a second-order perturbation analysis, and a uranyl .nbo reads as three bonding and three antibonding U–O orbitals per bond.
  • Only the alpha table of an open-shell run is read. NBO prints one table per spin and Orbitron’s orbital records carry no spin, so merging them would double the count with no way to separate them. The file warns nbo:extra_spin_tables_not_parsed:N rather than returning half its orbitals silently.

2.3 Streaming defaults

Orbitron now prefers streaming parsers whenever possible. Gaussian and NWChem log readers walk the file once to build a run summary, then seek straight to the requested stage/task when you load individual geometries, trajectories, or frequency sets. CLI/TUI/GUI all call the same boundary helpers:

  • gaussian_stage_scene_by_boundary / gaussian_stage_trajectory_by_boundary
  • gaussian_stage_frequency_by_boundary
  • nwchem_task_scene_by_boundary / nwchem_task_trajectory_by_boundary

If you script against the Rust API, use these helpers to avoid re-reading the full file.

Note: The orbitron_services::streaming trait (TrajectoryStream / TrajectoryStreamExt) exists and is exported, but no format implements it yet, so current services still load whole trajectories before playback. Background loaders keep the UI responsive; true frame-by-frame streaming waits on a real implementor.

2.4 Shared parser behavior

Parsers reuse helpers from io/pipelines/src/parsing_utils/ for finite floats, Fortran D exponents, coordinate triples, unit conversion, section markers, software-version detection, and common token patterns. Adoption varies by format, so parser-specific tests remain the source of truth for malformed input and boundary behavior.

These helpers reject non-finite coordinates and normalize recurring syntax, but they do not make every parser equally permissive. When a file cannot be read, use the reported format, section, and source warning to distinguish an unsupported construct from a damaged file. Large-output behavior is also format-specific: Gaussian and NWChem have byte-ranged stage or task loaders, while several other formats still parse the complete source.

These improvements affect all file formats supported by Orbitron, making the entire I/O pipeline more robust and maintainable. For technical details about the parsing utilities and their adoption, see the Developer Guide (§6.4 Parsing Utilities Reference).

2.5 Per-atom population coverage

The 2026 redesign of the Analysis panel (§3.6) made per-atom charges first-class — every supported format now surfaces them through the same UI (the “Charges” tab + the Atom Coloring halo overlay). Coverage by format:

Format Mulliken Löwdin Natural (NBO) APT
NWChem (.out) ✓ (modern + property-module headers) ✓ — —
Gaussian (.log) ✓ — ✓ (when pop=full / NBO) ✓ (frequency jobs)
Gaussian (.fchk) ✓ — — —
Molpro (.out) ✓ — — —
Molcas / OpenMolcas (.out) ✓ (column-oriented blocks) — — —

For optimization trajectories (NWChem, Gaussian), Orbitron backfills earlier frames with the converged populations so the Charges tab and halos stay visible regardless of which step you have parked. Without this, navigating to step 0 of an opt job used to drop the charges entirely.

For property-module runs (e.g. NWChem task scf property with the mulliken keyword) the parser returns the last Mulliken table emitted in the file — the converged value, not the preliminary atomic-guess Mulliken that some packages print early in the run.

2.6 Dative (coordination) bonds

A metal–ligand donation is a bond that both atoms’ valences have to agree about, and most connection-table formats cannot express one. Orbitron carries it as its own bond order and preserves it on export.

Where it comes from. Bond perception marks a metal–ligand pair as dative when the order search did not already find a multiple bond, and only when the ligand atom is a lone-pair donor (N, O, F, P, S, Cl, Br, I). Carbon is deliberately excluded: a metal–carbon bond is as likely to be covalent, and geometry alone cannot tell. A file that supplies its own bond orders keeps them.

What it fixes. Flattening a donation to a single bond costs the donor a hydrogen, because a single bond and a donation imply different valences. Read through a Molfile, a zinc tetraaza macrocycle used to come back as C₁₆H₂₄N₄Zn; it now reads C₁₆H₂₈N₄Zn, matching the geometry.

Export. V2000 has no code for a coordination bond, so a structure containing one is written as V3000 at any size, using bond type 9 with the donor first. The V3000 reader takes type 9 back as dative, so a round trip is lossless.

The limit worth knowing. SMILES and InChI both write a dative bond as a single bond, because that is how those formats express it and a hydrogen count derived from one valence with a string written from another would not describe the same molecule. So a metal complex’s InChI still counts the donor’s valence one too high. That is a limitation of the identifier formats, not something this changes.