Outputs

ProgramOutput is the core object that captures all information from a QC calculation including all input data, the computed values and files (collectively called Results), and additional metadata such as stdout and Provenance information. The .results attribute will correspond to the CalcType requested, e.g., a SinglePointResults, OptimizationsResults, etc.

qcio.ProgramOutput

ProgramOutput(**data: Any)

The core output object from a quantum chemistry calculation.

Attributes:

Name	Type	Description
input_data	InputType	The input data for the calculation. Any of qcio.Inputs.
success	Literal[True, False]	Whether the calculation was successful.
results	ResultsType	The results of the calculation. Contains parsed values and files. Any of qcio.Results.
stdout	str | None	The standard output from the calculation.
traceback	str | None	The traceback from the calculation, if it failed.
provenance	Provenance	The provenance information for the calculation.
extras	Dict[str, Any]	Additional information to bundle with the object. Use for schema development and scratch space.
pstdout	str	@property Print the stdout text.
ptraceback	str	@property Print the traceback text.

Source code in qcio/models/outputs.py

def __init__(self, **data: Any):
    """Backwards compatibility for files attribute."""

    if "files" in data:
        warnings.warn(
            "The 'files' attribute has been moved to 'results.files'. Please "
            "update your code accordingly.",
            category=FutureWarning,
            stacklevel=2,
        )

        # This moves files from the top level to the results attribute
        if isinstance(data["results"], dict):
            results_files_dict = data["results"].get("files", {})
        else:  # data["results"] is Files, SinglePointResults, OptimizationResults
            results_files_dict = data["results"].files

        results_files_dict.update(**data.pop("files"))

    super().__init__(**data)

Results

qcio.Results module-attribute

Results = Union[Files, SinglePointResults, OptimizationResults, ConformerSearchResults]

qcio.SinglePointResults

The computed results from a single point calculation.

Attributes:

Name	Type	Description
calcinfo_natoms	int | None	The number of atoms as computed by the program.
calcinfo_nalpha	int | None	The number of alpha electrons as computed by the program.
calcinfo_nbeta	int | None	The number of beta electrons as computed by the program.
calcinfo_nbasis	int | None	The number of basis functions in the calculation.
calcinfo_nmo	int | None	The number of molecular orbitals in the calculation.
energy	float | None	The electronic energy of the structure in Hartrees.
gradient	SerializableNDArray | None	The gradient of the structure in Hartrees/Bohr.
hessian	SerializableNDArray | 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	SerializableNDArray | None	3D n_vibmodes x n_atoms x 3 array containing un-mass-weighted Cartesian displacements of each normal mode.
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!).

qcio.OptimizationResults

Computed properties for an optimization.

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	The final, optimized Structure.
trajectory	list[ProgramOutput[ProgramInput, SinglePointResults] | ProgramOutput[ProgramInput, Files]]	The SinglePointOutput objects for each step of the optimization.

structures property

structures: list[Structure]

The Structure objects for each step of the optimization.

final_structure property

final_structure: Structure

The final Structure in the optimization.

energies property

energies: ndarray

The energies for each step of the optimization.

final_energy property

final_energy: float | None

The final energy in the optimization. Is np.nan if final calculation failed.

to_xyz

to_xyz() -> str

Return the trajectory as an xyz string.

Source code in qcio/models/outputs.py

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

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.	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 qcio/models/outputs.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.
        **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)

qcio.ConformerSearchResults

Results 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	SerializableNDArray	The energies for each conformer.
rotamers	list[Structure]	The rotamers found in the search.
rotamer_energies	SerializableNDArray	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.

conformers_filtered

conformers_filtered(threshold: float = 0.5, **rmsd_kwargs) -> tuple[list[Structure], SerializableNDArray]

Filter conformers to only unique Structures within rmsd of threshold.

Parameters:

Name	Type	Description	Default
threshold	float	The RMSD threshold in Angstrom for filtering conformers.	0.5
**rmsd_kwargs		Additional keyword arguments to pass to the rmsd function.	{}

Returns:

Type	Description
tuple[list[Structure], SerializableNDArray]	Tuple of the filtered conformers and their relative energies.

Source code in qcio/models/outputs.py

def conformers_filtered(
    self, threshold: float = 0.5, **rmsd_kwargs
) -> tuple[list[Structure], SerializableNDArray]:
    """Filter conformers to only unique Structures within rmsd of `threshold`.

    Args:
        threshold: The RMSD threshold in Angstrom for filtering conformers.
        **rmsd_kwargs: Additional keyword arguments to pass to the rmsd function.

    Returns:
        Tuple of the filtered conformers and their relative energies.
    """
    filtered = set()

    for i in range(len(self.conformers)):
        if i not in filtered:
            for j in range(i + 1, len(self.conformers)):
                if (
                    rmsd(self.conformers[i], self.conformers[j], **rmsd_kwargs)
                    < threshold
                ):
                    filtered.add(j)

    keep_indices = [i for i in range(len(self.conformers)) if i not in filtered]
    return [
        self.conformers[i] for i in keep_indices
    ], self.conformer_energies_relative[keep_indices]

qcio.Wavefunction

The wavefunction for a single point calculation.

Attributes:

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