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 localization and transformation algorithms.

This class defines the interface for selecting and transforming molecular orbitals. Implementations may produce spatially localized orbitals or other representations, such as natural orbitals. Concrete implementations should inherit from this class and implement the _run_impl 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.OrbitalLocalizer):
...     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 orbital transformation implementation
...         return transformed_wavefunction

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

Create an OrbitalLocalizer 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.OrbitalLocalizer):
...     def __init__(self):
...         super().__init__()  # Calls this constructor

aliases(self: qdk_chemistry.algorithms.OrbitalLocalizer) → list[str]

The algorithm’s aliases.

Returns:: All registered names for the algorithm
Return type:: list[str]

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

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 | SupportsIndex], loc_indices_b: collections.abc.Sequence[SupportsInt | SupportsIndex]) → qdk_chemistry.data.Wavefunction

Transform selected molecular orbitals in the given wavefunction.

Parameters:

wavefunction (qdk_chemistry.data.Wavefunction) – The molecular wavefunction to transform
loc_indices_a (list[int]) – Indices of alpha orbitals to transform; empty selects none
loc_indices_b (list[int]) – Indices of beta orbitals to transform; empty selects none

Notes

For restricted orbitals, loc_indices_b must match loc_indices_a. If both index lists are empty, the orbital transformation is a no-op.

Returns:

The output wavefunction with transformed orbitals

Return type:

qdk_chemistry.data.Wavefunction

Raises:

ValueError – If orbital indices are invalid or inconsistent
RuntimeError – If the transformation 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.QdkActiveSpaceQIOLocalizer

Bases: OrbitalLocalizer

QDK quantum-information orbital (QIO) active-space localizer.

Rotates restricted active orbitals to minimize the total single-orbital entropy using gradient-free Jacobi sweeps.

This class minimizes the QIO objective restricted to rotations within a fixed active space. It does not implement full-space QIO or QICAS, both of which mix orbitals across the active-space boundary.

Note

Requires a restricted active orbital space, matching alpha and beta localization indices, and spin-dependent active-space 1- and 2-RDMs.

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

Default constructor.

Initializes a quantum-information orbital localizer with default settings.

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

Transform selected molecular orbitals in the given wavefunction.

Parameters:

wavefunction (qdk_chemistry.data.Wavefunction) – The molecular wavefunction to transform
loc_indices_a (list[int]) – Indices of alpha orbitals to transform; empty selects none
loc_indices_b (list[int]) – Indices of beta orbitals to transform; empty selects none

Notes

For restricted orbitals, loc_indices_b must match loc_indices_a. If both index lists are empty, the orbital transformation is a no-op.

Returns:

The output wavefunction with transformed orbitals

Return type:

qdk_chemistry.data.Wavefunction

Raises:

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

class qdk_chemistry.algorithms.orbital_localizer.QdkGaugeFixingLocalizer

Bases: OrbitalLocalizer

QDK gauge-fixing orbital localizer.

Orbitals with equal occupation numbers span a well-defined subspace without being uniquely determined within it. This class resolves that freedom deterministically, using bounded coordinate-descent sweeps to reduce the mapped Hamiltonian coefficient 1-norm lambda = sum_l |h_l|, which sets the evolution time in phase estimation and the normalization of a linear-combination-of-unitaries block encoding.

Note

Requires restricted orbitals, an active space, an overlap matrix, and a spin-traced active 1-RDM that is diagonal in the input orbital basis, which is what QdkNaturalOrbitalLocalizer produces. Requires loc_indices_a == loc_indices_b, and those indices must be a subset of the active-space indices that does not split a degenerate block.

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

Default constructor.

Initializes a gauge-fixing localizer with default settings.

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

Transform selected molecular orbitals in the given wavefunction.

Parameters:

wavefunction (qdk_chemistry.data.Wavefunction) – The molecular wavefunction to transform
loc_indices_a (list[int]) – Indices of alpha orbitals to transform; empty selects none
loc_indices_b (list[int]) – Indices of beta orbitals to transform; empty selects none

Notes

For restricted orbitals, loc_indices_b must match loc_indices_a. If both index lists are empty, the orbital transformation is a no-op.

Returns:

The output wavefunction with transformed orbitals

Return type:

qdk_chemistry.data.Wavefunction

Raises:

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

class qdk_chemistry.algorithms.orbital_localizer.QdkMP2NaturalOrbitalLocalizer

Bases: OrbitalLocalizer

QDK MP2 natural orbital transformer.

Deprecated since version 2.0.0: Use QdkNaturalOrbitalLocalizer (qdk_natural_orbitals) with a wavefunction that already contains the active-space one-particle reduced density matrix (1-RDM).

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.QdkMP2NaturalOrbitalLocalizer) → None

Default constructor.

Initializes an MP2 natural orbital transformer with default settings.

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

Transform selected molecular orbitals in the given wavefunction.

Parameters:

wavefunction (qdk_chemistry.data.Wavefunction) – The molecular wavefunction to transform
loc_indices_a (list[int]) – Indices of alpha orbitals to transform; empty selects none
loc_indices_b (list[int]) – Indices of beta orbitals to transform; empty selects none

