qdk_chemistry.algorithms.projected_multi_configuration_calculator module

Public entry point for the projected multi-configuration calculator algorithms.

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

class qdk_chemistry.algorithms.projected_multi_configuration_calculator.ProjectedMultiConfigurationCalculator

Bases: pybind11_object

Abstract base class for projected multi-configurational (PMC) calculations in quantum chemistry.

This class provides the interface for projected multi-configurational-based quantum chemistry calculations. This contrasts the MultiConfigurationCalculator in that the space of determinants upon which the Hamiltonian is projected is taken to be a free parameter and must be specified. In this manner, the high-performance solvers which underly other MC algorithms can be interfaced with external methods for selecting important determinants.

The calculator takes a Hamiltonian and a set of configurations as input and returns both the calculated total energy and the corresponding multi-configurational wavefunction.

To create a custom PMC calculator, inherit from this class.

Examples

>>> import qdk_chemistry.algorithms as alg
>>> import qdk_chemistry.data as data
>>> class MyProjectedMultiConfigurationCalculator(alg.ProjectedMultiConfigurationCalculator):
...     def __init__(self):
...         super().__init__()  # Call the base class constructor
...     def _run_impl(self, hamiltonian: data.Hamiltonian, configurations: list[data.Configuration]) -> tuple[float, data.Wavefunction]:
...         # Custom PMC implementation
...         return energy, wavefunction

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

Create a ProjectedMultiConfigurationCalculator instance.

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

Examples

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

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

The algorithm’s name.

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

run(self: qdk_chemistry.algorithms.ProjectedMultiConfigurationCalculator, hamiltonian: qdk_chemistry.data.Hamiltonian, configurations: collections.abc.Sequence[qdk_chemistry.data.Configuration]) → tuple[float, qdk_chemistry.data.Wavefunction]

Perform projected multi-configurational calculation.

This method automatically locks settings before execution.

This method takes a Hamiltonian describing the quantum system and a set of configurations/determinants to project the Hamiltonian onto, and returns both the calculated energy and the optimized multi-configurational wavefunction.

Parameters:

hamiltonian (qdk_chemistry.data.Hamiltonian) – The Hamiltonian operator describing the quantum system
configurations (list[qdk_chemistry.data.Configuration]) – The set of configurations/determinants to project the Hamiltonian onto

Returns:

A tuple containing the calculated total energy (active + core) and the resulting multi-configurational wavefunction

Return type:

tuple[float, qdk_chemistry.data.Wavefunction]

Raises:

RuntimeError – If the calculation fails
ValueError – If hamiltonian or configurations are invalid

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

Access the calculator’s configuration settings.

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

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

The algorithm’s type name.

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

class qdk_chemistry.algorithms.projected_multi_configuration_calculator.QdkMacisPmc

Bases: ProjectedMultiConfigurationCalculator

QDK MACIS-based Projected Multi-Configuration (PMC) calculator.

This class provides a concrete implementation of the projected multi-configuration calculator using the MACIS library. It performs projections of the Hamiltonian onto a specified set of determinants to compute energies and wavefunctions for strongly correlated molecular systems.

The calculator inherits from ProjectedMultiConfigurationCalculator and uses MACIS library routines to perform the actual projected calculations where the determinant space is provided as input rather than generated adaptively.

Typical usage:

import qdk_chemistry.algorithms as alg
import qdk_chemistry.data as data

# Create a PMC calculator
pmc = alg.QdkMacisPmc()

# Configure PMC-specific settings
pmc.settings().set("davidson_res_tol", 1e-8)
pmc.settings().set("davidson_max_m", 200)

# Prepare configurations
configurations = [...]  # Your list of Configuration objects

# Run calculation
energy, wavefunction = pmc.run(hamiltonian, configurations)