Namespace qdk::chemistry::algorithms

namespace algorithms

Typedefs

using BasisOrGuessType = std::variant<std::shared_ptr<data::Orbitals>, std::shared_ptr<data::BasisSet>, std::string>

Type alias for basis set specification or initial guess.

Can be one of:

• A shared pointer to Orbitals for initial guess

• A shared pointer to BasisSet for custom basis

• A string for standard basis set name (e.g., “sto-3g”)

class ActiveSpaceSelector : public qdk::chemistry::algorithms::Algorithm<ActiveSpaceSelector, std::shared_ptr<data::Wavefunction>, std::shared_ptr<data::Wavefunction>>

#include <qdk/chemistry/algorithms/active_space.hpp>

Abstract base class for selecting active spaces in quantum chemistry calculations.

The ActiveSpaceSelector class defines an interface for algorithms that identify and select important orbitals to include in active space calculations. Active space methods are crucial for reducing the computational complexity of many-body calculations by focusing on the most chemically relevant orbitals while treating the rest as either fully occupied or empty.

Different active space selection algorithms can be implemented by deriving from this class and providing implementations for the pure virtual methods. The class works with the Factory pattern through ActiveSpaceSelectorFactory to allow runtime selection of different implementations.

Typical usage:

auto selector =
  qdk::chemistry::algorithms::ActiveSpaceSelectorFactory::create("algorithm_name");
selector->settings().set("parameter_name", value);
data::Orbitals orbitals_with_active_space =
  selector->run(wavefunction);

See also

ActiveSpaceSelectorFactory for creating instances of active space selectors

See also

data::Wavefunction for the wavefunction data structure used as input

See also

data::Settings for configuration parameters

Public Functions

ActiveSpaceSelector() = default

Default constructor for ActiveSpaceSelector.

This constructor initializes the ActiveSpaceSelector object.

virtual ~ActiveSpaceSelector() = default

Default destructor for ActiveSpaceSelector.

This destructor cleans up any resources used by the ActiveSpaceSelector.

virtual std::string name() const = 0

Access the algorithm’s name.

Returns:

The algorithm’s name

inline ReturnType run(Args... args) const

Selects the active space from the given orbitals.

Note

Settings are automatically locked when this method is called and cannot be modified during or after execution.

Note

The specific criteria and side effects (such as unitary rotations) for selecting the active space may vary between implementations. See the documentation for the specific active space selector being used (docstring).

Throws:

• std::runtime_error – if the active space selection fails or if the input orbitals already have an active space defined.

• qdk::chemistry::data::SettingsAreLocked – if attempting to modify settings after run) is called

Returns:

Orbitals with active space data populated. Depending on the implementation, the returned orbitals may be a copy with only metadata added (e.g., occupation/valence selectors), or they may include transformations to the underlying coefficients/energies (e.g., AVAS may rotate/canonicalize orbitals). The input orbitals are not modified.

inline std::string type_name() const final

Access the algorithm’s type name.

Returns:

The algorithm’s type name

struct ActiveSpaceSelectorFactory : public qdk::chemistry::algorithms::AlgorithmFactory<ActiveSpaceSelector, ActiveSpaceSelectorFactory>

#include <qdk/chemistry/algorithms/active_space.hpp>

Factory class for creating active space selector instances.

This class provides a mechanism to create active space selector instances based on a string key. It allows for easy extension and registration of different active space selection implementations.

Public Static Functions

static inline std::string algorithm_type_name()

static inline std::string default_algorithm_name()

static void register_default_instances()

template<typename Derived, typename ReturnType, typename ...Args>
class Algorithm

#include <qdk/chemistry/algorithms/algorithm.hpp>

Base class for algorithms.

This class automatically generates a run() method that locks settings and delegates to _run_impl().

Usage:

class ScfSolver : public Algorithm<ScfSolver,
                  std::pair<double, std::shared_ptr<Wavefunction>>,
                  std::shared_ptr<Structure>, int, int> {
 protected:
  std::pair<double, std::shared_ptr<Wavefunction>> _run_impl(
    std::shared_ptr<Structure> structure, int charge, int spin) const
override;
};

Template Parameters:

• Derived – The derived algorithm class such as ScfSolver

• ReturnType – The return type of the algorithm’s run() and _run_impl() methods

• Args – Parameter pack containing the types of input arguments required by the algorithm

Public Functions

Algorithm() = default

