qrunch.chemistry.reaction_path_problem

Functionality for defining and solving reaction path problems.

class ActiveSpaceElectronConfiguration

Bases: object

Active space electron configuration.

All fields are immutable (frozen=True) so an instance can be safely reused.

Parameters:

  • number_of_active_spatial_orbitals – The number of spatial orbitals in the active space.

  • number_of_active_alpha_electrons – The number of alpha electrons in the active space.

__init__(number_of_active_spatial_orbitals: int, number_of_active_alpha_electrons: int) → None
Parameters:

  • number_of_active_spatial_orbitals (int)

  • number_of_active_alpha_electrons (int)

Return type:

None

number_of_active_alpha_electrons: int
number_of_active_spatial_orbitals: int
class ActiveSpaceGroundStateProblemModifier

Bases: GroundStateProblemModifier

A Active space (AS) ground state problem modifier.

__init__(active_space_electron_configuration: ActiveSpaceElectronConfiguration) → None

Initialize a ActiveSpaceGroundStateProblemModifier.

The ActiveSpaceGroundStateProblemModifier modify an existing ground state problem to account for a active space (AS) calculation. It does so by creating a new ground state problem with a well-defined active space. This means that the integrals only include contributions from the active orbitals and the core hamiltonian is replaced by the inactive Fock matrix, which includes contributions from the inactive orbitals.

The new ground state problem include the inactive energy contribution, which is a constant energy arising from the inactive orbitals.

Parameters:

active_space_electron_configuration (ActiveSpaceElectronConfiguration) – The active space configuration to use in the builder.

Return type:

None

modify(problem: RestrictedGroundStateProblem | UnrestrictedGroundStateProblem) → RestrictedGroundStateProblem | UnrestrictedGroundStateProblem

Calculate the inactive Fock matrices and return the active space integrals.

The inactive Fock matrices include contributions from the inactive orbitals and are used in the Active Space (AS) calculation to account for interactions between active and inactive orbitals.

Parameters:

problem (RestrictedGroundStateProblem | UnrestrictedGroundStateProblem) – The ground state problem to modify.

Return type:

RestrictedGroundStateProblem | UnrestrictedGroundStateProblem

classmethod short_name() → str

Provide a short name for logging purposes.

Return type:

str

class ConfigurationInteractionReactionPathProblemCalculator

Bases: object

Class for performing full configuration interaction calculations on reactions.

__init__() → None

Initialize instance of the full configuration interaction calculator for reaction path problems.

Return type:

None

calculate(reaction_path_problem: RestrictedReactionPathProblem | UnrestrictedReactionPathProblem) → ReactionPathProblemCalculatorResult

Solve the configuration interaction (FCI or CASCI) calculation.

The FCI/CASCI energy is calculated for every geometry along the reaction path using the FCI/CASCI ground state problem calculator.

The Hamiltonian for all geometries are assumed to be real.

Parameters:

reaction_path_problem (RestrictedReactionPathProblem | UnrestrictedReactionPathProblem) – The reaction path problem to solve.

Return type:

ReactionPathProblemCalculatorResult

class EvenHandedRestrictedReactionPathProblemBuilder

Bases: object

Restricted reaction path problem builder which uses the even-handed subsystem selection method.

The Even-handed subsystem selection is described in https://doi.org/10.1063/1.5050533.

__init__(full_system_solver: MeanFieldCalculator, embedded_orbital_calculator: MolecularOrbitalCalculator, localizer: OrbitalLocalizer, orbital_assigner: OrbitalAssigner, projector_builder: ManbysLevelShiftProjectorBuilder, data_persister_manager: DataPersisterManager | None = None, problem_modifiers: list[GroundStateProblemModifier] | None = None, cube_generator: ProjectiveEmbeddingCubeGenerator | None = None, repulsion_integral_builder: TwoBodyElectronRepulsionIntegralBuilderProtocol | None = None) → None

Initialize an even-handed reaction path problem builder.

Parameters:
Return type:

None

build(reaction_configuration: ReactionConfiguration) → RestrictedReactionPathProblem

Build the reaction path problem.

This method uses the Even-handed subsystem selection as described in https://doi.org/10.1063/1.5050533.

Parameters:

reaction_configuration (ReactionConfiguration) – The reaction configuration object.

Return type:

RestrictedReactionPathProblem

build_cube_files(reaction_configuration: ReactionConfiguration) → None

Build cube files.

Parameters:

reaction_configuration (ReactionConfiguration) – The reaction configuration object.

Return type:

None

classmethod persistence_checkpoints() → list[str]

Define the persistence checkpoints used during the embedding process.

