qrunch.chemistry.molecular_orbital_calculators.mean_field.hartree_fock

Restricted and unrestricted Hartree-Fock (HF) calculators.

Classes

HartreeFockCalculator

A PySCF-based Hartree-Fock mean field calculator.

HartreeFockCalculatorOptions

Default options for the Hartree-Fock (HF) calculator.

RestrictedHartreeFockCalculator

A restricted Hartree-Fock mean field calculator.

UnrestrictedHartreeFockCalculator

A based unrestricted Hartree-Fock mean field calculator.
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) → UnrestrictedElectronPotential
effective_potential(molecular_configuration: MolecularConfiguration, density_operator: RestrictedDensityOperator) → 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:
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, additional_potential: UnrestrictedElectronPotential | None = None) → float
total_energy(molecular_configuration: MolecularConfiguration, density_operator: RestrictedDensityOperator, additional_potential: 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:
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 HartreeFockCalculatorOptions

Bases: DataclassPublicAPI

Default options for the Hartree-Fock (HF) calculator.

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

Parameters:

  • convergence_tolerance – Energy convergence tolerance (default=1e-9)

  • convergence_tolerance_gradient – Gradient convergence tolerance (default=3.1622776601683795e-05)

  • initial_guess – Minimal atomic orbital guess. See https://pyscf.org/user/scf.html#initial-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__(*, convergence_tolerance: float = 1e-09, convergence_tolerance_gradient: float = 3.1622776601683795e-05, 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:

  • convergence_tolerance (float)

  • convergence_tolerance_gradient (float)

  • 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

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',)
get_number_of_electrons_from_initial_guess: bool = False
initial_guess: Literal['minao', '1e', 'atom', 'huckel', 'vsap', 'chk'] | str = 'minao'
level_shift: float = 0.0
max_iterations: int = 50
verbose: int = 0
class RestrictedHartreeFockCalculator

Bases: object

A restricted 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: RestrictedDensityOperator) → 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 (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:

RestrictedElectronPotential

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

Solve the Hartree-Fock.

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

total_energy(molecular_configuration: MolecularConfiguration, density_operator: RestrictedDensityOperator, additional_potential: 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 (RestrictedDensityOperator) – The density matrix for which the energy is calculated.

  • additional_potential (RestrictedElectronPotential | None) – Additional potential added to the single electron hamiltonian. Defaults to None.

  • solvent_wrapper – A solvent wrapper that determines how the kernel is executed.

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 UnrestrictedHartreeFockCalculator

Bases: object

A based unrestricted 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) → UnrestrictedElectronPotential

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:
Raises:

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

Return type:

UnrestrictedElectronPotential

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

Run the Hartree-Fock calculator.

Parameters:
Return type:

UnrestrictedMolecularOrbitalCalculatorResult

total_energy(molecular_configuration: MolecularConfiguration, density_operator: UnrestrictedDensityOperator, additional_potential: UnrestrictedElectronPotential | 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:
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