qdk_chemistry.algorithms.active_space_selector module

Public entry point for the Active Space Selector algorithm.

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

class qdk_chemistry.algorithms.active_space_selector.ActiveSpaceSelector

Bases: pybind11_object

Abstract base class for active space selector algorithms.

This class defines the interface for selecting active spaces from a set of orbitals. Active space selection is a critical step in many quantum chemistry methods, particularly for multireference calculations. Concrete implementations should inherit from this class and implement the select_active_space method.

Return value semantics

Implementations return a new Wavefunction object with active-space data populated. Some selectors (e.g., occupation/valence) return a copy with only metadata updated. Others (e.g., AVAS) may rotate/canonicalize orbitals and recompute occupations, so the returned coefficients/occupations can differ from the input. The input Wavefunction object is never modified.

Examples

To create a custom active space selector, inherit from this class.:

>>> import qdk_chemistry.algorithms as alg
>>> import qdk_chemistry.data as data
>>> class MyActiveSpaceSelector(alg.ActiveSpaceSelector):
...     def __init__(self):
...         super().__init__()  # Call the base class constructor
...     # Implement the _run_impl method (called by run())
...     def _run_impl(self, wavefunction: data.Wavefunction) -> data.Wavefunction:
...         # Custom active space selection implementation that returns orbitals with active space populated.
...         # For selectors that only annotate, return a copied object with metadata set; for others,
...         # you may also rotate/transform the coefficients as needed.
...         act_orbitals = data.Orbitals(wavefunction.get_orbitals()) # Copy base data by default
...         act_orbitals.set_active_space_indices([0, 1, 2, 3])
...         act_orbitals.set_num_active_electrons(2)
...         ... # Additional logic to modify orbitals if needed
...         act_wavefunction = data.Wavefunction(...)
...         return act_wavefunction # Return modified wavefunction object

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

Create an ActiveSpaceSelector instance.

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

Examples

>>> # In a derived class:
>>> class MySelector(alg.ActiveSpaceSelector):
...     def __init__(self):
...         super().__init__()  # Calls parent constructor

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

The algorithm’s name.

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

run(self: qdk_chemistry.algorithms.ActiveSpaceSelector, wavefunction: qdk_chemistry.data.Wavefunction) → qdk_chemistry.data.Wavefunction

Select active space orbitals from the given wavefunction.

This method automatically locks settings before execution to prevent modifications during selection.

Parameters:: wavefunction (qdk_chemistry.data.Wavefunction) – The wavefunction from which to select the active space
Returns:: Wavefunction with active space data populated
Return type:: qdk_chemistry.data.Wavefunction
Raises:: SettingsAreLocked – If attempting to modify settings after run() is called

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

Access the selector’s configuration settings.

Returns:: Reference to the settings object for configuring the active space selector
Return type:: qdk_chemistry.data.Settings

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

The algorithm’s type name.

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

class qdk_chemistry.algorithms.active_space_selector.QdkAutocasActiveSpaceSelector

Bases: ActiveSpaceSelector

QDK Automated Complete Active Space (AutoCAS) selector.

This class provides an automated approach to selecting active space orbitals based on various criteria including occupation numbers, orbital energies, and other chemical information [SR19].

Typical usage:

import qdk_chemistry.algorithms as alg

# Create an AutoCAS selector
selector = alg.QdkAutocasActiveSpaceSelector()

# Select active space automatically
active_wfn = selector.run(wavefunction)

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

Default constructor.

Initializes an AutoCAS selector with default settings.

class qdk_chemistry.algorithms.active_space_selector.QdkAutocasEosActiveSpaceSelector

Bases: ActiveSpaceSelector

QDK entropy-based active space selector.

This class selects active space orbitals based on orbital entropy measures. It identifies orbitals with high entropy, which indicates strong electron correlation and multi-reference character. This method is a variant of the AutoCAS method that uses entropy as the primary criterion for selecting active orbitals [SR19].

Typical usage:

import qdk_chemistry.algorithms as alg

# Create an entropy-based selector
selector = alg.QdkAutocasEosActiveSpaceSelector()

# Configure entropy threshold
selector.settings().set("entropy_threshold", 0.1)

# Select active space
active_wfn = selector.run(wavefunction)

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

Default constructor.

Initializes an entropy-based active space selector with default settings.

class qdk_chemistry.algorithms.active_space_selector.QdkOccupationActiveSpaceSelector

Bases: ActiveSpaceSelector

QDK occupation-based active space selector.

This class selects active space orbitals based on their occupation numbers. It identifies orbitals that have partial occupations (not close to 0 or 2 electrons), which typically indicates significant multi-reference character and strong electron correlation.

Typical usage:

import qdk_chemistry.algorithms as alg

# Create an occupation-based selector
selector = alg.QdkOccupationActiveSpaceSelector()

# Configure occupation threshold
selector.settings().set("occupation_threshold", 0.1)

# Select active space
active_wfn = selector.run(wavefunction)

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

Default constructor.

Initializes an occupation-based active space selector with default settings.

class qdk_chemistry.algorithms.active_space_selector.QdkValenceActiveSpaceSelector

Bases: ActiveSpaceSelector

QDK valence-based active space selector.

This class selects active space orbitals based on valence orbital criteria. It identifies valence orbitals that are chemically significant for the molecular system under study.

Typical usage:

import qdk_chemistry.algorithms as alg

# Create a valence-based selector
selector = alg.QdkValenceActiveSpaceSelector()

# Select active space
active_wfn = selector.run(wavefunction)

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

Default constructor.

Initializes a valence-based active space selector with default settings.