virtual ~Algorithm() = default

inline virtual std::vector<std::string> aliases() const

Access the algorithm’s aliases.

The name aliases for this algorithm, including the primary name. By default, returns a vector containing only the primary name.

Returns:

A vector of name aliases

virtual std::string name() const = 0

Access the algorithm’s name.

Returns:

The algorithm’s name

inline virtual ReturnType run(Args... args) const

Auto-generated run() method.

Automatically locks settings and delegates to _run_impl()

Parameters:

args – Arguments forwarded to _run_impl() - types specified by the Args parameter pack

Returns:

ReturnType The result from executing _run_impl()

inline data::Settings &settings()

Access the algorithm’s settings.

Returns:

Reference to the algorithm’s Settings object

virtual std::string type_name() const = 0

Access the algorithm’s type name.

Returns:

The algorithm’s type name

template<typename BaseAlgorithmType, typename Derived>
class AlgorithmFactory

#include <qdk/chemistry/algorithms/algorithm.hpp>

Base class template for algorithm factories.

This class provides a generic factory pattern for creating algorithm instances based on string keys. It allows for easy extension and registration of different algorithm implementations.

Template parameters:

Usage:

// Define a concrete factory for ScfSolver
struct ScfSolverFactory : public AlgorithmFactory<ScfSolver> {
  // Optional: override default_key() for custom default behavior
};

// Register implementations
ScfSolverFactory::register_instance("hf", []() {
  return std::make_unique<HartreeFockSolver>();
});

// Create instances
auto solver = ScfSolverFactory::create("hf");

Template Parameters:

• BaseAlgorithmType – The base algorithm type that every registered implementation inherits from and whose run() signature is enforced.

• Derived – The factory type that implements algorithm-specific registration helpers (default names, etc.).

Public Types

using functor_type = std::function<return_type(void)>

using return_type = std::unique_ptr<BaseAlgorithmType>

Public Static Functions

static inline std::vector<std::string> available()

Get a list of all available algorithm keys.

This method returns a vector containing all registered keys for algorithm implementations.

Returns:

A vector of strings representing the available algorithm keys.

static inline void clear()

Clear all registered implementations.

This method removes all entries from the registry. Use with caution.

static inline return_type create(const std::string &name = "")

Create an algorithm instance.

This method creates an algorithm based on the provided key. If no key is provided or the key is empty, it defaults to the first registered implementation. To check any returned implementations, for its name use the name() method of the created instance. To list all available implementations, use the available() method of the factory.

Parameters:

name – The name to identify the desired algorithm implementation.

Throws:

std::runtime_error – if the name is not found in the registry.

Returns:

A unique pointer to the created algorithm instance.

static inline bool has(const std::string &key)

Check if a key exists in the registry.

Parameters:

key – The key to check.

Returns:

true if the key exists, false otherwise.

static inline void register_instance(functor_type func)

Register a new algorithm implementation.

This method allows the registration of a new algorithm implementation with a unique key. If the key already exists, an exception is thrown. The algorithm is registered under its primary name and all its aliases.

Parameters:

func – The function that creates the algorithm instance.

Throws:

std::runtime_error – if the key already exists or if type mismatch.

static inline bool unregister_instance(const std::string &key)

Unregister an algorithm implementation.

This method removes a previously registered algorithm implementation from the registry.

Parameters:

key – The key identifying the algorithm implementation to remove.

Returns:

true if the key was found and removed, false otherwise.

class DynamicalCorrelationCalculator : public qdk::chemistry::algorithms::Algorithm<DynamicalCorrelationCalculator, std::pair<double, std::shared_ptr<data::Wavefunction>>, std::shared_ptr<data::Ansatz>>

#include <qdk/chemistry/algorithms/dynamical_correlation_calculator.hpp>

Base class for reference-derived quantum chemistry methods.

This abstract base class provides a unified interface for quantum chemistry methods that provide corrections on top of a reference wavefunction, such as Møller-Plesset perturbation theory (MP2) and Coupled Cluster (CC) methods.

See also

data::Ansatz

See also

data::Wavefunction

See also

MP2Calculator

Public Functions

DynamicalCorrelationCalculator() = default

Default constructor.

virtual ~DynamicalCorrelationCalculator() = default

Virtual destructor.

virtual std::string name() const = 0

Access the algorithm’s name.

Returns:

The algorithm’s name

inline ReturnType run(Args... args) const

