qdk_chemistry.algorithms.orbital_localizer module

Public entry point for the orbital localization algorithms.

This module re-exports the core OrbitalLocalizer so that consumers can import it directly from qdk_chemistry.algorithms without depending on internal package paths.

class qdk_chemistry.algorithms.orbital_localizer.OrbitalLocalizer

Bases: pybind11_object

Abstract base class for orbital localizers.

This class defines the interface for localizing molecular orbitals. Localization transforms canonical molecular orbitals into localized orbitals that are spatially confined to specific regions or bonds. Concrete implementations should inherit from this class and implement the localize method.

Examples

>>> # To create a custom orbital localizer, inherit from this class.
>>> import qdk_chemistry.algorithms as alg
>>> import qdk_chemistry.data as data
>>> class MyLocalizer(alg.Localizer):
...     def __init__(self):
...         super().__init__()  # Call the base class constructor
...     # Implement the _run_impl method
...     def _run_impl(self, wavefunction: data.Wavefunction, loc_indices_a: list, loc_indices_b: list) -> data.Wavefunction:
...         # Custom localization implementation
...         return localized_wavefunction

__init__(self: qdk_chemistry.algorithms.OrbitalLocalizer) → None

Create a Localizer instance.

Default constructor for the abstract base class. This should typically be called from derived class constructors.

Examples

>>> # In a derived class:
>>> class MyLocalizer(alg.Localizer):
...     def __init__(self):
...         super().__init__()  # Calls this constructor

name(self: qdk_chemistry.algorithms.OrbitalLocalizer) → str

The algorithm’s name.

Returns:: The name of the algorithm
Return type:: str

run(self: qdk_chemistry.algorithms.OrbitalLocalizer, wavefunction: qdk_chemistry.data.Wavefunction, loc_indices_a: collections.abc.Sequence[SupportsInt], loc_indices_b: collections.abc.Sequence[SupportsInt]) → qdk_chemistry.data.Wavefunction

Localize molecular orbitals in the given wavefunction.

Parameters:

wavefunction (qdk_chemistry.data.Wavefunction) – The canonical molecular wavefunction to localize
loc_indices_a (list[int]) – Indices of alpha orbitals to localize (empty for no localization)
loc_indices_b (list[int]) – Indices of beta orbitals to localize (empty for no localization)

Notes

For restricted orbitals, loc_indices_b must match loc_indices_a.

Returns:

The localized molecular wavefunction

Return type:

qdk_chemistry.data.Wavefunction

Raises:

ValueError – If orbital indices are invalid or inconsistent
RuntimeError – If localization fails due to numerical issues

settings(self: qdk_chemistry.algorithms.OrbitalLocalizer) → qdk_chemistry.data.Settings

Access the localizer’s configuration settings.

Returns:: Reference to the settings object for configuring the localizer
Return type:: qdk_chemistry.data.Settings

type_name(self: qdk_chemistry.algorithms.OrbitalLocalizer) → str

The algorithm’s type name.

Returns:: The type name of the algorithm
Return type:: str

class qdk_chemistry.algorithms.orbital_localizer.QdkMP2NaturalOrbitalLocalizer

Bases: OrbitalLocalizer

QDK MP2 natural orbital transformer.

This class provides a concrete implementation that transforms canonical molecular orbitals into natural orbitals derived from second-order Møller-Plesset perturbation theory (MP2). Natural orbitals are eigenfunctions of the first-order reduced density matrix.

MP2 natural orbitals often provide a more compact representation of the electronic wavefunction, which can improve computational efficiency in correlation methods.

Note

Only supports restricted orbitals and closed-shell systems.

Typical usage:

import qdk_chemistry.algorithms as alg

# Create an MP2 natural orbital localizer
localizer = alg.QdkMP2NaturalOrbitalLocalizer()

# Transform to MP2 natural orbitals
no_wfn = localizer.run(wavefunction, loc_indices_a, loc_indices_b)

__init__(self: qdk_chemistry.algorithms.QdkPipekMezeyLocalizer) → None

Default constructor.

Initializes a Pipek-Mezey localizer with default settings.

class qdk_chemistry.algorithms.orbital_localizer.QdkVVHVLocalizer

Bases: OrbitalLocalizer

QDK Valence Virtual - Hard Virtual (VV-HV) orbital localizer.

This class provides a concrete implementation of the orbital localizer using the VV-HV localization algorithm. The VV-HV algorithm partitions virtual orbitals into valence virtuals (VVs) and hard virtuals (HVs) based on projection onto a minimal basis, then localizes each space separately.

The algorithm is particularly useful for post-Hartree-Fock methods where separate treatment of valence and Rydberg-like virtual orbitals improves computational efficiency and accuracy.

Implementation based on:: Subotnik et al. JCP 123, 114108 (2005) Wang et al. JCTC 21, 1163 (2025)

Note

This localizer requires all orbital indices to be covered in the localization call.

Typical usage:

import qdk_chemistry.algorithms as alg

# Create a VV-HV localizer
localizer = alg.QdkVVHVLocalizer()

# Configure settings if needed
localizer.settings().set("minimal_basis", "sto-3g")
localizer.settings().set("weighted_orthogonalization", True)
localizer.settings().set("max_iterations", 100)
localizer.settings().set("convergence_tolerance", 1e-8)

# Localize orbitals (must include all orbital indices)
localized_wfn = localizer.run(wavefunction, loc_indices_a, loc_indices_b)