Namespace qdk::chemistry::data

namespace data

Typedefs

using Constraint = std::variant<BoundConstraint<int64_t>, ListConstraint<int64_t>, BoundConstraint<double>, ListConstraint<std::string>>: Type for specifying limits on setting values.

using SettingValue = std::variant<bool, int64_t, double, std::string, std::vector<int64_t>, std::vector<double>, std::vector<std::string>>

Type-safe variant for storing different setting value types.

This variant can hold common types used in settings configurations. Note: All integer types are stored internally as int64_t (signed). Other integer types can be requested via get() with automatic conversion.

Enums

enum class AOType

Enumeration for atomic orbital types (spherical vs cartesian)

Values:

enumerator Spherical: Spherical harmonics (2l+1 functions per shell)

enumerator Cartesian: Cartesian coordinates (more functions for l>=2)

enum class Element : unsigned

Enumeration for chemical elements in the periodic table (1-118)

Values:

enumerator H

enumerator He

enumerator Li

enumerator Be

enumerator B

enumerator C

enumerator N

enumerator O

enumerator F

enumerator Ne

enumerator Na

enumerator Mg

enumerator Al

enumerator Si

enumerator P

enumerator S

enumerator Cl

enumerator Ar

enumerator K

enumerator Ca

enumerator Sc

enumerator Ti

enumerator V

enumerator Cr

enumerator Mn

enumerator Fe

enumerator Co

enumerator Ni

enumerator Cu

enumerator Zn

enumerator Ga

enumerator Ge

enumerator As

enumerator Se

enumerator Br

enumerator Kr

enumerator Rb

enumerator Sr

enumerator Y

enumerator Zr

enumerator Nb

enumerator Mo

enumerator Tc

enumerator Ru

enumerator Rh

enumerator Pd

enumerator Ag

enumerator Cd

enumerator In

enumerator Sn

enumerator Sb

enumerator Te

enumerator I

enumerator Xe

enumerator Cs

enumerator Ba

enumerator La

enumerator Ce

enumerator Pr

enumerator Nd

enumerator Pm

enumerator Sm

enumerator Eu

enumerator Gd

enumerator Tb

enumerator Dy

enumerator Ho

enumerator Er

enumerator Tm

enumerator Yb

enumerator Lu

enumerator Hf

enumerator Ta

enumerator W

enumerator Re

enumerator Os

enumerator Ir

enumerator Pt

enumerator Au

enumerator Hg

enumerator Tl

enumerator Pb

enumerator Bi

enumerator Po

enumerator At

enumerator Rn

enumerator Fr

enumerator Ra

enumerator Ac

enumerator Th

enumerator Pa

enumerator U

enumerator Np

enumerator Pu

enumerator Am

enumerator Cm

enumerator Bk

enumerator Cf

enumerator Es

enumerator Fm

enumerator Md

enumerator No

enumerator Lr

enumerator Rf

enumerator Db

enumerator Sg

enumerator Bh

enumerator Hs

enumerator Mt

enumerator Ds

enumerator Rg

enumerator Cn

enumerator Nh

enumerator Fl

enumerator Mc

enumerator Lv

enumerator Ts

enumerator Og

enum class HamiltonianType

Types of Hamiltonians supported.

Values:

enumerator Hermitian

enumerator NonHermitian

enum class OrbitalType

Enumeration for different types of atomic orbitals.

Values:

enumerator UL: ECP local potential (l=-1)

enumerator S: S orbital (angular momentum l=0)

enumerator P: P orbital (angular momentum l=1)

enumerator D: D orbital (angular momentum l=2)

enumerator F: F orbital (angular momentum l=3)

enumerator G: G orbital (angular momentum l=4)

enumerator H: H orbital (angular momentum l=5)

enumerator I: I orbital (angular momentum l=6)

enum class SpinChannel

Spin channels for one and two-electron integrals.

Values:

enumerator aa

enumerator bb

enumerator aaaa

enumerator aabb

enumerator bbbb

enum class WavefunctionType

Enum to distinguish between different wavefunction representations.

This enum allows tagging wavefunctions based on their mathematical role:

SelfDual: Wavefunctions that can be used as both bra and ket
NotSelfDual: Wavefunctions that are strictly bra or ket

This distinction maps to the use of hermitian or non-hermitian operators.

Values:

enumerator SelfDual

enumerator NotSelfDual

Functions

constexpr const char *get_current_ciaaw_version()

Variables

const std::unordered_map<unsigned, std::string> CHARGE_TO_SYMBOL

template<typename T> constexpr bool is_non_bool_integral_v = NonBoolIntegral<T>

Helper variable template for non-bool integral (for backward compatibility)

Template Parameters:: T – The type to check

template<typename T> constexpr bool is_non_bool_integral_vector_v = NonBoolIntegralVector<T>

Helper variable template for non-bool integral vector (for backward compatibility)

Template Parameters:: T – The type to check

template<typename T, typename Variant> constexpr bool is_variant_member_v = VariantMember<T, Variant>

Helper variable template for variant member check.

Template Parameters:

T – The type to check
Variant – The variant type to check against

template<typename T> constexpr bool is_vector_v = Vector<T>

Helper variable template for is_vector (for backward compatibility)

Template Parameters:: T – The type to check

static constexpr size_t MAX_ORBITAL_ANGULAR_MOMENTUM = 6: Maximum angular momentum for atomic orbitals supported in QDK/Chemistry.

std::unordered_map<std::string, unsigned> SYMBOL_TO_CHARGE

class Ansatz : public qdk::chemistry::data::DataClass, public std::enable_shared_from_this<Ansatz>

#include <qdk/chemistry/data/ansatz.hpp>

Represents a quantum chemical ansatz combining a Hamiltonian and wavefunction.

This class represents a complete quantum chemical ansatz, which consists of:

A Hamiltonian operator describing the system’s energy
A wavefunction describing the quantum state

The class is immutable after construction, meaning all data must be provided during construction and cannot be modified afterwards. This ensures consistency between the Hamiltonian and wavefunction throughout the calculation.

Common use cases:

Configuration interaction (CI) methods
Multi-configuration self-consistent field (MultiConfigurationScf) calculations
Coupled cluster calculations
Energy expectation value computations

Public Functions

Ansatz(Ansatz &&other) noexcept = default: Move constructor.

Ansatz(const Ansatz &other): Copy constructor.

Ansatz(const Hamiltonian &hamiltonian, const Wavefunction &wavefunction)

Constructor with Hamiltonian and Wavefunction objects.

Parameters:

hamiltonian – The Hamiltonian operator for the system
wavefunction – The wavefunction describing the quantum state

Throws:

std::invalid_argument – if orbital dimensions are inconsistent between Hamiltonian and wavefunction

Ansatz(std::shared_ptr<Hamiltonian> hamiltonian, std::shared_ptr<Wavefunction> wavefunction)

Constructor with shared pointers to Hamiltonian and Wavefunction.

Parameters:

hamiltonian – Shared pointer to the Hamiltonian operator
wavefunction – Shared pointer to the wavefunction

Throws:

std::invalid_argument – if pointers are nullptr or orbital dimensions are inconsistent

virtual ~Ansatz() = default: Destructor.

double calculate_energy() const

Calculate the energy expectation value ⟨ψ|H|ψ⟩

Note

This method will be implemented once energy calculation algorithms are available

Throws:: std::runtime_error – if calculation cannot be performed
Returns:: Energy expectation value in atomic units

std::shared_ptr<Hamiltonian> get_hamiltonian() const

Get shared pointer to the Hamiltonian.

Throws:: std::runtime_error – if Hamiltonian is not set
Returns:: Shared pointer to the Hamiltonian object

std::shared_ptr<Orbitals> get_orbitals() const

Get shared pointer to the orbital basis set from the Hamiltonian.

Throws:: std::runtime_error – if orbitals are not available
Returns:: Shared pointer to the Orbitals object

virtual std::string get_summary() const override

Get a summary string describing the Ansatz.

Returns:: Human-readable summary of the Ansatz

std::shared_ptr<Wavefunction> get_wavefunction() const

Get shared pointer to the wavefunction.

Throws:: std::runtime_error – if wavefunction is not set
Returns:: Shared pointer to the Wavefunction object

bool has_hamiltonian() const

Check if Hamiltonian is available.

Returns:: True if Hamiltonian is set

bool has_orbitals() const

Check if orbital data is available.

Returns:: True if orbitals are set in both Hamiltonian and wavefunction

bool has_wavefunction() const

Check if wavefunction is available.

Returns:: True if wavefunction is set

Ansatz &operator=(Ansatz &&other) noexcept = default: Move assignment operator.

Ansatz &operator=(const Ansatz &other): Copy assignment operator.

virtual void to_file(const std::string &filename, const std::string &type) const override

Generic file I/O - save to file based on type parameter.

Parameters:

filename – Path to file to create/overwrite
type – File format type (“json” or “hdf5”)

Throws:

std::runtime_error – if unsupported type or I/O error occurs

virtual void to_hdf5(H5::Group &group) const override

Serialize Ansatz to HDF5 group.

Parameters:: group – HDF5 group to write data to
Throws:: std::runtime_error – if I/O error occurs

virtual void to_hdf5_file(const std::string &filename) const override

Save Ansatz to HDF5 file (with validation)

Parameters:: filename – Path to HDF5 file to create/overwrite
Throws:: std::runtime_error – if I/O error occurs

virtual nlohmann::json to_json() const override

Convert Ansatz to JSON.

Returns:: JSON object containing Ansatz data

virtual void to_json_file(const std::string &filename) const override

Save Ansatz to JSON file (with validation)

Parameters:: filename – Path to JSON file to create/overwrite
Throws:: std::runtime_error – if I/O error occurs

void validate_orbital_consistency() const

Validate orbital consistency between Hamiltonian and wavefunction.

Throws:: std::runtime_error – if orbital dimensions are inconsistent

Public Static Functions

static std::shared_ptr<Ansatz> from_file(const std::string &filename, const std::string &type)

Generic file I/O - load from file based on type parameter.

Parameters:

filename – Path to file to read
type – File format type (“json” or “hdf5”)

Throws:

std::runtime_error – if file doesn’t exist, unsupported type, or I/O error occurs

Returns:

New Ansatz loaded from file

static std::shared_ptr<Ansatz> from_hdf5(H5::Group &group)

Load Ansatz from HDF5 group.

Parameters:: group – HDF5 group to read data from
Throws:: std::runtime_error – if I/O error occurs
Returns:: Shared pointer to const Ansatz loaded from group

static std::shared_ptr<Ansatz> from_hdf5_file(const std::string &filename)

Load Ansatz from HDF5 file (with validation)

Parameters:: filename – Path to HDF5 file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: Shared pointer to const Ansatz loaded from file

static std::shared_ptr<Ansatz> from_json(const nlohmann::json &j)

Load Ansatz from JSON.

Parameters:: j – JSON object containing Ansatz data
Throws:: std::runtime_error – if JSON is malformed
Returns:: Shared pointer to const Ansatz loaded from JSON

static std::shared_ptr<Ansatz> from_json_file(const std::string &filename)

Load Ansatz from JSON file (with validation)

Parameters:: filename – Path to JSON file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: Shared pointer to const Ansatz loaded from file

class BasisSet : public qdk::chemistry::data::DataClass, public std::enable_shared_from_this<BasisSet>

#include <qdk/chemistry/data/basis_set.hpp>

Represents an atomic orbital basis set using shell-based organization.

This class stores and manages atomic orbital basis set information using shells as the primary organizational unit. A shell represents a group of atomic orbitals with the same atom, angular momentum, and primitives. The class is designed to be immutable after construction, ensuring data integrity.

Features:

Shell-based storage for memory efficiency
Support for spherical or cartesian atomic orbitals
Mapping between shells/atomic orbitals and atoms
Mapping between shells/atomic orbitals and orbital types
Basis set metadata (name, parameters, references)
Integration with molecular structure information
On-demand expansion of shells to individual atomic orbitals

The shell-based approach matches standard quantum chemistry practices and provides efficient storage and computation.

Public Functions

BasisSet(BasisSet &&other) noexcept = default: Move constructor.

BasisSet(const BasisSet &other)

Copy constructor.

Note: this function generates a deep copy of the basis set.

BasisSet(const std::string &name, const std::vector<Shell> &shells, AOType atomic_orbital_type = AOType::Spherical)

Constructor with shells.

Parameters:

name – Name of the basis set
shells – Vector of shells to initialize the basis set with
atomic_orbital_type – Whether to use spherical or cartesian atomic orbitals

BasisSet(const std::string &name, const std::vector<Shell> &shells, const std::string &ecp_name, const std::vector<Shell> &ecp_shells, const std::vector<size_t> &ecp_electrons, const Structure &structure, AOType basis_type = AOType::Spherical)

Constructor with shells, ECP shells, ECP name, ECP electrons, and structure.

Parameters:

name – Name of the basis set
shells – Vector of shells to initialize the basis set with
ecp_name – Name of the ECP basis set
ecp_shells – Vector of ECP shells to initialize the basis set with
ecp_electrons – Vector containing numbers of ECP electrons for each atom
structure – The molecular structure
basis_type – Whether to use spherical or cartesian atomic orbitals

BasisSet(const std::string &name, const std::vector<Shell> &shells, const std::string &ecp_name, const std::vector<Shell> &ecp_shells, const std::vector<size_t> &ecp_electrons, std::shared_ptr<Structure> structure, AOType basis_type = AOType::Spherical)

Constructor with shells, ECP shells, ECP name, ECP electrons, and structure shared pointer.

Parameters:

name – Name of the basis set
shells – Vector of shells to initialize the basis set with
ecp_shells – Vector of ECP shells to initialize the basis set with
ecp_name – Name of the ECP basis set
ecp_electrons – Vector containing numbers of ECP electrons for each atom
structure – Shared pointer to the molecular structure
basis_type – Whether to use spherical or cartesian atomic orbitals

BasisSet(const std::string &name, const std::vector<Shell> &shells, const std::vector<Shell> &ecp_shells, const Structure &structure, AOType basis_type = AOType::Spherical)

Constructor with shells, ECP shells, and structure.

Parameters:

name – Name of the basis set
shells – Vector of shells to initialize the basis set with
ecp_shells – Vector of ECP shells to initialize the basis set with
structure – The molecular structure
basis_type – Whether to use spherical or cartesian atomic orbitals

BasisSet(const std::string &name, const std::vector<Shell> &shells, const std::vector<Shell> &ecp_shells, std::shared_ptr<Structure> structure, AOType basis_type = AOType::Spherical)

Constructor with shells, ECP shells, and structure shared pointer.

Parameters:

name – Name of the basis set
shells – Vector of shells to initialize the basis set with
ecp_shells – Vector of ECP shells to initialize the basis set with
structure – Shared pointer to the molecular structure
basis_type – Whether to use spherical or cartesian atomic orbitals

BasisSet(const std::string &name, const std::vector<Shell> &shells, const Structure &structure, AOType atomic_orbital_type = AOType::Spherical)

Constructor with shells and structure.

Parameters:

name – Name of the basis set
shells – Vector of shells to initialize the basis set with
structure – The molecular structure
atomic_orbital_type – Whether to use spherical or cartesian atomic orbitals

BasisSet(const std::string &name, const std::vector<Shell> &shells, std::shared_ptr<Structure> structure, AOType atomic_orbital_type = AOType::Spherical)

Constructor with shells and structure shared pointer.

Parameters:

name – Name of the basis set
shells – Vector of shells to initialize the basis set with
structure – Shared pointer to the molecular structure
atomic_orbital_type – Whether to use spherical or cartesian atomic orbitals

BasisSet(const std::string &name, const Structure &structure, AOType atomic_orbital_type = AOType::Spherical)

Constructor with basis set name and structure.

Parameters:

name – Name of the basis set (e.g., “6-31G”, “cc-pVDZ”)
structure – The molecular structure
atomic_orbital_type – Whether to use spherical or cartesian atomic orbitals

BasisSet(const std::string &name, std::shared_ptr<Structure> structure, AOType atomic_orbital_type = AOType::Spherical)

Constructor with basis set name and structure shared pointer.

Parameters:

name – Name of the basis set (e.g., “6-31G”, “cc-pVDZ”)
structure – Shared pointer to the molecular structure
atomic_orbital_type – Whether to use spherical or cartesian atomic orbitals

virtual ~BasisSet() = default: Default destructor.

std::pair<size_t, int> basis_to_shell_index(size_t atomic_orbital_index) const

Convert atomic orbital index to shell index and magnetic quantum number.

Parameters:: atomic_orbital_index – Global atomic orbital index
Returns:: Pair of (shell_index, magnetic_quantum_number)

size_t get_atom_index_for_atomic_orbital(size_t contracted_atomic_orbital_index) const

Get the atom index for a atomic orbital.

Parameters:: contracted_atomic_orbital_index – Index of the atomic orbital
Throws:: std::out_of_range – if atomic_orbital_index is invalid
Returns:: Index of the atom this atomic orbital belongs to

std::vector<size_t> get_atomic_orbital_indices_for_atom(size_t atom_index) const

Get all atomic orbital indices for a specific atom.

Parameters:: atom_index – Index of the atom
Returns:: Vector of atomic orbital indices for this atom

std::pair<size_t, int> get_atomic_orbital_info(size_t atomic_orbital_index) const

Get the shell index and magnetic quantum number for a atomic orbital index.

Parameters:: atomic_orbital_index – Index of the atomic orbital
Throws:: std::out_of_range – if index is invalid
Returns:: Pair containing (shell_index, magnetic_quantum_number)

AOType get_atomic_orbital_type() const

Get the basis type.

Returns:: Current basis type (spherical or cartesian)

const std::vector<size_t> &get_ecp_electrons() const

Get the ECP electrons vector.

Returns:: Vector containing numbers of ECP electrons for each atom

const std::string &get_ecp_name() const

Get the ECP name.

Returns:: Name of the ECP

const Shell &get_ecp_shell(size_t shell_index) const

Get a specific ECP shell by global index.

Parameters:: shell_index – Global index of the ECP shell
Throws:: std::out_of_range – if index is invalid
Returns:: Reference to the ECP shell

std::vector<size_t> get_ecp_shell_indices_for_atom(size_t atom_index) const

Get ECP shell indices for a specific atom.

Parameters:: atom_index – Index of the atom
Returns:: Vector of ECP shell indices for this atom

std::vector<size_t> get_ecp_shell_indices_for_atom_and_orbital_type(size_t atom_index, OrbitalType orbital_type) const

Get ECP shell indices for a specific atom and orbital type.

Parameters:

atom_index – Index of the atom
orbital_type – Type of orbital

Returns:

Vector of ECP shell indices matching both criteria

std::vector<size_t> get_ecp_shell_indices_for_orbital_type(OrbitalType orbital_type) const

Get ECP shell indices for a specific orbital type.

Parameters:: orbital_type – Type of orbital
Returns:: Vector of ECP shell indices of this type

std::vector<Shell> get_ecp_shells() const

Get all ECP shells (flattened from per-atom storage)

Returns:: Vector of all ECP shells

const std::vector<Shell> &get_ecp_shells_for_atom(size_t atom_index) const

Get ECP shells for a specific atom.

Parameters:: atom_index – Index of the atom
Returns:: Vector of ECP shells for this atom

const std::string &get_name() const

Get the basis set name.

Returns:: Name of the basis set

size_t get_num_atomic_orbitals() const

Get number of atomic orbitals (total from all shells)

Returns:: Total number of atomic orbitals

size_t get_num_atomic_orbitals_for_atom(size_t atom_index) const

Get number of atomic orbitals for a specific atom.

Parameters:: atom_index – Index of the atom
Returns:: Number of atomic orbitals for this atom

size_t get_num_atomic_orbitals_for_orbital_type(OrbitalType orbital_type) const

Get number of atomic orbitals for a specific orbital type.

Parameters:: orbital_type – Type of orbital
Returns:: Number of atomic orbitals of this type

size_t get_num_atoms() const

Get number of atoms that have shells.

Returns:: Number of atoms with shells

size_t get_num_ecp_shells() const

Get total number of ECP shells across all atoms.

Returns:: Total number of ECP shells

size_t get_num_shells() const

Get total number of shells across all atoms.

Returns:: Total number of shells

const Shell &get_shell(size_t shell_index) const

Get a specific shell by global index.

Parameters:: shell_index – Global index of the shell
Throws:: std::out_of_range – if index is invalid
Returns:: Reference to the shell

std::vector<size_t> get_shell_indices_for_atom(size_t atom_index) const

Get shell indices for a specific atom.

Parameters:: atom_index – Index of the atom
Returns:: Vector of shell indices for this atom

std::vector<size_t> get_shell_indices_for_atom_and_orbital_type(size_t atom_index, OrbitalType orbital_type) const

Get shell indices for a specific atom and orbital type.

Parameters:

atom_index – Index of the atom
orbital_type – Type of orbital

Returns:

Vector of shell indices matching both criteria

std::vector<size_t> get_shell_indices_for_orbital_type(OrbitalType orbital_type) const

Get shell indices for a specific orbital type.

Parameters:: orbital_type – Type of orbital
Returns:: Vector of shell indices of this type

std::vector<Shell> get_shells() const

Get all shells (flattened from per-atom storage)

Returns:: Vector of all shells

const std::vector<Shell> &get_shells_for_atom(size_t atom_index) const

Get shells for a specific atom.

Parameters:: atom_index – Index of the atom
Returns:: Vector of shells for this atom

const std::shared_ptr<Structure> get_structure() const

Get the molecular structure.

Throws:: std::runtime_error – if no structure is set
Returns:: Pointer to the molecular structure

virtual std::string get_summary() const override

Get summary string of basis set information.

Returns:: String describing the basis set

bool has_ecp_electrons() const

Check if ECP electrons are present.

Returns:: True if ECP electrons are present

bool has_ecp_shells() const

Check if this basis set has ECP shells.

Returns:: True if there are any ECP shells

bool has_structure() const

Check if a structure is associated with this basis set.

Returns:: True if structure is set

BasisSet &operator=(BasisSet &&other) noexcept = default: Move assignment operator.

BasisSet &operator=(const BasisSet &other)

Copy assignment operator.

Note: this function generates a deep copy of the basis set.

virtual void to_file(const std::string &filename, const std::string &type) const override

Generic file I/O - save to file based on type parameter.

Parameters:

filename – Path to file to create/overwrite
type – File format type (“json” or “hdf5”)

Throws:

std::runtime_error – if unsupported type or I/O error occurs

virtual void to_hdf5(H5::Group &group) const override

Serialize basis set to HDF5 group.

Parameters:: group – HDF5 group to write data to
Throws:: std::runtime_error – if I/O error occurs

virtual void to_hdf5_file(const std::string &filename) const override

Save basis set to HDF5 file (with validation)

Parameters:: filename – Path to HDF5 file to create/overwrite
Throws:: std::runtime_error – if I/O error occurs

virtual nlohmann::json to_json() const override

Convert basis set to JSON.

Returns:: JSON object containing basis set data

virtual void to_json_file(const std::string &filename) const override

Save basis set to JSON file (with validation)

Parameters:: filename – Path to JSON file to create/overwrite
Throws:: std::runtime_error – if I/O error occurs

Public Static Functions

static std::string atomic_orbital_type_to_string(AOType atomic_orbital_type)

Convert basis type to string.

Parameters:: atomic_orbital_type – The basis type to convert
Returns:: String representation (“spherical” or “cartesian”)

static std::shared_ptr<BasisSet> from_basis_name(const std::string &basis_name, const Structure &structure, const std::string &ecp_name = std::string(default_ecp_name), AOType atomic_orbital_type = AOType::Spherical)

Constructor with basis set name and structure.

Parameters:

basis_name – Name of the basis set (e.g., “6-31G”, “cc-pVDZ”)
structure – The molecular structure
ecp_name – Name of the ECP (default: “default_ecp”)
atomic_orbital_type – Whether to use spherical or cartesian atomic orbitals

Returns:

Shared pointer to the created BasisSet

static std::shared_ptr<BasisSet> from_basis_name(std::string basis_name, std::shared_ptr<Structure> structure, std::string ecp_name = std::string(default_ecp_name), AOType atomic_orbital_type = AOType::Spherical)

Constructor with basis set name and structure.

Parameters:

basis_name – Name of the basis set (e.g., “6-31G”, “cc-pVDZ”)
structure – Shared pointer to the molecular structure
ecp_name – Name of the ECP (default: “default_ecp”)
atomic_orbital_type – Whether to use spherical or cartesian atomic orbitals

Returns:

Shared pointer to the created BasisSet

static std::shared_ptr<BasisSet> from_element_map(const std::map<std::string, std::string> &element_to_basis_map, const Structure &structure, const std::map<std::string, std::string> &element_to_ecp_map = {}, AOType atomic_orbital_type = AOType::Spherical)

Constructor with basis set name and structure.

Parameters:

element_to_basis_map – Mapping from element symbols to basis set names
structure – The molecular structure
element_to_ecp_map – Mapping from element symbols to ECP names
atomic_orbital_type – Whether to use spherical or cartesian atomic orbitals

Returns:

Shared pointer to the created BasisSet

static std::shared_ptr<BasisSet> from_element_map(const std::map<std::string, std::string> &element_to_basis_map, std::shared_ptr<Structure> structure, const std::map<std::string, std::string> &element_to_ecp_map = {}, AOType atomic_orbital_type = AOType::Spherical)

Constructor with basis set name and structure.

Parameters:

element_to_basis_map – Mapping from element symbols to basis set names
structure – Shared pointer to the molecular structure
element_to_ecp_map – Mapping from element symbols to ECP names
atomic_orbital_type – Whether to use spherical or cartesian atomic orbitals

Returns:

Shared pointer to the created BasisSet

static std::shared_ptr<BasisSet> from_file(const std::string &filename, const std::string &type)

Generic file I/O - load from file based on type parameter.

Parameters:

filename – Path to file to read
type – File format type (“json” or “hdf5”)

Throws:

std::runtime_error – if file doesn’t exist, unsupported type, or I/O error occurs

Returns:

New BasisSet instance loaded from file

static std::shared_ptr<BasisSet> from_hdf5(H5::Group &group)

Load basis set from HDF5 group.

Parameters:: group – HDF5 group to read data from
Throws:: std::runtime_error – if I/O error occurs
Returns:: Shared pointer to const BasisSet instance loaded from group

static std::shared_ptr<BasisSet> from_hdf5_file(const std::string &filename)

Load basis set from HDF5 file (with validation)