Run main calculation.

This method performs the calculation using the provided ansatz and returns both the total energy and the resulting wavefunction.

Parameters:

args – Arguments to pass to the underlying algorithm, typically an Ansatz (Wavefunction and Hamiltonian) describing the system of interest

Throws:

• std::runtime_error – if the calculation fails

• std::invalid_argument – if the Ansatz is invalid

Returns:

A pair containing the total energy (first) and the resulting wavefunction (second)

inline std::string type_name() const override

Access the algorithm’s type name.

Returns:

The algorithm’s type name

struct DynamicalCorrelationCalculatorFactory : public qdk::chemistry::algorithms::AlgorithmFactory<DynamicalCorrelationCalculator, DynamicalCorrelationCalculatorFactory>

#include <qdk/chemistry/algorithms/dynamical_correlation_calculator.hpp>

Factory class for creating reference-derived calculator instances.

Public Static Functions

static inline std::string algorithm_type_name()

static inline std::string default_algorithm_name()

static void register_default_instances()

class ElectronicStructureSettings : public qdk::chemistry::data::Settings

#include <qdk/chemistry/algorithms/scf.hpp>

Base class for electronic structure algorithms.

Contains common settings for algorithms that work with electronic structure like basis sets, molecular charge, spin multiplicity.

Public Functions

inline ElectronicStructureSettings()

class HamiltonianConstructor : public qdk::chemistry::algorithms::Algorithm<HamiltonianConstructor, std::shared_ptr<data::Hamiltonian>, std::shared_ptr<data::Orbitals>>

#include <qdk/chemistry/algorithms/hamiltonian.hpp>

Abstract base class for constructing Hamiltonian operators.

This class provides the interface for constructing Hamiltonian operators from orbital data in quantum chemistry calculations. It serves as a base for various Hamiltonian construction methods.

The constructor takes orbital information as input and produces a complete Hamiltonian operator that can be used in subsequent quantum chemistry calculations.

See also

data::Hamiltonian

See also

data::Orbitals

See also

data::Settings

Public Functions

HamiltonianConstructor() = default

Default constructor.

Creates a Hamiltonian constructor with default settings.

virtual ~HamiltonianConstructor() = default

Virtual destructor.

Ensures proper cleanup of derived classes.

virtual std::string name() const = 0

Access the algorithm’s name.

Returns:

The algorithm’s name

inline ReturnType run(Args... args) const

Construct Hamiltonian operator from orbital data.

See also

data::Orbitals

See also

data::Hamiltonian

Note

Settings are automatically locked when this method is called and cannot be modified during or after execution.

Throws:

• std::runtime_error – if Hamiltonian construction fails

• std::invalid_argument – if orbital data is incomplete or invalid

• qdk::chemistry::data::SettingsAreLocked – if attempting to modify settings after run) is called

Returns:

The constructed Hamiltonian operator ready for use in quantum chemistry calculations

inline std::string type_name() const final

Access the algorithm’s type name.

Returns:

The algorithm’s type name

struct HamiltonianConstructorFactory : public qdk::chemistry::algorithms::AlgorithmFactory<HamiltonianConstructor, HamiltonianConstructorFactory>

#include <qdk/chemistry/algorithms/hamiltonian.hpp>

Factory class for creating Hamiltonian constructor instances.

The HamiltonianConstructorFactory implements the Factory design pattern to dynamically create and manage different implementations of Hamiltonian constructors. This allows the library to support multiple Hamiltonian construction methods while providing a unified interface for clients.

The factory maintains a registry of constructor implementations identified by string keys. New implementations can be registered at runtime using the register_instance method, and instances can be created using the create method.

Typical usage:

// Register a custom implementation
HamiltonianConstructorFactory::register_instance("my_method", []() {
    return std::make_unique<MyHamiltonianConstructor>();
});

// Create an instance
auto constructor = HamiltonianConstructorFactory::create("my_method");

// Get available implementations
auto available = HamiltonianConstructorFactory::available();

See also

HamiltonianConstructor for the interface implemented by concrete constructors

Public Static Functions

static inline std::string algorithm_type_name()

static inline std::string default_algorithm_name()

static void register_default_instances()

class Localizer : public qdk::chemistry::algorithms::Algorithm<Localizer, std::shared_ptr<data::Wavefunction>, std::shared_ptr<data::Wavefunction>, const std::vector<size_t>&, const std::vector<size_t>&>

