qrunch.chemistry.molecule.molecular_configuration

Module with the definition of a molecular configuration.

Module Attributes

DEFAULT_BASIS

Sentinel key used in a basis set dictionary to specify the default basis set for atoms not explicitly listed.

Functions

`basis_set_to_lines`(basis_set)	Format a dict-style basis set as a list of per-entry, aligned lines.
`basis_set_to_string`(basis_set)	Format a basis set specification as a human-readable string.
`log_basis_set`(header, basis_set[, ...])	Log a basis set specification at INFO level.
`select_aux_basis_from_orbital_basis`(basis_set)	Select an appropriate auxiliary basis set for density fitting based on the orbital basis set.
`to_basis_set`(basis_input)	Convert user-friendly basis set input to the internal format.

Classes

MolecularConfiguration

Describes a molecular configuration of a molecule.

DEFAULT_BASIS = <qrunch.chemistry.molecule.molecular_configuration._DefaultBasisKey object>

Sentinel key used in a basis set dictionary to specify the default basis set for atoms not explicitly listed.

Example:

# Use cc-pVDZ for all atoms, but 3-21G specifically for carbon
config = MolecularConfiguration(
    molecule=my_molecule,
    basis_set={
        DEFAULT_BASIS: BasisSet.CCPVDZ,
        Atom("C"): BasisSet.POPLE_321G,
    },
)

class MolecularConfiguration

Bases: object

Describes a molecular configuration of a molecule.

Initialize a molecular configuration.

Parameters:

molecule (Molecule) – Molecule to specify configuration for.
basis_set (BasisSet | dict[Atom, BasisSet] | dict[Atom | _DefaultBasisKey, BasisSet]) –
Basis set to use for the atoms types in the molecule. Can be specified as:
- A single BasisSet to use for all atoms.
- A dictionary mapping Atom to BasisSet for element-specific basis sets. Use DEFAULT_BASIS as a key to specify a default basis set for any atoms not explicitly listed in the dictionary.
charge (int) – Overall charge of the molecule.
spin_difference (int) – Difference between the number of spin up and spin down electrons (default: 0).
embedded_atoms (Sequence[int] | None) – Optional field describing which atoms are embedded.
solvent (Solvent | None) – Solvent for the molecular configuration to be embedded in.
aux_basis_set (BasisSet | dict[Atom, BasisSet] | dict[Atom | _DefaultBasisKey, BasisSet] | str | None) – Auxiliary basis set, used for density fitting. Can be specified in the same way as basis_set. The default is that the auxiliary basis set will be automatically selected based on the orbital basis set (e.g., cc-pVDZ → cc-pVDZ-RI). If no tailor-made auxiliary basis set can be found for the orbital basis set, then the auxiliary basis set will be auto-generated. “AutoAux” can be used as a string value to explicitly specify that the auxiliary basis set should be auto-generated.

Return type:

None

atom_to_atomic_orbital_indices_map() → dict[int, tuple[int, int]]

Return a map from the atom index to the start and end atomic orbital index.

Return type:: dict[int, tuple[int, int]]

auto_aux_basis_set() → Any

Auto Generate Auxiliary Basis set for the configuration.

Return type:: Any

property aux_basis_set: dict[Atom, BasisSet] | None: Auxiliary Basis set for the configuration.

property basis_set: dict[Atom, BasisSet]: Basis set for the configuration.

property charge: int: Charge of the configuration.

core_hamiltonian() → ndarray[tuple[Any, ...], dtype[float64]]

Return core hamiltonian in atomic basis.

Return type:: ndarray[tuple[Any, …], dtype[float64]]

embedded_atoms_string() → str

Provide a human-readable string representation for the embedded atoms.

Return type:: str

property molecule: Molecule: Molecule for the configuration.

nuclear_repulsion_energy() → float

Calculate the nuclear repulsion energy of the atoms in the molecule.

Return type:: float

number_of_alpha_electrons() → int

Calculate number of alpha electrons.

Return type:: int

number_of_atomic_orbitals() → int

Return the number of atomic orbitals.

Return type:: int

number_of_beta_electrons() → int

Calculate number of beta electrons.

Return type:: int

number_of_electrons() → int

Calculate the total number of electrons on the molecule.