These checkpoints specify computational stages where intermediate results can be saved and loaded to optimize computations and ensure reproducibility.

Return type:

list[str]

class EvenHandedUnrestrictedReactionPathProblemBuilder

Bases: object

Unrestricted reaction path problem builder which uses the even-handed subsystem selection method.

The Even-handed subsystem selection is described in https://doi.org/10.1063/1.5050533.

__init__(full_system_solver: MeanFieldCalculator, embedded_orbital_calculator: MolecularOrbitalCalculator, localizer: OrbitalLocalizer, orbital_assigner: OrbitalAssigner, projector_builder: ManbysLevelShiftProjectorBuilder, data_persister_manager: DataPersisterManager | None = None, problem_modifiers: list[GroundStateProblemModifier] | None = None, cube_generator: ProjectiveEmbeddingCubeGenerator | None = None, repulsion_integral_builder: TwoBodyElectronRepulsionIntegralBuilderProtocol | None = None) → None

Initialize an even-handed reaction path problem builder.

Parameters:
Return type:

None

build(reaction_configuration: ReactionConfiguration) → UnrestrictedReactionPathProblem

Build the reaction path problem.

This method uses the Even-handed subsystem selection as described in https://doi.org/10.1063/1.5050533.

Parameters:

reaction_configuration (ReactionConfiguration) – The reaction configuration object.

Return type:

UnrestrictedReactionPathProblem

build_cube_files(reaction_configuration: ReactionConfiguration) → None

Build cube files.

Parameters:

reaction_configuration (ReactionConfiguration) – The reaction configuration object.

Return type:

None

classmethod persistence_checkpoints() → list[str]

Define the persistence checkpoints used during the embedding process.

These checkpoints specify computational stages where intermediate results can be saved and loaded to optimize computations and ensure reproducibility.

Return type:

list[str]

class ManbysLevelShiftProjectorBuilder

Bases: object

Manby level shift projector.

The projector is defined as \(P = \mu S D_{env} S\), where \(\mu\) is the level shift parameter, \(S\) is the overlap matrix, and \(D_{env}\) is the density matrix for the environment.

References

  • Manby, F. R., Stella, M., Goodpaster, J. D., Miller III, T. F. “A simple, exact density-functional-theory embedding scheme.” Journal of Chemical Theory and Computation, 8 (8), 2564-2568, 2012.

__init__(level_shift_parameter: float = 100000.0) → None

Initialize the Manbys level shift projector.

Parameters:

level_shift_parameter (float) – Level shift parameter used to create the projector. Defaults to 1e5.

Return type:

None

build_matrix(environment_density_matrix: ndarray[Any, dtype[float64]], overlap_matrix: ndarray[Any, dtype[float64]]) → ndarray[Any, dtype[float64]]

Get the matrix for the projector.

Parameters:

  • environment_density_matrix (ndarray[Any, dtype[float64]]) – Density matrix of the environment.

  • overlap_matrix (ndarray[Any, dtype[float64]]) – Overlap matrix.

Return type:

ndarray[Any, dtype[float64]]

class PipekMezeyLocalizer

Bases: OrbitalLocalizer

The Pipek-Mezey localization.

__init__(population_method: PopulationMethod = PopulationMethod.META_LOWDIN, options: LocalizationOptions = LocalizationOptions(convergence_tolerance=1e-06, convergence_tolerance_gradient=None, max_cycle=100, max_iterations=20, max_stepsize=0.05, initial_guess='molecular', exponent=2)) → None

Initialize the Pipek-Mezey localization.

This method transforms delocalized molecular orbitals into localized orbitals that are more chemically intuitive. The localized orbitals can be associated with specific bonds or lone pairs in a molecule, aiding in the interpretation of chemical structures and reactions.

Pipek-Mezey Localization Algorithm

The Pipek-Mezey localization procedure [PipekMezey1989] aims to maximize the sum of the squares of atomic partial charges (populations) for each orbital. By doing so, the method localizes orbitals on individual atoms or between pairs of atoms (chemical bonds), enhancing the chemical interpretability of the wavefunction.

The localization criterion Omega is defined as:

\[\Omega = \sum_{i}^{N_{\text{occ}}} \sum_{A}^{N_{\text{atoms}}} [q_{iA}]^2\]

where:

  • \(N_{\text{occ}}\) is the number of occupied molecular orbitals.

  • \(N_{\text{atoms}}\) is the number of atoms in the molecule.

  • \(q_{iA}\) is the Mulliken population of orbital \(i\) on atom \(A\), calculated as:

\[q_{iA} = \sum_{\mu \in A} \sum_{\nu} C_{\mu i} S_{\mu \nu} C_{\nu i}\]