#include <qdk/chemistry/algorithms/localization.hpp>

Abstract base class for orbital localization algorithms.

The Localizer class provides a common interface for various orbital localization methods used in quantum chemistry. Orbital localization transforms canonical molecular orbitals (which are typically delocalized across the entire molecule) into localized orbitals that are confined subject to some metric (spatial, bond, etc.).

This class uses the Factory design pattern through LocalizerFactory to allow dynamic creation of different localization algorithms at runtime.

Example usage:

// Create a concrete localizer (e.g., BoysLocalizer)
auto localizer =
qdk::chemistry::algorithms::LocalizerFactory::create_localizer(
  "mp2_natural_orbitals");
// Create indices for all orbitals
auto all_indices = wavefunction->orbitals->get_all_mo_indices();
auto localized_orbital_wavefunction = localizer->run(wavefunction,
  all_indices, all_indices);

Public Functions

Localizer() = default

Default constructor.

virtual ~Localizer() = default

Virtual destructor for proper inheritance.

virtual std::string name() const = 0

Access the algorithm’s name.

Returns:

The algorithm’s name

inline ReturnType run(Args... args) const

Localize the given molecular orbitals.

Note

Settings are automatically locked when this method is called and cannot be modified during or after execution.

Note

The specific requirements for the inputs and settings affecting this method may vary by implementation. See the documentation for the specific localizer being used (docstring).

Note

The number of electrons is an input for the MP2NaturalOrbitalLocalizer and VVHVLocalizer. Orbital indices < n_alpha_electrons/n_beta_electrons are treated as occupied, indices >= n_alpha_electrons/n_beta_electrons are treated as virtual.

Note

For restricted orbitals, loc_indices_a and loc_indices_b must be identical

Note

All localizer implementations require sorted index arrays for performance and consistency reasons

Throws:

• std::runtime_error – If localization fails

• std::invalid_argument – If the input orbitals are invalid for the specified instance of the localizer

• qdk::chemistry::data::SettingsAreLocked – if attempting to modify settings after run() is called

• std::invalid_argument – If loc_indices_a or loc_indices_b are not sorted

• qdk::chemistry::data::SettingsAreLocked – if attempting to modify settings after run() is called

Returns:

The localized molecular orbitals with updated coefficients.

inline std::string type_name() const final

Access the algorithm’s type name.

Returns:

The algorithm’s type name

struct LocalizerFactory : public qdk::chemistry::algorithms::AlgorithmFactory<Localizer, LocalizerFactory>

#include <qdk/chemistry/algorithms/localization.hpp>

Factory class for creating localizer instances.

This class provides a mechanism to create localizer instances based on a string key. It allows for easy extension and registration of different localization implementations.

Public Static Functions

static inline std::string algorithm_type_name()

static inline std::string default_algorithm_name()

static void register_default_instances()

class MultiConfigurationCalculator : public qdk::chemistry::algorithms::Algorithm<MultiConfigurationCalculator, std::pair<double, std::shared_ptr<data::Wavefunction>>, std::shared_ptr<data::Hamiltonian>, unsigned int, unsigned int>

#include <qdk/chemistry/algorithms/mc.hpp>

Abstract base class for multi-configurational calculations in quantum chemistry.

This class provides the interface for multi-configurational-based quantum chemistry calculations. It serves as a base for various multi-configurational methods, such as Complete Active Space CI (CAS-CI), and other multi-reference quantum mechanical algorithms.

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

See also

data::Hamiltonian

See also

data::Wavefunction

See also

data::Settings

Public Functions

MultiConfigurationCalculator() = default

Default constructor.

Creates a multi-configurational calculator with default settings.

virtual ~MultiConfigurationCalculator() = default

Virtual destructor.

Ensures proper cleanup of derived classes.

virtual std::string name() const = 0

Access the algorithm’s name.

Returns:

The algorithm’s name

inline ReturnType run(Args... args) const

Perform multi-configurational calculation.

This method is auto-generated by the Algorithm base class and automatically locks settings before execution, then delegates to _run_impl().

See also

data::Hamiltonian

See also

data::Wavefunction

Note

Settings are automatically locked when this method is called and cannot be modified during or after execution.

Throws:

• std::runtime_error – if the calculation fails

• std::invalid_argument – if hamiltonian is invalid

• qdk::chemistry::data::SettingsAreLocked – if attempting to modify settings after run() is called

