qdk_chemistry.plugins.pyscf.localization module

PySCF orbital localization module for qdk_chemistry.

This module provides orbital localization capabilities using the PySCF library and integrates PySCF localization algorithms into the QDK/Chemistry framework.

The implementation supports both restricted (closed-shell) and unrestricted (open-shell) orbitals: occupied, singly-occupied and virtual spaces are detected and localized separately to preserve orthogonality and physical character.

Supported localization methods (selected via the settings method):

• “pipek-mezey” [BP93] (Pipek-Mezey, supports a configurable population analysis),

• “foster-boys” (Foster-Boys),

• “edmiston-ruedenberg” (Edmiston-Ruedenberg),

• “cholesky” (Cholesky-based orthogonalization/localization).

This module registers a pyscf localizer with the QDK/Chemistry localizer registry at import time, making the functionality available via qdk_chemistry.algorithms.create("orbital_localizer", "pyscf").

Requires: PySCF (the code uses the pyscf.lo localization routines).

class qdk_chemistry.plugins.pyscf.localization.PyscfLocalizer

Bases: OrbitalLocalizer

PySCF-based orbital localizer for quantum chemistry calculations.

This class implements orbital localization using routines from PySCF. It supports multiple localization algorithms and works with both restricted (closed-shell) and unrestricted (open-shell) orbital inputs.

Key behavior:

• Supported algorithms: Pipek-Mezey (PM), Foster-Boys (FB), Edmiston-Ruedenberg (ER), and a Cholesky-based localizer.

• It is the user’s responsibility to provide appropriate orbital indices (e.g., only occupied orbitals or only virtual orbitals).

Examples

>>> localizer = PyscfLocalizer()
>>> # Localize occupied orbitals (user provides appropriate indices)
>>> occ_indices = [0, 1, 2, 3, 4]  # indices of occupied orbitals
>>> localized_orbitals = localizer.run(canonical_orbitals, occ_indices, occ_indices)

Notes

Uses Mulliken population analysis for the Pipek-Mezey method by default. The population method can be configured via the population_method setting.

__init__()

Initialize the PySCF localizer with default settings.

name()

Return the settings for the localizer.

Return type:

str

class qdk_chemistry.plugins.pyscf.localization.PyscfLocalizerSettings

Bases: Settings

Configuration settings for PySCF orbital localization.

This class manages settings for orbital localization procedures using PySCF. It inherits from the Settings base class and exposes the configurable options used by PyscfLocalizer.

method

The localization algorithm to use (default = “pipek-mezey”). Supported values (case-insensitive) include “pipek-mezey”, “foster-boys”, “edmiston-ruedenberg”, and “cholesky”.

Type:

str

population_method

The population analysis used for the Pipek-Mezey localization (default = “mulliken”). Passed through to PySCF’s PM implementation (for example, “mulliken”).

Type:

str

occupation_threshold

Tolerance threshold used to classify orbitals as occupied, singly-occupied (for ROHF/UHF), or virtual (default = 1e-10). Orbitals with occupations below this threshold are considered unoccupied.

Type:

float

Examples

>>> settings = PyscfLocalizerSettings()
>>> settings.get("occupation_threshold")
1e-10
>>> settings.set("occupation_threshold", 1e-8)
>>> settings.set("population_method", "mulliken")

__init__()

Initialize the localization object with default parameters.