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.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 |
gradient |
SerializableMatrix | None
|
The gradient of the structure in |
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 |
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 |
str | None
|
The partitioning scheme of |
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 |
str | None
|
The partitioning scheme of
|
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 = |
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 |
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
|
shell_atoms |
list[int] | None
|
The atom (0-based) of each shell of |
shell_angular_momenta |
list[int] | None
|
The angular momentum l of each shell of
|
point_charge_gradient |
SerializableMatrix | None
|
n_charges x 3 gradient of the energy with respect
to the positions of external point charges, in |
energy_components |
dict[str, float]
|
Terms of the energy (Hartrees) that add up to |
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 |
str | None
|
|
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 |
energies |
ndarray
|
|
structures |
list[Structure]
|
|
final_structure |
Structure | None
|
|
final_energy |
float | 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 |
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 |
Source code in src/qcdata/models/data.py
583 584 585 586 587 588 589 590 591 | |
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 |
energies |
ndarray
|
|
structures |
list[Structure]
|
|
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
|
|
energies |
ndarray
|
|
structures |
list[Structure]
|
|
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]
|
|
energies |
ndarray
|
|
conformer_energies |
ndarray
|
|
rotamer_energies |
ndarray
|
|
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.