Returns:

A pair containing the calculated energy (first) and the resulting multi-configurational wavefunction (second)

inline std::string type_name() const final

Access the algorithm’s type name.

Returns:

The algorithm’s type name

struct MultiConfigurationCalculatorFactory : public qdk::chemistry::algorithms::AlgorithmFactory<MultiConfigurationCalculator, MultiConfigurationCalculatorFactory>

#include <qdk/chemistry/algorithms/mc.hpp>

Factory class for creating multi-configurational calculator instances.

The MultiConfigurationCalculatorFactory implements the Factory design pattern to dynamically create and manage different implementations of multi-configurational calculators. This allows the library to support multiple MC calculation methods while providing a unified interface for clients.

The factory maintains a registry of calculator implementations identified by string keys. New implementations can be registered at runtime using the register_builder method, and instances can be created using the create method.

Typical usage:

// Register a custom implementation
MultiConfigurationCalculatorFactory::register_instance("my_method", []() {
    return std::make_unique<MyMultiConfigurationCalculator>();
});

// Create an instance
auto calculator = MultiConfigurationCalculatorFactory::create("my_method");

// Get available implementations
auto available = MultiConfigurationCalculatorFactory::available();

See also

MultiConfigurationCalculator for the interface implemented by concrete calculators

Public Static Functions

static inline std::string algorithm_type_name()

static inline std::string default_algorithm_name()

static void register_default_instances()

class MultiConfigurationScf : public qdk::chemistry::algorithms::Algorithm<MultiConfigurationScf, std::pair<double, std::shared_ptr<data::Wavefunction>>, std::shared_ptr<data::Orbitals>, std::shared_ptr<HamiltonianConstructor>, std::shared_ptr<MultiConfigurationCalculator>, unsigned int, unsigned int>

#include <qdk/chemistry/algorithms/mcscf.hpp>

Abstract base class for multi-configurational Self-Consistent Field (MCSCF) calculations.

The MultiConfigurationScf class provides an interface for multi-configurational Self-Consistent Field methods that simultaneously optimize both the molecular orbital coefficients and the configuration interaction coefficients.

The solver takes a Hamiltonian as input and produces the optimized energy and multi-configurational wavefunction.

Typical usage:

TODO 

See also

data::Hamiltonian

See also

data::Wavefunction

See also

data::Settings

Public Functions

MultiConfigurationScf() = default

Default constructor.

Creates an MultiConfigurationScf solver with default settings.

virtual ~MultiConfigurationScf() = default

Virtual destructor.

Ensures proper cleanup of derived classes.

virtual std::string name() const = 0

Access the algorithm’s name.

Returns:

The algorithm’s name

inline ReturnType run(Args... args) const

Perform an MultiConfigurationScf calculation.

This pure virtual method must be implemented by derived classes to perform the MultiConfigurationScf calculation, which optimizes both orbital and CI coefficients. The method takes a Hamiltonian describing the quantum system and returns both the calculated energy and the optimized multi-configurational wavefunction, including both optimized orbital coefficients and CI coefficients.

See also

data::Hamiltonian

See also

data::Wavefunction

Note

This method is const as it should not modify the solver’s state

Note

The specific requirements for the inputs and settings affecting this method may vary by implementation. See the documentation for the specific MultiConfigurationScf solver being used (docstring).

Throws:

• std::runtime_error – if calculation fails to converge

• std::invalid_argument – if hamiltonian is invalid

Returns:

A pair containing the calculated energy (first) and the resulting multi-configurational wavefunction (second)

inline std::string type_name() const final

Access the algorithm’s type name.

Returns:

The algorithm’s type name

struct MultiConfigurationScfFactory : public qdk::chemistry::algorithms::AlgorithmFactory<MultiConfigurationScf, MultiConfigurationScfFactory>

#include <qdk/chemistry/algorithms/mcscf.hpp>

Factory class for creating MultiConfigurationScf solver instances.

The MultiConfigurationScfFactory implements the Factory design pattern to dynamically create and manage different implementations of MultiConfigurationScf solvers. This allows the library to support multiple MultiConfigurationScf methods while providing a unified interface for clients.

The factory maintains a registry of solver implementations identified by string keys. New implementations can be registered at runtime using the register_builder method, and instances can be created using the create method.

Typical usage:

