qrunch.chemistry.molecular_orbital_calculators.mean_field

Module containing PyScf solvers employing mean-field methods.

Classes

MeanFieldCalculatorSubCreator

Mean-field calculator sub-creator.

class DftCalculator

Bases: MeanFieldCalculator

An unrestricted density functional theory calculator.

__init__(options: DftCalculatorOptions = DftCalculatorOptions(functional='b3lyp', convergence_tolerance=1e-09, convergence_tolerance_gradient=3.1622776601683795e-05, grid_level=3, initial_guess='minao', max_iterations=50, level_shift=0.0, verbose=0, get_number_of_electrons_from_initial_guess=False, fallback_options=('SOSCF',), do_density_fitting=False)) → None

Initialize the DFT calculator.

Parameters:: options (DftCalculatorOptions) – DFT calculator options.
Return type:: None

effective_potential(molecular_configuration: MolecularConfiguration, density_operator: UnrestrictedDensityOperator | RestrictedDensityOperator) → UnrestrictedElectronPotential | RestrictedElectronPotential

Compute the effective potential matrix for a given density matrix.

The effective potential includes the Coulomb and exchange interactions. It is used in constructing the Fock matrix in self-consistent field calculations.

Parameters:

molecular_configuration (MolecularConfiguration) – The molecular configuration.
density_operator (UnrestrictedDensityOperator | RestrictedDensityOperator) – The density operator.
solvent_wrapper – A solvent wrapper that determines how the kernel is executed.

Raises:

ValueError – If the density matrix is not square with a size equal to the number of atomic orbitals.

Return type:

UnrestrictedElectronPotential | RestrictedElectronPotential

solve_restricted(molecular_configuration: MolecularConfiguration, initial_guess: RestrictedDensityOperator | None = None, additional_potential: RestrictedElectronPotential | None = None) → RestrictedMolecularOrbitalCalculatorResult

Run the restricted DFT calculation.

Parameters:

molecular_configuration (MolecularConfiguration) – Input molecule configuration.
initial_guess (RestrictedDensityOperator | None) – Initial guess for the density matrix. The number of electrons is inferred from this guess.
None. (Default to)
additional_potential (RestrictedElectronPotential | None) – Additional potential added to the single electron hamiltonian. Defaults to None.

Return type:

RestrictedMolecularOrbitalCalculatorResult

solve_unrestricted(molecular_configuration: MolecularConfiguration, initial_guess: UnrestrictedDensityOperator | None = None, additional_potential: UnrestrictedElectronPotential | None = None) → UnrestrictedMolecularOrbitalCalculatorResult

Run the unrestricted DFT calculation.

Parameters:

molecular_configuration (MolecularConfiguration) – Input molecule configuration.
initial_guess (UnrestrictedDensityOperator | None) – Initial guess for the density matrix. The number of electrons is inferred from this guess.
None. (Default to)
additional_potential (UnrestrictedElectronPotential | None) – Additional potential added to the single electron hamiltonian. Defaults to None.

Return type:

UnrestrictedMolecularOrbitalCalculatorResult

total_energy(molecular_configuration: MolecularConfiguration, density_operator: UnrestrictedDensityOperator | RestrictedDensityOperator, additional_potential: UnrestrictedElectronPotential | RestrictedElectronPotential | None = None) → float

Calculate total energy of a molecular configuration for an electronic configuration given by a density matrix.

The additional potential, if given, is used to calculate an additional potential energy which is added to the final result.

Parameters:

molecular_configuration (MolecularConfiguration) – The molecular configuration.
density_operator (UnrestrictedDensityOperator | RestrictedDensityOperator) – The density matrix for which the energy is calculated.
additional_potential (UnrestrictedElectronPotential | RestrictedElectronPotential | None) – Additional potential added to the single electron hamiltonian. Defaults to None.

Raises:

ValueError – If the density matrix, or the supplied additional potential is not square with a size equal to the number of atomic orbitals.

Return type:

float

class DftCalculatorOptions

Bases: DataclassPublicAPI

Default options for the DFT calculator.

For details, see https://pyscf.org/user/dft.html. Options controlling DftCalculator. All fields are immutable (frozen=True) so an instance can be safely reused.

Parameters:

functional – Default functional (default=”b3lyp”)
convergence_tolerance – Energy convergence tolerance (default=1e-9)
convergence_tolerance_gradient – Gradient convergence tolerance (default=3.1622776601683795e-05)
grid_level – Default grid level (default=3)
initial_guess – Minimal atomic orbital guess (default=”minao”)
max_iterations – Maximum number of SCF iterations (default=50)
level_shift – Energy level shift (default=0.0)
verbose – Verbosity level (default=0)
get_number_of_electrons_from_initial_guess – If true, the number of electrons in the initial guess will always overwrite the number of electrons in the molecular configuration. (default=False)
fallback_options – Fallback options in case default SCF settings fail to converge.
do_density_fitting – Utilize density fitting (default=False)

__init__(*, functional: str = 'b3lyp', convergence_tolerance: float = 1e-09, convergence_tolerance_gradient: float = 3.1622776601683795e-05, grid_level: int = 3, initial_guess: Literal['minao', '1e', 'atom', 'huckel', 'vsap', 'chk'] | str = 'minao', max_iterations: int = 50, level_shift: float = 0.0, verbose: int = 0, get_number_of_electrons_from_initial_guess: bool = False, fallback_options: tuple[Literal['SOSCF', 'LevelShift(0.1)']] = ('SOSCF',), do_density_fitting: bool = False) → None

