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. For a populated trajectory, a failed final step still contributes its evaluated structure, and any available energy is retained. An unavailable energy is nan, independently of execution success.

ScanData defaults to an empty trajectory. 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 = Union[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]	The frequencies of the structure in wavenumbers.
normal_modes_cartesian	SerializableTensor3D | None	3D n_vibmodes x n_atoms x 3 array containing un-mass-weighted Cartesian displacements of each normal mode in Bohr.
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!).

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
energies	ndarray	The energies for each step of the optimization.
structures	list[Structure]	The Structure objects for each step of the optimization.
final_structure	Structure | None	The final, optimized Structure.
trajectory	list[ProgramOutput[ProgramInput, SinglePointData]]	The ProgramOutput objects for each step of the optimization.

energies property

energies: ndarray

The energies for each step of the optimization.

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.

structures property

structures: list[Structure]

The Structure objects for each step of the optimization.

save

save(
    filepath: Path | str,
    exclude_none: bool = True,
    exclude_unset: bool = True,
    indent: int = 4,
    **kwargs: dict[str, Any],
) -> None

Save an OptimizationOutput to a file.

Parameters:

Name	Type	Description	Default
filepath	Path | str	The path to save the molecule to.	required
exclude_none	bool	If True, attributes with a value of None will not be written to the file.	True
exclude_unset	bool	If True, attributes that have not been set will not be written to the file. Defaults to True for compact files.	True
**kwargs	dict[str, Any]	Additional keyword arguments to pass to the json serializer.	{}

Note

If the filepath has a .xyz extension, the trajectory will be saved to a multi-structure xyz file.

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

def save(
    self,
    filepath: Path | str,
    exclude_none: bool = True,
    exclude_unset: bool = True,
    indent: int = 4,
    **kwargs: dict[str, Any],
) -> None:
    """Save an OptimizationOutput to a file.

    Args:
        filepath: The path to save the molecule to.
        exclude_none: If True, attributes with a value of None will not be written
            to the file.
        exclude_unset: If True, attributes that have not been set will not be
            written to the file. Defaults to True for compact files.
        **kwargs: Additional keyword arguments to pass to the json serializer.

    Note:
        If the filepath has a `.xyz` extension, the trajectory will be saved to a
        multi-structure `xyz` file.
    """
    filepath = Path(filepath)
    if filepath.suffix == ".xyz":
        filepath.write_text(self.to_xyz())
        return
    super().save(filepath, exclude_none, exclude_unset, indent, **kwargs)

to_xyz

to_xyz() -> str

Return the trajectory as an xyz string.

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

def to_xyz(self) -> str:
    """Return the trajectory as an `xyz` string."""
    return to_multi_xyz(
        prog_output.input_data.structure for prog_output in self.trajectory
    )

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

qcdata.ConformerSearchData

Data from a conformer search calculation.

Conformers and rotamers are sorted by energy.

Attributes:

Name	Type	Description
conformers	list[Structure]	The conformers found in the search.
conformer_energies	SerializableVector	The energies for each conformer.
rotamers	list[Structure]	The rotamers found in the search.
rotamer_energies	SerializableVector	The energies for each rotamer.

conformer_energies_relative property

conformer_energies_relative: ndarray

The relative energies for each conformer in the search.

rotamer_energies_relative property

rotamer_energies_relative: ndarray

The relative energies for each rotamer in the search.

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.

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.