// Register a custom implementation
MultiConfigurationScfFactory::register_instance("my_mcscf", []() {
    return std::make_unique<MyMultiConfigurationScf>();
});

// Create an instance
auto mcscf = MultiConfigurationScfFactory::create("my_mcscf");

See also

MultiConfigurationScf for the interface implemented by concrete solvers

Public Static Functions

static inline std::string algorithm_type_name()

static inline std::string default_algorithm_name()

static inline void register_default_instances()

class MultiConfigurationSettings : public qdk::chemistry::data::Settings

#include <qdk/chemistry/algorithms/mc.hpp>

Settings class specific to multi-configurational calculations.

This class extends the base Settings class with parameters specific to multi-configurational calculations. It provides default values for commonly used settings in MC calculations such as reduced density matrix generation and convergence thresholds.

See also

data::Settings

Subclassed by qdk::chemistry::algorithms::ProjectedMultiConfigurationSettings

Public Functions

inline MultiConfigurationSettings()

Default constructor.

Creates a multi-configurational settings object with default parameter values.

virtual ~MultiConfigurationSettings() = default

Virtual destructor.

class ProjectedMultiConfigurationCalculator : public qdk::chemistry::algorithms::Algorithm<ProjectedMultiConfigurationCalculator, std::pair<double, std::shared_ptr<data::Wavefunction>>, std::shared_ptr<data::Hamiltonian>, const std::vector<data::Configuration>&>

#include <qdk/chemistry/algorithms/pmc.hpp>

Abstract base class for projected multi-configurational 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 energy and the corresponding multi-configurational wavefunction.

See also

data::Hamiltonian

See also

data::Wavefunction

See also

data::Settings

Public Functions

ProjectedMultiConfigurationCalculator() = default

Default constructor.

Creates a projected multi-configurational calculator with default settings.

virtual ~ProjectedMultiConfigurationCalculator() = default

Virtual destructor.

Ensures proper cleanup of derived classes.

virtual std::string name() const = 0

Access the algorithm’s name.

Returns:

The algorithm’s name

inline ReturnType run(Args... args) const

Perform projected multi-configurational calculation.

See also

data::Hamiltonian

See also

data::Wavefunction

See also

data::Configuration

Note

Settings are automatically locked when this method is called and cannot be modified during or after execution.

Throws:

• std::runtime_error – if the calculation fails

• std::invalid_argument – if hamiltonian is invalid

• std::invalid_argument – if configurations is invalid

• qdk::chemistry::data::SettingsAreLocked – if attempting to modify settings after run() is called

Returns:

A pair containing the calculated energy (first) and the resulting multi-configurational wavefunction (second)

inline std::string type_name() const final

Access the algorithm’s type name.

Returns:

The algorithm’s type name

struct ProjectedMultiConfigurationCalculatorFactory : public qdk::chemistry::algorithms::AlgorithmFactory<ProjectedMultiConfigurationCalculator, ProjectedMultiConfigurationCalculatorFactory>

#include <qdk/chemistry/algorithms/pmc.hpp>

Factory class for creating projected multi-configurational calculator instances.

The ProjectedMultiConfigurationCalculatorFactory implements the Factory design pattern to dynamically create and manage different implementations of projected multi-configurational calculators. This allows the library to support multiple PMC calculation methods while providing a unified interface for clients.

The factory maintains a registry of calculator implementations identified by string keys. New implementations can be registered at runtime using the register_builder method, and instances can be created using the create method.

Typical usage:

// Register a custom implementation
ProjectedMultiConfigurationCalculatorFactory::register_instance("my_method",
[]() { return std::make_unique<MyProjectedMultiConfigurationCalculator>();
});

// Create an instance
auto calculator =
ProjectedMultiConfigurationCalculatorFactory::create("my_method");

// Get available implementations
auto available = ProjectedMultiConfigurationCalculatorFactory::available();

See also

ProjectedMultiConfigurationCalculator for the interface implemented by concrete calculators

Public Static Functions

static inline std::string algorithm_type_name()

static inline std::string default_algorithm_name()

static void register_default_instances()

class ProjectedMultiConfigurationSettings : public qdk::chemistry::algorithms::MultiConfigurationSettings

#include <qdk/chemistry/algorithms/pmc.hpp>

Settings class specific to multi-configurational calculations.

This class extends the base Settings class with parameters specific to projected multi-configurational calculations. It provides default values for commonly used settings in PMC calculations such as reduced density matrix generation and convergence thresholds.