Parameters:: filename – Path to HDF5 file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: Shared pointer to const BasisSet instance loaded from file

static std::shared_ptr<BasisSet> from_index_map(const std::map<size_t, std::string> &index_to_basis_map, const Structure &structure, const std::map<size_t, std::string> &index_to_ecp_map = {}, AOType atomic_orbital_type = AOType::Spherical)

Constructor with basis set name and structure.

Parameters:

index_to_basis_map – Mapping from atom indices (as strings) to basis set names
structure – The molecular structure
index_to_ecp_map – Mapping from atom indices to ECP names
atomic_orbital_type – Whether to use spherical or cartesian atomic orbitals

Returns:

Shared pointer to the created BasisSet

static std::shared_ptr<BasisSet> from_index_map(const std::map<size_t, std::string> &index_to_basis_map, std::shared_ptr<Structure> structure, const std::map<size_t, std::string> &index_to_ecp_map = {}, AOType atomic_orbital_type = AOType::Spherical)

Constructor with basis set name and structure.

Parameters:

index_to_basis_map – Mapping from atom indices (as strings) to basis set names
structure – Shared pointer to the molecular structure
index_to_ecp_map – Mapping from atom indices to ECP names
atomic_orbital_type – Whether to use spherical or cartesian atomic orbitals

Returns:

Shared pointer to the created BasisSet

static std::shared_ptr<BasisSet> from_json(const nlohmann::json &j)

Load basis set from JSON.

Parameters:: j – JSON object containing basis set data
Throws:: std::runtime_error – if JSON is malformed
Returns:: Shared pointer to const BasisSet instance loaded from JSON

static std::shared_ptr<BasisSet> from_json_file(const std::string &filename)

Load basis set from JSON file (with validation)

Parameters:: filename – Path to JSON file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: Shared pointer to const BasisSet instance loaded from file

static int get_angular_momentum(OrbitalType orbital_type)

Get angular momentum quantum number for orbital type.

Parameters:: orbital_type – Type of orbital
Returns:: Angular momentum quantum number (l)

static int get_num_orbitals_for_l(int l, AOType atomic_orbital_type = AOType::Spherical)

Get number of orbitals for given angular momentum.

Parameters:

l – Angular momentum quantum number
atomic_orbital_type – Whether to use spherical or cartesian atomic orbitals

Returns:

Number of orbitals

static inline int get_orbital_size(OrbitalType orbital_type)

static std::vector<std::string> get_supported_basis_set_names()

Get supported basis set names.

Returns:: Vector of supported basis set names

static std::vector<Element> get_supported_elements_for_basis_set(std::string basis_name)

Get supported elements for a given basis set.

Parameters:: basis_name – Name of the basis set
Returns:: Vector of supported elements as enum

static OrbitalType l_to_orbital_type(int l)

Convert an integer orbital angular momentum quantum number to orbital type.

Parameters:: l – Angular momentum quantum number
Throws:: std::invalid_argument – if l is out of range
Returns:: Orbital type enumeration

static std::string orbital_type_to_string(OrbitalType orbital_type)

Convert orbital type to string.

Parameters:: orbital_type – Type of orbital
Returns:: String representation (e.g., “s”, “p”, “d”)

static AOType string_to_atomic_orbital_type(const std::string &basis_string)

Convert string to basis type.

Parameters:: basis_string – String representation (“spherical” or “cartesian”)
Throws:: std::invalid_argument – if string is invalid
Returns:: Basis type enumeration

static OrbitalType string_to_orbital_type(const std::string &orbital_string)

Convert string to orbital type.

Parameters:: orbital_string – String representation (e.g., “s”, “p”, “d”)
Throws:: std::invalid_argument – if string is invalid
Returns:: Orbital type enumeration

Public Static Attributes

static constexpr std::string_view custom_ecp_name = "custom_ecp": Name for custom ecps.

static constexpr std::string_view custom_name = "custom_basis_set": Name for custom basis sets.

static constexpr std::string_view default_ecp_name = "default_ecp": Default name for default ecp.

template<typename T> struct BoundConstraint

#include <qdk/chemistry/data/settings.hpp>

Constraint specifying minimum and maximum bounds for a setting value.

This constraint type defines inclusive bounds [min, max] for numeric settings. By default, min and max are set to the type’s limits.

Template Parameters:: T – The type of the bounded value (int64_t or double)

Public Members

T max = std::numeric_limits<T>::max(): Maximum allowed value (inclusive)

T min = std::numeric_limits<T>::min(): Minimum allowed value (inclusive)

class CanonicalFourCenterHamiltonianContainer : public qdk::chemistry::data::HamiltonianContainer

#include <qdk/chemistry/data/hamiltonian_containers/canonical_four_center.hpp>

Contains a molecular Hamiltonian using canonical four center integrals, implemented as a subclass of HamiltonianContainer.

This class stores molecular Hamiltonian data for quantum chemistry calculations, specifically designed for active space methods. It contains:

One-electron integrals (kinetic + nuclear attraction) in MO representation
Two-electron integrals (electron-electron repulsion) in MO representation
Molecular orbital information for the active space
Core energy contributions from inactive orbitals and nuclear repulsion

This class implies that all inactive orbitals are fully occupied for the purpose of computing the core energy and inactive Fock matrix.

The Hamiltonian is immutable after construction, meaning all data must be provided during construction and cannot be modified afterwards. The Hamiltonian supports both restricted and unrestricted calculations and integrates with the broader quantum chemistry framework for active space methods.

Public Functions

CanonicalFourCenterHamiltonianContainer(const Eigen::MatrixXd &one_body_integrals, const Eigen::VectorXd &two_body_integrals, std::shared_ptr<Orbitals> orbitals, double core_energy, const Eigen::MatrixXd &inactive_fock_matrix, HamiltonianType type = HamiltonianType::Hermitian)

Constructor for active space Hamiltonian with four center integrals.

Parameters:

one_body_integrals – One-electron integrals in MO basis [norb x norb]
two_body_integrals – Two-electron integrals in MO basis [norb x norb x norb x norb]
orbitals – Shared pointer to molecular orbital data for the system
core_energy – Core energy (nuclear repulsion + inactive orbital energy)
inactive_fock_matrix – Inactive Fock matrix for the selected active space
type – Type of Hamiltonian (Hermitian by default)

Throws:

std::invalid_argument – if orbitals pointer is nullptr

CanonicalFourCenterHamiltonianContainer(const Eigen::MatrixXd &one_body_integrals_alpha, const Eigen::MatrixXd &one_body_integrals_beta, const Eigen::VectorXd &two_body_integrals_aaaa, const Eigen::VectorXd &two_body_integrals_aabb, const Eigen::VectorXd &two_body_integrals_bbbb, std::shared_ptr<Orbitals> orbitals, double core_energy, const Eigen::MatrixXd &inactive_fock_matrix_alpha, const Eigen::MatrixXd &inactive_fock_matrix_beta, HamiltonianType type = HamiltonianType::Hermitian)

Constructor for active space Hamiltonian with four center integrals using separate spin components.

Parameters:

one_body_integrals_alpha – One-electron integrals for alpha spin in MO basis
one_body_integrals_beta – One-electron integrals for beta spin in MO basis
two_body_integrals_aaaa – Two-electron alpha-alpha-alpha-alpha integrals
two_body_integrals_aabb – Two-electron alpha-beta-alpha-beta integrals
two_body_integrals_bbbb – Two-electron beta-beta-beta-beta integrals
orbitals – Shared pointer to molecular orbital data for the system
core_energy – Core energy (nuclear repulsion + inactive orbital energy)
inactive_fock_matrix_alpha – Inactive Fock matrix for alpha spin in the selected active space
inactive_fock_matrix_beta – Inactive Fock matrix for beta spin in the selected active space
type – Type of Hamiltonian (Hermitian by default)

Throws:

std::invalid_argument – if orbitals pointer is nullptr

~CanonicalFourCenterHamiltonianContainer() = default: Destructor.

virtual std::unique_ptr<HamiltonianContainer> clone() const final override

Create a deep copy of this container.

Returns:: Unique pointer to a cloned container

virtual std::string get_container_type() const final override

Get the type of the underlying container.

Returns:: String identifying the container type (e.g., “canonical_four_center”, “density_fitted”)

virtual double get_two_body_element(unsigned i, unsigned j, unsigned k, unsigned l, SpinChannel channel = SpinChannel::aaaa) const final override

Get specific two-electron integral element.

Parameters:

i – First orbital index
j – Second orbital index
k – Third orbital index
l – Fourth orbital index
channel – Spin channel to query (aaaa, aabb, or bbbb), defaults to aaaa

Throws:

std::out_of_range – if indices are invalid

Returns:

Two-electron integral (ij|kl)

virtual std::tuple<const Eigen::VectorXd&, const Eigen::VectorXd&, const Eigen::VectorXd&> get_two_body_integrals() const final override

Get two-electron integrals in MO basis for all spin channels.

Throws:: std::runtime_error – if integrals are not set
Returns:: Tuple of references to (aaaa, aabb, bbbb) two-electron integrals vectors

virtual bool has_two_body_integrals() const final override

Check if two-body integrals are available.

Returns:: True if two-body integrals are set

virtual bool is_restricted() const final override

Check if the Hamiltonian is restricted.

Returns:: True if alpha and beta integrals are identical

virtual bool is_valid() const final override

Check if the Hamiltonian data is complete and consistent.

Returns:: True if all required data is set and dimensions are consistent

virtual void to_fcidump_file(const std::string &filename, size_t nalpha, size_t nbeta) const final override

Save Hamiltonian to an FCIDUMP file.

Parameters:

filename – Path to FCIDUMP file to create/overwrite
nalpha – Number of alpha electrons
nbeta – Number of beta electrons

Throws:

std::runtime_error – if I/O error occurs

virtual void to_hdf5(H5::Group &group) const final override

Serialize Hamiltonian data to HDF5 group.

Parameters:: group – HDF5 group to write data to
Throws:: std::runtime_error – if I/O error occurs

virtual nlohmann::json to_json() const final override

Convert Hamiltonian to JSON.

Returns:: JSON object containing Hamiltonian data

Public Static Functions

static std::unique_ptr<CanonicalFourCenterHamiltonianContainer> from_hdf5(H5::Group &group)

Deserialize Hamiltonian data from HDF5 group.

Parameters:: group – HDF5 group to read data from
Throws:: std::runtime_error – if I/O error occurs
Returns:: Unique pointer to Hamiltonian loaded from group

static std::unique_ptr<CanonicalFourCenterHamiltonianContainer> from_json(const nlohmann::json &j)

Load Hamiltonian from JSON.

Parameters:: j – JSON object containing Hamiltonian data
Throws:: std::runtime_error – if JSON is malformed
Returns:: Shared pointer to Hamiltonian loaded from JSON

class CasWavefunctionContainer : public qdk::chemistry::data::WavefunctionContainer

#include <qdk/chemistry/data/wavefunction_containers/cas.hpp>

Public Types

using CoeffContainer = ContainerTypes::VectorVariant

using DeterminantVector = ContainerTypes::DeterminantVector

using MatrixVariant = ContainerTypes::MatrixVariant

using ScalarVariant = ContainerTypes::ScalarVariant

using VectorVariant = ContainerTypes::VectorVariant

Public Functions

CasWavefunctionContainer(const VectorVariant &coeffs, const DeterminantVector &dets, std::shared_ptr<Orbitals> orbitals, const std::optional<MatrixVariant> &one_rdm_spin_traced, const std::optional<MatrixVariant> &one_rdm_aa, const std::optional<MatrixVariant> &one_rdm_bb, const std::optional<VectorVariant> &two_rdm_spin_traced, const std::optional<VectorVariant> &two_rdm_aabb, const std::optional<VectorVariant> &two_rdm_aaaa, const std::optional<VectorVariant> &two_rdm_bbbb, WavefunctionType type = WavefunctionType::SelfDual)

Constructs a wavefunction with full reduced density matrix (RDM) data.

Parameters:

coeffs – The vector of CI coefficients (can be real or complex)
dets – The vector of determinants
orbitals – Shared pointer to orbital basis set
one_rdm_spin_traced – Spin-traced 1-RDM for active orbitals (optional)
one_rdm_aa – Alpha-alpha block of 1-RDM for active orbitals (optional)
one_rdm_bb – Beta-beta block of 1-RDM for active orbitals (optional)
two_rdm_spin_traced – Spin-traced 2-RDM for active orbitals (optional)
two_rdm_aabb – Alpha-alpha-beta-beta block of 2-RDM for active orbitals (optional)
two_rdm_aaaa – Alpha-alpha-alpha-alpha block of 2-RDM for active orbitals (optional)
two_rdm_bbbb – Beta-beta-beta-beta block of 2-RDM for active orbitals (optional)
type – Wavefunction type (SelfDual or NotSelfDual)

CasWavefunctionContainer(const VectorVariant &coeffs, const DeterminantVector &dets, std::shared_ptr<Orbitals> orbitals, const std::optional<MatrixVariant> &one_rdm_spin_traced, const std::optional<VectorVariant> &two_rdm_spin_traced, WavefunctionType type = WavefunctionType::SelfDual)

Constructs a wavefunction with full reduced density matrix (RDM) data.

Parameters:

coeffs – The vector of CI coefficients (can be real or complex)
dets – The vector of determinants
orbitals – Shared pointer to orbital basis set
one_rdm_spin_traced – Spin-traced 1-RDM for active orbitals (optional)
two_rdm_spin_traced – Spin-traced 2-RDM for active orbitals (optional)
type – Wavefunction type (SelfDual or NotSelfDual)

CasWavefunctionContainer(const VectorVariant &coeffs, const DeterminantVector &dets, std::shared_ptr<Orbitals> orbitals, WavefunctionType type = WavefunctionType::SelfDual)

Constructs a wavefunction without reduced density matrices (RDMs)

Parameters:

coeffs – The vector of CI coefficients (can be real or complex)
dets – The vector of determinants
orbitals – Shared pointer to orbital basis set
type – Wavefunction type (SelfDual or NotSelfDual)

~CasWavefunctionContainer() override = default: Destructor.

virtual void clear_caches() const override

Clear cached data to release memory.

Clears the following cached data for Complete Active Space (CAS) wavefunctions:

One-particle RDMs: spin-traced (_one_rdm_spin_traced) and spin-dependent (_one_rdm_spin_dependent_aa, _one_rdm_spin_dependent_bb)
Two-particle RDMs: spin-traced (_two_rdm_spin_traced) and spin-dependent (_two_rdm_spin_dependent_aaaa, _two_rdm_spin_dependent_aabb, _two_rdm_spin_dependent_bbbb)

virtual std::unique_ptr<WavefunctionContainer> clone() const override: Clone method for deep copying.

virtual const DeterminantVector &get_active_determinants() const override

Get all determinants in the wavefunction.

Returns:: Vector of all configurations/determinants

virtual std::pair<size_t, size_t> get_active_num_electrons() const override

Get number of active alpha and beta electrons.

Returns:: Pair of (n_alpha_active, n_beta_active) electrons

virtual std::pair<Eigen::VectorXd, Eigen::VectorXd> get_active_orbital_occupations() const override

Get orbital occupations for active orbitals only.

Returns:: Pair of (alpha_active_occupations, beta_active_occupations)

virtual ScalarVariant get_coefficient(const Configuration &det) const override

Get coefficient for a specific determinant.

The configuration is expected to be a determinant describing only the wavefunction’s active space.

Parameters:: det – Configuration/determinant to get coefficient for
Returns:: Coefficient of the determinant

virtual const VectorVariant &get_coefficients() const override

Get all determinants in the wavefunction.

Returns:: Vector of all configurations/determinants

virtual const ConfigurationSet &get_configuration_set() const override

Get the configuration set for this wavefunction.

Throws:: std::runtime_error – if configuration set is not available
Returns:: Reference to the configuration set containing determinants and orbitals

virtual std::string get_container_type() const override

Get container type identifier for serialization.

Returns:: String “cas”

virtual std::shared_ptr<Orbitals> get_orbitals() const override

Get reference to orbital basis set.

Returns:: Shared pointer to orbitals

virtual std::pair<size_t, size_t> get_total_num_electrons() const override

Get total number of alpha and beta electrons (active + inactive)

Returns:: Pair of (n_alpha_total, n_beta_total) electrons

virtual std::pair<Eigen::VectorXd, Eigen::VectorXd> get_total_orbital_occupations() const override

Get orbital occupations for all orbitals (total = active + inactive.

virtual)

Returns:: Pair of (alpha_occupations_total, beta_occupations_total)

virtual bool has_coefficients() const override

Check if this container has coefficients data.

Returns:: True if coefficients are available, false otherwise

virtual bool has_configuration_set() const override

Check if this container has configuration set data.

Returns:: True if configuration set is available, false otherwise

virtual bool is_complex() const override

Check if the wavefunction is complex-valued.

Returns:: True if coefficients are complex, false if real

virtual double norm() const override

Calculate norm of the wavefunction.

Returns:: Norm

virtual ScalarVariant overlap(const WavefunctionContainer &other) const override

Calculate overlap with another wavefunction.

Parameters:: other – Other wavefunction
Returns:: Overlap value

virtual size_t size() const override

Get number of determinants.

Returns:: Number of determinants in the wavefunction

virtual nlohmann::json to_json() const override

Convert container to JSON format.

Returns:: JSON object containing container data

class Configuration : public qdk::chemistry::data::DataClass

#include <qdk/chemistry/data/configuration.hpp>

Represents a configuration (or occupation number vector) with efficient bit-packing.

The Configuration class provides a memory-efficient representation of orbital occupations for calculations. Each orbital can be in one of four states: unoccupied, alpha-occupied, beta-occupied, or doubly-occupied. The implementation uses bit-packing (2 bits per orbital) for memory efficiency.

Public Functions

Configuration() = default

Default constructor.

Creates a configuration with 0 orbitals

template<size_t N> inline Configuration(const std::bitset<N> &orbs, size_t num_orbitals)

Constructor from bitset representation.

Note

First half of bitset (indices 0 to N/2-1) represents alpha orbitals Second half (indices N/2 to N-1) represents beta orbitals

Note

Orbital ordering is little-endian (right to left) within each word.

Template Parameters:

N – Size of the bitset (must be even)

Parameters:

orbs – Bitset representation of the state
num_orbitals – Number of spatial orbitals to use from the bitset

Throws:

std::invalid_argument – If num_orbitals exceeds N/2

Configuration(const std::string &str)

Constructor from string representation.

Note

The length of the string determines the number of orbitals

Note

Orbital indexing is from left to right

Parameters:: str – String representation of configuration (e.g., “22du0d00”) where ‘0’ = unoccupied, ‘u’ = alpha, ‘d’ = beta, ‘2’ = doubly occupied
Throws:: std::invalid_argument – If the string contains invalid characters

std::tuple<size_t, size_t> get_n_electrons() const

Get the number of alpha and beta electrons in the configuration.

Returns:: A tuple containing (number of alpha electrons, number of beta electrons)

size_t get_orbital_capacity() const

Get the max orbital capacity of the configuration.

Returns:: Number of spatial orbitals the configuration can represent

virtual std::string get_summary() const override

Get a summary string describing the configuration.

Returns:: String containing configuration summary information

bool has_alpha_electron(size_t orbital_idx) const

Check if a specific orbital has an alpha electron.

Parameters:: orbital_idx – The orbital index (0-indexed)
Returns:: true if the orbital has an alpha electron, false otherwise

bool has_beta_electron(size_t orbital_idx) const

Check if a specific orbital has a beta electron.

Parameters:: orbital_idx – The orbital index (0-indexed)
Returns:: true if the orbital has a beta electron, false otherwise

bool operator!=(const Configuration &other) const

Inequality comparison operator.

Parameters:: other – The configuration to compare with
Returns:: true if the configurations differ, false if they are identical

bool operator==(const Configuration &other) const

Equality comparison operator.

Note

Used for std::find and other algorithms

Parameters:: other – The configuration to compare with
Returns:: true if the configurations are identical, false otherwise

std::pair<std::string, std::string> to_binary_strings(size_t num_orbitals) const

Convert configuration to separate alpha and beta binary strings in little-endian format.

Converts the compact representation to two binary strings:

Alpha string: ‘1’ if orbital has alpha or doubly occupied
Beta string: ‘1’ if orbital has beta or doubly occupied Example: “2du0” -> (“1010”, “1100”)

Throws:: std::runtime_error – If num_orbitals exceeds configuration capacity
Parameters:: num_orbitals – How many orbitals to extract (if we want to slice for active space)
Returns:: Pair of binary strings (alpha, beta) where ‘1’ indicates occupied and ‘0’ indicates unoccupied for each spin channel, in little endian format

template<size_t N> inline std::bitset<N> to_bitset() const

Convert the configuration to a bitset representation.

Note

The returned bitset will have the first half (indices 0 to N/2-1) representing alpha orbitals and the second half (indices N/2 to N-1) representing beta orbitals

Note

Orbital ordering is little-endian (right to left) within each word.

Template Parameters:: N – Size of the bitset (must be even)
Throws:: std::invalid_argument – If the configuration has more orbitals than N/2
Returns:: Bitset representation of the configuration

virtual void to_file(const std::string &filename, const std::string &type) const override

Save configuration to file in the specified format.

Parameters:

filename – Path to the output file
type – Format type (“json” or “hdf5”)

Throws:

std::invalid_argument – if format type is not supported
std::runtime_error – if I/O error occurs

virtual void to_hdf5(H5::Group &group) const override

Save configuration to HDF5 group.

Parameters:: group – HDF5 group to save data to
Throws:: std::runtime_error – if I/O error occurs

virtual void to_hdf5_file(const std::string &filename) const override

Save configuration to HDF5 file.

Parameters:: filename – Path to the output HDF5 file
Throws:: std::runtime_error – if I/O error occurs

virtual nlohmann::json to_json() const override

Convert configuration to JSON representation.

Returns:: JSON object containing the serialized data

virtual void to_json_file(const std::string &filename) const override

Save configuration to JSON file.

Parameters:: filename – Path to the output JSON file
Throws:: std::runtime_error – if I/O error occurs

std::string to_string() const

Convert the configuration to a string representation.

Returns:: String representation where each character represents an orbital: ‘0’ = unoccupied, ‘u’ = alpha, ‘d’ = beta, ‘2’ = doubly occupied

Public Static Functions

static Configuration canonical_hf_configuration(size_t n_alpha, size_t n_beta, size_t n_orbitals)

Create a canonical Hartree-Fock configuration using the Aufbau principle.

Fills orbitals from lowest energy according to the Aufbau principle:

Doubly occupied orbitals for paired electrons
Singly occupied orbitals for unpaired electrons (alpha first if n_alpha > n_beta)
Unoccupied orbitals for remaining positions

Parameters:

n_alpha – Number of alpha electrons
n_beta – Number of beta electrons
n_orbitals – Total number of orbitals

Returns:

Configuration representing the HF ground state

static Configuration from_binary_strings(std::string alpha_string, std::string beta_string)

Convert separate alpha and beta binary strings in little-endian format to a Configuration.

Parameters:

alpha_string – Alpha string where ‘1’ indicates occupied and ‘0’ indicates unoccupied for each spin channel, in little endian format
beta_string – Beta string where ‘1’ indicates occupied and ‘0’ indicates unoccupied for each spin channel, in little endian format

Returns:

Configuration object

static Configuration from_file(const std::string &filename, const std::string &type)

Load configuration from file in specified format.

Parameters:

filename – Path to file to read
type – Format type (“json” or “hdf5”)

Throws:

std::invalid_argument – if unknown type
std::runtime_error – if file doesn’t exist or I/O error occurs

Returns:

New Configuration instance loaded from file

static Configuration from_hdf5(H5::Group &group)

Load configuration from HDF5 group.

Parameters:: group – HDF5 group to read from
Throws:: std::runtime_error – if I/O error occurs
Returns:: New Configuration instance created from HDF5 data

static Configuration from_hdf5_file(const std::string &filename)

Load configuration from HDF5 file.

Parameters:: filename – Path to HDF5 file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: New Configuration instance loaded from file

static Configuration from_json(const nlohmann::json &j)

Load configuration from JSON.

Parameters:: j – JSON object containing configuration data
Throws:: std::runtime_error – if JSON is malformed
Returns:: New Configuration instance created from JSON

static Configuration from_json_file(const std::string &filename)

Load configuration from JSON file.

Parameters:: filename – Path to JSON file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: New Configuration instance loaded from file

class ConfigurationSet : public qdk::chemistry::data::DataClass

#include <qdk/chemistry/data/configuration_set.hpp>

Associates a collection of Configuration objects with orbital information.

This class manages a set of configurations that share the same single-particle basis, specifically the active space of an Orbitals object. By storing the orbital information at the set level rather than in each configuration, we eliminate redundant storage of the number of orbitals.

Key design points:

Configurations represent only the active space, not the full orbital set
Inactive and virtual orbitals are not included in the configuration representation
All configurations in the set must be consistent with the active space size
Provides iteration and access methods similar to std::vector
Immutable after construction to ensure consistency

Public Functions

ConfigurationSet(const std::vector<Configuration> &configurations, std::shared_ptr<Orbitals> orbitals)

Construct a ConfigurationSet from configurations and orbital information.

Note

All configurations must have the same number of orbitals and sufficient capacity to represent the active space defined in the orbitals object. Configurations only represent the active space; inactive and virtual orbitals are not included in the configuration representation.

Parameters:

configurations – Vector of configurations (representing active space only)
orbitals – Shared pointer to orbital basis set

Throws:

std::invalid_argument – if configurations are inconsistent with active space or if orbitals pointer is null

ConfigurationSet(std::vector<Configuration> &&configurations, std::shared_ptr<Orbitals> orbitals)

Construct a ConfigurationSet from configurations and orbital information (move)

Note

All configurations must have the same number of orbitals and sufficient capacity to represent the active space defined in the orbitals object. Configurations only represent the active space; inactive and virtual orbitals are not included in the configuration representation.

Parameters:

configurations – Vector of configurations (representing active space only, moved)
orbitals – Shared pointer to orbital basis set

Throws:

std::invalid_argument – if configurations are inconsistent with active space or if orbitals pointer is null

const Configuration &at(size_t idx) const

Access configuration by index with bounds checking.

Parameters:: idx – Index
Throws:: std::out_of_range – if index is invalid
Returns:: Const reference to configuration

std::vector<Configuration>::const_iterator begin() const

std::vector<Configuration>::const_iterator cbegin() const

