ProgramOutput

More extensive documentation is available at https://qcio.coltonhicks.com.

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

pstdout property

pstdout: None

Print the stdout text

ptraceback property

ptraceback: None

Print the traceback text

files property

files: dict[str, str | bytes]

Return the files attribute.

return_result property

return_result: (
    float | SerializableNDArray | Structure | None
)

Return the primary result of the calculation.

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

Return the primary result of the calculation.

Source code in qcio/models/outputs.py

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

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

final_structure property

final_structure: Structure

The final Structure in the optimization.

final_energy property

final_energy: float | None

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

energies property

energies: ndarray

The energies for each step of the optimization.

structures property

structures: list[Structure]

The Structure objects for each step of the optimization.

molecules property

molecules: list[Structure]

The Structure objects for each step of the optimization.

return_result

return_result(calctype: CalcType) -> Structure | None

Return the primary result of the calculation.

Source code in qcio/models/outputs.py

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

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 to_multi_xyz(
        prog_output.input_data.structure 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.models.outputs.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]