See also

data::Settings

Public Functions

inline ProjectedMultiConfigurationSettings()

Default constructor.

Creates a multi-configurational settings object with default parameter values. It inherits default settings from MultiConfigurationSettings.

virtual ~ProjectedMultiConfigurationSettings() = default

Virtual destructor.

class ScfSolver : public qdk::chemistry::algorithms::Algorithm<ScfSolver, std::pair<double, std::shared_ptr<data::Wavefunction>>, std::shared_ptr<data::Structure>, int, int, BasisOrGuessType>

#include <qdk/chemistry/algorithms/scf.hpp>

Abstract base class for Self-Consistent Field (SCF) solvers.

The ScfSolver class provides a common interface for various SCF algorithms used in quantum chemistry calculations. This class uses the Factory design pattern to enable the dynamic creation of different SCF solver implementations.

The solver takes a molecular structure as input and produces the converged total energy (electronic + nuclear repulsion) and corresponding molecular orbitals and single determinant wavefunction.

Example usage:

// Create a concrete SCF solver (e.g., HartreeFockSolver)
auto scf_solver = qdk::chemistry::ScfSolver::create("default");

// Configure solver settings
scf_solver->settings().set("max_iterations", 100);

// Perform SCF calculation
auto [energy, wavefunction] = scf_solver->run(molecular_structure, 0, 1,
"cc-pvdz");

std::cout << "SCF Total Energy: " << energy << " Hartree" << std::endl;

Public Functions

inline ScfSolver()

Default constructor.

virtual ~ScfSolver() = default

Virtual destructor for proper inheritance.

virtual std::string name() const = 0

Access the algorithm’s name.

Returns:

The algorithm’s name

inline ReturnType run(Args... args) const

Solve the SCF equations for a given molecular structure.

This method performs the iterative SCF procedure to find the self-consistent molecular orbitals and total energy.

The specific algorithm (HF, DFT, etc.) is determined by the concrete implementation.

Note

Settings are automatically locked when this method is called and cannot be modified during or after execution.

Note

The specific requirements for the inputs and settings affecting the SCF calculation may vary by implementation. See the documentation for the specific SCF solver being used.

Throws:

• std::runtime_error – If SCF fails to converge

• std::invalid_argument – If the input structure is invalid

• qdk::chemistry::data::SettingsAreLocked – If attempting to modify settings after run() is called

Returns:

A pair containing:

• double: The converged total energy in Hartree

• data::Wavefunction: The converged wavefunction, including orbitals, their energies, coefficients, and occupancies

inline std::string type_name() const final

Access the algorithm’s type name.

Returns:

The algorithm’s type name

struct ScfSolverFactory : public qdk::chemistry::algorithms::AlgorithmFactory<ScfSolver, ScfSolverFactory>

#include <qdk/chemistry/algorithms/scf.hpp>

Factory class for creating SCF solvers.

Public Static Functions

static inline std::string algorithm_type_name()

static inline std::string default_algorithm_name()

static void register_default_instances()

class StabilityChecker : public qdk::chemistry::algorithms::Algorithm<StabilityChecker, std::pair<bool, std::shared_ptr<data::StabilityResult>>, std::shared_ptr<data::Wavefunction>>

#include <qdk/chemistry/algorithms/stability.hpp>

Abstract base class for wavefunction stability checking algorithms with respect to orbital rotation.

The StabilityChecker class provides a common interface for various stability checking methods used in quantum chemistry. Stability checking examines the second-order response of a wavefunction to determine if it corresponds to a true minimum or if there are directions in which the energy can be lowered.

This class uses the Factory design pattern through StabilityCheckerFactory to allow dynamic creation of different stability checking algorithms at runtime.

Example usage:

// Create a concrete stability checker
auto checker =
qdk::chemistry::algorithms::StabilityCheckerFactory::create("pyscf");

// Configure checker settings
checker->settings().set("nroots", 5);

// Perform stability check
auto [is_stable, result] = checker->run(wavefunction);

if (is_stable) {
  std::cout << "Wavefunction is stable" << std::endl;
} else {
  std::cout << "Wavefunction is unstable" << std::endl;
}
auto smallest_eigenvalue = result->get_smallest_eigenvalue();
std::cout << "Smallest eigenvalue: " << smallest_eigenvalue << std::endl;

Public Functions

StabilityChecker() = default

Default constructor.