std::vector<Configuration>::const_iterator cend() const

bool empty() const

Check if the set is empty.

Returns:: True if empty

std::vector<Configuration>::const_iterator end() const

const std::vector<Configuration> &get_configurations() const

Get the configurations.

Returns:: Const reference to vector of configurations

std::shared_ptr<Orbitals> get_orbitals() const

Get the orbital information.

Returns:: Shared pointer to orbitals

virtual std::string get_summary() const override

Get a summary string describing the configuration set.

Returns:: String containing object summary information

bool operator!=(const ConfigurationSet &other) const

Check inequality with another ConfigurationSet.

Parameters:: other – Other set
Returns:: True if not equal

bool operator==(const ConfigurationSet &other) const

Check equality with another ConfigurationSet.

Parameters:: other – Other set
Returns:: True if equal (same configurations and orbitals point to same object)

const Configuration &operator[](size_t idx) const

Access configuration by index.

Parameters:: idx – Index
Returns:: Const reference to configuration

size_t size() const

Get the number of configurations in the set.

Returns:: Number of configurations

virtual void to_file(const std::string &filename, const std::string &type) const override

Save object to file in the specified format.

Parameters:

filename – Path to the output file
type – Format type (e.g., “json”, “hdf5”)

Throws:

std::invalid_argument – if format type is not supported
std::runtime_error – if I/O error occurs

virtual void to_hdf5(H5::Group &group) const override

Serialize configuration set to HDF5.

Note

This serializes both configurations and orbitals recursively

Parameters:: group – HDF5 group to write to

virtual void to_hdf5_file(const std::string &filename) const override

Save object to HDF5 file.

Parameters:: filename – Path to the output HDF5 file
Throws:: std::runtime_error – if I/O error occurs

virtual nlohmann::json to_json() const override

Serialize configuration set to JSON.

Note

This serializes both configurations and orbitals recursively

Returns:: JSON representation (includes configurations and orbitals)

virtual void to_json_file(const std::string &filename) const override

Save object to JSON file.

Parameters:: filename – Path to the output JSON file
Throws:: std::runtime_error – if I/O error occurs

Public Static Functions

static ConfigurationSet from_file(const std::string &filename, const std::string &type)

Load configuration set from file in the specified format.

Parameters:

filename – Path to the input file
type – Format type (e.g., “json”, “hdf5”)

Throws:

std::invalid_argument – if format type is not supported
std::runtime_error – if I/O error occurs

Returns:

ConfigurationSet object

static ConfigurationSet from_hdf5(H5::Group &group)

Deserialize configuration set from HDF5.

Note

Orbitals are deserialized from the HDF5 “orbitals” subgroup

Parameters:: group – HDF5 group to read from
Returns:: ConfigurationSet object

static ConfigurationSet from_hdf5_file(const std::string &filename)

Load configuration set from HDF5 file.

Parameters:: filename – Path to the input HDF5 file
Throws:: std::runtime_error – if I/O error occurs
Returns:: ConfigurationSet object

static ConfigurationSet from_json(const nlohmann::json &j)

Deserialize configuration set from JSON.

Note

Orbitals are deserialized from the JSON “orbitals” field

Parameters:: j – JSON object containing configuration and orbital data
Returns:: ConfigurationSet object

static ConfigurationSet from_json_file(const std::string &filename)

Load configuration set from JSON file.

Parameters:: filename – Path to the input JSON file
Throws:: std::runtime_error – if I/O error occurs
Returns:: ConfigurationSet object

class CoupledClusterContainer : public qdk::chemistry::data::WavefunctionContainer

#include <qdk/chemistry/data/wavefunction_containers/cc.hpp>

Wavefunction container representing a coupled cluster wavefunction.

Public Types

using DeterminantVector = ContainerTypes::DeterminantVector

using MatrixVariant = ContainerTypes::MatrixVariant

using ScalarVariant = ContainerTypes::ScalarVariant

using VectorVariant = ContainerTypes::VectorVariant

Public Functions

CoupledClusterContainer(std::shared_ptr<Orbitals> orbitals, std::shared_ptr<Wavefunction> wavefunction, const std::optional<VectorVariant> &t1_amplitudes, const std::optional<VectorVariant> &t2_amplitudes)

Constructs a coupled cluster wavefunction with amplitudes.

T1/T2 amplitudes are stored if provided

Parameters:

orbitals – Shared pointer to orbitals
wavefunction – Shared pointer to wavefunction
t1_amplitudes – T1 amplitudes (optional)
t2_amplitudes – T2 amplitudes (optional)

CoupledClusterContainer(std::shared_ptr<Orbitals> orbitals, std::shared_ptr<Wavefunction> wavefunction, const std::optional<VectorVariant> &t1_amplitudes, const std::optional<VectorVariant> &t2_amplitudes, const std::optional<MatrixVariant> &one_rdm_spin_traced, const std::optional<MatrixVariant> &one_rdm_aa, const std::optional<MatrixVariant> &one_rdm_bb, const std::optional<VectorVariant> &two_rdm_spin_traced, const std::optional<VectorVariant> &two_rdm_aabb, const std::optional<VectorVariant> &two_rdm_aaaa, const std::optional<VectorVariant> &two_rdm_bbbb)

Constructs a coupled cluster wavefunction with amplitudes and full one- and two-body RDM data.

T1/T2 amplitudes and RDMs are stored if provided

Parameters:

orbitals – Shared pointer to orbitals
wavefunction – Shared pointer to wavefunction
t1_amplitudes – T1 amplitudes (optional)
t2_amplitudes – T2 amplitudes (optional)
one_rdm_spin_traced – Spin-traced 1-RDM for active orbitals (optional)
one_rdm_aa – Alpha-alpha block of 1-RDM for active orbitals (optional)
one_rdm_bb – Beta-beta block of 1-RDM for active orbitals (optional)
two_rdm_spin_traced – Spin-traced 2-RDM for active orbitals (optional)
two_rdm_aabb – Alpha-beta-beta-alpha block of 2-RDM for active orbitals (optional)
two_rdm_aaaa – Alpha-alpha-alpha-alpha block of 2-RDM for active orbitals (optional)
two_rdm_bbbb – Beta-beta-beta-beta block of 2-RDM for active orbitals (optional)

CoupledClusterContainer(std::shared_ptr<Orbitals> orbitals, std::shared_ptr<Wavefunction> wavefunction, const std::optional<VectorVariant> &t1_amplitudes, const std::optional<VectorVariant> &t2_amplitudes, const std::optional<MatrixVariant> &one_rdm_spin_traced, const std::optional<VectorVariant> &two_rdm_spin_traced)

Constructs a coupled cluster wavefunction with amplitudes and spin-traced RDMs.

T1/T2 amplitudes and RDMs are stored if provided

Parameters:

orbitals – Shared pointer to orbitals
wavefunction – Shared pointer to wavefunction
t1_amplitudes – T1 amplitudes (optional)
t2_amplitudes – T2 amplitudes (optional)
one_rdm_spin_traced – Spin-traced 1-RDM for active orbitals (optional)
two_rdm_spin_traced – Spin-traced 2-RDM for active orbitals (optional)

CoupledClusterContainer(std::shared_ptr<Orbitals> orbitals, std::shared_ptr<Wavefunction> wavefunction, const std::optional<VectorVariant> &t1_amplitudes_aa, const std::optional<VectorVariant> &t1_amplitudes_bb, const std::optional<VectorVariant> &t2_amplitudes_abab, const std::optional<VectorVariant> &t2_amplitudes_aaaa, const std::optional<VectorVariant> &t2_amplitudes_bbbb)

Constructs a coupled cluster wavefunction with spin-separated amplitudes.

T1/T2 amplitudes are stored if provided

Parameters:

orbitals – Shared pointer to orbitals
wavefunction – Shared pointer to wavefunction
t1_amplitudes_aa – Alpha T1 amplitudes (optional)
t1_amplitudes_bb – Beta T1 amplitudes (optional)
t2_amplitudes_abab – Alpha-beta T2 amplitudes (optional)
t2_amplitudes_aaaa – Alpha-alpha T2 amplitudes (optional)
t2_amplitudes_bbbb – Beta-beta T2 amplitudes (optional)

CoupledClusterContainer(std::shared_ptr<Orbitals> orbitals, std::shared_ptr<Wavefunction> wavefunction, const std::optional<VectorVariant> &t1_amplitudes_aa, const std::optional<VectorVariant> &t1_amplitudes_bb, const std::optional<VectorVariant> &t2_amplitudes_abab, const std::optional<VectorVariant> &t2_amplitudes_aaaa, const std::optional<VectorVariant> &t2_amplitudes_bbbb, const std::optional<MatrixVariant> &one_rdm_spin_traced, const std::optional<MatrixVariant> &one_rdm_aa, const std::optional<MatrixVariant> &one_rdm_bb, const std::optional<VectorVariant> &two_rdm_spin_traced, const std::optional<VectorVariant> &two_rdm_aabb, const std::optional<VectorVariant> &two_rdm_aaaa, const std::optional<VectorVariant> &two_rdm_bbbb)

Constructs a coupled cluster wavefunction with spin-separated amplitudes and full one- and two-body RDM data.

T1/T2 amplitudes and RDMs are stored if provided

Parameters:

orbitals – Shared pointer to orbitals
wavefunction – Shared pointer to wavefunction
t1_amplitudes_aa – Alpha T1 amplitudes (optional)
t1_amplitudes_bb – Beta T1 amplitudes (optional)
t2_amplitudes_abab – Alpha-beta T2 amplitudes (optional)
t2_amplitudes_aaaa – Alpha-alpha T2 amplitudes (optional)
t2_amplitudes_bbbb – Beta-beta T2 amplitudes (optional)
one_rdm_spin_traced – Spin-traced 1-RDM for active orbitals (optional)
one_rdm_aa – Alpha-alpha block of 1-RDM for active orbitals (optional)
one_rdm_bb – Beta-beta block of 1-RDM for active orbitals (optional)
two_rdm_spin_traced – Spin-traced 2-RDM for active orbitals (optional)
two_rdm_aabb – Alpha-beta-beta-alpha block of 2-RDM for active orbitals (optional)
two_rdm_aaaa – Alpha-alpha-alpha-alpha block of 2-RDM for active orbitals (optional)
two_rdm_bbbb – Beta-beta-beta-beta block of 2-RDM for active orbitals (optional)

CoupledClusterContainer(std::shared_ptr<Orbitals> orbitals, std::shared_ptr<Wavefunction> wavefunction, const std::optional<VectorVariant> &t1_amplitudes_aa, const std::optional<VectorVariant> &t1_amplitudes_bb, const std::optional<VectorVariant> &t2_amplitudes_abab, const std::optional<VectorVariant> &t2_amplitudes_aaaa, const std::optional<VectorVariant> &t2_amplitudes_bbbb, const std::optional<MatrixVariant> &one_rdm_spin_traced, const std::optional<VectorVariant> &two_rdm_spin_traced)

Constructs a coupled cluster wavefunction with spin-separated amplitudes and spin-traced RDMs.

T1/T2 amplitudes and RDMs are stored if provided

Parameters:

orbitals – Shared pointer to orbitals
wavefunction – Shared pointer to wavefunction
t1_amplitudes_aa – Alpha T1 amplitudes (optional)
t1_amplitudes_bb – Beta T1 amplitudes (optional)
t2_amplitudes_abab – Alpha-beta T2 amplitudes (optional)
t2_amplitudes_aaaa – Alpha-alpha T2 amplitudes (optional)
t2_amplitudes_bbbb – Beta-beta T2 amplitudes (optional)
one_rdm_spin_traced – Spin-traced 1-RDM for active orbitals (optional)
two_rdm_spin_traced – Spin-traced 2-RDM for active orbitals (optional)

~CoupledClusterContainer() override = default: Destructor.

virtual void clear_caches() const override

Clear cached data to release memory.

Clears the following cached data:

Determinant vector cache (_determinant_vector_cache)
One-particle RDMs (spin-traced and spin-dependent)
Two-particle RDMs (spin-traced and spin-dependent)

This is particularly useful for freeing memory when the cached RDMs are no longer needed.

virtual std::unique_ptr<WavefunctionContainer> clone() const override

Create a deep copy of this container.

Returns:: Unique pointer to cloned container

bool contains_determinant(const Configuration &det) const

Check if a determinant is in the reference wavefunction.

Parameters:: det – Configuration/determinant to check
Returns:: True if determinant matches any reference determinant

bool contains_reference(const Configuration &det) const

Check if a determinant is in the reference wavefunction.

Parameters:: det – Configuration/determinant to check
Returns:: True if determinant matches any reference determinant

virtual const DeterminantVector &get_active_determinants() const override: Not implemented for CC wavefunctions.

virtual std::pair<size_t, size_t> get_active_num_electrons() const override

Get number of active alpha and beta electrons.

Returns:: Pair of (n_alpha_active, n_beta_active) electrons

virtual std::pair<Eigen::VectorXd, Eigen::VectorXd> get_active_orbital_occupations() const override

Get orbital occupations for active orbitals only.

Returns:: Pair of (alpha_active_occupations, beta_active_occupations)

virtual ScalarVariant get_coefficient(const Configuration &det) const override: Not implemented for CC wavefunctions.

virtual const VectorVariant &get_coefficients() const override: Not implemented for CC wavefunctions.

virtual std::string get_container_type() const override

Get container type identifier for serialization.

Returns:: String “coupled_cluster”

virtual std::shared_ptr<Orbitals> get_orbitals() const override

Get reference to orbitals.

Returns:: Shared pointer to orbitals

std::pair<const VectorVariant&, const VectorVariant&> get_t1_amplitudes() const

Get T1 amplitudes.

Returns T1 amplitudes if they were provided at construction.

Throws:: std::runtime_error – if T1 amplitudes are not available
Returns:: Pair of (alpha, beta) T1 amplitudes

std::tuple<const VectorVariant&, const VectorVariant&, const VectorVariant&> get_t2_amplitudes() const

Get T2 amplitudes.

Returns T2 amplitudes if they were provided at construction.

Throws:: std::runtime_error – if T2 amplitudes are not available
Returns:: Tuple of (alpha-beta, alpha-alpha, beta-beta) T2 amplitudes

virtual std::pair<size_t, size_t> get_total_num_electrons() const override

Get total number of alpha and beta electrons (active + inactive)

Returns:: Pair of (n_alpha_total, n_beta_total) electrons

virtual std::pair<Eigen::VectorXd, Eigen::VectorXd> get_total_orbital_occupations() const override

Get orbital occupations for all orbitals (total = active + inactive.

virtual)

Returns:: Pair of (alpha_occupations_total, beta_occupations_total)

std::shared_ptr<Wavefunction> get_wavefunction() const

Get reference to wavefunction.

Returns:: Shared pointer to wavefunction

bool has_t1_amplitudes() const

Check if T1 amplitudes are available.

Returns:: True if T1 amplitudes are available

bool has_t2_amplitudes() const

Check if T2 amplitudes are available.

Returns:: True if T2 amplitudes are available

virtual bool is_complex() const override

Check if the wavefunction is complex-valued.

Returns:: True if amplitudes contain complex values

virtual double norm() const override: Not implemented for CC wavefunctions.

virtual ScalarVariant overlap(const WavefunctionContainer &other) const override: Not implemented for CC wavefunctions.

virtual size_t size() const override

Get number of determinants (not meaningful for CC wavefunctions)

Throws:: std::runtime_error – Always throws as this is not meaningful for CC wavefunctions

virtual void to_hdf5(H5::Group &group) const override

Convert container to HDF5 group.

Parameters:: group – HDF5 group to write container data to
Throws:: std::runtime_error – if HDF5 I/O error occurs

virtual nlohmann::json to_json() const override

Convert container to JSON format.

Returns:: JSON object containing container data

Public Static Functions

static std::unique_ptr<CoupledClusterContainer> from_hdf5(H5::Group &group)

Load container from HDF5 group.

Parameters:: group – HDF5 group containing container data
Throws:: std::runtime_error – if HDF5 data is malformed or I/O error occurs
Returns:: Unique pointer to CC container created from HDF5 group

static std::unique_ptr<CoupledClusterContainer> from_json(const nlohmann::json &j)

Load container from JSON format.

Parameters:: j – JSON object containing container data
Throws:: std::runtime_error – if JSON is malformed
Returns:: Unique pointer to CC container created from JSON data

class DataClass

#include <qdk/chemistry/data/data_class.hpp>

Base interface class providing common methods for data classes.

This class defines a common interface that all QDK chemistry data classes should implement.

Subclassed by qdk::chemistry::data::Ansatz, qdk::chemistry::data::BasisSet, qdk::chemistry::data::Configuration, qdk::chemistry::data::ConfigurationSet, qdk::chemistry::data::Hamiltonian, qdk::chemistry::data::Orbitals, qdk::chemistry::data::Settings, qdk::chemistry::data::StabilityResult, qdk::chemistry::data::Structure, qdk::chemistry::data::Wavefunction

Public Functions

virtual ~DataClass() = default

virtual std::string get_summary() const = 0

Get a summary string describing the object.

Returns:: String containing object summary information

virtual void to_file(const std::string &filename, const std::string &type) const = 0

Save object to file in the specified format.

Parameters:

filename – Path to the output file
type – Format type (e.g., “json”, “hdf5”, “xyz”)

Throws:

std::invalid_argument – if format type is not supported
std::runtime_error – if I/O error occurs

virtual void to_hdf5(H5::Group &group) const = 0

Save object to HDF5 group.

Parameters:: group – HDF5 group to save data to
Throws:: std::runtime_error – if I/O error occurs

virtual void to_hdf5_file(const std::string &filename) const = 0

Save object to HDF5 file.

Parameters:: filename – Path to the output HDF5 file
Throws:: std::runtime_error – if I/O error occurs

virtual nlohmann::json to_json() const = 0

Convert object to JSON representation.

Returns:: JSON object containing the serialized data

virtual void to_json_file(const std::string &filename) const = 0

Save object to JSON file.

Parameters:: filename – Path to the output JSON file
Throws:: std::runtime_error – if I/O error occurs

class Hamiltonian : public qdk::chemistry::data::DataClass, public std::enable_shared_from_this<Hamiltonian>

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

Provides an interface to a molecular Hamiltonian in the molecular orbital basis by wrapping an implementation from HamiltonianContainer.

This class provides an interface to molecular Hamiltonian data for quantum chemistry calculations, specifically designed for active space methods. It interfaces with a HamiltonianContainer that stores:

One-electron integrals (kinetic + nuclear attraction) in MO representation
Two-electron integrals (electron-electron repulsion) in MO representation
Molecular orbital information for the active space
Core energy contributions from inactive orbitals and nuclear repulsion

Public Functions

Hamiltonian(const Hamiltonian &other): Copy constructor.

Hamiltonian(Hamiltonian &&other) noexcept = default: Move constructor.

Hamiltonian(std::unique_ptr<HamiltonianContainer> container)

Constructor for Hamiltonian with a HamiltonianContainer.

Parameters:: container – Unique pointer to HamiltonianContainer holding the data

~Hamiltonian() = default: Destructor.

template<typename T> inline const T &get_container() const

Get typed reference to the underlying container.

Template Parameters:: T – Container type to cast to
Throws:: std::bad_cast – if container is not of type T
Returns:: Reference to container as type T

std::string get_container_type() const

Get the type of the underlying container.

Returns:: String identifying the container type (e.g., “canonical_four_center”, “density_fitted”)

double get_core_energy() const

Get core energy.

Returns:: Core energy in atomic units

std::pair<const Eigen::MatrixXd&, const Eigen::MatrixXd&> get_inactive_fock_matrix() const

Get tuple of inactive Fock matrices (alpha, beta) for the selected active space.

Throws:: std::runtime_error – if inactive Fock matrix is not set
Returns:: Reference to the inactive Fock matrix

double get_one_body_element(unsigned i, unsigned j, SpinChannel channel = SpinChannel::aa) const

Get specific one-electron integral element.

Parameters:

i – First orbital index
j – Second orbital index
channel – Spin channel to query (aa, or bb), defaults to aa

Throws:

std::out_of_range – if indices are invalid

Returns:

One-electron integral (i|h|j);

std::tuple<const Eigen::MatrixXd&, const Eigen::MatrixXd&> get_one_body_integrals() const

Get tuple of alpha, beta one-electron integrals in MO basis.

Throws:: std::runtime_error – if integrals are not set
Returns:: Reference to alpha, beta one-electron integrals matrices

const std::shared_ptr<Orbitals> get_orbitals() const

Get molecular orbital data.

Throws:: std::runtime_error – if orbitals are not set
Returns:: Reference to the orbitals object

virtual std::string get_summary() const override

Get summary string of Hamiltonian information.

Returns:: String describing the Hamiltonian

double get_two_body_element(unsigned i, unsigned j, unsigned k, unsigned l, SpinChannel channel = SpinChannel::aaaa) const

Get specific two-electron integral element.

Parameters:

i – First orbital index
j – Second orbital index
k – Third orbital index
l – Fourth orbital index
channel – Spin channel to query (aaaa, aabb, or bbbb), defaults to aaaa

Throws:

std::out_of_range – if indices are invalid

Returns:

Two-electron integral (ij|kl)

std::tuple<const Eigen::VectorXd&, const Eigen::VectorXd&, const Eigen::VectorXd&> get_two_body_integrals() const

Get two-electron integrals in MO basis for all spin channels.

Throws:: std::runtime_error – if integrals are not set
Returns:: Tuple of references to (aaaa, aabb, bbbb) two-electron integrals vectors

HamiltonianType get_type() const

Get the type of Hamiltonian (Hermitian or NonHermitian)

Returns:: HamiltonianType enum value

template<typename T> inline bool has_container_type() const

Check if container is of specific type.

Template Parameters:: T – Container type to check
Returns:: True if container is of type T

bool has_inactive_fock_matrix() const

Check if inactive Fock matrix is available.

Returns:: True if inactive Fock matrix is set

bool has_one_body_integrals() const

Check if one-body integrals are available.

Returns:: True if one-body integrals are set

bool has_orbitals() const

Check if orbital data is available.

Returns:: True if orbitals are set

bool has_two_body_integrals() const

Check if two-body integrals are available.

Returns:: True if two-body integrals are set

bool is_hermitian() const

Check if the Hamiltonian is Hermitian.

Returns:: True if the Hamiltonian type is Hermitian

bool is_restricted() const

Check if the Hamiltonian is restricted.

Returns:: True if alpha and beta integrals are identical

bool is_unrestricted() const

Check if the Hamiltonian is unrestricted.

Returns:: True if alpha and beta integrals are different

Hamiltonian &operator=(const Hamiltonian &other): Copy assignment operator.

Hamiltonian &operator=(Hamiltonian &&other) noexcept = default: Move assignment operator.

void to_fcidump_file(const std::string &filename, size_t nalpha, size_t nbeta) const

Save Hamiltonian to an FCIDUMP file.

Parameters:

filename – Path to FCIDUMP file to create/overwrite
nalpha – Number of alpha electrons
nbeta – Number of beta electrons

Throws:

std::runtime_error – if I/O error occurs

virtual void to_file(const std::string &filename, const std::string &type) const override

Generic file I/O - save to file based on type parameter.

Parameters:

filename – Path to file to create/overwrite
type – File format type (“json” or “hdf5”)

Throws:

std::runtime_error – if unsupported type or I/O error occurs

virtual void to_hdf5(H5::Group &group) const override

Serialize Hamiltonian data to HDF5 group.

Parameters:: group – HDF5 group to write data to
Throws:: std::runtime_error – if I/O error occurs

virtual void to_hdf5_file(const std::string &filename) const override

Save Hamiltonian to HDF5 file (with validation)

Parameters:: filename – Path to HDF5 file to create/overwrite
Throws:: std::runtime_error – if I/O error occurs

virtual nlohmann::json to_json() const override

Convert Hamiltonian to JSON.

Returns:: JSON object containing Hamiltonian data

virtual void to_json_file(const std::string &filename) const override

Save Hamiltonian to JSON file (with validation)

Parameters:: filename – Path to JSON file to create/overwrite
Throws:: std::runtime_error – if I/O error occurs

Public Static Functions

static std::shared_ptr<Hamiltonian> from_file(const std::string &filename, const std::string &type)

Generic file I/O - load from file based on type parameter.

Parameters:

filename – Path to file to read
type – File format type (“json” or “hdf5”)

Throws:

std::runtime_error – if file doesn’t exist, unsupported type, or I/O error occurs

Returns:

Shared pointer to const Hamiltonian loaded from file

static std::shared_ptr<Hamiltonian> from_hdf5(H5::Group &group)

Deserialize Hamiltonian data from HDF5 group.

Parameters:: group – HDF5 group to read data from
Throws:: std::runtime_error – if I/O error occurs
Returns:: Shared pointer to const Hamiltonian loaded from group

static std::shared_ptr<Hamiltonian> from_hdf5_file(const std::string &filename)

Load Hamiltonian from HDF5 file (with validation)

Parameters:: filename – Path to HDF5 file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: Shared pointer to const Hamiltonian loaded from file

static std::shared_ptr<Hamiltonian> from_json(const nlohmann::json &j)

Load Hamiltonian from JSON.

Parameters:: j – JSON object containing Hamiltonian data
Throws:: std::runtime_error – if JSON is malformed
Returns:: Shared pointer to const Hamiltonian loaded from JSON

static std::shared_ptr<Hamiltonian> from_json_file(const std::string &filename)

Load Hamiltonian from JSON file (with validation)

Parameters:: filename – Path to JSON file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: Shared pointer to const Hamiltonian loaded from file

class HamiltonianContainer

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

Pure virtual base class for a molecular Hamiltonian implementation in the molecular orbital basis.

Concrete subclasses must provide an implementation that defines the underlying storage and/or computation mechanism for two-electron integrals.

This class stores molecular Hamiltonian data for quantum chemistry calculations, specifically designed for active space methods. It contains:

One-electron integrals (kinetic + nuclear attraction) in MO representation
Molecular orbital information for the active space
Core energy contributions from inactive orbitals and nuclear repulsion

Note that this class does not store two-electron integrals; derived classes are expected to implement storage and access for these integrals.

This class implies that all inactive orbitals are fully occupied for the purpose of computing the core energy and inactive Fock matrix.

The Hamiltonian is immutable after construction, meaning all data must be provided during construction and cannot be modified afterwards. The Hamiltonian supports both restricted and unrestricted calculations and integrates with the broader quantum chemistry framework for active space methods.

