Projected Multi-Configuration calculations

The ProjectedMultiConfigurationCalculator algorithm in QDK/Chemistry performs Projected Multi-Configuration (PMC) calculations to solve the electronic structure problem for a specified set of electronic configurations. Following QDK/Chemistry’s algorithm design principles, it takes a Hamiltonian instance and a set of configurations as input and produces a Wavefunction instance as output. This calculator provides a flexible interface for projecting the Hamiltonian onto a user-defined determinant space, enabling integration with external determinant selection methods.

Overview

The ProjectedMultiConfigurationCalculator algorithm projects the Hamiltonian onto a user-specified space of configurations (Slater determinants) and solves the resulting eigenvalue problem to obtain the ground state energy and wavefunction. This contrasts with MultiConfigurationCalculator, where the solver determines which configurations to include.

Note

In contrast to the MultiConfigurationCalculator, where the spin and number of particles are explicitly defined via the number of alpha and beta particles, the ProjectedMultiConfigurationCalculator derives these symmetry properties from the provided configurations. Hence, all configurations must share the same number of alpha and beta electrons.

Using the ProjectedMultiConfigurationCalculator

This section demonstrates how to create, configure, and run a PMC calculation. The run method takes a Hamiltonian object and a list of configurations as input, and returns a Wavefunction object along with its associated energy.

Input requirements

The ProjectedMultiConfigurationCalculator requires the following inputs:

Hamiltonian

A Hamiltonian instance that defines the electronic structure problem.

Configurations

A collection of Configuration objects specifying the determinants to include in the calculation. Each configuration defines the occupation of orbitals in the active space.

Creating a PMC calculator

  // Create a MACIS PMC calculator instance
  auto pmc_calculator =
      ProjectedMultiConfigurationCalculatorFactory::create("macis_pmc");

from qdk_chemistry.algorithms import create

# Create a MACIS PMC calculator instance
pmc_calculator = create("projected_multi_configuration_calculator", "macis_pmc")

Configuring settings

Settings can be modified using the settings() object. See Available implementations below for implementation-specific options.

  // Set the convergence threshold for the CI iterations
  pmc_calculator->settings().set("ci_residual_tolerance", 1.0e-6);
  pmc_calculator->settings().set("davidson_res_tol", 1.0e-8);

# Configure the PMC calculator using the settings interface
pmc_calculator.settings().set("ci_residual_tolerance", 1.0e-6)
pmc_calculator.settings().set("davidson_res_tol", 1.0e-8)

Running the calculation

  // Create a structure (H2 molecule)
  std::vector<Eigen::Vector3d> coords = {{0.0, 0.0, 0.0}, {0.0, 0.0, 1.4}};
  std::vector<std::string> symbols = {"H", "H"};
  std::shared_ptr<Structure> structure =
      std::make_shared<Structure>(coords, symbols);

  // Run SCF to get orbitals
  auto scf_solver = ScfSolverFactory::create();
  auto [E_scf, wfn] = scf_solver->run(structure, 0, 1, "sto-3g");

  // Build Hamiltonian from orbitals
  auto ham_constructor = HamiltonianConstructorFactory::create();
  auto hamiltonian = ham_constructor->run(wfn->get_orbitals());

  // Define configurations
  std::vector<Configuration> configurations = {
      Configuration("20"),  // Ground state (both electrons in lowest orbital)
      Configuration("02"),  // Excited state (both electrons in higher orbital)
  };

  // Run the PMC calculation
  auto [E_pmc, pmc_wavefunction] =
      pmc_calculator->run(hamiltonian, configurations);

  std::cout << "SCF Energy: " << E_scf << " Hartree" << std::endl;
  std::cout << "PMC Energy: " << E_pmc << " Hartree" << std::endl;

import numpy as np
from qdk_chemistry.algorithms import create
from qdk_chemistry.data import Configuration, Structure

# Create a structure (H2 molecule)
coords = np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 1.4]])
symbols = ["H", "H"]
structure = Structure(coords, symbols)

# Run SCF to get orbitals
scf_solver = create("scf_solver")
E_scf, wfn = scf_solver.run(
    structure, charge=0, spin_multiplicity=1, basis_or_guess="sto-3g"
)

# Build Hamiltonian from orbitals
ham_constructor = create("hamiltonian_constructor")
hamiltonian = ham_constructor.run(wfn.get_orbitals())

# Define configurations
configurations = [
    Configuration("20"),  # Ground state (both electrons in lowest orbital)
    Configuration("02"),  # Excited state (both electrons in higher orbital)
]

# Run the PMC calculation
E_pmc, pmc_wavefunction = pmc_calculator.run(hamiltonian, configurations)

print(f"SCF Energy: {E_scf:.10f} Hartree")
print(f"PMC Energy: {E_pmc:.10f} Hartree")

Available settings

The ProjectedMultiConfigurationCalculator accepts a range of settings to control its behavior. All implementations share a common base set of settings from ProjectedMultiConfigurationSettings:

Setting

Type

Default

Description

ci_residual_tolerance

float

1e-6

Convergence threshold for CI Davidson solver

davidson_iterations

int

200

Maximum number of Davidson iterations

calculate_one_rdm

bool

False

Calculate one-electron reduced density matrix

calculate_two_rdm

bool

False

Calculate two-electron reduced density matrix

See Settings for a more general treatment of settings in QDK/Chemistry.

Available implementations

QDK/Chemistry’s ProjectedMultiConfigurationCalculator provides a unified interface for projected multi-configurational calculations. You can discover available implementations programmatically:

  auto names = ProjectedMultiConfigurationCalculatorFactory::available();
  for (const auto& name : names) {
    std::cout << name << std::endl;
  }

from qdk_chemistry.algorithms import registry

available = registry.available("projected_multi_configuration_calculator")
print(available)

MACIS PMC

Factory name: "macis_pmc" (default)

The MACIS (Many-body Adaptive Configuration Interaction Solver) PMC implementation provides a high-performance solver for projecting the Hamiltonian onto a specified set of configurations. This implementation leverages the same efficient parallel algorithms used in MACIS ASCI but applies them to a fixed, user-provided determinant space.

Settings

In addition to the common settings, MACIS PMC supports the following implementation-specific settings:

Setting

Type

Default

Description

iterative_solver_dimension_cutoff

int

100

Matrix size cutoff for using iterative eigensolver. If the number of determinants is below this value, dense diagonalization is used instead

H_thresh

float

1e-16

Hamiltonian matrix entries threshold for dense diagonalization

h_el_tol

float

1e-8

Electron interaction tolerance for Hamiltonian-wavefunction products in iterative solver

davidson_res_tol

float

1e-8

Residual tolerance for Davidson solver convergence

davidson_max_m

int

200

Maximum allowed subspace size for Davidson solver

Further reading