Here:

  • \(C_{\mu i}\) are the coefficients of the molecular orbitals.

  • \(S_{\mu \nu}\) is the overlap between atomic orbitals \(\mu\) and \(\nu\).

  • The sum over \(\mu \in A\) includes all basis functions centered on atom \(A\).

Implementation Details

The method involves iteratively rotating pairs of occupied molecular orbitals to increase \(\Omega\) until convergence is achieved. This is typically done using a Jacobi-like rotation procedure that ensures the orthogonality of the resulting localized orbitals.

Advantages

  • Chemical Intuition: Produces orbitals that correspond closely to chemical bonds and lone pairs.

  • Computational Efficiency: Generally faster than other localization methods like Boys localization.

  • Applicability: Suitable for both ab initio and semiempirical wavefunctions.

[PipekMezey1989]

Pipek, J., & Mezey, P. G. (1989). A fast intrinsic localization procedure applicable for ab initio and semiempirical linear combination of atomic orbital wave functions. The Journal of Chemical Physics, 90(9), 4916-4926. doi:10.1063/1.456588 [1]

param population_method:

The method for calculating the orbital population

param options:

The algorithmic options

Parameters:
Return type:

None

run(molecular_configuration: MolecularConfiguration, occupied_molecular_orbitals: RestrictedOccupiedMolecularOrbitals | UnrestrictedOccupiedMolecularOrbitals) → RestrictedOccupiedMolecularOrbitals | UnrestrictedOccupiedMolecularOrbitals

Run the localization algorithm that maximizes the orbital population.

Parameters:
Return type:

RestrictedOccupiedMolecularOrbitals | UnrestrictedOccupiedMolecularOrbitals

class SimpleReactionPathProblemBuilder

Bases: ReactionPathProblemBuilder

Simple reaction path problem builder.

Each molecular ground state problem is made one at a time without knowledge of the rest of the reaction.

__init__(ground_state_problem_builder: GroundStateProblemBuilder) → None

Initialize an instance of the simple reaction path problem builder.

Parameters:

ground_state_problem_builder (GroundStateProblemBuilder) – Problem builder to be used on every molecular configuration in the reaction.

Return type:

None

build_restricted(reaction_configuration: ReactionConfiguration) → RestrictedReactionPathProblem

Build the restricted reaction path problem.

Parameters:

reaction_configuration (ReactionConfiguration) – The reaction configuration object.

Return type:

RestrictedReactionPathProblem

build_restricted_cube_files(reaction_configuration: ReactionConfiguration) → None

Build restricted cube files.

Parameters:

reaction_configuration (ReactionConfiguration) – The reaction configuration object.

Return type:

None

build_unrestricted(reaction_configuration: ReactionConfiguration) → UnrestrictedReactionPathProblem

Build the unrestricted reaction path problem.

Parameters:

reaction_configuration (ReactionConfiguration) – The reaction configuration object.

Return type:

UnrestrictedReactionPathProblem

build_unrestricted_cube_files(reaction_configuration: ReactionConfiguration) → None

Build unrestricted cube files.

Parameters:

reaction_configuration (ReactionConfiguration) – The reaction configuration object.

Return type:

None

class TotalWeightBasedOrbitalAssigner

Bases: OrbitalAssigner

Assigns molecular orbitals to embedded and environment regions based on total AO contributions.

__init__(assignment_tolerance: float | Literal['kmeans_midpoint', 'largest_gap_midpoint'] = 'kmeans_midpoint') → None

Initialize a total weight based molecular orbital assigner.

Parameters:

assignment_tolerance (float | Literal['kmeans_midpoint', 'largest_gap_midpoint']) –

Fractional threshold for assigning an MO to the embedded region.

If the fraction of AO weight in the embedded region > assignment_tolerance, the molecular orbital is assigned to embedded region.

Return type:

None

assign(molecular_configuration: MolecularConfiguration, local_occupied_molecular_orbitals: UnrestrictedOccupiedMolecularOrbitals | RestrictedOccupiedMolecularOrbitals) → UnrestrictedOrbitalAssignmentResult | RestrictedOrbitalAssignmentResult

Assign occupied molecular orbitals to embedded or environment regions.

Assigns occupied molecular orbitals to embedded or environment regions based on the total weights of their atomic orbital contributions.

Parameters:
Raises:

ValueError – If there are atomic orbitals not assigned to any region.

Return type:

UnrestrictedOrbitalAssignmentResult | RestrictedOrbitalAssignmentResult

Modules

builders

Module containing everything needed to build a reaction path problem.

calculators

Module containing calculators for solving reaction path problems.