Subclassed by qdk::chemistry::data::CanonicalFourCenterHamiltonianContainer

Public Functions

HamiltonianContainer(const Eigen::MatrixXd &one_body_integrals, std::shared_ptr<Orbitals> orbitals, double core_energy, const Eigen::MatrixXd &inactive_fock_matrix, HamiltonianType type = HamiltonianType::Hermitian)

Constructor for active space Hamiltonian with shared_ptr orbitals and inactive Fock matrix.

Parameters:

one_body_integrals – One-electron integrals in MO basis [norb x norb]
orbitals – Shared pointer to molecular orbital data for the system
core_energy – Core energy (nuclear repulsion + inactive orbital energy)
inactive_fock_matrix – Inactive Fock matrix for the selected active space
type – Type of Hamiltonian (Hermitian by default)

Throws:

std::invalid_argument – if orbitals pointer is nullptr

HamiltonianContainer(const Eigen::MatrixXd &one_body_integrals_alpha, const Eigen::MatrixXd &one_body_integrals_beta, std::shared_ptr<Orbitals> orbitals, double core_energy, const Eigen::MatrixXd &inactive_fock_matrix_alpha, const Eigen::MatrixXd &inactive_fock_matrix_beta, HamiltonianType type = HamiltonianType::Hermitian)

Constructor for unrestricted active space Hamiltonian with separate spin components.

Parameters:

one_body_integrals_alpha – One-electron integrals for alpha spin in MO basis
one_body_integrals_beta – One-electron integrals for beta spin in MO basis
orbitals – Shared pointer to molecular orbital data for the system
core_energy – Core energy (nuclear repulsion + inactive orbital energy)
inactive_fock_matrix_alpha – Inactive Fock matrix for alpha spin in the selected active space
inactive_fock_matrix_beta – Inactive Fock matrix for beta spin in the selected active space
type – Type of Hamiltonian (Hermitian by default)

Throws:

std::invalid_argument – if orbitals pointer is nullptr

virtual ~HamiltonianContainer() = default: Destructor.

virtual std::unique_ptr<HamiltonianContainer> clone() const = 0

Create a deep copy of this container.

Returns:: Unique pointer to a cloned container

virtual std::string get_container_type() const = 0

Get the type of the underlying container.

Returns:: String identifying the container type (e.g., “canonical_four_center”, “density_fitted”)

double get_core_energy() const

Get core energy.

Returns:: Core energy in atomic units

std::pair<const Eigen::MatrixXd&, const Eigen::MatrixXd&> get_inactive_fock_matrix() const

Get inactive Fock matrix for the selected active space.

Throws:: std::runtime_error – if inactive Fock matrix is not set
Returns:: Reference to the inactive Fock matrix

double get_one_body_element(unsigned i, unsigned j, SpinChannel channel = SpinChannel::aa) const

Get specific one-electron integral element.

Parameters:

i – First orbital index
j – Second orbital index
channel – Spin channel to query (aa, or bb), defaults to aa

Throws:

std::out_of_range – if indices are invalid

Returns:

One-electron integral (i|h|j)

std::tuple<const Eigen::MatrixXd&, const Eigen::MatrixXd&> get_one_body_integrals() const

Get tuple of alpha, beta one-electron integrals in MO basis.

Throws:: std::runtime_error – if integrals are not set
Returns:: Reference to alpha, beta one-electron integrals matrices

const std::shared_ptr<Orbitals> get_orbitals() const

Get molecular orbital data.

Throws:: std::runtime_error – if orbitals are not set
Returns:: Reference to the orbitals object

virtual double get_two_body_element(unsigned i, unsigned j, unsigned k, unsigned l, SpinChannel channel = SpinChannel::aaaa) const = 0

Get specific two-electron integral element.

Parameters:

i – First orbital index
j – Second orbital index
k – Third orbital index
l – Fourth orbital index
channel – Spin channel to query (aaaa, aabb, or bbbb), defaults to aaaa

Throws:

std::out_of_range – if indices are invalid

Returns:

Two-electron integral (ij|kl)

virtual std::tuple<const Eigen::VectorXd&, const Eigen::VectorXd&, const Eigen::VectorXd&> get_two_body_integrals() const = 0

Get two-electron integrals in MO basis for all spin channels.

Throws:: std::runtime_error – if integrals are not set
Returns:: Tuple of references to (aaaa, aabb, bbbb) two-electron integrals vectors

HamiltonianType get_type() const

Get the type of Hamiltonian (Hermitian or NonHermitian)

Returns:: HamiltonianType enum value

bool has_inactive_fock_matrix() const

Check if inactive Fock matrix is available.

Returns:: True if inactive Fock matrix is set

bool has_one_body_integrals() const

Check if one-body integrals are available.

Returns:: True if one-body integrals are set

bool has_orbitals() const

Check if orbital data is available.

Returns:: True if orbitals are set

virtual bool has_two_body_integrals() const = 0

Check if two-body integrals are available.

Returns:: True if two-body integrals are set

bool is_hermitian() const

Check if the Hamiltonian is Hermitian.

Returns:: True if the Hamiltonian type is Hermitian

virtual bool is_restricted() const = 0

Check if the Hamiltonian is restricted.

Returns:: True if alpha and beta integrals are identical

bool is_unrestricted() const

Check if the Hamiltonian is unrestricted.

Returns:: True if alpha and beta integrals are different

virtual bool is_valid() const = 0

Check if the Hamiltonian data is complete and consistent.

Returns:: True if all required data is set and dimensions are consistent

virtual void to_fcidump_file(const std::string &filename, size_t nalpha, size_t nbeta) const = 0

Save Hamiltonian to an FCIDUMP file.

Parameters:

filename – Path to FCIDUMP file to create/overwrite
nalpha – Number of alpha electrons
nbeta – Number of beta electrons

Throws:

std::runtime_error – if I/O error occurs

virtual void to_hdf5(H5::Group &group) const = 0

Serialize Hamiltonian data to HDF5 group.

Parameters:: group – HDF5 group to write data to
Throws:: std::runtime_error – if I/O error occurs

virtual nlohmann::json to_json() const = 0

Convert Hamiltonian to JSON.

Returns:: JSON object containing Hamiltonian data

Public Static Functions

static std::unique_ptr<HamiltonianContainer> from_hdf5(H5::Group &group)

Deserialize Hamiltonian data from HDF5 group.

Parameters:: group – HDF5 group to read data from
Throws:: std::runtime_error – if I/O error occurs
Returns:: Unique pointer to Hamiltonian loaded from group

static std::unique_ptr<HamiltonianContainer> from_json(const nlohmann::json &j)

Load Hamiltonian from JSON.

Parameters:: j – JSON object containing Hamiltonian data
Throws:: std::runtime_error – if JSON is malformed
Returns:: Unique pointer to Hamiltonian loaded from JSON

template<typename T, typename Variant> struct is_variant_member_impl

Concept to check if a type is a member of a std::variant.

Template Parameters:

T – The type to check
Variant – The variant type to check against

template<typename T> struct is_vector_impl : public std::false_type

#include <qdk/chemistry/data/settings.hpp>

Concept to detect if a type is a std::vector.

Template Parameters:: T – The type to check

template<typename T> struct ListConstraint

#include <qdk/chemistry/data/settings.hpp>

Constraint specifying a list of allowed values for a setting.

This constraint type defines an explicit set of allowed values for a setting. The setting value must match one of the values in the allowed_values vector.

Template Parameters:: T – The type of the allowed values (int64_t or std::string)

Public Members

std::vector<T> allowed_values: Vector of allowed values for the setting.

class ModelOrbitals : public qdk::chemistry::data::Orbitals

#include <qdk/chemistry/data/orbitals.hpp>

Simple subclass of Orbitals for model systems without basis set information.

This class allows creating Orbitals objects with a specified basis size and whether the calculation is restricted or unrestricted, without needing to provide full coefficient or energy data. The class allows for model Hamiltonians and Wavefunctions to be fully specified without explicit basis set details.

Calls to any functions requiring actual data (e.g. get_coefficients, get_energies, calculate_ao_density_matrix, etc.) will throw runtime errors.

Public Functions

ModelOrbitals(const ModelOrbitals &other)

ModelOrbitals(size_t basis_size, bool restricted)

ModelOrbitals(size_t basis_size, const std::tuple<std::vector<size_t>, std::vector<size_t>> &indices)

Constructor with active and inactive space indices (restricted)

Parameters:

basis_size – Number of atomic orbitals (and molecular orbitals)
indices – Orbital indices as tuple of (active, inactive) space indices. For restricted calculations, the same indices are used for both alpha and beta spin channels.

ModelOrbitals(size_t basis_size, const std::tuple<std::vector<size_t>, std::vector<size_t>, std::vector<size_t>, std::vector<size_t>> &indices)

Constructor with active and inactive space indices (unrestricted)

Parameters:

basis_size – Number of atomic orbitals (and molecular orbitals)
indices – Orbital indices as tuple of (active_alpha, inactive_alpha, active_beta, inactive_beta) space indices. For unrestricted calculations, separate indices can be specified for alpha and beta spin channels.

virtual ~ModelOrbitals() = default

virtual Eigen::MatrixXd calculate_ao_density_matrix(const Eigen::VectorXd &occupations) const override

Calculate atomic orbital (AO) density matrix from restricted occupation vector.

Parameters:: occupations – Occupation vector (size must match number of MOs)
Throws:: std::runtime_error – if occupation vector size doesn’t match number of MOs
Returns:: AO density matrix (total alpha + beta)

virtual std::pair<Eigen::MatrixXd, Eigen::MatrixXd> calculate_ao_density_matrix(const Eigen::VectorXd &occupations_alpha, const Eigen::VectorXd &occupations_beta) const override

Calculate AO density matrix from occupation vectors.

Parameters:

occupations_alpha – Alpha spin occupation vector (size must match number of MOs)
occupations_beta – Beta spin occupation vector (size must match number of MOs)

Throws:

std::runtime_error – if occupation vector sizes don’t match number of MOs

Returns:

Pair of (alpha, beta) AO density matrices

virtual Eigen::MatrixXd calculate_ao_density_matrix_from_rdm(const Eigen::MatrixXd &rdm) const override

Calculate atomic orbital (AO) density matrix from 1RDM in molecular orbital (MO) space (restricted)

Parameters:: rdm – 1RDM in MO basis (size must match number of MOs x MOs)
Throws:: std::runtime_error – if 1RDM matrix size doesn’t match number of MOs
Returns:: AO density matrix (total alpha + beta)

virtual std::pair<Eigen::MatrixXd, Eigen::MatrixXd> calculate_ao_density_matrix_from_rdm(const Eigen::MatrixXd &rdm_alpha, const Eigen::MatrixXd &rdm_beta) const override

Calculate atomic orbital (AO) density matrix from 1RDM in molecular orbital (MO) space.

Parameters:

rdm_alpha – Alpha 1RDM in MO basis (size must match number of MOs x MOs)
rdm_beta – Beta 1RDM in MO basis (size must match number of MOs x MOs)

Throws:

std::runtime_error – if 1RDM matrix sizes don’t match number of MOs

Returns:

Pair of (alpha, beta) AO density matrices

virtual std::vector<size_t> get_all_mo_indices() const override

Get all molecular orbital indices as a vector.

Returns:: Vector containing indices [0, 1, 2, …, num_molecular_orbitals-1]

virtual std::shared_ptr<BasisSet> get_basis_set() const override

Get basis set information.

Throws:: std::runtime_error – if basis set is not set
Returns:: Reference to the basis set object

virtual std::pair<const Eigen::MatrixXd&, const Eigen::MatrixXd&> get_coefficients() const override

Get orbital coefficients.

Throws:: std::runtime_error – if coefficients are not set
Returns:: Pair of references to (alpha, beta) coefficient matrices

virtual const Eigen::MatrixXd &get_coefficients_alpha() const override

Get alpha orbital coefficients.

Returns:: Reference to alpha coefficient matrix

virtual const Eigen::MatrixXd &get_coefficients_beta() const override

Get beta orbital coefficients.

Returns:: Reference to beta coefficient matrix

virtual std::pair<const Eigen::VectorXd&, const Eigen::VectorXd&> get_energies() const override

Get orbital energies.

Throws:: std::runtime_error – if energies are not set
Returns:: Pair of references to (alpha, beta) energy vectors

virtual const Eigen::VectorXd &get_energies_alpha() const override

Get alpha orbital energies.

Returns:: Reference to alpha energy vector

virtual const Eigen::VectorXd &get_energies_beta() const override

Get beta orbital energies.

Returns:: Reference to beta energy vector

virtual std::tuple<Eigen::MatrixXd, Eigen::MatrixXd, Eigen::MatrixXd> get_mo_overlap() const override

Get all molecular orbital (MO) overlap matrices.

Computes the overlap matrices between molecular orbitals by transforming the atomic orbital overlap matrix to the molecular orbital basis:

S_MO^αα = C_α^T * S_AO * C_α (alpha-alpha overlap)
S_MO^αβ = C_α^T * S_AO * C_β (alpha-beta overlap)
S_MO^ββ = C_β^T * S_AO * C_β (beta-beta overlap)

For restricted calculations, alpha-alpha = beta-beta and alpha-beta = alpha-alpha. For orthonormal MOs, alpha-alpha and beta-beta should be identity matrices.

Throws:: std::runtime_error – if atomic orbital (AO) overlap matrix or coefficients are not set
Returns:: Tuple of (alpha-alpha, alpha-beta, beta-beta) MO overlap matrices

virtual Eigen::MatrixXd get_mo_overlap_alpha_alpha() const override

Get alpha-alpha molecular orbital (MO) overlap matrix.

Computes the overlap matrix between alpha molecular orbitals by transforming the atomic orbital overlap matrix using the alpha MO coefficients. For orthonormal alpha MOs, this should be the identity matrix.

Throws:: std::runtime_error – if AO overlap matrix or alpha coefficients are not set
Returns:: MO overlap matrix S_MO^αα = C_α^T * S_AO * C_α

virtual Eigen::MatrixXd get_mo_overlap_alpha_beta() const override

Get alpha-beta molecular orbital (MO) overlap matrix.

Computes the overlap matrix between alpha and beta molecular orbitals. For restricted calculations, this equals the alpha-alpha overlap matrix.

Throws:: std::runtime_error – if AO overlap matrix or coefficients are not set
Returns:: MO overlap matrix S_MO^αβ = C_α^T * S_AO * C_β

virtual Eigen::MatrixXd get_mo_overlap_beta_beta() const override

Get beta-beta molecular orbital (MO) overlap matrix.

Computes the overlap matrix between beta molecular orbitals by transforming the atomic orbital overlap matrix using the beta MO coefficients. For orthonormal beta MOs, this should be the identity matrix. For restricted calculations, this equals the alpha-alpha overlap matrix.

Throws:: std::runtime_error – if AO overlap matrix or beta coefficients are not set
Returns:: MO overlap matrix S_MO^ββ = C_β^T * S_AO * C_β

inline virtual size_t get_num_atomic_orbitals() const override

Get number of atomic orbitals.

Returns:: Number of AOs (rows in coefficient matrix)

inline virtual size_t get_num_molecular_orbitals() const override

Get number of molecular orbitals.

Returns:: Number of molecular orbitals (columns in coefficient matrix)

virtual const Eigen::MatrixXd &get_overlap_matrix() const override

Get overlap matrix.

Returns:: Reference to overlap matrix

virtual bool is_restricted() const override

Check if calculation is restricted (RHF/RKS)

Returns:: True if alpha and beta coefficients are identical

virtual bool is_unrestricted() const override

Check if calculation is unrestricted (UHF/UKS)

Returns:: True if alpha and beta coefficients are different

ModelOrbitals &operator=(const ModelOrbitals &other)

virtual void to_hdf5(H5::Group &group) const override

Serialize ModelOrbitals to HDF5 group.

Parameters:: group – HDF5 group to write data to
Throws:: std::runtime_error – if I/O error occurs

virtual nlohmann::json to_json() const override

Convert orbital data to JSON.

Throws:: std::runtime_error – if data is invalid
Returns:: JSON object containing orbital data

Public Static Functions

static std::shared_ptr<ModelOrbitals> from_hdf5(H5::Group &group)

Load ModelOrbitals from HDF5 group.

Parameters:: group – HDF5 group containing ModelOrbitals data
Throws:: std::runtime_error – if HDF5 data is malformed or I/O error occurs
Returns:: Shared pointer to ModelOrbitals object loaded from group

static std::shared_ptr<ModelOrbitals> from_json(const nlohmann::json &j)

class MP2Container : public qdk::chemistry::data::WavefunctionContainer

#include <qdk/chemistry/data/wavefunction_containers/mp2.hpp>

Wavefunction container representing an MP2 wavefunction.

This container stores an MP2 wavefunction with a Hamiltonian reference. Amplitudes can be computed on-demand (lazy evaluation) when first requested.

Public Types

using DeterminantVector = ContainerTypes::DeterminantVector

using MatrixVariant = ContainerTypes::MatrixVariant

using ScalarVariant = ContainerTypes::ScalarVariant

using VectorVariant = ContainerTypes::VectorVariant

Public Functions

MP2Container(std::shared_ptr<Hamiltonian> hamiltonian, std::shared_ptr<Wavefunction> wavefunction, const std::string &partitioning = "mp")

Constructs an MP2 wavefunction.

Parameters:

hamiltonian – Shared pointer to the Hamiltonian
wavefunction – Shared pointer to the wavefunction
partitioning – Choice of partitioning in perbutation theory: the default is Moeller-Plesset Hamiltonian partitioning, keyword “mp”

~MP2Container() override = default: Destructor.

virtual void clear_caches() const override: Clear all cached data.

virtual std::unique_ptr<WavefunctionContainer> clone() const override

Create a deep copy of this container.

Returns:: Unique pointer to cloned container

bool contains_determinant(const Configuration &det) const

Check if a determinant is contained in the wavefunction.

Parameters:: det – Configuration to check
Returns:: True if determinant is in the wavefunction

bool contains_reference(const Configuration &det) const

Check if a determinant is a reference determinant.

Parameters:: det – Configuration to check
Returns:: True if determinant is a reference

virtual const DeterminantVector &get_active_determinants() const override: Not implemented for MP2 wavefunctions.

virtual std::pair<size_t, size_t> get_active_num_electrons() const override

Get number of active electrons (alpha and beta)

Returns:: Pair of (n_alpha_active, n_beta_active)

virtual std::pair<Eigen::VectorXd, Eigen::VectorXd> get_active_orbital_occupations() const override: Not implemented for MP2 wavefunctions.

virtual ScalarVariant get_coefficient(const Configuration &det) const override: Not implemented for MP2 wavefunctions.

virtual const VectorVariant &get_coefficients() const override: Not implemented for MP2 wavefunctions.

virtual std::string get_container_type() const override

Get container type identifier.

Returns:: String identifying container type

std::shared_ptr<Hamiltonian> get_hamiltonian() const

Get reference to Hamiltonian.

Returns:: Shared pointer to Hamiltonian

virtual std::shared_ptr<Orbitals> get_orbitals() const override

Get reference to orbitals.

Returns:: Shared pointer to orbitals

std::pair<const VectorVariant&, const VectorVariant&> get_t1_amplitudes() const

Get T1 amplitudes.

Returns:: Pair of (alpha, beta) T1 amplitudes

std::tuple<const VectorVariant&, const VectorVariant&, const VectorVariant&> get_t2_amplitudes() const

Get T2 amplitudes.

Returns:: Tuple of (alpha-beta, alpha-alpha, beta-beta) T2 amplitudes

virtual std::pair<size_t, size_t> get_total_num_electrons() const override

Get total number of electrons (alpha and beta)

Returns:: Pair of (n_alpha, n_beta)

virtual std::pair<Eigen::VectorXd, Eigen::VectorXd> get_total_orbital_occupations() const override: Not implemented for MP2 wavefunctions.

std::shared_ptr<Wavefunction> get_wavefunction() const

Get reference to Wavefunction.

Returns:: Shared pointer to Wavefunction

bool has_t1_amplitudes() const

Check if T1 amplitudes are available.

Returns:: Whether the amplitudes have been calculated

bool has_t2_amplitudes() const

Check if T2 amplitudes are available.

Returns:: Whether the amplitudes have been calculated

virtual bool is_complex() const override

Check if wavefunction uses complex numbers.

Returns:: True if wavefunction is complex

virtual double norm() const override: Not implemented for MP2 wavefunctions.

virtual ScalarVariant overlap(const WavefunctionContainer &other) const override: Not implemented for MP2 wavefunctions.

virtual size_t size() const override

Get number of determinants.

Throws:: std::runtime_error – Always throws as this is not meaningful for MP2 wavefunctions

virtual void to_hdf5(H5::Group &group) const override

Serialize to HDF5.

Parameters:: group – HDF5 group to write to

virtual nlohmann::json to_json() const override

Serialize to JSON.

Returns:: JSON representation of the container

Public Static Functions

static std::unique_ptr<MP2Container> from_hdf5(H5::Group &group)

Deserialize from HDF5.

Parameters:: group – HDF5 group to read from
Returns:: Unique pointer to MP2Container

static std::unique_ptr<MP2Container> from_json(const nlohmann::json &j)

Deserialize from JSON.

Parameters:: j – JSON object
Returns:: Unique pointer to MP2Container

class Orbitals : public qdk::chemistry::data::DataClass, public std::enable_shared_from_this<Orbitals>

#include <qdk/chemistry/data/orbitals.hpp>

Represents molecular orbitals with coefficients and energies.

This class stores molecular orbital data including:

Orbital coefficients (alpha/beta spin channels)
Orbital energies (alpha/beta spin channels)
Atomic orbital (AO) overlap matrix
Basis set information

Supports both restricted (RHF/RKS) and unrestricted (UHF/UKS) calculations.

This class is immutable after construction - all data must be provided during construction and cannot be modified afterward.

Subclassed by qdk::chemistry::data::ModelOrbitals

Public Types

typedef std::tuple<std::vector<size_t>, std::vector<size_t>> RestrictedCASIndices

typedef std::tuple<std::vector<size_t>, std::vector<size_t>, std::vector<size_t>, std::vector<size_t>> UnrestrictedCASIndices

Public Functions

Orbitals(const Eigen::MatrixXd &coefficients, const std::optional<Eigen::VectorXd> &energies, const std::optional<Eigen::MatrixXd> &ao_overlap, std::shared_ptr<BasisSet> basis_set, const std::optional<RestrictedCASIndices> &indices = std::nullopt)

Constructor for restricted orbitals with shared pointer to basis set.

Parameters:

coefficients – The molecular orbital coefficients matrix
energies – The orbital energies (optional)
ao_overlap – The atomic orbital overlap matrix (optional)
basis_set – The basis set as shared pointer
indices – Orbital indices as tuple of (active, inactive) space indices. For restricted calculations, the same indices are used for both alpha and beta spin channels.

Orbitals(const Eigen::MatrixXd &coefficients_alpha, const Eigen::MatrixXd &coefficients_beta, const std::optional<Eigen::VectorXd> &energies_alpha, const std::optional<Eigen::VectorXd> &energies_beta, const std::optional<Eigen::MatrixXd> &ao_overlap, std::shared_ptr<BasisSet> basis_set, const std::optional<UnrestrictedCASIndices> &indices = std::nullopt)

Constructor for unrestricted orbitals with shared pointer to basis set.

Parameters:

coefficients_alpha – The alpha molecular orbital coefficients matrix
coefficients_beta – The beta molecular orbital coefficients matrix
energies_alpha – The alpha orbital energies (optional)
energies_beta – The beta orbital energies (optional)
ao_overlap – The atomic orbital overlap matrix (optional)
basis_set – The basis set as shared pointer
indices – Orbital indices as tuple of (active_alpha, inactive_alpha, active_beta, inactive_beta) space indices. For unrestricted calculations, separate indices can be specified for alpha and beta spin channels.

Orbitals(const Orbitals &other)

Copy constructor.

Parameters:: other – The orbitals object to copy from

virtual ~Orbitals(): Destructor.

virtual Eigen::MatrixXd calculate_ao_density_matrix(const Eigen::VectorXd &occupations) const

Calculate atomic orbital (AO) density matrix from restricted occupation vector.

Parameters:: occupations – Occupation vector (size must match number of MOs)
Throws:: std::runtime_error – if occupation vector size doesn’t match number of MOs
Returns:: AO density matrix (total alpha + beta)

virtual std::pair<Eigen::MatrixXd, Eigen::MatrixXd> calculate_ao_density_matrix(const Eigen::VectorXd &occupations_alpha, const Eigen::VectorXd &occupations_beta) const

Calculate AO density matrix from occupation vectors.

Parameters:

occupations_alpha – Alpha spin occupation vector (size must match number of MOs)
occupations_beta – Beta spin occupation vector (size must match number of MOs)

Throws:

std::runtime_error – if occupation vector sizes don’t match number of MOs

Returns:

Pair of (alpha, beta) AO density matrices

virtual Eigen::MatrixXd calculate_ao_density_matrix_from_rdm(const Eigen::MatrixXd &rdm) const

Calculate atomic orbital (AO) density matrix from 1RDM in molecular orbital (MO) space (restricted)

Parameters:: rdm – 1RDM in MO basis (size must match number of MOs x MOs)
Throws:: std::runtime_error – if 1RDM matrix size doesn’t match number of MOs
Returns:: AO density matrix (total alpha + beta)

virtual std::pair<Eigen::MatrixXd, Eigen::MatrixXd> calculate_ao_density_matrix_from_rdm(const Eigen::MatrixXd &rdm_alpha, const Eigen::MatrixXd &rdm_beta) const

Calculate atomic orbital (AO) density matrix from 1RDM in molecular orbital (MO) space.

Parameters:

rdm_alpha – Alpha 1RDM in MO basis (size must match number of MOs x MOs)
rdm_beta – Beta 1RDM in MO basis (size must match number of MOs x MOs)

Throws:

std::runtime_error – if 1RDM matrix sizes don’t match number of MOs

Returns:

Pair of (alpha, beta) AO density matrices

virtual std::pair<const std::vector<size_t>&, const std::vector<size_t>&> get_active_space_indices() const

Get active space information.

Returns:: Pair of (alpha, beta) active space indices

virtual std::vector<size_t> get_all_mo_indices() const

Get all molecular orbital indices as a vector.

Returns:: Vector containing indices [0, 1, 2, …, num_molecular_orbitals-1]

virtual std::shared_ptr<BasisSet> get_basis_set() const

Get basis set information.