virtual ~StabilityChecker() = default

Virtual destructor for proper inheritance.

virtual std::string name() const override = 0

inline ReturnType run(Args... args) const

Check the stability of the given wavefunction with respect to orbital rotation.

This method performs stability analysis on the input wavefunction by examining the eigenvalues of the electronic Hessian matrix. A stable wavefunction should have all non-negative eigenvalues. Near-zero eigenvalues may indicate orbital degeneracy.

The specific algorithm (PySCF-based, etc.) is determined by the concrete implementation.

Note

Settings are automatically locked when this method is called and cannot be modified during or after execution.

Note

The specific requirements for the inputs and settings affecting the stability check may vary by implementation. See the documentation for the specific stability checker being used.

Throws:

• std::runtime_error – If stability analysis fails

• std::invalid_argument – If the input wavefunction is invalid for the specified instance of the stability checker

• qdk::chemistry::data::SettingsAreLocked – If attempting to modify settings after run() is called

Returns:

A pair containing:

• bool: Overall stability status (true if stable, false if unstable)

• data::StabilityResult: Detailed stability information including eigenvalues and eigenvectors of the stability matrix, which can be used to start a new SCF calculation if an instability is detected.

inline std::string type_name() const override

struct StabilityCheckerFactory : public qdk::chemistry::algorithms::AlgorithmFactory<StabilityChecker, StabilityCheckerFactory>

#include <qdk/chemistry/algorithms/stability.hpp>

Factory class for creating stability checker instances.

This class provides a mechanism to create stability checker instances based on a string key. It allows for easy extension and registration of different stability checking implementations.

Public Static Functions

static inline std::string algorithm_type_name()

static inline std::string default_algorithm_name()

static void register_default_instances()

namespace detail

Functions

std::vector<size_t> _get_inactive_space_indices(size_t nelec, const std::vector<size_t> &active_space_indices)

Helper function to determine inactive space indices for restricted orbitals.

Parameters:

• nelec – Number of electrons

• active_space_indices – Active space orbital indices

Returns:

Vector of inactive space orbital indices

std::pair<std::vector<size_t>, std::vector<size_t>> _get_inactive_space_indices(size_t nelec_a, size_t nelec_b, const std::vector<size_t> &active_space_indices_a, const std::vector<size_t> &active_space_indices_b)

Helper function to determine inactive space indices for unrestricted orbitals.

Parameters:

• nelec_a – Number of alpha electrons

• nelec_b – Number of beta electrons

• active_space_indices_a – Alpha active space orbital indices

• active_space_indices_b – Beta active space orbital indices

Returns:

Pair of vectors containing (alpha_inactive_space_indices, beta_inactive_space_indices)

std::tuple<double, std::vector<size_t>, Eigen::VectorXd> _sort_entropies_and_indices(std::shared_ptr<data::Wavefunction> wavefunction, bool normalize_entropies)

Helper function to sort entropies and their corresponding orbital indices in descending order.

Parameters:

• wavefunction – The wavefunction containing orbital entropies and indices.

• normalize_entropies – If true, normalize entropies by the maximum entropy value.

Throws:

std::runtime_error – if the wavefunction does not have single orbital entropies.

Returns:

A pair containing a vector of sorted orbital indices and a vector of sorted entropies.

std::shared_ptr<data::Orbitals> new_orbitals(std::shared_ptr<data::Wavefunction> wavefunction, const std::vector<size_t> &active_space_indices_a, const std::optional<std::vector<size_t>> &active_space_indices_b = std::nullopt)

Create a new Orbitals object with the specified active space indices.

Parameters:

• wavefunction – The wavefunction containing the orbitals.

• active_space_indices_a – The active space orbital indices for alpha electrons.

• active_space_indices_b – The active space orbital indices for beta electrons (optional for restricted orbitals).

Returns:

A new Orbitals object with the specified active space indices.

std::shared_ptr<data::Wavefunction> new_wavefunction(std::shared_ptr<data::Wavefunction> wavefunction, std::shared_ptr<data::Orbitals> new_orbitals)

Create a new Wavefunction object with updated orbitals.

Generate a new Wavefunction by replacing the orbitals of the given wavefunction with the provided new orbitals, keeping the identical total, determinants.

Parameters:

• wavefunction – The original wavefunction.

• new_orbitals – The new orbitals to set in the wavefunction.

Returns:

A new Wavefunction object with the updated orbitals.