Return type:: int

number_of_spatial_orbitals() → int

Calculate the number of spatial orbitals.

Return type:: int

overlap_matrix() → ndarray[tuple[Any, ...], dtype[float64]]

Return the atomic orbital overlap matrix.

Return type:: ndarray[tuple[Any, …], dtype[float64]]

property pyscf_molecule: Mole: Get the PySCF molecule.

property spin_difference: int: Spin of the configuration.

update_spin_and_charge(new_spin_difference: int, new_charge: int) → None

Update both spin_difference and charge at the same time.

If both spin_difference and charge are changed separately, the intermediate molecule might fail validation. To avoid this, this method can be used instead.

Parameters:

new_spin_difference (int) – new spin_difference to be set on the molecule.
new_charge (int) – new charge to be set on the molecule.

Return type:

None

basis_set_to_lines(basis_set: dict[Atom, BasisSet] | dict[Atom | _DefaultBasisKey, BasisSet]) → list[str]

Format a dict-style basis set as a list of per-entry, aligned lines.

Each line is indented by four spaces with the symbol right-aligned to the width of the longest symbol so values line up vertically. Lines contain no trailing commas or newlines so callers can join them or emit one log line per entry.

Parameters:: basis_set (dict[Atom, BasisSet] | dict[Atom | _DefaultBasisKey, BasisSet]) – The dict-style basis set specification to format.
Return type:: list[str]

basis_set_to_string(basis_set: BasisSet | dict[Atom, BasisSet] | dict[Atom | _DefaultBasisKey, BasisSet] | None) → str

Format a basis set specification as a human-readable string.

For None or a single BasisSet value a one-line string is returned. For a dict-style basis set the entries are joined into a multi-line string with each symbol right-aligned to the width of the longest symbol.

Parameters:: basis_set (BasisSet | dict[Atom, BasisSet] | dict[Atom | _DefaultBasisKey, BasisSet] | None) – The basis set specification to format.
Return type:: str

log_basis_set(header: str, basis_set: BasisSet | dict[Atom, BasisSet] | dict[Atom | _DefaultBasisKey, BasisSet] | None, indentation_width: int = 4) → None

Log a basis set specification at INFO level.

For None or a single BasisSet, the header and value are logged on the same line. For a dict-style basis set, the header is logged first and each entry is logged on its own line so the logging framework prefixes every line with its usual timestamp and level.

Parameters:

header (str) – Text printed before the basis set value (e.g. "Density-fitting basis set:").
basis_set (BasisSet | dict[Atom, BasisSet] | dict[Atom | _DefaultBasisKey, BasisSet] | None) – The basis set specification to log.
indentation_width (int) – Adds indentation to the log message.

Return type:

None

Select an appropriate auxiliary basis set for density fitting based on the orbital basis set.

Parameters:: basis_set (BasisSet | dict[Atom, BasisSet] | dict[Atom | _DefaultBasisKey, BasisSet]) – The basis set specification from the user.
Return type:: BasisSet | dict[Atom | _DefaultBasisKey, BasisSet] | None

Convert user-friendly basis set input to the internal format.

Parameters:: basis_input (str | Literal['sto-3g', '3-21g', '6-31g', '6-31g*', 'def2-svp', 'def2-tzvp', 'def2-tzvpp', 'cc-pvdz', 'cc-pvtz', 'cc-pvqz', 'aug-cc-pvdz', 'aug-cc-pvtz', 'aug-cc-pvqz', 'pc-0', 'pc-1', 'pc-2', 'pc-seg-0', 'pc-seg-1', 'pc-seg-2', 'weigend'] | ~qrunch.chemistry.molecule.basis_sets.BasisSet | ~collections.abc.Mapping[~qrunch.chemistry.molecule.atom.Atom, ~qrunch.chemistry.molecule.basis_sets.BasisSet | str] | ~collections.abc.Mapping[str, ~qrunch.chemistry.molecule.basis_sets.BasisSet | str] | ~collections.abc.Mapping[~qrunch.chemistry.molecule.atom.Atom | str, ~qrunch.chemistry.molecule.basis_sets.BasisSet | str]) – Basis set specification from the user.
Return type:: BasisSet | dict[Atom | _DefaultBasisKey, BasisSet]