Throws:: std::runtime_error – if basis set is not set
Returns:: Reference to the basis set object

virtual std::pair<const Eigen::MatrixXd&, const Eigen::MatrixXd&> get_coefficients() const

Get orbital coefficients.

Throws:: std::runtime_error – if coefficients are not set
Returns:: Pair of references to (alpha, beta) coefficient matrices

virtual const Eigen::MatrixXd &get_coefficients_alpha() const

Get alpha orbital coefficients.

Returns:: Reference to alpha coefficient matrix

virtual const Eigen::MatrixXd &get_coefficients_beta() const

Get beta orbital coefficients.

Returns:: Reference to beta coefficient matrix

virtual std::pair<const Eigen::VectorXd&, const Eigen::VectorXd&> get_energies() const

Get orbital energies.

Throws:: std::runtime_error – if energies are not set
Returns:: Pair of references to (alpha, beta) energy vectors

virtual const Eigen::VectorXd &get_energies_alpha() const

Get alpha orbital energies.

Returns:: Reference to alpha energy vector

virtual const Eigen::VectorXd &get_energies_beta() const

Get beta orbital energies.

Returns:: Reference to beta energy vector

std::pair<const std::vector<size_t>&, const std::vector<size_t>&> get_inactive_space_indices() const

Get inactive space information.

Returns:: Pair of (alpha, beta) inactive space indices

virtual std::tuple<Eigen::MatrixXd, Eigen::MatrixXd, Eigen::MatrixXd> get_mo_overlap() const

Get all molecular orbital (MO) overlap matrices.

Computes the overlap matrices between molecular orbitals by transforming the atomic orbital overlap matrix to the molecular orbital basis:

S_MO^αα = C_α^T * S_AO * C_α (alpha-alpha overlap)
S_MO^αβ = C_α^T * S_AO * C_β (alpha-beta overlap)
S_MO^ββ = C_β^T * S_AO * C_β (beta-beta overlap)

For restricted calculations, alpha-alpha = beta-beta and alpha-beta = alpha-alpha. For orthonormal MOs, alpha-alpha and beta-beta should be identity matrices.

Throws:: std::runtime_error – if atomic orbital (AO) overlap matrix or coefficients are not set
Returns:: Tuple of (alpha-alpha, alpha-beta, beta-beta) MO overlap matrices

virtual Eigen::MatrixXd get_mo_overlap_alpha_alpha() const

Get alpha-alpha molecular orbital (MO) overlap matrix.

Computes the overlap matrix between alpha molecular orbitals by transforming the atomic orbital overlap matrix using the alpha MO coefficients. For orthonormal alpha MOs, this should be the identity matrix.

Throws:: std::runtime_error – if AO overlap matrix or alpha coefficients are not set
Returns:: MO overlap matrix S_MO^αα = C_α^T * S_AO * C_α

virtual Eigen::MatrixXd get_mo_overlap_alpha_beta() const

Get alpha-beta molecular orbital (MO) overlap matrix.

Computes the overlap matrix between alpha and beta molecular orbitals. For restricted calculations, this equals the alpha-alpha overlap matrix.

Throws:: std::runtime_error – if AO overlap matrix or coefficients are not set
Returns:: MO overlap matrix S_MO^αβ = C_α^T * S_AO * C_β

virtual Eigen::MatrixXd get_mo_overlap_beta_beta() const

Get beta-beta molecular orbital (MO) overlap matrix.

Computes the overlap matrix between beta molecular orbitals by transforming the atomic orbital overlap matrix using the beta MO coefficients. For orthonormal beta MOs, this should be the identity matrix. For restricted calculations, this equals the alpha-alpha overlap matrix.

Throws:: std::runtime_error – if AO overlap matrix or beta coefficients are not set
Returns:: MO overlap matrix S_MO^ββ = C_β^T * S_AO * C_β

virtual size_t get_num_atomic_orbitals() const

Get number of atomic orbitals.

Returns:: Number of AOs (rows in coefficient matrix)

virtual size_t get_num_molecular_orbitals() const

Get number of molecular orbitals.

Returns:: Number of molecular orbitals (columns in coefficient matrix)

virtual const Eigen::MatrixXd &get_overlap_matrix() const

Get overlap matrix.

Returns:: Reference to overlap matrix

virtual std::string get_summary() const override

Get summary string of orbital information.

Returns:: String describing the orbital data

std::pair<std::vector<size_t>, std::vector<size_t>> get_virtual_space_indices() const

Get virtual space information (orbitals not in active or inactive)

Returns:: Pair of (alpha, beta) virtual space indices

bool has_active_space() const

Check if calculation has an active space.

Returns:: True if active space is set

bool has_basis_set() const

Check if basis set information is available.

Returns:: True if basis set is set

bool has_energies() const

Check if energies are set.

Returns:: True if energies are set

bool has_inactive_space() const

Check if calculation has an inactive space.

Returns:: True if inactive space is set

bool has_overlap_matrix() const

Check if instance has an overlap matrix.

Returns:: True if overlap matrix is set

virtual bool is_restricted() const

Check if calculation is restricted (RHF/RKS)

Returns:: True if alpha and beta coefficients are identical

virtual bool is_unrestricted() const

Check if calculation is unrestricted (UHF/UKS)

Returns:: True if alpha and beta coefficients are different

Orbitals &operator=(const Orbitals &other)

Copy assignment operator.

Parameters:: other – The orbitals object to copy from
Returns:: Reference to this object

virtual void to_file(const std::string &filename, const std::string &type) const override

Save orbital data to file based on type parameter.

Parameters:

filename – Path to file to create/overwrite
type – File format type (“json” or “hdf5”)

Throws:

std::runtime_error – if data is invalid, unsupported type, or I/O error occurs

virtual void to_hdf5(H5::Group &group) const override

Serialize orbital data to HDF5 group.

Parameters:: group – HDF5 group to write data to
Throws:: std::runtime_error – if I/O error occurs

virtual void to_hdf5_file(const std::string &filename) const override

Save orbital data to HDF5 file (with validation)

Parameters:: filename – Path to HDF5 file to create/overwrite
Throws:: std::runtime_error – if data is invalid or I/O error occurs

virtual nlohmann::json to_json() const override

Convert orbital data to JSON.

Throws:: std::runtime_error – if data is invalid
Returns:: JSON object containing orbital data

virtual void to_json_file(const std::string &filename) const override

Save orbital data to JSON file (with validation)

Parameters:: filename – Path to JSON file to create/overwrite
Throws:: std::runtime_error – if data is invalid or I/O error occurs

Public Static Functions

static std::shared_ptr<Orbitals> from_file(const std::string &filename, const std::string &type)

Load orbital data from file based on type parameter.

Parameters:

filename – Path to file to read
type – File format type (“json” or “hdf5”)

Throws:

std::runtime_error – if file doesn’t exist, unsupported type, or I/O error occurs

Returns:

New Orbitals object loaded from file

static std::shared_ptr<Orbitals> from_hdf5(H5::Group &group)

Load orbital data from HDF5 group.

Parameters:: group – HDF5 group containing orbital data
Throws:: std::runtime_error – if HDF5 data is malformed or I/O error occurs
Returns:: Shared pointer to Orbitals object loaded from group

static std::shared_ptr<Orbitals> from_hdf5_file(const std::string &filename)

Load orbital data from HDF5 file.

Parameters:: filename – Path to HDF5 file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: Shared pointer to const Orbitals object loaded from file

static std::shared_ptr<Orbitals> from_json(const nlohmann::json &j)

Load orbital data from JSON.

Parameters:: j – JSON object containing orbital data
Throws:: std::runtime_error – if JSON is malformed or missing required data
Returns:: Shared pointer to const Orbitals object loaded from JSON

static std::shared_ptr<Orbitals> from_json_file(const std::string &filename)

Load orbital data from JSON file.

Parameters:: filename – Path to JSON file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: Shared pointer to const Orbitals object loaded from file

class PauliOperator : public qdk::chemistry::data::PauliOperatorExpression

#include <qdk/chemistry/data/pauli_operator.hpp>

A PauliOperatorExpression representing a single Pauli operator acting on a qubit.

This class serves as the leaf node in the expression tree for PauliOperatorExpression trees. It represents one of the four Pauli operators:

Identity (I)
Pauli-X (X)
Pauli-Y (Y)
Pauli-Z (Z)

Public Functions

PauliOperator(std::uint8_t operator_type, std::uint64_t qubit_index)

Constructs a PauliOperator with the specified type and qubit index.

Parameters:

operator_type – The type of Pauli operator (0=I, 1=X, 2=Y, 3=Z).
qubit_index – The index of the qubit this operator acts on.

virtual std::unique_ptr<PauliOperatorExpression> clone() const override

Creates a deep copy of this Pauli operator.

See also

PauliOperatorExpression::clone()

Returns:: A unique_ptr to the cloned Pauli operator.

virtual std::unique_ptr<SumPauliOperatorExpression> distribute() const override

Distributes this Pauli operator.

Since a single Pauli operator is already in simplest form, this method simply returns a new SumPauliOperatorExpression containing this operator.

See also

PauliOperatorExpression::distribute()

Returns:: A new SumPauliOperatorExpression containing this operator.

inline std::uint8_t get_operator_type() const

Returns the type of this Pauli operator.

Returns:: The operator type (0=I, 1=X, 2=Y, 3=Z).

inline std::uint64_t get_qubit_index() const

Returns the qubit index this Pauli operator acts on.

Returns:: The qubit index.

virtual std::uint64_t max_qubit_index() const override

Returns the maximum qubit index referenced in this operator.

Since this operator acts on a single qubit, it simply returns that index.

Returns:: The qubit index this operator acts on.

virtual std::uint64_t min_qubit_index() const override

Returns the minimum qubit index referenced in this operator.

Since this operator acts on a single qubit, it simply returns that index.

Returns:: The qubit index this operator acts on.

virtual std::uint64_t num_qubits() const override

Returns the number of qubits spanned by this operator.

Since this operator acts on a single qubit, it always returns 1.

Returns:: 1

virtual std::unique_ptr<SumPauliOperatorExpression> prune_threshold(double epsilon) const override

Returns a sum containing this operator if it meets the threshold.

Single Pauli operators have an implicit coefficient of 1.0.

Parameters:: epsilon – Terms with |coefficient| < epsilon are excluded.
Returns:: A SumPauliOperatorExpression containing this operator if epsilon <= 1.0, or an empty sum otherwise.

virtual std::unique_ptr<PauliOperatorExpression> simplify() const override

Simplifies this Pauli operator.

Since a single Pauli operator is already in simplest form, this method simply returns a clone of this operator.

See also

PauliOperatorExpression::simplify()

Returns:: A clone of this Pauli operator.

virtual std::string to_canonical_string(std::uint64_t min_qubit, std::uint64_t max_qubit) const override

Returns the canonical string representation for a qubit range.

See PauliOperatorExpression::to_canonical_string() for more details.

Parameters:

min_qubit – The minimum qubit index to include.
max_qubit – The maximum qubit index to include (inclusive).

Returns:

A string of length (max_qubit - min_qubit + 1).

virtual std::string to_canonical_string(std::uint64_t num_qubits) const override

Returns the canonical string representation of this Pauli operator.

Wraps to_canonical_string(0, max_qubit_index()+1).

Parameters:: num_qubits – The total number of qubits to represent.
Returns:: A string of length num_qubits.

virtual std::vector<std::pair<std::complex<double>, std::string>> to_canonical_terms() const override

Returns a vector of (coefficient, canonical_string) pairs.

Wraps to_canonical_terms(max_qubit_index()+1).

Returns:: Vector of pairs where each pair contains the coefficient and canonical string for each term.

virtual std::vector<std::pair<std::complex<double>, std::string>> to_canonical_terms(std::uint64_t num_qubits) const override

Returns a vector of (coefficient, canonical_string) pairs.

For a single Pauli operator, this returns a single pair with coefficient 1.0 and the canonical string representation if the requested num_qubits includes the qubit this operator acts on. Otherwise, it returns a single pair with coefficient 1.0 and a string of all identities.

Parameters:: num_qubits – The total number of qubits to represent.
Returns:: Vector of pairs where each pair contains the coefficient and canonical string for each term.

char to_char() const

Returns the character representation of this Pauli operator.

Throws:: std::runtime_error – If the operator type is invalid (not 0-3).
Returns:: ‘I’, ‘X’, ‘Y’, or ‘Z’.

virtual std::string to_string() const override

Returns a string representation of this Pauli operator.

For example, “X(0)” for a Pauli-X operator on qubit 0.

See PauliOperatorExpression::to_string() for more details.

See also

PauliOperatorExpression::to_string()

Returns:: A string representing this Pauli operator.

Public Static Functions

static inline PauliOperator I(std::uint64_t qubit_index)

Factory method to create an Identity operator on a specified qubit.

Parameters:: qubit_index – The index of the qubit.
Returns:: PauliOperator representing the Identity operator on the specified qubit.

static inline PauliOperator X(std::uint64_t qubit_index)

Factory method to create a Pauli-X operator on a specified qubit.

Parameters:: qubit_index – The index of the qubit.
Returns:: PauliOperator representing the Pauli-X operator on the specified qubit.

static inline PauliOperator Y(std::uint64_t qubit_index)

Factory method to create a Pauli-Y operator on a specified qubit.

Parameters:: qubit_index – The index of the qubit.
Returns:: PauliOperator representing the Pauli-Y operator on the specified qubit.

static inline PauliOperator Z(std::uint64_t qubit_index)

Factory method to create a Pauli-Z operator on a specified qubit.

Parameters:: qubit_index – The index of the qubit.
Returns:: PauliOperator representing the Pauli-Z operator on the specified qubit.

class PauliOperatorExpression

#include <qdk/chemistry/data/pauli_operator.hpp>

Base interface for Pauli operator expressions.

Subclassed by qdk::chemistry::data::PauliOperator, qdk::chemistry::data::ProductPauliOperatorExpression, qdk::chemistry::data::SumPauliOperatorExpression

Public Functions

virtual ~PauliOperatorExpression() = default

inline PauliOperator *as_pauli_operator()

Attempts to dynamically cast this expression to a PauliOperator.

Returns:: Pointer to PauliOperator if successful, nullptr otherwise.

inline const PauliOperator *as_pauli_operator() const

Attempts to dynamically cast this expression to a PauliOperator.

Returns:: Pointer to PauliOperator if successful, nullptr otherwise.

inline ProductPauliOperatorExpression *as_product_expression()

Attempts to dynamically cast this expression to a ProductPauliOperatorExpression.

Returns:: Pointer to ProductPauliOperatorExpression if successful, nullptr otherwise.

inline const ProductPauliOperatorExpression *as_product_expression() const

Attempts to dynamically cast this expression to a ProductPauliOperatorExpression.

Returns:: Pointer to ProductPauliOperatorExpression if successful, nullptr otherwise.

inline SumPauliOperatorExpression *as_sum_expression()

Attempts to dynamically cast this expression to a SumPauliOperatorExpression.

Returns:: Pointer to SumPauliOperatorExpression if successful, nullptr otherwise.

inline const SumPauliOperatorExpression *as_sum_expression() const

Attempts to dynamically cast this expression to a SumPauliOperatorExpression.

Returns:: Pointer to SumPauliOperatorExpression if successful, nullptr otherwise.

virtual std::unique_ptr<PauliOperatorExpression> clone() const = 0

Creates a deep copy of this expression.

Returns:: A unique_ptr to the cloned expression.

virtual std::unique_ptr<SumPauliOperatorExpression> distribute() const = 0

Distributes nested expressions to create a flat sum of products.

For example, it transforms expressions like (A + B) * (C - D) into A*C - A*D + B*C - B*D.

Returns:: A new SumPauliOperatorExpression in distributed form.

bool is_distributed() const

Returns whether this expression is in distributed form.

An expression is in distributed form when it contains no nested sums inside products. Specifically:

A PauliOperator is always distributed
A ProductPauliOperatorExpression is distributed if all its factors are distributed and none are SumPauliOperatorExpressions
A SumPauliOperatorExpression is distributed if all its terms are distributed

Distributed form is required by to_canonical_string() and to_canonical_terms(). Use distribute() to convert an expression to distributed form.

See also

distribute()

Returns:: true if this expression is in distributed form, false otherwise.

inline bool is_pauli_operator() const

Returns whether this expression is a Pauli operator.

Returns:: true if this is a PauliOperator, false otherwise.

inline bool is_product_expression() const

Returns whether this expression is a product expression.

Returns:: true if this is a ProductPauliOperatorExpression, false otherwise.

inline bool is_sum_expression() const

Returns whether this expression is a sum expression.

Returns:: true if this is a SumPauliOperatorExpression, false otherwise.

virtual std::uint64_t max_qubit_index() const = 0

Returns the maximum qubit index referenced in this expression.

Throws:: std::logic_error – If the expression is empty.
Returns:: The maximum qubit index.

virtual std::uint64_t min_qubit_index() const = 0

Returns the minimum qubit index referenced in this expression.

Throws:: std::logic_error – If the expression is empty.
Returns:: The minimum qubit index.

virtual std::uint64_t num_qubits() const = 0

Returns the number of qubits spanned by this expression.

Returns:: max_qubit_index() - min_qubit_index() + 1, or 0 if empty.

virtual std::unique_ptr<SumPauliOperatorExpression> prune_threshold(double epsilon) const = 0

Returns a new expression with small-magnitude terms removed.

Parameters:: epsilon – Terms with |coefficient| < epsilon are excluded.
Returns:: A new SumPauliOperatorExpression with small terms filtered out.

virtual std::unique_ptr<PauliOperatorExpression> simplify() const = 0

Simplifies the expression by combining like terms and carrying out qubit-wise multiplications.

For example, it combines terms like 2*X(0)*Y(1) + 3*X(0)*Y(1) into 5*X(0)*Y(1), and simplifies products like X(0)*X(0) into I(0).

This function will also reorder terms into a canonical form. e.g. X(1)*Y(0) will be reordered to Y(0)*X(1).

By convention, distribute will be called internally before simplify to ensure the expression is in a suitable form for simplification.

Returns:: A new simplified PauliOperatorExpression.

virtual std::string to_canonical_string(std::uint64_t min_qubit, std::uint64_t max_qubit) const = 0

Returns the canonical string representation for a qubit range.

The canonical string is a sequence of characters representing the Pauli operators on each qubit, in little-endian order (qubit 0 is leftmost). Identity operators are represented as ‘I’.

For example, for min_qubit=1 and max_qubit=3 for the expression

X(0) * Y(1) * Z(3) * X(4)

the returned string would be “YIZ”.

Parameters:

min_qubit – The minimum qubit index to include.
max_qubit – The maximum qubit index to include (inclusive).

Returns:

A canonical string representation.

virtual std::string to_canonical_string(std::uint64_t num_qubits) const = 0

Returns the canonical string representation of this expression.

Wraps to_canonical_string(0, max_qubit_index()+1).

Parameters:: num_qubits – The total number of qubits to represent.
Returns:: A canonical string representation.

virtual std::vector<std::pair<std::complex<double>, std::string>> to_canonical_terms() const = 0

Returns a vector of (coefficient, canonical_string) pairs.

Wraps to_canonical_terms(max_qubit_index()+1).

Returns:: Vector of pairs where each pair contains the coefficient and canonical string for each term.

virtual std::vector<std::pair<std::complex<double>, std::string>> to_canonical_terms(std::uint64_t num_qubits) const = 0

Returns a vector of (coefficient, canonical_string) pairs.

For example, the expression 2*X(0)*Z(2) + 3i*Y(1) on 4 qubits would return: [ (2, “XIZI”), (3i, “IYII”) ]

Parameters:: num_qubits – The total number of qubits to represent.
Returns:: Vector of pairs where each pair contains the coefficient and canonical string for each term.

virtual std::string to_string() const = 0

Returns a string representation of this expression.

Returns a human-readable string showing the structure of the arithmetic expression. For example, a product of two Pauli operators might be represented as “(X(0) * Z(1))”.

For the canonical string representation consistent with other frameworks, use to_canonical_string().

See also

to_canonical_string()

Returns:: A string representing this expression.

class ProductPauliOperatorExpression : public qdk::chemistry::data::PauliOperatorExpression

#include <qdk/chemistry/data/pauli_operator.hpp>

A PauliOperatorExpression representing Kronecker products of multiple PauliOperatorExpression instances.

For example, the expression X(0) * Y(1) represents the Pauli-X operator on qubit 0 tensor product with the Pauli-Y operator on qubit 1, with an implicit coefficient of 1.0.

The class also supports nesting of expressions, e.g., 2.0 * (X(0) + Z(2)) * Y(1)

where the left factor is SumPauliOperatorExpression and the right factor is a PauliOperator.

The product expression follows standard arithmetic rules for Kronecker products:

Distributive: A*(B + C) = A*B + A*C
Associative: (A*B)*C = A*(B*C)
Non-commutative: A*B != B*A in general for expressions acting on overlapping qubits.

Public Functions

ProductPauliOperatorExpression(): Constructs an empty ProductPauliOperatorExpression with coefficient 1.0.

ProductPauliOperatorExpression(const PauliOperatorExpression &left, const PauliOperatorExpression &right)

Constructs a ProductPauliOperatorExpression representing the product of two PauliOperatorExpression instances.

For example: auto left = PauliOperator::X(0); auto right = SumPauliOperatorExpression(PauliOperator::Y(1), PauliOperator::Z(2)); auto product = ProductPauliOperatorExpression(left, right);

Parameters:

left – The left PauliOperatorExpression factor.
right – The right PauliOperatorExpression factor.

ProductPauliOperatorExpression(const ProductPauliOperatorExpression &other)

Copy constructor.

Deep copies all factors.

Parameters:: other – The ProductPauliOperatorExpression to copy.

ProductPauliOperatorExpression(std::complex<double> coefficient)

Constructs a ProductPauliOperatorExpression with the specified coefficient and no expression factors.

Parameters:: coefficient – The scalar coefficient for this product expression.

ProductPauliOperatorExpression(std::complex<double> coefficient, const PauliOperatorExpression &expr)

Constructs a ProductPauliOperatorExpression with the specified coefficient and a single PauliOperatorExpression factor.

Parameters:

coefficient – The scalar coefficient for this product expression.
expr – The PauliOperatorExpression factor.

void add_factor(std::unique_ptr<PauliOperatorExpression> factor)

Appends a factor to this product.

The factor is added to the end of the factor list. Ownership is transferred to this expression.

Parameters:: factor – The expression to append.

virtual std::unique_ptr<PauliOperatorExpression> clone() const override

Creates a deep copy of this product expression.

Returns:: A unique_ptr to a new ProductPauliOperatorExpression.

virtual std::unique_ptr<SumPauliOperatorExpression> distribute() const override

Expands this product into a flat sum of products.

Recursively distributes multiplication over addition for all factors. For example, (X(0) + Y(0)) * Z(1) becomes X(0)*Z(1) + Y(0)*Z(1).

The result is always a SumPauliOperatorExpression where each term is a ProductPauliOperatorExpression containing only PauliOperator factors (no nested sums).

Returns:: A new SumPauliOperatorExpression in distributed form.

std::complex<double> get_coefficient() const

Returns the scalar coefficient of this product.

Returns:: The complex coefficient.

const std::vector<std::unique_ptr<PauliOperatorExpression>> &get_factors() const

Returns a const reference to the internal factor list.

Returns:: Vector of expression factors in multiplication order.

virtual std::uint64_t max_qubit_index() const override

Returns the maximum qubit index referenced in this expression.

Throws:: std::logic_error – If the expression has no factors.
Returns:: The maximum qubit index.

virtual std::uint64_t min_qubit_index() const override

Returns the minimum qubit index referenced in this expression.

Throws:: std::logic_error – If the expression has no factors.
Returns:: The minimum qubit index.

void multiply_coefficient(std::complex<double> c)

Multiplies the coefficient by the given scalar.

Parameters:: c – The scalar to multiply by.

virtual std::uint64_t num_qubits() const override

Returns the number of qubits spanned by this expression.

Returns:: max_qubit_index() - min_qubit_index() + 1, or 0 if empty.

virtual std::unique_ptr<SumPauliOperatorExpression> prune_threshold(double epsilon) const override

Returns a sum containing this product if it meets the threshold.

Parameters:: epsilon – Terms with |coefficient| < epsilon are excluded.
Returns:: A SumPauliOperatorExpression containing this product, or an empty sum if excluded.

void set_coefficient(std::complex<double> c)

Sets the scalar coefficient of this product.

Parameters:: c – The new coefficient value.

virtual std::unique_ptr<PauliOperatorExpression> simplify() const override

Simplifies this product by applying Pauli algebra rules.

If the expression is not already distributed, distribute() is called first.

Simplification performs the following steps:

Unrolls nested products into a flat list of PauliOperators
Sorts factors by qubit index (stable sort)
Combines operators on the same qubit using Pauli multiplication:
- P * P = I for any Pauli P
- X * Y = iZ, Y * Z = iX, Z * X = iY (cyclic)
- Y * X = -iZ, Z * Y = -iX, X * Z = -iY (anti-cyclic)
Strips identity operators from the result
Accumulates phase factors into the coefficient

Returns:: A simplified ProductPauliOperatorExpression with sorted, non-identity factors and updated coefficient.

virtual std::string to_canonical_string(std::uint64_t min_qubit, std::uint64_t max_qubit) const override

Returns the canonical string representation for a qubit range.

Parameters:

min_qubit – The minimum qubit index to include.
max_qubit – The maximum qubit index to include (inclusive).

Throws:

std::logic_error – If the expression is not in distributed form.

Returns:

A string of length (max_qubit - min_qubit + 1).

virtual std::string to_canonical_string(std::uint64_t num_qubits) const override

Returns the canonical string representation of this product.

The canonical string is a sequence of characters representing the Pauli operators on each qubit, in little-endian order (qubit 0 is leftmost). Identity operators are represented as ‘I’. The expression is simplified internally before generating the string.

Parameters:: num_qubits – The total number of qubits to represent.
Throws:: std::logic_error – If the expression is not in distributed form. Call distribute() first.
Returns:: A string of length num_qubits, e.g., “XIZI” for X(0)*Z(2) on 4 qubits.

virtual std::vector<std::pair<std::complex<double>, std::string>> to_canonical_terms() const override

Returns this product as a single (coefficient, canonical_string) pair.

Uses max_qubit_index() + 1 as the qubit count. An empty product returns a single term with coefficient and “I”.

