Skip to content

Data

Data is the union of file-only FileData and structured result types. All result types inherit from FileData and require provenance, which identifies the producing program and its optional version. When contained in a ProgramOutput, the concrete type depends on the requested CalcType.

Standalone data objects hold scientific values and producer identity. They do not duplicate the calculation input; retain a ProgramOutput when you need that context.

Empty data is valid for every scientific type. For an empty OptimizationData, final_structure and final_energy return None; structures and energies are empty collections. With frames, a failed final step still contributes its evaluated structure, and any available energy is retained. An unavailable energy is nan, independently of execution success.

Frames: structures inside a calculation

A Frame is one structure inside a larger calculation, with what was computed there: an optimizer step, an IRC point, an image of a path. An optimization's frames start with its starting structure, so n steps give n + 1 frames, and final_structure is the last frame's (the optimized one after a success). A frame is a ProgramOutput without input_data (both build on OutputBase: success, logs, traceback, execution). The parent's input already holds the program, model, and keywords, so a frame keeps only its structure and results, a SinglePointData that is never None (empty, with the producing program's provenance, when nothing was computed). ProgramInput.from_spec(parent_spec, frame.structure) rebuilds a step's exact input; Frame.from_output(output) records a subprogram's output as a frame. Passing a ProgramOutput where a frame is expected converts it, taking the step's structure from its input; a saved ProgramOutput is not a frame.

Results that hold frames read the same way: structures, energies (one per frame, nan where none was computed), to_xyz(), and save("x.xyz"), which writes the structures as a multi-structure xyz file. That holds for OptimizationData (one frame per step), PathData, PathOptimizationData (its final path), and ConformerSearchData (its conformers; rotamer_energies reads its rotamers the same way).

PathData is a path of frames in order, with ts_index marking the transition state if there is one. For an IRC the frames run from the end of the reverse branch, through the transition state, to the end of the forward branch; for a chain (NEB, string) they are the images, endpoints included. forward_barrier and reverse_barrier are the transition state's energy above the first and last frames, in Hartree. PathOptimizationData.paths holds the path at every iteration, like an optimization's steps; final_path is the result.

Fields are named after what they hold: frames (OptimizationData, PathData), paths (PathOptimizationData), points (ScanData, one constrained optimization per point), and conformers/rotamers (ConformerSearchData, frames sorted by energy). The former name trajectory (of OptimizationData and ScanData) is not accepted: a payload that uses it fails validation like any unknown field. ConformerSearchData holds frames only; conformer_energies and rotamer_energies are properties that read their energies.

ScanData defaults to no points. Its structures preserves one entry per scan point, using None when a point has no optimization steps. XYZ export raises ValueError if a point lacks a final structure rather than silently omitting it.

Array schemas describe the canonical nested JSON representation: vectors are one-dimensional, geometry/gradients/Hessians are matrices, and normal modes have three dimensions. Constructors continue to accept flat arrays where scientific shape validators can reshape them.

qcdata.Data module-attribute

Data = FileData | StructuredData

qcdata.FileData

File-only results and the common base for structured calculation data.

Attributes:

Name Type Description
provenance Provenance

Required identity of the program that produced the data.

files dict[str, str | bytes]

Output files, with binary content encoded as base64 during serialization.

extras FreeDict

Additional result information.

qcdata.SinglePointData

The computed data from a single point calculation.

Attributes:

Name Type Description
energy float | None

The electronic energy of the structure in Hartrees.

gradient SerializableMatrix | None

The gradient of the structure in Hartrees/Bohr.

hessian SerializableMatrix | None

The full Cartesian second derivative of the energy at the input geometry (Eh/bohr^2), 3N x 3N, never projected. Away from a stationary point the gradient gives rotations a part in it, which projection would lose. Projection belongs to vibrational_analysis, which records it.

nuclear_repulsion_energy float | None

The nuclear repulsion energy of the structure in Hartrees.

wavefunction Wavefunction | None

Wavefunction data from the calculation.

dipole_moment list[float] | None

The x, y, z components of the dipole moment (e bohr, not Debye) of the method's charge distribution, electrons and nuclei, whatever the method: an SCF density, a force field's or tight-binding model's charges (GFN-FF's EEQ charges), an ML potential's prediction.

quadrupole_moment SerializableMatrix | None