Notes

For restricted orbitals, loc_indices_b must match loc_indices_a. If both index lists are empty, the orbital transformation is a no-op.

Returns:

The output wavefunction with transformed orbitals

Return type:

qdk_chemistry.data.Wavefunction

Raises:

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

class qdk_chemistry.algorithms.orbital_localizer.QdkNaturalOrbitalLocalizer

Bases: OrbitalLocalizer

QDK natural orbital transformer.

This class provides a concrete implementation that transforms molecular orbitals into natural orbitals by diagonalizing the spin-traced one-particle reduced density matrix (1-RDM). Natural orbitals are eigenfunctions of the 1-RDM, and their eigenvalues are the occupation numbers.

Note

Requires loc_indices_a == loc_indices_b (natural orbitals are a single set). Requires loc_indices_a/loc_indices_b to match the orbitals’ active-space indices exactly. Requires a spin-traced 1-RDM and an active space in the wavefunction. For unrestricted Slaterdeterminant, the 1-RDM is expressed in the alpha MO basis and the output is always a restricted set of natural orbitals.

Typical usage:

import qdk_chemistry.algorithms as alg

# Create a natural orbital localizer
localizer = alg.QdkNaturalOrbitalLocalizer()

# Transform to natural orbitals
no_wfn = localizer.run(wavefunction, active_indices, active_indices)

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

Default constructor.

Initializes a natural orbital transformer with default settings.

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

Transform selected molecular orbitals in the given wavefunction.

Parameters:

wavefunction (qdk_chemistry.data.Wavefunction) – The molecular wavefunction to transform
loc_indices_a (list[int]) – Indices of alpha orbitals to transform; empty selects none
loc_indices_b (list[int]) – Indices of beta orbitals to transform; empty selects none

Notes

For restricted orbitals, loc_indices_b must match loc_indices_a. If both index lists are empty, the orbital transformation is a no-op.

Returns:

The output wavefunction with transformed orbitals

Return type:

qdk_chemistry.data.Wavefunction

Raises:

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

class qdk_chemistry.algorithms.orbital_localizer.QdkPipekMezeyLocalizer

Bases: OrbitalLocalizer

QDK Pipek-Mezey orbital localizer.

This class provides a concrete implementation of the orbital localizer using the Pipek-Mezey localization algorithm. The Pipek-Mezey algorithm maximizes the sum of squares of atomic orbital populations on atoms, resulting in orbitals that are more localized to individual atoms or bonds.

This implementation separately localizes occupied and virtual orbitals to maintain the occupied-virtual separation.

Typical usage:

import qdk_chemistry.algorithms as alg

# Create a Pipek-Mezey localizer
localizer = alg.QdkPipekMezeyLocalizer()

# Configure settings if needed
localizer.settings().set("max_iterations", 100)
localizer.settings().set("convergence_tolerance", 1e-8)

# Localize orbitals
localized_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.

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

Transform selected molecular orbitals in the given wavefunction.

Parameters:

wavefunction (qdk_chemistry.data.Wavefunction) – The molecular wavefunction to transform
loc_indices_a (list[int]) – Indices of alpha orbitals to transform; empty selects none
loc_indices_b (list[int]) – Indices of beta orbitals to transform; empty selects none

Notes

For restricted orbitals, loc_indices_b must match loc_indices_a. If both index lists are empty, the orbital transformation is a no-op.

Returns:

The output wavefunction with transformed orbitals

Return type:

qdk_chemistry.data.Wavefunction

Raises:

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

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)

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

Default constructor.

Initializes a VV-HV localizer with default settings.

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

Transform selected molecular orbitals in the given wavefunction.

Parameters:

wavefunction (qdk_chemistry.data.Wavefunction) – The molecular wavefunction to transform
loc_indices_a (list[int]) – Indices of alpha orbitals to transform; empty selects none
loc_indices_b (list[int]) – Indices of beta orbitals to transform; empty selects none

Notes

For restricted orbitals, loc_indices_b must match loc_indices_a. If both index lists are empty, the orbital transformation is a no-op.

Returns:

The output wavefunction with transformed orbitals

Return type:

qdk_chemistry.data.Wavefunction

Raises:

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

qdk_chemistry.algorithms.orbital_localizer.new_aufbau_determinant_wavefunction(wavefunction: qdk_chemistry.data.Wavefunction, orbitals: qdk_chemistry.data.Orbitals) → qdk_chemistry.data.Wavefunction

Create an Aufbau determinant wavefunction for an orbital basis.

The determinant is the canonical Aufbau determinant implied by the input wavefunction’s electron counts and the supplied orbitals. If the orbitals define an active space, the determinant is projected into that active space.

Parameters:

wavefunction (qdk_chemistry.data.Wavefunction) – Wavefunction providing electron counts
orbitals (qdk_chemistry.data.Orbitals) – Orbital basis for the returned wavefunction

Returns:

Aufbau determinant wavefunction with the supplied orbitals

Return type:

qdk_chemistry.data.Wavefunction