Throws:: std::logic_error – If the expression is not in distributed form.
Returns:: A vector containing one pair.

virtual std::vector<std::pair<std::complex<double>, std::string>> to_canonical_terms(std::uint64_t num_qubits) const override

Returns this product as a single (coefficient, canonical_string) pair.

Parameters:: num_qubits – The total number of qubits to represent.
Throws:: std::logic_error – If the expression is not in distributed form.
Returns:: A vector containing one pair.

virtual std::string to_string() const override

Returns a human-readable string representation of this product.

Renders the coefficient (if not 1) followed by factors joined with “ * “. Sum factors are wrapped in parentheses. An empty product returns “1” or the coefficient string.

To improve readability, coefficients sufficiently close (within fp64 epsilon: ~2.22e-16) to {-1, 1, i, -i} are rendered as “-”, “”, “i”, or “-i” respectively.

Returns:: A string like “2 * X(0) * Y(1)” or “(X(0) + Z(1)) * Y(2)”.

class SciWavefunctionContainer : public qdk::chemistry::data::WavefunctionContainer

#include <qdk/chemistry/data/wavefunction_containers/sci.hpp>

Public Types

using DeterminantVector = ContainerTypes::DeterminantVector

using MatrixVariant = ContainerTypes::MatrixVariant

using ScalarVariant = ContainerTypes::ScalarVariant

using VectorVariant = ContainerTypes::VectorVariant

Public Functions

SciWavefunctionContainer(const VectorVariant &coeffs, const DeterminantVector &dets, std::shared_ptr<Orbitals> orbitals, const std::optional<MatrixVariant> &one_rdm_spin_traced, const std::optional<MatrixVariant> &one_rdm_aa, const std::optional<MatrixVariant> &one_rdm_bb, const std::optional<VectorVariant> &two_rdm_spin_traced, const std::optional<VectorVariant> &two_rdm_aabb, const std::optional<VectorVariant> &two_rdm_aaaa, const std::optional<VectorVariant> &two_rdm_bbbb, WavefunctionType type = WavefunctionType::SelfDual)

Constructs a wavefunction with full reduced density matrix (RDM) data.

Parameters:

coeffs – The vector of CI coefficients (can be real or complex)
dets – The vector of determinants
orbitals – Shared pointer to orbital basis set
one_rdm_spin_traced – Spin-traced 1-RDM for active orbitals (optional)
one_rdm_aa – Alpha-alpha block of 1-RDM for active orbitals (optional)
one_rdm_bb – Beta-beta block of 1-RDM for active orbitals (optional)
two_rdm_spin_traced – Spin-traced 2-RDM for active orbitals (optional)
two_rdm_aabb – Alpha-alpha-beta-beta block of 2-RDM for active orbitals (optional)
two_rdm_aaaa – Alpha-alpha-alpha-alpha block of 2-RDM for active orbitals (optional)
two_rdm_bbbb – Beta-beta-beta-beta block of 2-RDM for active orbitals (optional)
type – The type of wavefunction

SciWavefunctionContainer(const VectorVariant &coeffs, const DeterminantVector &dets, std::shared_ptr<Orbitals> orbitals, const std::optional<MatrixVariant> &one_rdm_spin_traced, const std::optional<VectorVariant> &two_rdm_spin_traced, WavefunctionType type = WavefunctionType::SelfDual)

Constructs a wavefunction with full reduced density matrix (RDM) data.

Parameters:

coeffs – The vector of CI coefficients (can be real or complex)
dets – The vector of determinants
orbitals – Shared pointer to orbital basis set
one_rdm_spin_traced – Spin-traced 1-RDM for active orbitals (optional)
two_rdm_spin_traced – Spin-traced 2-RDM for active orbitals (optional)
type – The type of wavefunction

SciWavefunctionContainer(const VectorVariant &coeffs, const DeterminantVector &dets, std::shared_ptr<Orbitals> orbitals, WavefunctionType type = WavefunctionType::SelfDual)

Constructs a wavefunction with full reduced density matrix data.

Parameters:

coeffs – The vector of CI coefficients (can be real or complex)
dets – The vector of determinants
orbitals – Shared pointer to orbital basis set
type – The type of wavefunction

~SciWavefunctionContainer() override = default: Destructor.

virtual void clear_caches() const override

Clear cached data to release memory.

Clears the following cached data for Selected Configuration Interaction (SCI) wavefunctions:

One-particle RDMs: spin-traced (_one_rdm_spin_traced) and spin-dependent (_one_rdm_spin_dependent_aa, _one_rdm_spin_dependent_bb)
Two-particle RDMs: spin-traced (_two_rdm_spin_traced) and spin-dependent (_two_rdm_spin_dependent_aaaa, _two_rdm_spin_dependent_aabb, _two_rdm_spin_dependent_bbbb)

virtual std::unique_ptr<WavefunctionContainer> clone() const override: Clone method for deep copying.

virtual const DeterminantVector &get_active_determinants() const override

Get all determinants in the wavefunction.

Returns:: Vector of all configurations/determinants

virtual std::pair<size_t, size_t> get_active_num_electrons() const override

Get number of active alpha and beta electrons.

Returns:: Pair of (n_alpha_active, n_beta_active) electrons

virtual std::pair<Eigen::VectorXd, Eigen::VectorXd> get_active_orbital_occupations() const override

Get orbital occupations for active orbitals only.

Returns:: Pair of (alpha_active_occupations, beta_active_occupations)

virtual ScalarVariant get_coefficient(const Configuration &det) const override

Get coefficient for a specific determinant.

The configuration is expected to be a determinant describing only the wavefunction’s active space.

Parameters:: det – Configuration/determinant to get coefficient for
Returns:: Coefficient of the determinant

virtual const VectorVariant &get_coefficients() const override

Get all determinants in the wavefunction.

Returns:: Vector of all configurations/determinants

virtual const ConfigurationSet &get_configuration_set() const override

Get the configuration set for this wavefunction.

Throws:: std::runtime_error – if configuration set is not available
Returns:: Reference to the configuration set containing determinants and orbitals

virtual std::string get_container_type() const override

Get container type identifier for serialization.

Returns:: String “sci”

virtual std::shared_ptr<Orbitals> get_orbitals() const override

Get reference to orbital basis set.

Returns:: Shared pointer to orbitals

virtual std::pair<size_t, size_t> get_total_num_electrons() const override

Get total number of alpha and beta electrons (active + inactive)

Returns:: Pair of (n_alpha_total, n_beta_total) electrons

virtual std::pair<Eigen::VectorXd, Eigen::VectorXd> get_total_orbital_occupations() const override

Get orbital occupations for all orbitals (total = active + inactive.

virtual)

Returns:: Pair of (alpha_occupations_total, beta_occupations_total)

virtual bool has_coefficients() const override

Check if this container has coefficients data.

Returns:: True if coefficients are available, false otherwise

virtual bool has_configuration_set() const override

Check if this container has configuration set data.

Returns:: True if configuration set is available, false otherwise

virtual bool is_complex() const override

Check if the wavefunction is complex-valued.

Returns:: True if coefficients are complex, false if real

virtual double norm() const override

Calculate norm of the wavefunction.

Returns:: Norm

virtual ScalarVariant overlap(const WavefunctionContainer &other) const override

Calculate overlap with another wavefunction.

Parameters:: other – Other wavefunction
Returns:: Overlap value

virtual size_t size() const override

Get number of determinants.

Returns:: Number of determinants in the wavefunction

virtual nlohmann::json to_json() const override

Convert container to JSON format.

Returns:: JSON object containing container data

class SettingNotFound : public std::runtime_error

#include <qdk/chemistry/data/settings.hpp>

Exception thrown when a setting is not found.

Public Functions

inline explicit SettingNotFound(const std::string &key)

class Settings : public qdk::chemistry::data::DataClass, public std::enable_shared_from_this<Settings>

#include <qdk/chemistry/data/settings.hpp>

Base class for extensible settings objects.

This class provides a flexible settings system that can:

Store arbitrary typed values using a variant system
Be easily extended by derived classes during construction only
Map seamlessly to Python dictionaries via pybind11
Provide type-safe access to settings with default values
Support nested settings structures
Prevent extension of the settings map after class initialization

The settings map can only be populated during construction using the protected set_default methods. This design ensures that the available settings are fixed at initialization time and cannot be extended later.

Usage:

class MySettings : public Settings {
public:
    MySettings() {
        // Can only call set_default during construction
        set_default("max_iterations", 100);
        set_default("convergence_threshold", 1e-6);
        set_default("method", std::string("default"));
    }

    // Convenience getters with validation (optional)
    int32_t get_max_iterations() const { return
get<int32_t>("max_iterations"); } double get_convergence_threshold() const {
return get<double>("convergence_threshold"); } std::string get_method() const
{ return get<std::string>("method"); }

    // After construction, only existing settings can be modified
    void set_max_iterations(int32_t value) { set("max_iterations", value); }
    void set_convergence_threshold(double value) {
set("convergence_threshold", value); }
};

Subclassed by qdk::chemistry::algorithms::ElectronicStructureSettings, qdk::chemistry::algorithms::MultiConfigurationSettings

Public Functions

Settings() = default: Default constructor.

Settings(const Settings &other) = default: Copy constructor.

Settings(Settings &&other) noexcept = default: Move constructor.

virtual ~Settings() = default: Virtual destructor for proper inheritance.

std::string as_table(size_t max_width = 120, bool show_undocumented = false) const

Print settings as a formatted table.

Prints all documented settings in a table format with columns: Key, Value, Limits, Description

The table fits within the specified width with multi-line descriptions as needed. Non-integer numeric values are displayed in scientific notation.

Parameters:

max_width – Maximum total width of the table (default: 120)
show_undocumented – Whether to show undocumented settings (default: false)

Returns:

Formatted table string

bool empty() const

Check if settings are empty.

Returns:: true if no settings are stored

SettingValue get(const std::string &key) const

Get a setting value as variant.

Parameters:: key – The setting key
Throws:: SettingNotFound – if key doesn’t exist
Returns:: The setting value as SettingValue variant

template<typename T> inline T get(const std::string &key) const

Get a setting value with type checking.

Parameters:

key – The setting key

Throws:

SettingNotFound – if key doesn’t exist
SettingTypeMismatch – if type conversion fails

Returns:

The setting value

const std::map<std::string, SettingValue> &get_all_settings() const

Get all settings as a map for Python interoperability.

Returns:: Map of setting keys to their SettingValue variants

std::string get_as_string(const std::string &key) const

Get a setting value as a string representation.

Parameters:: key – The setting key
Throws:: SettingNotFound – if key doesn’t exist
Returns:: String representation of the value

std::string get_description(const std::string &key) const

Get the description of a setting.

Parameters:: key – The setting key
Throws:: SettingNotFound – if key doesn’t exist or has no description
Returns:: The description string

Constraint get_limits(const std::string &key) const

Get the limits of a setting.

Parameters:: key – The setting key
Throws:: SettingNotFound – if key doesn’t exist or has no limits
Returns:: The limit value (can be range or enumeration)

SettingValue get_or_default(const std::string &key, const SettingValue &default_value) const

Get a setting value with a default if not found (variant version)

Parameters:

key – The setting key
default_value – The default value to return if key not found

Returns:

The setting value or default

template<typename T> inline T get_or_default(const std::string &key, const T &default_value) const

Get a setting value with a default if not found (template version)

Parameters:

key – The setting key
default_value – The default value to return if key not found

Returns:

The setting value or default

virtual std::string get_summary() const override

Get a summary string describing the settings.

Returns:: String containing settings summary information

std::string get_type_name(const std::string &key) const

Get the type name of a setting value.

Parameters:: key – The setting key
Returns:: String representation of the type, or “not_found” if key doesn’t exist

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

Check if a setting exists.

Parameters:: key – The setting key
Returns:: true if the setting exists

bool has_description(const std::string &key) const

Check if a setting has a description.

Parameters:: key – The setting key
Returns:: true if the setting has a description

bool has_limits(const std::string &key) const

Check if a setting has defined limits.

Parameters:: key – The setting key
Returns:: true if the setting has limits defined

template<typename T> inline bool has_type(const std::string &key) const

Check if a setting exists and has the expected type.

Parameters:: key – The setting key
Returns:: true if the setting exists and has the correct type

bool is_documented(const std::string &key) const

Check if a setting is documented.

Parameters:: key – The setting key
Throws:: SettingNotFound – if key doesn’t exist
Returns:: true if the setting is marked as documented

std::vector<std::string> keys() const

Get all setting keys.

Returns:: Vector of all setting keys

void lock() const: Lock the settings to prevent further modifications.

Settings &operator=(const Settings &other) = delete: Copy assignment operator.

Settings &operator=(Settings &&other) noexcept = default: Move assignment operator.

void set(const std::string &key, const char *value)

Sets the value for a given key in the settings.

This overload allows setting the value using a C-style string. Internally, the value is converted to a std::string and passed to the main set function.

Parameters:

key – The key to associate with the value.
value – The C-style string value to set.

void set(const std::string &key, const SettingValue &value)

Set a setting value.

Parameters:

key – The setting key
value – The setting value

template<NonIntegralBool T> inline void set(const std::string &key, const T &value)

Set a setting value (template version for convenience)

Note

This template is disabled for non-int64_t integers to avoid ambiguity

Parameters:

key – The setting key
value – The setting value

template<typename Integer> inline void set(const std::string &key, Integer value)

size_t size() const

Get the number of settings.

Returns:: Number of settings

virtual void to_file(const std::string &filename, const std::string &type) const override

Save settings to file in specified format.

Parameters:

filename – Path to file to create/overwrite
type – Format type (“json” or “hdf5”)

Throws:

std::invalid_argument – if unknown type
std::runtime_error – if I/O error occurs

virtual void to_hdf5(H5::Group &group) const override

Save settings to HDF5 group.

Parameters:: group – HDF5 group to save data to
Throws:: std::runtime_error – if I/O error occurs

virtual void to_hdf5_file(const std::string &filename) const override

Save settings to HDF5 file.

Parameters:: filename – Path to HDF5 file to create/overwrite
Throws:: std::runtime_error – if I/O error occurs

virtual nlohmann::json to_json() const override

Convert settings to JSON.

Returns:: JSON object containing all settings

virtual void to_json_file(const std::string &filename) const override

Save settings to JSON file.

Parameters:: filename – Path to JSON file to write
Throws:: std::runtime_error – if file cannot be opened or written

template<typename T> inline std::optional<T> try_get(const std::string &key) const

Try to get a setting value with type checking, returns optional.

Parameters:: key – The setting key
Returns:: Optional containing the value if found and correct type, empty otherwise

void update(const Settings &other_settings)

Apply settings from another Settings object.

This method performs a bulk update of settings from another Settings object. Only keys that exist in both this object and the other_settings object will be updated. All keys in other_settings must already exist in this settings object. If any key is missing, the entire operation fails and no settings are modified. This ensures atomicity of the bulk update.

Parameters:

other_settings – The Settings object to copy values from

Throws:

SettingNotFound – if any key from other_settings doesn’t exist in this object
SettingTypeMismatch – if any value type is incompatible

void update(const std::map<std::string, SettingValue> &updates_map)

Apply multiple settings from a map.

This method performs a bulk update of settings. All keys in the map must already exist in the settings. If any key is missing, the entire operation fails and no settings are modified. This ensures atomicity of the bulk update.

Parameters:

updates_map – Map of setting keys to their new values

Throws:

SettingNotFound – if any key doesn’t exist
SettingTypeMismatch – if any value type is incompatible

void update(const std::map<std::string, std::string> &updates_map)

Apply multiple settings from a string-to-string map.

This method performs a bulk update of settings from string representations. The string values are parsed based on the current type of each setting. All keys in the map must already exist in the settings. If any key is missing or any value cannot be parsed, the entire operation fails and no settings are modified. This ensures atomicity of the bulk update.

Supported string formats:

bool: “true”/”false”, “1”/”0”, “yes”/”no”, “on”/”off” (case-insensitive)
integers: Standard integer format (e.g., “123”, “-456”)
floating-point: Standard float format (e.g., “3.14”, “1e-6”)
string: Direct string value
vectors: JSON array format (e.g., “[1,2,3]” or “[“a”,”b”,”c”]”)

Parameters:

updates_map – Map of setting keys to their new values as strings

Throws:

SettingNotFound – if any key doesn’t exist
std::runtime_error – if any string value cannot be parsed to the expected type

void update(const std::string &key, const SettingValue &value)

Update a setting value (variant version), throwing if key doesn’t exist.

Parameters:

key – The setting key
value – The new value

Throws:

SettingNotFound – if key doesn’t exist

template<typename T> inline void update(const std::string &key, const T &value)

Update a setting value, throwing if key doesn’t exist.

Parameters:

key – The setting key
value – The new value

Throws:

SettingNotFound – if key doesn’t exist

void validate_required(const std::vector<std::string> &required_keys) const

Validate that all required settings are present.

Parameters:: required_keys – Vector of required setting keys
Throws:: SettingNotFound – if any required setting is missing

Public Static Functions

static std::shared_ptr<Settings> from_file(const std::string &filename, const std::string &type)

Create settings from file in specified format (static factory method)

Parameters:

filename – Path to file to read
type – Format type (“json” or “hdf5”)

Throws:

std::invalid_argument – if unknown type
std::runtime_error – if file doesn’t exist or I/O error occurs

Returns:

Shared pointer to new Settings instance

static std::shared_ptr<Settings> from_hdf5(H5::Group &group)

Create settings from HDF5 group (static factory method)

Parameters:: group – HDF5 group to read
Throws:: std::runtime_error – if I/O error occurs
Returns:: Shared pointer to new Settings instance

static std::shared_ptr<Settings> from_hdf5_file(const std::string &filename)

Create settings from HDF5 file (static factory method)

Parameters:: filename – Path to HDF5 file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: Shared pointer to new Settings instance

static std::shared_ptr<Settings> from_json(const nlohmann::json &json_obj)

Create settings from JSON (static factory method)

Parameters:: json_obj – JSON object containing settings data
Throws:: std::runtime_error – if JSON is malformed
Returns:: Shared pointer to new Settings instance

static std::shared_ptr<Settings> from_json_file(const std::string &filename)

Create settings from JSON file (static factory method)

Parameters:: filename – Path to JSON file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: Shared pointer to new Settings instance

class SettingsAreLocked : public std::runtime_error

#include <qdk/chemistry/data/settings.hpp>

Exception thrown when modification of locked settings is requested.

Public Functions

inline explicit SettingsAreLocked()

class SettingTypeMismatch : public std::runtime_error

#include <qdk/chemistry/data/settings.hpp>

Exception thrown when a setting type conversion fails.

Public Functions

inline explicit SettingTypeMismatch(const std::string &key, const std::string &expected_type)

struct Shell

#include <qdk/chemistry/data/basis_set.hpp>

Information about a shell of atomic orbitals.

A shell represents a group of atomic orbitals that share the same atom, angular momentum, and primitive functions, but differ in magnetic quantum numbers. For example, a p-shell contains px, py, pz functions.

Primitive data is stored as raw vectors instead of Primitive objects for better performance and simpler data handling.

By convention, the coefficients are stored as the raw, unnormalized contraction coefficients for the primitives. This convention is adopted to facilitate compatibility with various quantum chemistry software packages and libraries, which often use raw coefficients in their basis set definitions. The normalization of these coefficients is typically handled during the computation of integrals or other operations, rather than being stored in the basis set itself.

Public Functions

inline Shell(size_t atom_idx, OrbitalType orb_type, const Eigen::VectorXd &exp, const Eigen::VectorXd &coeff): Constructor with primitive data.

inline Shell(size_t atom_idx, OrbitalType orb_type, const Eigen::VectorXd &exp, const Eigen::VectorXd &coeff, const Eigen::VectorXi &rpow): Constructor with primitive data and radial powers (for ECP shells)

Shell(size_t atom_idx, OrbitalType orb_type, const std::vector<double> &exp_list, const std::vector<double> &coeff_list): Constructor with vectors for primitives.

Shell(size_t atom_idx, OrbitalType orb_type, const std::vector<double> &exp_list, const std::vector<double> &coeff_list, const std::vector<int> &rpow_list): Constructor with vectors for primitives and radial powers (for ECP shells)

inline int get_angular_momentum() const: Get angular momentum quantum number.

inline size_t get_num_atomic_orbitals(AOType atomic_orbital_type = AOType::Spherical) const

Get number of atomic orbitals in this shell.

Parameters:: atomic_orbital_type – Whether to use spherical or cartesian atomic

inline size_t get_num_primitives() const: Get number of primitives in this shell.

inline bool has_radial_powers() const: Check if this shell has radial powers (i.e., is an ECP shell)

Public Members

size_t atom_index = 0ul: Index of the atom this shell belongs to.

Eigen::VectorXd coefficients: Contraction coefficients for primitives.

Eigen::VectorXd exponents: Orbital exponents for primitive Gaussians.

OrbitalType orbital_type = OrbitalType::S: Type of orbital (s, p, d, f, etc.)

Eigen::VectorXi rpowers: Radial powers for ECP shells (r^n terms)

class SlaterDeterminantContainer : public qdk::chemistry::data::WavefunctionContainer

#include <qdk/chemistry/data/wavefunction_containers/sd.hpp>

Wavefunction container representing a single Slater determinant.

This class represents the simplest wavefunction - a single Slater determinant with coefficient 1.0. It provides efficient storage and computation for single-determinant wavefunctions such as Hartree-Fock reference states.

Public Types

using DeterminantVector = ContainerTypes::DeterminantVector

using MatrixVariant = ContainerTypes::MatrixVariant

using ScalarVariant = ContainerTypes::ScalarVariant

using VectorVariant = ContainerTypes::VectorVariant

Public Functions

SlaterDeterminantContainer(const Configuration &det, std::shared_ptr<Orbitals> orbitals, WavefunctionType type = WavefunctionType::SelfDual)

Constructs a single Slater determinant wavefunction.

This constructor validates that:

The configuration has sufficient orbital capacity for the active space
Any orbitals beyond the active space size are unoccupied

Note: Configurations only represent the active space, not the full orbital space. Inactive and virtual orbitals are not included in the configuration representation.

Parameters:

det – The single determinant configuration (representing active space only)
orbitals – Shared pointer to orbital basis set
type – Type of wavefunction (default: SelfDual)

Throws:

std::invalid_argument – If validation fails

~SlaterDeterminantContainer() override = default

virtual void clear_caches() const override

Clear cached data to release memory.

Clears the following cached data:

Determinant vector cache (_determinant_vector_cache)
One-particle RDMs (spin-traced and spin-dependent)
Two-particle RDMs (spin-traced and spin-dependent)

This is particularly useful for freeing memory when the cached RDMs are no longer needed.

virtual std::unique_ptr<WavefunctionContainer> clone() const override: Create a deep copy of this container.

bool contains_determinant(const Configuration &det) const: Check if a determinant matches the stored one.

virtual const DeterminantVector &get_active_determinants() const override: Get all determinants in the wavefunction.

virtual std::pair<size_t, size_t> get_active_num_electrons() const override

Get number of active alpha and beta electrons.

Returns:: Pair of (n_alpha_active, n_beta_active) electrons

virtual std::tuple<const MatrixVariant&, const MatrixVariant&> get_active_one_rdm_spin_dependent() const override: Get spin-dependent one-particle RDMs for active orbitals only.

virtual const MatrixVariant &get_active_one_rdm_spin_traced() const override: Get spin-traced one-particle RDM for active orbitals only.

virtual std::pair<Eigen::VectorXd, Eigen::VectorXd> get_active_orbital_occupations() const override

Get orbital occupations for active orbitals only.

Returns:: Pair of (alpha_active_occupations, beta_active_occupations)

virtual std::tuple<const VectorVariant&, const VectorVariant&, const VectorVariant&> get_active_two_rdm_spin_dependent() const override: Get spin-dependent two-particle RDMs for active orbitals only.

virtual const VectorVariant &get_active_two_rdm_spin_traced() const override: Get spin-traced two-particle RDM for active orbitals only.

virtual ScalarVariant get_coefficient(const Configuration &det) const override

Get coefficient for a specific determinant.

The configuration is expected to be a determinant describing only the wavefunction’s active space.

For single determinant: returns 1.0 if det matches, 0.0 otherwise.

Parameters:: det – Configuration/determinant to get coefficient for
Returns:: Coefficient of the determinant

virtual const VectorVariant &get_coefficients() const override

Get all coefficients (always a single coefficient of 1.0)

Returns:: Vector of all coefficients (real or complex)

virtual std::string get_container_type() const override

Get container type identifier for serialization.

Returns:: String “sd”

virtual std::shared_ptr<Orbitals> get_orbitals() const override

Get reference to orbital basis set.

Returns:: Shared pointer to orbitals

virtual Eigen::VectorXd get_single_orbital_entropies() const override: Calculate single orbital entropies for active orbitals only.

virtual std::pair<size_t, size_t> get_total_num_electrons() const override

Get total number of alpha and beta electrons (active + inactive)

Returns:: Pair of (n_alpha_total, n_beta_total) electrons

virtual std::pair<Eigen::VectorXd, Eigen::VectorXd> get_total_orbital_occupations() const override

Get orbital occupations for all orbitals (total = active + inactive.

virtual)

Returns:: Pair of (alpha_occupations_total, beta_occupations_total)

virtual bool has_one_rdm_spin_dependent() const override

Check if spin-dependent one-particle RDMs for active orbitals are available.

Returns:: True if available

virtual bool has_one_rdm_spin_traced() const override

Check if spin-traced one-particle RDM for active orbitals is available.

Returns:: True if available

virtual bool has_two_rdm_spin_dependent() const override

Check if spin-dependent two-particle RDMs for active orbitals are available.

Returns:: True if available

virtual bool has_two_rdm_spin_traced() const override

Check if spin-traced two-particle RDM for active orbitals is available.

Returns:: True if available

virtual bool is_complex() const override

Check if the wavefunction is complex-valued.

Returns:: Always false for Slater determinants (coefficients are unity)

virtual double norm() const override: Calculate norm of the wavefunction.

virtual ScalarVariant overlap(const WavefunctionContainer &other) const override: Calculate overlap with another wavefunction.

virtual size_t size() const override: Get number of determinants.

virtual void to_hdf5(H5::Group &group) const override

Convert container to HDF5 group.

Parameters:: group – HDF5 group to write container data to
Throws:: std::runtime_error – if HDF5 I/O error occurs

virtual nlohmann::json to_json() const override

Convert container to JSON format.

