qrunch.chemistry.ground_state_problem.builders.tools.localization.orbital_localizers

Molecular orbital localization.

Module Attributes

DEFAULT_OPTIONS

Default options for the PipekMezeyLocalization

Functions

restricted_occupied_molecular_orbital_coefficients(...)

Extract the occupied molecular orbital coefficients.

restricted_virtual_molecular_orbital_coefficients(...)

Extract the virtual molecular orbital coefficients.

unrestricted_occupied_molecular_orbital_coefficients(...)

Extract the occupied molecular orbital coefficients.

unrestricted_virtual_molecular_orbital_coefficients(...)

Extract the virtual molecular orbital coefficients.

Classes

LocalizationOptions

Configuration options for the localization algorithms.

PipekMezeyLocalizer

The Pipek-Mezey localization.

PopulationMethod

Enumeration of population methods for orbital localization.

RestrictedPipekMezeyLocalizer

The Pipek-Mezey localization.

UnrestrictedPipekMezeyLocalizer

Unrestricted Pipek-Mezey localizer.
DEFAULT_OPTIONS = LocalizationOptions(convergence_tolerance=1e-06, convergence_tolerance_gradient=None, max_cycle=100, max_iterations=20, max_stepsize=0.05, initial_guess='molecular', exponent=2)

Default options for the PipekMezeyLocalization

class LocalizationOptions

Bases: DataclassPublicAPI

Configuration options for the localization algorithms.

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

Parameters:

  • convergence_tolerance – Converge threshold. (default=1e-6)

  • convergence_tolerance_gradient – Converge threshold for orbital rotation gradients. (default=None)

  • max_cycle – The max. number of macro iterations. (default=100)

  • max_iterations – The max. number of iterations in each macro iteration. (default=20)

  • max_stepsize – The step size for orbital rotation. Small step (0.005 - 0.05) is preferred. (default=0.05)

  • initial_guess – Initial guess. “molecular” means mo_coeff will be used, “atomic” means atomic orbitals will be used.

  • exponent – The power to define norm. It can be 2 or 4. Default 2. (default=2)

__init__(*, convergence_tolerance: float = 1e-06, convergence_tolerance_gradient: float | None = None, max_cycle: int = 100, max_iterations: int = 20, max_stepsize: float = 0.05, initial_guess: Literal['molecular', 'atomic'] = 'molecular', exponent: Literal[2, 4] = 2) → None
Parameters:

  • convergence_tolerance (float)

  • convergence_tolerance_gradient (float | None)

  • max_cycle (int)

  • max_iterations (int)

  • max_stepsize (float)

  • initial_guess (Literal['molecular', 'atomic'])

  • exponent (Literal[2, 4])

Return type:

None

convergence_tolerance: float = 1e-06
convergence_tolerance_gradient: float | None = None
exponent: Literal[2, 4] = 2
initial_guess: Literal['molecular', 'atomic'] = 'molecular'
max_cycle: int = 100
max_iterations: int = 20
max_stepsize: float = 0.05
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] (1,2,3)

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) → RestrictedOccupiedMolecularOrbitals
run(molecular_configuration: MolecularConfiguration, occupied_molecular_orbitals: UnrestrictedOccupiedMolecularOrbitals) → UnrestrictedOccupiedMolecularOrbitals

Run the localization algorithm that maximizes the orbital population.

Parameters:
Return type:

RestrictedOccupiedMolecularOrbitals | UnrestrictedOccupiedMolecularOrbitals

class PopulationMethod

Bases: Enum

Enumeration of population methods for orbital localization.

LOWDIN = 'lowdin'
META_LOWDIN = 'meta-lowdin'
MULLIKEN = 'mulliken'
class RestrictedPipekMezeyLocalizer

Bases: object

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.

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) → RestrictedOccupiedMolecularOrbitals

Run the localization algorithm that maximizes the orbital population.

Parameters:
Return type:

RestrictedOccupiedMolecularOrbitals

class UnrestrictedPipekMezeyLocalizer

Bases: object

Unrestricted Pipek-Mezey localizer.

__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.

param options:

The algorithmic options

param population_method:

The method for calculating the orbital population

Parameters:
Return type:

None

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

Run the localization algorithm that maximizes the orbital population.

Parameters:
Return type:

UnrestrictedOccupiedMolecularOrbitals

restricted_occupied_molecular_orbital_coefficients(molecular_orbitals: RestrictedMolecularOrbitals, molecular_orbital_occupations: RestrictedMolecularOrbitalOccupations) → RestrictedOccupiedMolecularOrbitals

Extract the occupied molecular orbital coefficients.

Parameters:
Return type:

RestrictedOccupiedMolecularOrbitals

restricted_virtual_molecular_orbital_coefficients(molecular_orbitals: RestrictedMolecularOrbitals, molecular_orbital_occupations: RestrictedMolecularOrbitalOccupations) → RestrictedOccupiedMolecularOrbitals

Extract the virtual molecular orbital coefficients.

Parameters:
Return type:

RestrictedOccupiedMolecularOrbitals

unrestricted_occupied_molecular_orbital_coefficients(molecular_orbitals: UnrestrictedMolecularOrbitals, molecular_orbital_occupations: UnrestrictedMolecularOrbitalOccupations) → UnrestrictedOccupiedMolecularOrbitals

Extract the occupied molecular orbital coefficients.

Parameters:
Return type:

UnrestrictedOccupiedMolecularOrbitals

unrestricted_virtual_molecular_orbital_coefficients(molecular_orbitals: UnrestrictedMolecularOrbitals, molecular_orbital_occupations: UnrestrictedMolecularOrbitalOccupations) → UnrestrictedOccupiedMolecularOrbitals

Extract the virtual molecular orbital coefficients.

Parameters:
Return type:

UnrestrictedOccupiedMolecularOrbitals