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. It 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(child_output) records a child calculation as a frame. Passing ProgramOutputs where frames are expected, or loading trajectories saved before frames existed, converts them, taking each step's structure from its input.

Results that hold structures read the same way: structures, energies (nan where none was computed), to_xyz(), and save("x.xyz"). That holds for OptimizationData (one frame per step), PathData, PathOptimizationData (its final path), and ConformerSearchData (its conformers).

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 names OptimizationData.trajectory and ScanData.trajectory are still accepted when constructing or loading and readable as properties, with a FutureWarning. ConformerSearchData still accepts lists of structures with conformer_energies/rotamer_energies arrays, turning each into a frame, and keeps those arrays as properties.

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	dict[str, Any]	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 hessian of the structure in Hartrees/Bohr^2.
nuclear_repulsion_energy	float | None	The nuclear repulsion energy of the structure in Hartrees.
wavefunction	Wavefunction | None	Wavefunction data from the calculation.
freqs_wavenumber	list[float]	Harmonic vibrational frequencies in wavenumbers (cm^-1), negative for imaginary modes.
normal_modes_cartesian	SerializableTensor3D | None	n_vibmodes x n_atoms x 3 array of normal modes, one per entry of freqs_wavenumber and in the same order. Each mode is a Cartesian displacement (not mass-weighted) scaled to unit length, in the input structure's frame and atom order; it is dimensionless. The sign of a mode is arbitrary. Multiplying a mode by the square root of each atom's mass and normalizing gives the eigenvector of the mass-weighted Hessian.
gibbs_free_energy	float | None	Gibbs free energy (i.e. thermochemical analysis) in Hartrees of a system where translation / rotation / vibration degrees of freedom are approximated using ideal gas / rigid rotor / harmonic oscillator respectively.
scf_dipole_moment	list[float] | None	The x, y, z component of the dipole moment of the structure in units of e a0 (NOT Debye!).
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; parsers record it in extras when it is not the program's default.
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).

return_result

return_result(
    calctype: CalcType,
) -> float | SerializableNDArray | None

Return the primary result of the calculation.

Source code in src/qcdata/models/data.py

def return_result(self, calctype: CalcType) -> float | SerializableNDArray | None:
    """Return the primary result of the calculation."""
    return getattr(self, calctype.value)

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 optimizer step: its structure and what was computed there. Formerly trajectory, which is still accepted when constructing or loading and readable as a deprecated property.
energies	ndarray	@property The energy of each step.
structures	list[Structure]	@property The structure of each step.
final_structure	Structure | None	@property The final, optimized structure.

final_energy property

final_energy: float | None

The final step's energy, None for no steps, or np.nan if unavailable.

final_structure property

final_structure: Structure | None

The last evaluated structure, or None when there are no steps.

trajectory property

trajectory: list[Frame]

Deprecated name for frames.

return_result

return_result(calctype: CalcType) -> Structure | None

Return the primary result of the optimization.

Parameters:

Name	Type	Description	Default
calctype	CalcType	The calculation type. Unused; an optimization's primary result is always its final structure.	required

Returns:

Type	Description
Structure | None	The final structure, or None if there are no frames.

Source code in src/qcdata/models/data.py

def return_result(self, calctype: CalcType) -> Structure | None:
    """Return the primary result of the optimization.

    Args:
        calctype: The calculation type. Unused; an optimization's primary result
            is always its final structure.

    Returns:
        The final structure, or None if there are no frames.
    """
    return self.final_structure

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 child calculation'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

@classmethod
def from_output(cls, output: ProgramOutput[Any, Any]) -> Self:
    """Record a child calculation'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.

return_result

return_result(calctype: CalcType) -> list[Structure]

Return the primary result: the structures along the path.

Source code in src/qcdata/models/data.py

def return_result(self, calctype: CalcType) -> list[Structure]:
    """Return the primary result: the structures along the path."""
    return self.structures

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.

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.

energies property

energies: ndarray

The energies of the final path's frames, in Hartree.

final_path property

final_path: PathData | None

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

structures property

structures: list[Structure]

The structures of the final path.

return_result

return_result(calctype: CalcType) -> PathData | None

Return the primary result: the final path.

Source code in src/qcdata/models/data.py

def return_result(self, calctype: CalcType) -> PathData | None:
    """Return the primary result: the final path."""
    return self.final_path

to_xyz

to_xyz() -> str

Return the final path as a multi-structure xyz string.

Source code in src/qcdata/models/data.py

def to_xyz(self) -> str:
    """Return the final path as a multi-structure `xyz` string."""
    return to_multi_xyz(self.structures)

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). Constructing or loading with lists of structures and separate energy arrays (conformer_energies, rotamer_energies), the form before frames, still works: each structure becomes a frame with its energy.

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.
conformer_energies	ndarray	@property The conformers' energies in Hartree.
rotamer_energies	ndarray	@property The rotamers' energies in Hartree.

conformer_energies property

conformer_energies: ndarray

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

conformer_energies_relative property

conformer_energies_relative: ndarray

The relative energies for each conformer in the search.

energies property

energies: ndarray

The conformers' energies in Hartree, lowest first (shared interface).

rotamer_energies property

rotamer_energies: ndarray

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

rotamer_energies_relative property

rotamer_energies_relative: ndarray

The relative energies for each rotamer in the search.

structures property

structures: list[Structure]

The conformers' structures, lowest energy first.

to_xyz

to_xyz() -> str

Return the conformers as a multi-structure xyz string.

Source code in src/qcdata/models/data.py

def to_xyz(self) -> str:
    """Return the conformers as a multi-structure `xyz` string."""
    return to_multi_xyz(self.structures)

qcdata.Wavefunction

The wavefunction for a single point calculation.

Attributes:

Name	Type	Description
scf_eigenvalues_a	SerializableVector | None	The SCF alpha-spin orbital eigenvalues.
scf_eigenvalues_b	SerializableVector | None	The SCF beta-spin orbital eigenvalues.
scf_occupations_a	SerializableVector | None	The SCF alpha-spin orbital occupations.
scf_occupations_b	SerializableVector | None	The SCF beta-spin orbital occupations.

to_numpy classmethod

to_numpy(
    val: ndarray | None, _info: ValidationInfo
) -> ndarray | None

Ensure orbital eigenvalues and occupations are stored as numpy arrays.

Parameters:

Name	Type	Description	Default
val	ndarray | None	The eigenvalue or occupation vector, or None if not provided.	required
_info	ValidationInfo	Pydantic validation context (unused).	required

Returns:

Type	Description
ndarray | None	The value as a numpy array, or None if it was not provided.

Source code in src/qcdata/models/data.py

@field_validator(
    "scf_eigenvalues_a",
    "scf_eigenvalues_b",
    "scf_occupations_a",
    "scf_occupations_b",
)
@classmethod
def to_numpy(
    cls, val: np.ndarray | None, _info: ValidationInfo
) -> np.ndarray | None:
    """Ensure orbital eigenvalues and occupations are stored as numpy arrays.

    Args:
        val: The eigenvalue or occupation vector, or None if not provided.
        _info: Pydantic validation context (unused).

    Returns:
        The value as a numpy array, or None if it was not provided.
    """
    return np.asarray(val) if val is not None else None

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.