Returns:: JSON object containing container data

Public Static Functions

static std::unique_ptr<SlaterDeterminantContainer> from_hdf5(H5::Group &group)

Load container from HDF5 group.

Parameters:: group – HDF5 group containing container data
Throws:: std::runtime_error – if HDF5 data is malformed or I/O error occurs
Returns:: Unique pointer to SD container created from HDF5 group

static std::unique_ptr<SlaterDeterminantContainer> from_json(const nlohmann::json &j)

Load container from JSON format.

Parameters:: j – JSON object containing container data
Throws:: std::runtime_error – if JSON is malformed
Returns:: Unique pointer to SD container created from JSON data

class StabilityResult : public qdk::chemistry::data::DataClass, public std::enable_shared_from_this<StabilityResult>

#include <qdk/chemistry/data/stability_result.hpp>

Result structure for wavefunction stability analysis.

The StabilityResult class encapsulates the results of a stability check performed on a wavefunction. It contains information about whether the wavefunction is stable, along with the eigenvalues and eigenvectors of the stability matrix for both internal and external stability. (See J. Chem. Phys. 66, 3045–3050 (1977) for classification of stability types.)

This class provides:

Internal and external stability status
Overall stability status (stable only if both internal and external are stable)
Internal and external eigenvalues of the stability matrices
Internal and external eigenvectors of the stability matrices
Convenient access methods for stability analysis results

Eigenvector Format

The eigenvectors encode orbital rotation parameters between occupied and virtual orbitals. The required size depends on the orbital type:

RHF (Restricted Hartree-Fock):

Size: num_occupied_orbitals * num_virtual_orbitals
Where: num_virtual_orbitals = num_molecular_orbitals - num_occupied_orbitals
Elements represent rotations between occupied and virtual spatial orbitals
Both spins rotate together (spin symmetry preserved)

UHF (Unrestricted Hartree-Fock):

Size: num_alpha_occupied_orbitals * num_alpha_virtual_orbitals + num_beta_occupied_orbitals * num_beta_virtual_orbitals
Where: num_alpha_virtual_orbitals = num_molecular_orbitals - num_alpha_occupied_orbitals num_beta_virtual_orbitals = num_molecular_orbitals - num_beta_occupied_orbitals
First num_alpha_occupied_orbitals * num_alpha_virtual_orbitals elements: alpha rotations
Last num_beta_occupied_orbitals * num_beta_virtual_orbitals elements: beta rotations
Alpha and beta orbitals rotate independently

ROHF (Restricted Open-shell Hartree-Fock):

The rotation mask is the union of two rectangular blocks:
1. Alpha block: num_alpha_occupied_orbitals * num_alpha_virtual_orbitals
2. Beta block: num_beta_occupied_orbitals * num_beta_virtual_orbitals
Size calculation for union (assuming num_alpha_occupied >= num_beta_occupied): num_alpha_occupied_orbitals * (num_molecular_orbitals - num_alpha_occupied_orbitals) + (num_alpha_occupied_orbitals - num_beta_occupied_orbitals) * num_beta_occupied_orbitals
This equals the virtual-occupied block plus the additional doubly-occupied to singly-occupied block

Indexing Convention: The occupied orbital index varies fastest. For the element corresponding to occupied orbital i and virtual orbital a, the index is computed as: index = i + a * num_occupied. This convention is from row-major eigenvector (num_virtual, num_occupied).

Note

Internal stability typically refers to stability against perturbations within the same method (e.g. RHF -> RHF), while external stability refers to stability against perturbations between different methods (e.g. RHF -> UHF).

Public Functions

StabilityResult() = default: Default constructor.

inline StabilityResult(bool internal_stable, bool external_stable, const Eigen::VectorXd &internal_eigenvalues, const Eigen::MatrixXd &internal_eigenvectors, const Eigen::VectorXd &external_eigenvalues, const Eigen::MatrixXd &external_eigenvectors)

Construct a StabilityResult with specific values.

Parameters:

internal_stable – True if internal stability is satisfied
external_stable – True if external stability is satisfied
internal_eigenvalues – Eigenvalues of the internal stability matrix
internal_eigenvectors – Eigenvectors of the internal stability matrix
external_eigenvalues – Eigenvalues of the external stability matrix
external_eigenvectors – Eigenvectors of the external stability matrix

StabilityResult(const StabilityResult&) = default: Copy constructor.

StabilityResult(StabilityResult&&) noexcept = default: Move constructor.

virtual ~StabilityResult() = default: Destructor.

bool empty() const

Check if the stability result is empty.

Returns:: true if no eigenvalues/eigenvectors are present for internal or external

inline size_t external_size() const

Get the number of external eigenvalues.

Returns:: Number of external eigenvalues in the stability matrix

inline const Eigen::VectorXd &get_external_eigenvalues() const

Get the external eigenvalues of the stability matrix.

Returns:: Reference to the external eigenvalues vector

inline const Eigen::MatrixXd &get_external_eigenvectors() const

Get the external eigenvectors of the stability matrix.

Returns:: Reference to the external eigenvectors matrix

inline const Eigen::VectorXd &get_internal_eigenvalues() const

Get the internal eigenvalues of the stability matrix.

Returns:: Reference to the internal eigenvalues vector

inline const Eigen::MatrixXd &get_internal_eigenvectors() const

Get the internal eigenvectors of the stability matrix.

Returns:: Reference to the internal eigenvectors matrix

double get_smallest_eigenvalue() const

Get the smallest eigenvalue across both internal and external.

Throws:: std::runtime_error – if no eigenvalues are present
Returns:: Smallest eigenvalue overall (most negative for unstable systems)

std::pair<double, Eigen::VectorXd> get_smallest_eigenvalue_and_vector() const

Get the smallest eigenvalue and its corresponding eigenvector across both internal and external.

Throws:: std::runtime_error – if no eigenvalues are present
Returns:: Pair of (eigenvalue, eigenvector) for the smallest eigenvalue overall

double get_smallest_external_eigenvalue() const

Get the smallest external eigenvalue.

Throws:: std::runtime_error – if no external eigenvalues are present
Returns:: Smallest external eigenvalue (most negative for unstable systems)

std::pair<double, Eigen::VectorXd> get_smallest_external_eigenvalue_and_vector() const

Get the smallest external eigenvalue and its corresponding eigenvector.

Throws:: std::runtime_error – if no external eigenvalues are present
Returns:: Pair of (eigenvalue, eigenvector) for the smallest external eigenvalue

double get_smallest_internal_eigenvalue() const

Get the smallest internal eigenvalue.

Throws:: std::runtime_error – if no internal eigenvalues are present
Returns:: Smallest internal eigenvalue (most negative for unstable systems)

std::pair<double, Eigen::VectorXd> get_smallest_internal_eigenvalue_and_vector() const

Get the smallest internal eigenvalue and its corresponding eigenvector.

Throws:: std::runtime_error – if no internal eigenvalues are present
Returns:: Pair of (eigenvalue, eigenvector) for the smallest internal eigenvalue

virtual std::string get_summary() const override

Get summary string of stability result information.

Returns:: String describing the stability result

bool has_external_result() const

Check if external stability data is present.

Returns:: true if external eigenvalues are present

bool has_internal_result() const

Check if internal stability data is present.

Returns:: true if internal eigenvalues are present

inline size_t internal_size() const

Get the number of internal eigenvalues.

Returns:: Number of internal eigenvalues in the stability matrix

inline bool is_external_stable() const

Check if external stability is satisfied.

Returns:: True if external stability is satisfied

inline bool is_internal_stable() const

Check if internal stability is satisfied.

Returns:: True if internal stability is satisfied

inline bool is_stable() const

Check if the wavefunction is stable overall.

Returns:: True if both internal and external stability are satisfied

StabilityResult &operator=(const StabilityResult&) = default: Copy assignment operator.

StabilityResult &operator=(StabilityResult&&) noexcept = default: Move assignment operator.

inline void set_external_eigenvalues(const Eigen::VectorXd &external_eigenvalues)

Set the external eigenvalues.

Parameters:: external_eigenvalues – The external eigenvalues of the stability matrix

inline void set_external_eigenvectors(const Eigen::MatrixXd &external_eigenvectors)

Set the external eigenvectors.

Parameters:: external_eigenvectors – The external eigenvectors of the stability matrix

inline void set_external_stable(bool external_stable)

Set the external stability status.

Parameters:: external_stable – True if external stability is satisfied

inline void set_internal_eigenvalues(const Eigen::VectorXd &internal_eigenvalues)

Set the internal eigenvalues.

Parameters:: internal_eigenvalues – The internal eigenvalues of the stability matrix

inline void set_internal_eigenvectors(const Eigen::MatrixXd &internal_eigenvectors)

Set the internal eigenvectors.

Parameters:: internal_eigenvectors – The internal eigenvectors of the stability matrix

inline void set_internal_stable(bool internal_stable)

Set the internal stability status.

Parameters:: internal_stable – True if internal stability is satisfied

virtual void to_file(const std::string &filename, const std::string &type) const override

Save object to file in the specified format.

Parameters:

filename – Path to the output file
type – Format type (e.g., “json”, “hdf5”)

Throws:

std::invalid_argument – if format type is not supported
std::runtime_error – if I/O error occurs

virtual void to_hdf5(H5::Group &group) const override

Save object to HDF5 group.

Parameters:: group – HDF5 group to save data to
Throws:: std::runtime_error – if I/O error occurs

virtual void to_hdf5_file(const std::string &filename) const override

Save object to HDF5 file.

Parameters:: filename – Path to the output HDF5 file
Throws:: std::runtime_error – if I/O error occurs

virtual nlohmann::json to_json() const override

Convert object to JSON representation.

Returns:: JSON object containing the serialized data

virtual void to_json_file(const std::string &filename) const override

Save object to JSON file.

Parameters:: filename – Path to the output JSON file
Throws:: std::runtime_error – if I/O error occurs

Public Static Functions

static std::shared_ptr<StabilityResult> from_file(const std::string &filename, const std::string &type)

Load object from file in the specified format.

Parameters:

filename – Path to the input file
type – Format type (e.g., “json”, “hdf5”)

Throws:

std::invalid_argument – if format type is not supported
std::runtime_error – if I/O error occurs

Returns:

Shared pointer to the loaded StabilityResult

static std::shared_ptr<StabilityResult> from_hdf5(H5::Group &group)

Load object from HDF5 group.

Parameters:: group – HDF5 group to load data from
Throws:: std::runtime_error – if I/O error occurs
Returns:: Shared pointer to the loaded StabilityResult

static std::shared_ptr<StabilityResult> from_hdf5_file(const std::string &filename)

Load object from HDF5 file.

Parameters:: filename – Path to the input HDF5 file
Throws:: std::runtime_error – if I/O error occurs
Returns:: Shared pointer to the loaded StabilityResult

static std::shared_ptr<StabilityResult> from_json(const nlohmann::json &j)

Load object from JSON data.

Parameters:: j – JSON object containing the serialized data
Throws:: std::runtime_error – if JSON data is invalid
Returns:: Shared pointer to the loaded StabilityResult

static std::shared_ptr<StabilityResult> from_json_file(const std::string &filename)

Load object from JSON file.

Parameters:: filename – Path to the input JSON file
Throws:: std::runtime_error – if I/O error occurs
Returns:: Shared pointer to the loaded StabilityResult

class Structure : public qdk::chemistry::data::DataClass, public std::enable_shared_from_this<Structure>

#include <qdk/chemistry/data/structure.hpp>

Represents a molecular structure with atomic coordinates, elements, masses, and nuclear charges.

This class stores and manipulates molecular structure data including:

Atomic coordinates in 3D space
Atomic element identifiers using Element enum
Atomic masses (in atomic mass units)
Nuclear charges (atomic numbers) for each atom
Serialization to/from JSON and XYZ formats
Basic geometric operations and validation

The structure can be constructed from various input formats and provides convenient access to atomic properties and molecular geometry. Standard atomic masses and nuclear charges are used by default unless otherwise specified. The class is designed to be immutable after construction, ensuring data integrity.

Public Functions

Structure(const Eigen::MatrixXd &coordinates, const std::vector<Element> &elements, const Eigen::VectorXd &masses = {}, const Eigen::VectorXd &nuclear_charges = {})

Constructor with coordinates, elements, masses, and nuclear charges.

Parameters:

coordinates – Matrix of atomic coordinates (N x 3) in Bohr
elements – Vector of atomic elements using enum
masses – Vector of atomic masses in AMU (default: use default masses)
nuclear_charges – Vector of nuclear charges (default: use default charges)

Throws:

std::invalid_argument – if dimensions don’t match

Structure(const Eigen::MatrixXd &coordinates, const std::vector<std::string> &symbols, const Eigen::VectorXd &masses = {}, const Eigen::VectorXd &nuclear_charges = {})

Constructor from atomic symbols and coordinates.

Parameters:

coordinates – Matrix of atomic coordinates (N x 3) in Bohr
symbols – Vector of atomic symbols (e.g., “H”, “C”, “O”)
masses – Vector of atomic masses in AMU (default: use default masses)
nuclear_charges – Vector of nuclear charges (default: use default charges)

Throws:

std::invalid_argument – if dimensions don’t match or unknown symbols

Structure(const std::vector<Eigen::Vector3d> &coordinates, const std::vector<Element> &elements, const std::vector<double> &masses = {}, const std::vector<double> &nuclear_charges = {})

Constructor from atomic elements and coordinates as vector.

Parameters:

coordinates – Vector of atomic coordinates (N x 3) in Bohr
elements – Vector of atomic elements using enum
masses – Vector of atomic masses in AMU (default: use default masses)
nuclear_charges – Vector of nuclear charges (default: use default charges)

Throws:

std::invalid_argument – if dimensions don’t match

Structure(const std::vector<Eigen::Vector3d> &coordinates, const std::vector<std::string> &symbols, const std::vector<double> &masses = {}, const std::vector<double> &nuclear_charges = {})

Constructor from atomic symbols and coordinates as vector.

Parameters:

coordinates – Vector of atomic coordinates (N x 3) in Bohr
symbols – Vector of atomic symbols (e.g., “H”, “C”, “O”)
masses – Vector of atomic masses in AMU (default: use default masses)
nuclear_charges – Vector of nuclear charges (default: use default charges)

Throws:

std::invalid_argument – if dimensions don’t match or unknown symbols

Structure(const Structure &other) = default: Copy constructor.

Structure(Structure &&other) noexcept = default: Move constructor.

virtual ~Structure() = default: Destructor.

double calculate_nuclear_repulsion_energy() const

Calculate nuclear-nuclear repulsion energy.

This function calculates the Coulombic repulsion energy between all nuclei in the structure using the formula: E_nn = sum_{i<j} Z_i * Z_j / |R_i - R_j| where Z_i is the nuclear charge of atom i and R_i is its position vector.

Returns:: Nuclear repulsion energy in atomic units (Hartree)

Eigen::Vector3d get_atom_coordinates(size_t atom_index) const

Get coordinates for a specific atom.

Parameters:: atom_index – Index of the atom (0-based)
Throws:: std::out_of_range – if atom_index is invalid
Returns:: 3D coordinates as Eigen::Vector3d

Element get_atom_element(size_t atom_index) const

Get element for a specific atom.

Parameters:: atom_index – Index of the atom (0-based)
Throws:: std::out_of_range – if atom_index is invalid
Returns:: Atomic element enum

double get_atom_mass(size_t atom_index) const

Get mass for a specific atom.

Parameters:: atom_index – Index of the atom (0-based)
Throws:: std::out_of_range – if atom_index is invalid
Returns:: Atomic mass in AMU

double get_atom_nuclear_charge(size_t atom_index) const

Get nuclear charge for a specific atom.

Parameters:: atom_index – Index of the atom (0-based)
Throws:: std::out_of_range – if atom_index is invalid
Returns:: Nuclear charge (atomic number)

std::string get_atom_symbol(size_t atom_index) const

Get atomic symbol for a specific atom.

Parameters:: atom_index – Index of the atom (0-based)
Throws:: std::out_of_range – if atom_index is invalid
Returns:: Atomic symbol (e.g., “H”, “C”, “O”)

std::vector<std::string> get_atomic_symbols() const

Get all atomic symbols.

Returns:: Vector of atomic symbols

inline const Eigen::MatrixXd &get_coordinates() const

Get the atomic coordinates matrix.

Returns:: Matrix of coordinates (N x 3) in Bohr

inline const std::vector<Element> &get_elements() const

Get the atomic elements vector.

Returns:: Vector of atomic elements

inline const Eigen::VectorXd &get_masses() const

Get the atomic masses vector.

Returns:: Vector of atomic masses in AMU

inline const Eigen::VectorXd &get_nuclear_charges() const

Get the nuclear charges vector.

Returns:: Vector of nuclear charges (atomic numbers)

inline size_t get_num_atoms() const

Get the number of atoms in the structure.

Returns:: Number of atoms

virtual std::string get_summary() const override

Get summary string of structure information.

Returns:: String describing the structure

double get_total_mass() const

Calculate the total molecular mass.

Returns:: Total mass in AMU

inline bool is_empty() const

Check if the structure is empty.

Returns:: True if no atoms are present

Structure &operator=(const Structure &other) = default: Copy assignment operator.

Structure &operator=(Structure &&other) noexcept = default: Move assignment operator.

virtual void to_file(const std::string &filename, const std::string &type) const override

Save structure to file in specified format.

Parameters:

filename – Path to file to create/overwrite
type – Format type (“json”, “xyz”, or “hdf5”)

Throws:

std::invalid_argument – if unknown type
std::runtime_error – if I/O error occurs

virtual void to_hdf5(H5::Group &group) const override

Convert structure to HDF5 group.

Parameters:: group – HDF5 group to write structure data to
Throws:: std::runtime_error – if HDF5 I/O error occurs

virtual void to_hdf5_file(const std::string &filename) const override

Save structure to HDF5 file.

Parameters:: filename – Path to HDF5 file to create/overwrite
Throws:: std::runtime_error – if I/O error occurs

virtual nlohmann::json to_json() const override

Convert structure to JSON format.

Returns:: JSON object containing structure data with coordinates in Bohr

virtual void to_json_file(const std::string &filename) const override

Save structure to JSON file.

Parameters:: filename – Path to JSON file to create/overwrite
Throws:: std::runtime_error – if I/O error occurs

std::string to_xyz(const std::string &comment = "") const

Convert structure to XYZ format string.

Parameters:: comment – Optional comment line (default: empty)
Returns:: XYZ format string with coordinates in Angstrom

void to_xyz_file(const std::string &filename, const std::string &comment = "") const

Save structure to XYZ file.

Parameters:

filename – Path to XYZ file to create/overwrite
comment – Optional comment line (default: empty)

Throws:

std::runtime_error – if I/O error occurs

Public Static Functions

static unsigned element_to_nuclear_charge(Element element)

Convert element enum to nuclear charge.

Parameters:: element – Atomic element enum
Returns:: Nuclear charge (atomic number)

static std::string element_to_symbol(Element element)

Convert element enum to atomic symbol.

Parameters:: element – Atomic element enum
Returns:: Atomic symbol (e.g., “H”, “C”, “O”)

static std::shared_ptr<Structure> from_file(const std::string &filename, const std::string &type)

Load structure from file in specified format.

Parameters:

filename – Path to file to create/overwrite
type – Format type (“json”, “xyz”, or “hdf5”)

Throws:

std::invalid_argument – if unknown type
std::runtime_error – if I/O error occurs

Returns:

Structure object created from file

static std::shared_ptr<Structure> from_hdf5(H5::Group &group)

Load structure from HDF5 group.

Parameters:: group – HDF5 group containing structure data
Throws:: std::runtime_error – if HDF5 data is malformed or I/O error occurs
Returns:: Shared pointer to Structure object created from HDF5 group

static std::shared_ptr<Structure> from_hdf5_file(const std::string &filename)

Load structure from HDF5 file.

Parameters:: filename – Path to HDF5 file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: Shared pointer to Structure object created from HDF5 file

static std::shared_ptr<Structure> from_json(const nlohmann::json &j)

Load structure from JSON format.

Parameters:: j – JSON object containing structure data with coordinates in Bohr
Throws:: std::runtime_error – if JSON is malformed
Returns:: Shared pointer to const Structure object created from JSON data

static std::shared_ptr<Structure> from_json_file(const std::string &filename)

Load structure from JSON file.

Parameters:: filename – Path to JSON file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: Shared pointer to const Structure object created from JSON file

static std::shared_ptr<Structure> from_xyz(const std::string &xyz_string)

Load structure from XYZ format string.

Parameters:: xyz_string – XYZ format string with coordinates in Angstrom
Throws:: std::runtime_error – if XYZ format is invalid
Returns:: Structure object created from XYZ string

static std::shared_ptr<Structure> from_xyz_file(const std::string &filename)

Load structure from XYZ file.

Parameters:: filename – Path to XYZ file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: Shared pointer to a Structure object created from XYZ file

static double get_default_atomic_mass(Element element)

Get standard atomic mass for an element.

Parameters:: element – Atomic element enum
Returns:: Standard atomic mass in AMU

static double get_default_atomic_mass(std::string symbol)

Get atomic mass for an element symbol string.

Parameters:: symbol – Element symbol (e.g., “H”, “H2”, “C”, “C12”, “C13”) Using an element symbol string without a mass number returns the standard atomic weight. “D” (deuterium) can be used as alias for “H2”. “T” (tritium) can be used as alias for “H3”.
Returns:: Atomic mass in AMU

static unsigned get_default_nuclear_charge(Element element)

Get nuclear charge for an element.

Parameters:: element – Atomic element enum
Returns:: Nuclear charge (atomic number)

static Element nuclear_charge_to_element(unsigned nuclear_charge)

Convert nuclear charge to element enum.

Parameters:: nuclear_charge – Nuclear charge (atomic number)
Throws:: std::invalid_argument – if unknown nuclear charge
Returns:: Atomic element enum

static std::string nuclear_charge_to_symbol(unsigned nuclear_charge)

Convert nuclear charge to atomic symbol.

Parameters:: nuclear_charge – Nuclear charge (atomic number)
Throws:: std::invalid_argument – if unknown nuclear charge
Returns:: Atomic symbol (e.g., “H”, “C”, “O”)

static Element symbol_to_element(const std::string &symbol)

Convert atomic symbol to element enum.

Parameters:: symbol – Atomic symbol (e.g., “H”, “C”, “O”)
Throws:: std::invalid_argument – if unknown symbol
Returns:: Atomic element enum

static unsigned symbol_to_nuclear_charge(const std::string &symbol)

Convert atomic symbol to nuclear charge.

Parameters:: symbol – Atomic symbol (e.g., “H”, “C”, “O”)
Throws:: std::invalid_argument – if unknown symbol
Returns:: Nuclear charge (atomic number)

class SumPauliOperatorExpression : public qdk::chemistry::data::PauliOperatorExpression

#include <qdk/chemistry/data/pauli_operator.hpp>

A PauliOperatorExpression representing a sum of expressions.

This class represents linear combinations of Pauli operator expressions. For example, 2*X(0) + 3*Y(1)*Z(2) represents a sum of two terms.

Terms can be any PauliOperatorExpression type, including nested sums and products. The distribute() and simplify() methods can be used to flatten and combine terms.

Public Functions

SumPauliOperatorExpression(): Constructs an empty sum (represents zero).

SumPauliOperatorExpression(const PauliOperatorExpression &left, const PauliOperatorExpression &right)

Constructs a sum of two expressions.

Parameters:

left – The first term.
right – The second term.

SumPauliOperatorExpression(const SumPauliOperatorExpression &other)

Copy constructor.

Deep copies all terms.

Parameters:: other – The SumPauliOperatorExpression to copy.

void add_term(std::unique_ptr<PauliOperatorExpression> term)

Appends a term to this sum.

Ownership is transferred.

Parameters:: term – The expression to add.

virtual std::unique_ptr<PauliOperatorExpression> clone() const override

Creates a deep copy of this sum expression.

Returns:: A unique_ptr to a new SumPauliOperatorExpression.

virtual std::unique_ptr<SumPauliOperatorExpression> distribute() const override

Distributes all terms and returns a flat sum of products.

Calls distribute() on each term and collects all resulting products. The result contains only ProductPauliOperatorExpression terms, each containing only PauliOperator factors.

Returns:: A new SumPauliOperatorExpression in distributed form.

const std::vector<std::unique_ptr<PauliOperatorExpression>> &get_terms() const

Returns a const reference to the internal term list.

Returns:: Vector of expression terms in addition order.

virtual std::uint64_t max_qubit_index() const override

Returns the maximum qubit index referenced in this expression.

Throws:: std::logic_error – If the expression has no terms.
Returns:: The maximum qubit index.

virtual std::uint64_t min_qubit_index() const override

Returns the minimum qubit index referenced in this expression.

Throws:: std::logic_error – If the expression has no terms.
Returns:: The minimum qubit index.

virtual std::uint64_t num_qubits() const override

Returns the number of qubits spanned by this expression.

Returns:: max_qubit_index() - min_qubit_index() + 1, or 0 if empty.

virtual std::unique_ptr<SumPauliOperatorExpression> prune_threshold(double epsilon) const override

Returns a sum with small-magnitude terms removed.

Recursively processes nested sums. Bare PauliOperators have an implicit coefficient of 1.0.

Parameters:: epsilon – Terms with |coefficient| < epsilon are excluded.
Returns:: A new SumPauliOperatorExpression with small terms filtered out.

virtual std::unique_ptr<PauliOperatorExpression> simplify() const override

Simplifies this sum by combining like terms.

Simplification performs the following steps:

Distributes the expression to flatten nested sums/products
Simplifies each term individually (applying Pauli algebra)
Collects like terms: terms with identical Pauli strings have their coefficients added together
Removes terms with exactly zero coefficients

Term ordering is preserved for non-duplicate terms.

Returns:: A simplified SumPauliOperatorExpression.

virtual std::string to_canonical_string(std::uint64_t min_qubit, std::uint64_t max_qubit) const override

Returns the canonical string for a single-term sum.

Parameters:

min_qubit – The minimum qubit index to include.
max_qubit – The maximum qubit index to include (inclusive).

Throws:

std::logic_error – If the sum has more than one term after simplification.

Returns:

The canonical string, or “0” if empty.

virtual std::string to_canonical_string(std::uint64_t num_qubits) const override

Returns the canonical string for a single-term sum.

This method simplifies the sum first. It is intended for sums that reduce to a single term after simplification.