3 x 3 quadrupole moment (e bohr^2) of the method's charge distribution, electrons and nuclei, about the coordinate origin, whatever the method: Buckingham's traceless tensor (1/2) sum q (3 r_i r_j - r^2 delta_ij). Programs with another form convert to it.

atomic_charges SerializableVector | None

Partial charge on each atom in units of e, ordered like the structure's atoms. The partitioning scheme (Mulliken, Lowdin, CM5, ...) is the program's; atomic_charges_kind names it.

atomic_charges_kind str | None

The partitioning scheme of atomic_charges: mulliken, lowdin, eeq, eeqbc, cm5, hirshfeld, ...

atomic_spin_populations SerializableVector | None

Alpha minus beta electrons on each atom (e), ordered like the structure's atoms, in the partition atomic_spin_populations_kind names.

atomic_spin_populations_kind str | None

The partitioning scheme of atomic_spin_populations, from the values of atomic_charges_kind; required with them.

atomic_dipoles SerializableMatrix | None

n_atoms x 3: each atom's electronic dipole moment (e bohr) about its own nucleus, mu_A = -sum_{mu on A} (P D^A)_mu,mu with P = P_a + P_b and D^A_nu,mu = , the integrals about the atom of the column AO. Electrons only: no nuclear charge.

atomic_quadrupoles SerializableTensor3D | None

n_atoms x 3 x 3: each atom's electronic quadrupole moment (e bohr^2) about its own nucleus, in Buckingham's traceless form (3/2) M - (1/2) tr(M) I, with M_ij = -sum_{mu on A} (P Q^A_ij)_mu,mu and Q^A_ij the integrals of (r - R_A)_i (r - R_A)_j, as for atomic_dipoles.

shell_populations SerializableVector | None

Electrons in each shell of the basis set, sum_{mu in shell} (P S)_mu,mu with P = P_a + P_b, indexed like wavefunction.basis.shells. Populations, not charges, which depend on method-specific reference occupations.

shell_atoms list[int] | None

The atom (0-based) of each shell of shell_populations, so they stand without a basis set; required with them.

shell_angular_momenta list[int] | None

The angular momentum l of each shell of shell_populations; required with them.

point_charge_gradient SerializableMatrix | None

n_charges x 3 gradient of the energy with respect to the positions of external point charges, in Hartrees/Bohr, ordered like the point charges given to the calculation (QM/MM electrostatic embedding).

energy_components dict[str, float]

Terms of the energy (Hartrees) that add up to energy: a partition, never overlapping terms. Standard keys are listed in the conventions (nuclear_repulsion, one_electron, coulomb, exchange, xc, vv10, dispersion, solvation_electrostatic, solvation_cds, ...); what a component contains is the program's (a tight-binding electronic term is not a DFT one). A hierarchy of sub-terms, if a program has one, belongs in the output's record.

scf_iterations int | None

Number of SCF iterations of the final SCF.

scf_s_squared float | None

Expectation value of S^2 of the SCF reference (dimensionless); S(S+1) for a pure spin state, so the excess is the spin contamination.

polarizability SerializableMatrix | None

3 x 3 static dipole polarizability (e^2 bohr^2 / Hartree).

bond_orders SerializableMatrix | None

n_atoms x n_atoms bond orders, in the form bond_orders_kind names.

bond_orders_kind str | None

mayer (sum (PS)_mn (PS)_nm over the AOs of two atoms, what xtb prints as "Wiberg"), wiberg (in an orthogonalized basis), ...

vibrational_analysis VibrationalAnalysis | None

The harmonic analysis of the Hessian with the choices behind it (masses, projection, symmetry), when the program made one: the home of frequencies and normal modes.

thermochemistry list[Thermochemistry]

Ideal-gas thermochemistry, one entry per temperature and standard state: the home of free energies.

options: members: false

qcdata.OptimizationData

Computed data for an optimization (may be for a minimum or transition state).

Attributes:

Name Type Description
frames list[Frame]

One Frame per structure evaluated, in order, the starting structure first: its structure and what was computed there. An optimization of n steps has n + 1 frames.

energies ndarray

@property The energy of each frame.

structures list[Structure]

@property The structure of each frame.

final_structure Structure | None

@property The last frame's structure: the optimized one when the optimization succeeded, else the last one evaluated.

final_energy float | None

@property The last frame's energy.

final_energy property

final_energy: float | None

The last frame's energy, None without frames, np.nan if not computed.

final_structure property

final_structure: Structure | None

The last frame's structure (the optimized one after a success), or None.