Parameters:

functional (str)
convergence_tolerance (float)
convergence_tolerance_gradient (float)
grid_level (int)
initial_guess (Literal['minao', '1e', 'atom', 'huckel', 'vsap', 'chk'] | str)
max_iterations (int)
level_shift (float)
verbose (int)
get_number_of_electrons_from_initial_guess (bool)
fallback_options (tuple[Literal['SOSCF', 'LevelShift(0.1)']])
do_density_fitting (bool)

Return type:

None

static __new__(cls, *args: Any, **kwargs: Any) → Any

Parameters:

args (Any)
kwargs (Any)

Return type:

Any

convergence_tolerance: float = 1e-09

convergence_tolerance_gradient: float = 3.1622776601683795e-05

do_density_fitting: bool = False

fallback_options: tuple[Literal['SOSCF', 'LevelShift(0.1)']] = ('SOSCF',)

functional: str = 'b3lyp'

get_number_of_electrons_from_initial_guess: bool = False

grid_level: int = 3

initial_guess: Literal['minao', '1e', 'atom', 'huckel', 'vsap', 'chk'] | str = 'minao'

level_shift: float = 0.0

max_iterations: int = 50

verbose: int = 0

class HartreeFockCalculator

Bases: MeanFieldCalculator

A PySCF-based Hartree-Fock mean field calculator.

__init__(options: HartreeFockCalculatorOptions = HartreeFockCalculatorOptions(convergence_tolerance=1e-09, convergence_tolerance_gradient=3.1622776601683795e-05, initial_guess='minao', max_iterations=50, level_shift=0.0, verbose=0, get_number_of_electrons_from_initial_guess=False, fallback_options=('SOSCF',), do_density_fitting=False)) → None

Initialize the Hartree-Fock calculator.

Parameters:: options (HartreeFockCalculatorOptions) – options for the Hartree-Fock calculator.
Return type:: None

effective_potential(molecular_configuration: MolecularConfiguration, density_operator: UnrestrictedDensityOperator | RestrictedDensityOperator) → UnrestrictedElectronPotential | RestrictedElectronPotential

Compute the effective potential matrix for a given density matrix.

The effective potential includes the Coulomb and exchange interactions. It is used in constructing the Fock matrix in self-consistent field calculations.

Parameters:

molecular_configuration (MolecularConfiguration) – The molecular configuration.
density_operator (UnrestrictedDensityOperator | RestrictedDensityOperator) – The density operator.
solvent_wrapper – A solvent wrapper that determines how the kernel is executed.

Raises:

ValueError – If the density matrix is not square with a size equal to the number of atomic orbitals.

Return type:

UnrestrictedElectronPotential | RestrictedElectronPotential

solve_restricted(molecular_configuration: MolecularConfiguration, initial_guess: RestrictedDensityOperator | None = None, additional_potential: RestrictedElectronPotential | None = None) → RestrictedMolecularOrbitalCalculatorResult

Run the restricted Hartree-Fock calculation.

Parameters:

molecular_configuration (MolecularConfiguration) – Input molecule configuration.
initial_guess (RestrictedDensityOperator | None) – Initial guess for the density matrix. The number of electrons is inferred from this guess. Defaults to None.
additional_potential (RestrictedElectronPotential | None) – Additional potential added to the single electron hamiltonian. Defaults to None.

Return type:

RestrictedMolecularOrbitalCalculatorResult

solve_unrestricted(molecular_configuration: MolecularConfiguration, initial_guess: UnrestrictedDensityOperator | None = None, additional_potential: UnrestrictedElectronPotential | None = None) → UnrestrictedMolecularOrbitalCalculatorResult

Run the unrestricted Hartree-Fock calculation.

Parameters:

molecular_configuration (MolecularConfiguration) – Input molecule configuration.
initial_guess (UnrestrictedDensityOperator | None) – Initial guess for the density matrix. The number of electrons is inferred from this guess. Defaults to None.
additional_potential (UnrestrictedElectronPotential | None) – Additional potential added to the single electron hamiltonian. Defaults to None.

Return type:

UnrestrictedMolecularOrbitalCalculatorResult

total_energy(molecular_configuration: MolecularConfiguration, density_operator: UnrestrictedDensityOperator | RestrictedDensityOperator, additional_potential: UnrestrictedElectronPotential | RestrictedElectronPotential | None = None) → float

Calculate total energy of a molecular configuration for an electronic configuration given by a density matrix.

The additional potential, if given, is used to calculate an additional potential energy which is added to the final result.

Parameters:

molecular_configuration (MolecularConfiguration) – The molecular configuration.
density_operator (UnrestrictedDensityOperator | RestrictedDensityOperator) – The density matrix for which the energy is calculated.
additional_potential (UnrestrictedElectronPotential | RestrictedElectronPotential | None) – Additional potential added to the single electron hamiltonian. Defaults to None.

Raises:

ValueError – If the density matrix, or the supplied additional potential is not square with a size equal to the number of atomic orbitals.

Return type:

float

Modules

`density_functional_theory`	Wrapper around the PySCF density functional theory (DFT) calculator.
`hartree_fock`	Restricted and unrestricted Hartree-Fock (HF) calculators.
`mean_field_protocols`	Contains the interface for the mean-field chemistry calculators.
`mean_field_utils`	Utility methods for mean-field calculators.