Results

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

qcio.Results

The core results 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.
data	DataType	The data from the calculation. Contains parsed values and files. Any of qcio.Data.
logs	str | None	The logs 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 results. Use for schema development and scratch space.
plogs	str	@property Print the logs.
ptraceback	str	@property Print the traceback.

files property

files: dict[str, str | bytes]

Return the files attribute.

plogs property

plogs: None

Print the logs

pstdout property

pstdout: None

Print the logs

ptraceback property

ptraceback: None

Print the traceback

results property

results: DataType

Return the data attribute.

return_result property

return_result: (
    float | SerializableNDArray | Structure | None
)

Return the primary result of the calculation.

stdout property

stdout: str | None

Backwards compatibility for .stdout attribute.

options: members: false

Data

qcio.Data module-attribute

Data = Union[Files, StructuredData]

qcio.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	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 src/qcio/models/results.py

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

options: members: false

qcio.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	The final, optimized Structure.
trajectory	list[Results[ProgramInput, SinglePointData] | Results[ProgramInput, Files]]	The Results 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 energy in the optimization. Is np.nan if final calculation failed.

final_structure property

final_structure: Structure

The final Structure in the optimization.

structures property

structures: 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 src/qcio/models/results.py

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

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 src/qcio/models/results.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)

to_xyz

to_xyz() -> str

Return the trajectory as an xyz string.

Source code in src/qcio/models/results.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

qcio.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	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 = 1.0, **rmsd_kwargs
) -> tuple[list[Structure], SerializableNDArray]

Moved since qcio 0.15.0

This convenience method has moved to [qcinf.filter_conformers][] and this stub will be removed from qcio in a future release.

from qcinf import filter_conformers

filtered_csr = filter_conformers(
    conformers=csr
    threshold=1.0,          # Bohr
    backend="qcinf",      # or "rdkit",
    **rmsd_kwargs,
)

Source code in src/qcio/models/results.py

def conformers_filtered(
    self,
    threshold: float = 1.0,
    **rmsd_kwargs,
) -> tuple[list[Structure], SerializableNDArray]:
    """
    !!! warning "Moved since *qcio* 0.15.0"
        This convenience method has moved to
        [`qcinf.filter_conformers`][qcinf.filter_conformers]
        and this stub will be **removed** from *qcio* in a future release.

        ```python
        from qcinf import filter_conformers

        filtered_csr = filter_conformers(
            conformers=csr
            threshold=1.0,          # Bohr
            backend="qcinf",      # or "rdkit",
            **rmsd_kwargs,
        )
        ```
    """

    warnings.warn(
        "`ConformerSearchResults.conformers_filtered()` is deprecated. "
        "Install *qcinf* and use `qcinf.filter_conformers` instead.",
        DeprecationWarning,
        stacklevel=2,
    )
    raise NotImplementedError(
        "Method removed.  Replace with:\n\n"
        "    from qcinf import filter_conformers\n\n"
        "    filtered_csr = filter_conformers(\n"
        "        prog_output.results,\n"
        "        threshold=1.0,\n"
        "        backend='qcinf',\n"
        "        **rmsd_kwargs\n"
        "    )"
    )

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.