options: members: - structures - final_structure - energies - final_energy - to_xyz - save

qcdata.Frame

One structure inside a larger calculation, with what was computed there.

A step of an optimization, a point of an IRC, an image of a path. It is a ProgramOutput without input_data: the parent calculation's input already holds the program, model, and keywords, so a frame keeps only its structure. ProgramInput.from_spec(parent_spec, frame.structure) rebuilds a step's input.

Attributes:

Name Type Description
structure Structure

The structure of this step.

results SinglePointData

What was computed at it; an empty SinglePointData (with the producing program's provenance) when nothing was.

from_output classmethod

from_output(output: ProgramOutput[Any, Any]) -> Self

Record a subprogram's output as a step, at its input's structure.

Raises:

Type Description
ValidationError

The output's results are not SinglePointData, or its input has no single structure.

Source code in src/qcdata/models/data.py
583
584
585
586
587
588
589
590
591
@classmethod
def from_output(cls, output: ProgramOutput[Any, Any]) -> Self:
    """Record a subprogram's output as a step, at its input's structure.

    Raises:
        ValidationError: The output's results are not `SinglePointData`, or its
            input has no single structure.
    """
    return cls.model_validate(output)

options: members: - from_output

qcdata.PathData

A path of structures through a reaction: an IRC, or a chain of images.

For an IRC the frames run from the end of the reverse branch, through the transition state, to the end of the forward branch. For a chain (NEB, string, growing string) they are the images in order, endpoints included.

Attributes:

Name Type Description
frames list[Frame]

The structures along the path, in order, with what was computed at each.

ts_index int | None

The position of the transition state in frames, if the path has one: the starting saddle point of an IRC, or the highest (climbing) image of a chain.

energies ndarray

@property The energy of each frame.

structures list[Structure]

@property The structure of each frame.

forward_barrier property

forward_barrier: float | None

The transition state's energy above the first frame, in Hartree.

reverse_barrier property

reverse_barrier: float | None

The transition state's energy above the last frame, in Hartree.

transition_state property

transition_state: Frame | None

The frame at ts_index, or None.

options: members: - structures - energies - transition_state - forward_barrier - reverse_barrier - to_xyz - save

qcdata.PathOptimizationData

Computed data for a path optimization (NEB, string, growing string, ...).

Like an optimization's frames, but each step is a whole path. The shared reading interface (structures, energies, to_xyz, save("*.xyz")) reads the final path.

Attributes:

Name Type Description
paths list[PathData]

The path at each iteration, the optimized one last.

final_path PathData | None

@property The last path, or None when there are none.

energies ndarray

@property The energy of each frame of the final path.

structures list[Structure]

@property The structures of the final path.

final_path property

final_path: PathData | None

The optimized (last) path, or None when there are no iterations.

options: members: - final_path - structures - energies - to_xyz

qcdata.ConformerSearchData

Data from a conformer search calculation.

Conformers and rotamers are Frames, sorted by energy (lowest first; frames without an energy last). The shared reading interface (structures, energies, to_xyz, save("*.xyz")) reads the conformers.

Attributes:

Name Type Description
conformers list[Frame]

The conformers found, each with what was computed for it.

rotamers list[Frame]

The rotamers found, each with what was computed for it.

structures list[Structure]

@property The conformers' structures.

energies ndarray

@property The conformers' energies in Hartree, one per conformer, np.nan where none was computed.

conformer_energies ndarray

@property The same as energies.

rotamer_energies ndarray

@property The rotamers' energies, read the same way.

conformer_energies property

conformer_energies: ndarray

The conformers' energies in Hartree, lowest first; np.nan if unknown.

conformer_energies_relative property

conformer_energies_relative: ndarray

Each conformer's energy above the lowest, in Hartree; np.nan if unknown.

rotamer_energies property

rotamer_energies: ndarray

The rotamers' energies in Hartree, lowest first; np.nan if unknown.

rotamer_energies_relative property

rotamer_energies_relative: ndarray

Each rotamer's energy above the lowest, in Hartree; np.nan if unknown.

Wavefunction is documented with the orbitals.

Selecting a scientific data type

Use the shared get_data_type(calctype) lookup rather than maintaining a mapping in parsers or execution packages. It accepts either CalcType or its string value:

from qcdata import get_data_type

results = get_data_type("optimization")(provenance={"program": "geometric"})

File-only execution uses FileData directly. Unknown calculation types raise ValueError.