Parameters:: num_qubits – The total number of qubits to represent.
Throws:: std::logic_error – If the sum has more than one term after simplification. Use to_canonical_terms() for multi-term sums.
Returns:: The canonical string of the single term, or “0” if empty.

virtual std::vector<std::pair<std::complex<double>, std::string>> to_canonical_terms() const override

Returns each term as a (coefficient, canonical_string) pair.

Uses the range [0, max_qubit_index()] for the canonical strings. Returns an empty vector for an empty sum.

Throws:: std::logic_error – If any term is not in distributed form.
Returns:: Vector of (coefficient, canonical_string) pairs.

virtual std::vector<std::pair<std::complex<double>, std::string>> to_canonical_terms(std::uint64_t num_qubits) const override

Returns each term as a (coefficient, canonical_string) pair.

Each term in the sum produces one entry. This method does not simplify or combine like terms; call simplify() first if that is desired.

Parameters:: num_qubits – The total number of qubits to represent.
Throws:: std::logic_error – If any term is not in distributed form.
Returns:: Vector of (coefficient, canonical_string) pairs.

virtual std::string to_string() const override

Returns a human-readable string representation of this sum.

Terms are joined with “ + “ or “ - “ depending on sign. An empty sum returns “0”.

Returns:: A string like “X(0) + 2 * Y(1) - Z(2)”.

class Wavefunction : public qdk::chemistry::data::DataClass, public std::enable_shared_from_this<Wavefunction>

#include <qdk/chemistry/data/wavefunction.hpp>

Main wavefunction class that wraps container implementations.

This class provides a high-level interface to wavefunction data by delegating to specific container implementations. It combines orbital information with wavefunction coefficients and provides convenient access to all wavefunction properties. All methods redirect to the underlying container.

Public Types

using DeterminantVector = ContainerTypes::DeterminantVector

using MatrixVariant = ContainerTypes::MatrixVariant

using ScalarVariant = ContainerTypes::ScalarVariant

using VectorVariant = ContainerTypes::VectorVariant

Public Functions

Wavefunction(const Wavefunction &other): Copy constructor.

Wavefunction(std::unique_ptr<WavefunctionContainer> container)

Construct wavefunction with container (orbitals are stored in container)

Parameters:: container – Wavefunction container implementation

Wavefunction(Wavefunction &&other) noexcept = default: Move constructor.

~Wavefunction() = default

Configuration get_active_determinant(const Configuration &total_determinant) const

Extract active space determinant from a full orbital space determinant.

Removes inactive and virtual orbital information, keeping only the active space orbitals.

Parameters:: total_determinant – Configuration representing full orbital space
Returns:: Configuration representing only the active space portion

const DeterminantVector &get_active_determinants() const

Get all determinants in the wavefunction.

Returns:: Vector of all configurations/determinants

virtual std::pair<size_t, size_t> get_active_num_electrons() const

Get number of active alpha and beta electrons.

Returns:: Pair of (n_alpha_active, n_beta_active) electrons

std::tuple<const MatrixVariant&, const MatrixVariant&> get_active_one_rdm_spin_dependent() const

Get spin-dependent one-particle RDMs.

Returns:: Tuple of (alpha-alpha, beta-beta) one-particle RDMs

const MatrixVariant &get_active_one_rdm_spin_traced() const

Get spin-traced one-particle RDM.

Returns:: Spin-traced one-particle RDM

std::pair<Eigen::VectorXd, Eigen::VectorXd> get_active_orbital_occupations() const

Get orbital occupations for active orbitals only.

Returns:: Pair of (alpha_active_occupations, beta_active_occupations)

std::tuple<const VectorVariant&, const VectorVariant&, const VectorVariant&> get_active_two_rdm_spin_dependent() const

Get spin-dependent two-particle RDMs.

Returns:: Tuple of (aabb, aaaa, bbbb) two-particle RDMs

const VectorVariant &get_active_two_rdm_spin_traced() const

Get spin-traced two-particle RDM.

Returns:: Spin-traced two-particle RDM

ScalarVariant get_coefficient(const Configuration &det) const

Get coefficient for a specific determinant.

The configuration is expected to be a determinant describing only the wavefunction’s active space.

Parameters:: det – Configuration/determinant to get coefficient for
Returns:: Scalar coefficient (real or complex)

const VectorVariant &get_coefficients() const

Get coefficients for all determinants as a vector, in which the sequence of coefficients is consistent with the vector from get_active_determinants()

Returns:: Vector of coefficients (real or complex)

template<typename T> inline const T &get_container() const

Get typed reference to the underlying container.

Template Parameters:: T – Container type to cast to
Throws:: std::bad_cast – if container is not of type T
Returns:: Reference to container as type T

virtual std::string get_container_type() const

Get the type of the underlying container.

Returns:: String identifying the container type (e.g., “cas”, “sci”, “sd”)

virtual std::shared_ptr<Orbitals> get_orbitals() const

Get reference to orbital basis set.

Returns:: Shared pointer to orbitals

virtual Eigen::VectorXd get_single_orbital_entropies() const

Calculate single orbital entropies for active orbitals only.

Returns:: Vector of orbital entropies for active orbitals (always real)

virtual std::string get_summary() const override

Get a summary string.

Returns:: String containing summary

Configuration get_total_determinant(const Configuration &active_determinant) const

Convert active space determinant to full orbital space determinant.

Expands active-space-only determinant to full orbital space by prepending doubly occupied inactive orbitals and appending unoccupied virtual orbitals.

Parameters:: active_determinant – Configuration representing only active space
Returns:: Configuration representing full orbital space

DeterminantVector get_total_determinants() const

Get all determinants in the wavefunction with full orbital space.

Converts stored active-space-only determinants to full orbital space by prepending doubly occupied inactive orbitals and appending unoccupied virtual orbitals.

Returns:: Vector of all configurations/determinants including inactive and virtual orbitals

virtual std::pair<size_t, size_t> get_total_num_electrons() const

Get total number of alpha and beta electrons (active + inactive)

Returns:: Pair of (n_alpha_total, n_beta_total) electrons

std::pair<Eigen::VectorXd, Eigen::VectorXd> get_total_orbital_occupations() const

Get orbital occupations for all orbitals (total = active + inactive.

virtual)

Returns:: Pair of (alpha_occupations_total, beta_occupations_total)

WavefunctionType get_type() const

Get the wavefunction type (SelfDual or NotSelfDual)

Returns:: WavefunctionType enum value

template<typename T> inline bool has_container_type() const

Check if container is of specific type.

Template Parameters:: T – Container type to check
Returns:: True if container is of type T

bool has_one_rdm_spin_dependent() const

Check if spin-dependent one-particle RDMs are available.

Returns:: True if available

bool has_one_rdm_spin_traced() const

Check if spin-traced one-particle RDM is available.

Returns:: True if available

virtual bool has_single_orbital_entropies() const

Checks if single-orbital entropies for active orbitals are available.

Returns:: True if single-orbital entropies are available, false otherwise

bool has_two_rdm_spin_dependent() const

Check if spin-dependent two-particle RDMs are available.

Returns:: True if available

bool has_two_rdm_spin_traced() const

Check if spin-traced two-particle RDM is available.

Returns:: True if available

bool is_complex() const

Check if the wavefunction is complex-valued.

Returns:: True if complex, false if real

double norm() const

Calculate norm of the wavefunction.

Returns:: Norm (always real)

Wavefunction &operator=(const Wavefunction &other): Copy assignment operator.

Wavefunction &operator=(Wavefunction &&other) noexcept = default: Move assignment operator.

ScalarVariant overlap(const Wavefunction &other) const

Calculate overlap with another wavefunction.

Parameters:: other – Other wavefunction
Returns:: Overlap value (real or complex)

size_t size() const

Get number of determinants.

Returns:: Number of determinants in the wavefunction

virtual void to_file(const std::string &filename, const std::string &type) const override

Save wavefunction to file in specified format.

Parameters:

filename – Path to file to create/overwrite
type – Format type (“json” or “hdf5”)

Throws:

std::invalid_argument – if unknown type
std::runtime_error – if I/O error occurs

virtual void to_hdf5(H5::Group &group) const override

Convert wavefunction to HDF5 group.

Parameters:: group – HDF5 group to write wavefunction data to
Throws:: std::runtime_error – if HDF5 I/O error occurs

virtual void to_hdf5_file(const std::string &filename) const override

Save wavefunction to HDF5 file.

Parameters:: filename – Path to HDF5 file to create/overwrite
Throws:: std::runtime_error – if I/O error occurs

virtual nlohmann::json to_json() const override

Convert wavefunction to JSON format.

Returns:: JSON object containing wavefunction data

virtual void to_json_file(const std::string &filename) const override

Save wavefunction to JSON file.

Parameters:: filename – Path to JSON file to create/overwrite
Throws:: std::runtime_error – if I/O error occurs

Public Static Functions

static std::shared_ptr<Wavefunction> from_file(const std::string &filename, const std::string &type)

Load wavefunction from file in specified format.

Parameters:

filename – Path to file to read
type – Format type (“json” or “hdf5”)

Throws:

std::invalid_argument – if unknown type
std::runtime_error – if file doesn’t exist or I/O error occurs

Returns:

Shared pointer to Wavefunction object created from file

static std::shared_ptr<Wavefunction> from_hdf5(H5::Group &group)

Load wavefunction from HDF5 group.

Note that due to significant code duplication in the cas and sci containers, their common logic is shared in this base class, and not re-implemented in the cas and sci containers.

Parameters:: group – HDF5 group containing wavefunction data
Throws:: std::runtime_error – if HDF5 data is malformed or I/O error occurs
Returns:: Shared pointer to Wavefunction object created from HDF5 group

static std::shared_ptr<Wavefunction> from_hdf5_file(const std::string &filename)

Load wavefunction from HDF5 file.

Parameters:: filename – Path to HDF5 file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: Shared pointer to Wavefunction object created from HDF5 file

static std::shared_ptr<Wavefunction> from_json(const nlohmann::json &j)

Load wavefunction from JSON format.

Parameters:: j – JSON object containing wavefunction data
Throws:: std::runtime_error – if JSON is malformed
Returns:: Shared pointer to Wavefunction object created from JSON data

static std::shared_ptr<Wavefunction> from_json_file(const std::string &filename)

Load wavefunction from JSON file.

Parameters:: filename – Path to JSON file to read
Throws:: std::runtime_error – if file doesn’t exist or I/O error occurs
Returns:: Shared pointer to Wavefunction object created from JSON file

class WavefunctionContainer

#include <qdk/chemistry/data/wavefunction.hpp>

Abstract base class for wavefunction containers.

This class provides the interface for different types of wavefunction representations (e.g., CI, MCSCF, coupled cluster). It uses variant types to support both real and complex arithmetic, and provides methods for accessing coefficients, reduced density matrices (RDMs), and other wavefunction properties.

Subclassed by qdk::chemistry::data::CasWavefunctionContainer, qdk::chemistry::data::CoupledClusterContainer, qdk::chemistry::data::MP2Container, qdk::chemistry::data::SciWavefunctionContainer, qdk::chemistry::data::SlaterDeterminantContainer

Public Types

using DeterminantVector = ContainerTypes::DeterminantVector

using MatrixVariant = ContainerTypes::MatrixVariant

using ScalarVariant = ContainerTypes::ScalarVariant

using VectorVariant = ContainerTypes::VectorVariant

Public Functions

WavefunctionContainer(const std::optional<MatrixVariant> &one_rdm_spin_traced, const std::optional<MatrixVariant> &one_rdm_aa, const std::optional<MatrixVariant> &one_rdm_bb, const std::optional<VectorVariant> &two_rdm_spin_traced, const std::optional<VectorVariant> &two_rdm_aabb, const std::optional<VectorVariant> &two_rdm_aaaa, const std::optional<VectorVariant> &two_rdm_bbbb, WavefunctionType type = WavefunctionType::SelfDual)

Constructs a wavefunction container with reduced density matrix (RDM) data.

Parameters:

one_rdm_spin_traced – Spin-traced 1-RDM for active orbitals (optional)
one_rdm_aa – Alpha-alpha block of 1-RDM for active orbitals (optional)
one_rdm_bb – Beta-beta block of 1-RDM for active orbitals (optional)
two_rdm_spin_traced – Spin-traced 2-RDM for active orbitals (optional)
two_rdm_aabb – Alpha-beta-alpha-beta block of 2-RDM for active orbitals (optional)
two_rdm_aaaa – Alpha-alpha-alpha-alpha block of 2-RDM for active orbitals (optional)
two_rdm_bbbb – Beta-beta-beta-beta block of 2-RDM for active orbitals (optional)
type – The type of wavefunction

WavefunctionContainer(const std::optional<MatrixVariant> &one_rdm_spin_traced, const std::optional<VectorVariant> &two_rdm_spin_traced, WavefunctionType type = WavefunctionType::SelfDual)

Constructs a wavefunction with spin-traced reduced density matrix (RDM) data.

Parameters:

one_rdm_spin_traced – Spin-traced 1-RDM for active orbitals (optional)
two_rdm_spin_traced – Spin-traced 2-RDM for active orbitals (optional)
type – The type of wavefunction

WavefunctionContainer(WavefunctionType type = WavefunctionType::SelfDual)

Constructor.

Parameters:: type – Type of wavefunction (SelfDual or NotSelfDual)

virtual ~WavefunctionContainer() = default

virtual void clear_caches() const = 0

Clear cached data to release memory.

This method cleans up memoized evaluations of data derived from the wavefunction, such as reduced density matrices (RDMs), and other computed properties. Each derived container implementation decides specifically what cached data to clear based on its internal structure.

Calling this method can help manage memory usage for large systems.

virtual std::unique_ptr<WavefunctionContainer> clone() const = 0

Create a deep copy of this container.

Returns:: Unique pointer to a cloned container

virtual const DeterminantVector &get_active_determinants() const = 0

Get all determinants in the wavefunction.

Returns:: Vector of all configurations/determinants

virtual std::pair<size_t, size_t> get_active_num_electrons() const = 0

Get number of active alpha and beta electrons.

Returns:: Pair of (n_alpha_active, n_beta_active) electrons

virtual std::tuple<const MatrixVariant&, const MatrixVariant&> get_active_one_rdm_spin_dependent() const

Get spin-dependent one-particle RDMs for active orbitals only.

Returns:: Tuple of (alpha-alpha, beta-beta) one-particle RDMs for active orbitals

virtual const MatrixVariant &get_active_one_rdm_spin_traced() const

Get spin-traced one-particle RDM for active orbitals only.

Returns:: Spin-traced one-particle RDM for active orbitals

virtual std::pair<Eigen::VectorXd, Eigen::VectorXd> get_active_orbital_occupations() const = 0

Get orbital occupations for active orbitals only.

Returns:: Pair of (alpha_active_occupations, beta_active_occupations)

virtual std::tuple<const VectorVariant&, const VectorVariant&, const VectorVariant&> get_active_two_rdm_spin_dependent() const

Get spin-dependent two-particle RDMs for active orbitals only.

Returns:: Tuple of (aabb, aaaa, bbbb) two-particle RDMs for active orbitals

virtual const VectorVariant &get_active_two_rdm_spin_traced() const

Get spin-traced two-particle RDM for active orbitals only.

Returns:: Spin-traced two-particle RDM for active orbitals

virtual ScalarVariant get_coefficient(const Configuration &det) const = 0

Get coefficient for a specific determinant.

Parameters:: det – Configuration/determinant to get coefficient for
Returns:: Scalar coefficient (real or complex)

virtual const VectorVariant &get_coefficients() const = 0

Get all coefficients.

Returns:: Vector of all coefficients (real or complex)

inline virtual const ConfigurationSet &get_configuration_set() const

Get the configuration set for this wavefunction.

Throws:: std::runtime_error – if configuration set is not available
Returns:: Reference to the configuration set containing determinants and orbitals

virtual std::string get_container_type() const = 0

Get container type identifier for serialization.

Returns:: String identifying the container type (e.g., “cas”, “sci”, “sd”)

virtual std::shared_ptr<Orbitals> get_orbitals() const = 0

Get reference to orbital basis set.

Returns:: Shared pointer to orbitals

virtual Eigen::VectorXd get_single_orbital_entropies() const

Calculate single orbital entropies for active orbitals only.

This function uses the method of Boguslawski & Tecmer (2015), doi:10.1002/qua.24832, :cite:Boguslawski2015.

Returns:: Vector of orbital entropies for active orbitals (always real)

virtual std::pair<size_t, size_t> get_total_num_electrons() const = 0

Get total number of alpha and beta electrons (active + inactive)

Returns:: Pair of (n_alpha_total, n_beta_total) electrons

virtual std::pair<Eigen::VectorXd, Eigen::VectorXd> get_total_orbital_occupations() const = 0

Get orbital occupations for all orbitals (total = active + inactive.

virtual)

Returns:: Pair of (alpha_occupations_total, beta_occupations_total)

WavefunctionType get_type() const

Get the wavefunction type (SelfDual or NotSelfDual)

Returns:: WavefunctionType enum value

inline virtual bool has_coefficients() const

Check if this container has coefficients data.

Returns:: True if coefficients are available, false otherwise

inline virtual bool has_configuration_set() const

Check if this container has configuration set data.

Returns:: True if configuration set is available, false otherwise

virtual bool has_one_rdm_spin_dependent() const

Check if spin-dependent one-particle RDMs for active orbitals are available.

Returns:: True if available

virtual bool has_one_rdm_spin_traced() const

Check if spin-traced one-particle RDM for active orbitals is available.

Returns:: True if available

virtual bool has_single_orbital_entropies() const

Checks if single-orbital entropies for active orbitals are available.

Returns:: True if single-orbital entropies are available, false otherwise

virtual bool has_two_rdm_spin_dependent() const

Check if spin-dependent two-particle RDMs for active orbitals are available.

Returns:: True if available

virtual bool has_two_rdm_spin_traced() const

Check if spin-traced two-particle RDM for active orbitals is available.

Returns:: True if available

virtual bool is_complex() const = 0

Check if the wavefunction is complex-valued.

Returns:: True if complex, false if real

virtual double norm() const = 0

Calculate norm of the wavefunction.

Returns:: Norm (always real)

virtual ScalarVariant overlap(const WavefunctionContainer &other) const = 0

Calculate overlap with another wavefunction.

Parameters:: other – Other wavefunction container
Returns:: Overlap value (real or complex)

virtual size_t size() const = 0

Get number of determinants.

Returns:: Number of determinants in the wavefunction

virtual void to_hdf5(H5::Group &group) const

Convert container to HDF5 group.

Parameters:: group – HDF5 group to write container data to
Throws:: std::runtime_error – if HDF5 I/O error occurs

virtual nlohmann::json to_json() const = 0

Convert container to JSON format.

Returns:: JSON object containing container data

Public Static Functions

static std::unique_ptr<WavefunctionContainer> from_hdf5(H5::Group &group)

Load container from HDF5 group.

Parameters:: group – HDF5 group containing container data
Throws:: std::runtime_error – if HDF5 data is malformed or I/O error occurs
Returns:: Unique pointer to container created from HDF5 group

static std::unique_ptr<WavefunctionContainer> from_json(const nlohmann::json &j)

Load container from JSON format.

Parameters:: j – JSON object containing container data
Throws:: std::runtime_error – if JSON is malformed
Returns:: Unique pointer to container created from JSON data

namespace ciaaw_2024

CIAAW 2024 recommended values for atomic weights.

Standard atomic weights in AMU (atomic mass units) for all elements 1-118. IUPAC (International Union of Pure and Applied Chemistry) Commission on Isotopic Abundances and Atomic Weights (CIAAW), 2024.

T. Prohaska et al., Standard atomic weights of the elements 2021 (IUPAC Technical Report), Pure and Applied Chemistry 2022, 94, 573-600 (DOI: 10.1515/pac-2019-0603). :cite:Prohaska2022

Standard atomic masses of gadolinium, lutetium, and zirconium have been revised by IUPAC CIAAW in 2024 and these revisions are included here.

For radioactive elements the mass number of the most stable isotope is used as standard atomic weight.

F. G. Kondev et al., The NUBASE2020 evaluation of nuclear physics properties, Chinese Physics C 2021, 45, 030001 (DOI: 10.1088/1674-1137/abddae). :cite:Kondev2021

Isotope masses in AMU (atomic mass units) for all elements 1-118. IUPAC (International Union of Pure and Applied Chemistry) Commission on Isotopic Abundances and Atomic Weights (CIAAW), 2021.

W. J. Huang et al., The AME 2020 atomic mass evaluation (I). Evaluation of input data, and adjustment procedures, Chinese Physics C 2021, 45, 030002 (DOI: 10.1088/1674-1137/abddb0). :cite:Huang2021

M. Wang et al., The AME 2020 atomic mass evaluation (II). Tables, graphs and references, Chinese Physics C 2021, 45, 030003 (DOI: 10.1088/1674-1137/abddaf). :cite:Wang2021

F. G. Kondev et al., The NUBASE2020 evaluation of nuclear physics properties, Chinese Physics C 2021, 45, 030001 (DOI: 10.1088/1674-1137/abddae). :cite:Kondev2021

Functions

inline double get_atomic_weight(Element element)

Get atomic weight for an Element.

This function converts Element to unsigned and looks up the standard atomic weight.

Parameters:: element – Element enum value
Throws:: std::invalid_argument – if element is not found in the atomic weights map
Returns:: Atomic weight in AMU

inline double get_atomic_weight(unsigned Z, unsigned A)

Get atomic weight for an atomic number Z and mass number A.

This function looks up the atomic weight for the given pair of atomic number Z and mass number A.

Parameters:

Z – Atomic number (proton count)
A – Mass number (proton + neutron count) for a specific isotope mass or 0 for a standard atomic weight

Throws:

std::invalid_argument – if pair of atomic number Z and mass number A is not found in the atomic weights map

Returns:

Atomic weight in AMU

constexpr unsigned isotope(const unsigned Z, const unsigned A) noexcept

Helper function to calculate unique unsigned keys for isotopes.

For isotopes, put the atomic mass number in the unsigned’s bit representation. Z ranges up to 118 < 128 = 2^7, so we use 7 bits for Z. A ranges up to 295 < 512 = 2^9, so we need at least 16 bits total.

Parameters:

Z – Atomic number (proton count)
A – Mass number (proton + neutron count) for a specific isotope mass or 0 for a standard atomic weight

Returns:

Encoded unsigned key for atomic weight representation

Variables

const std::unordered_map<unsigned, double> atomic_weights

Standard atomic weights and specific isotope masses in AMU (atomic mass units)

Includes both standard atomic weights for elements 1-118 and specific isotope masses. For the standard atomic weights of radioactive elements, the mass numbers of the most stable isotopes are used.

namespace ContainerTypes

Common type definitions used across all container types.

This struct provides centralized type definitions for scalar, matrix, and vector types that can be either real or complex, used throughout the wavefunction system.

Typedefs

using DeterminantVector = std::vector<Configuration>

using MatrixVariant = std::variant<Eigen::MatrixXd, Eigen::MatrixXcd>

using ScalarVariant = std::variant<double, std::complex<double>>

using VectorVariant = std::variant<Eigen::VectorXd, Eigen::VectorXcd>

namespace detail

Functions

std::shared_ptr<ContainerTypes::MatrixVariant> add_matrix_variants(const ContainerTypes::MatrixVariant &mat1, const ContainerTypes::MatrixVariant &mat2)

Helper to add two ContainerTypes::MatrixVariants.

Parameters:

mat1 – First matrix variant
mat2 – Second matrix variant

Returns:

Shared pointer to new ContainerTypes::MatrixVariant containing the sum

std::shared_ptr<ContainerTypes::VectorVariant> add_vector_variants(const ContainerTypes::VectorVariant &vec1, const ContainerTypes::VectorVariant &vec2)

Helper to add two ContainerTypes::VectorVariants.

Parameters:

vec1 – First vector variant
vec2 – Second vector variant

Returns:

Shared pointer to new ContainerTypes::VectorVariant containing the sum

std::string denormalize_basis_set_name(const std::string &normalized)

Denormalize basis set name from filesystem representation.

Reverses the normalization:

’st’ -> ‘*’
’sl’ -> ‘/’
’pl’ -> ‘+’

Parameters:: normalized – Normalized name from filesystem
Returns:: Original basis set name

bool is_matrix_variant_complex(const ContainerTypes::MatrixVariant &variant)

Check if a ContainerTypes::MatrixVariant contains complex type.

Parameters:: variant – The matrix variant to check
Returns:: True if contains Eigen::MatrixXcd, false if Eigen::MatrixXd

bool is_vector_variant_complex(const ContainerTypes::VectorVariant &variant)

Check if a ContainerTypes::VectorVariant contains complex type.

Parameters:: variant – The vector variant to check
Returns:: True if contains Eigen::VectorXcd, false if Eigen::VectorXd

template<typename Scalar> std::shared_ptr<ContainerTypes::MatrixVariant> multiply_matrix_variant(const ContainerTypes::MatrixVariant &matrix, Scalar scalar)

Helper to create a ContainerTypes::MatrixVariant from scalar multiplication.

Parameters:

matrix – The matrix variant to multiply
scalar – The scalar value to multiply by

Returns:

Shared pointer to new ContainerTypes::MatrixVariant containing the result

template<typename Scalar> std::shared_ptr<ContainerTypes::VectorVariant> multiply_vector_variant(const ContainerTypes::VectorVariant &vector, Scalar scalar)

Helper to create a ContainerTypes::VectorVariant from scalar multiplication.

Parameters:

vector – The vector variant to multiply
scalar – The scalar value to multiply by

Returns:

Shared pointer to new ContainerTypes::VectorVariant containing the result

std::string normalize_basis_set_name(const std::string &name)

Normalize basis set name for filesystem usage.

Replaces special characters that are problematic in filenames:

’*’ -> ‘st’ (star)
’/’ -> ‘sl’ (slash)
’+’ -> ‘pl’ (plus)

Parameters:: name – Original basis set name (e.g., “6-31g*+”)
Returns:: Normalized name safe for filesystem (e.g., “6-31g_st__pl_”)

std::shared_ptr<ContainerTypes::VectorVariant> transpose_ijkl_klij_vector_variant(const ContainerTypes::VectorVariant &variant, int norbs)

Transpose a 2-RDM vector from (ij|kl) to (kl|ij) ordering.

Parameters:

variant – The vector variant to transpose
norbs – Number of orbitals

Returns:

shared pointer to new ContainerTypes::VectorVariant containing the transposed data