inquanto.embeddings

inquanto.embeddings module provides classes to decompose a system to smaller fragments for which more accurate theories can be applied.

DMET

InQuanto submodule for DMET (Density Matrix Embedding Theory).

This submodule contains a collection of DMET classes and functions to perform a DMET simulation for chemistry Hamiltonian.

class DMETRHF(hamiltonian_operator, one_body_rdm_rhf, scf_max_iteration=20, scf_tolerance=1e-5, newton_maxiter=5, newton_tol=1e-5, occupation_rtol=1e-5, occupation_atol=1e-8, check_unitary=False, check_unitary_atol=1e-10)

Bases: object

Basic RHF-DMET class to drive the DMET computations given the fragment solvers.

All density matrices are represented in spatial orbitals.

Parameters:

  • hamiltonian_operator (Union[ChemistryRestrictedIntegralOperator, TypeVar(PySCFRestrictedIntegralOperatorT, bound= PySCFChemistryRestrictedIntegralOperator)]) – Hamiltonian in orthogonal localized basis.

  • one_body_rdm_rhf (Union[ndarray, RestrictedOneBodyRDM]) – RHF RDM in orthogonal localized basis.

  • scf_max_iteration (int, default: 20) – Max iteration for the outer scf loop.

  • scf_tolerance (float, default: 1e-5) – SCF convergence tolerance for the outer loop for \(|u - u'| <\) scf_tolerance.

  • newton_maxiter (int, default: 5) – Max iteration for the newton solver inner loop (chemical potential).

  • newton_tol (float, default: 1e-5) – Convergence tolerance for the chemical potential, \(|N-N'| <\) newton_tol.

  • occupation_rtol (float, default: 1e-5) – Relative tolerance (numpy.isclose) to check orbital occupation.

  • occupation_atol (float, default: 1e-8) – Absolute tolerance (numpy.isclose) to check orbital occupation.

  • check_unitary (bool, default: False) – Whether to perform the check for unitarity of the rotation matrix before fragment rotation basis change.

  • check_unitary_atol (float, default: 1e-10) – Absolute tolerance of unitarity check.

static construct_random_parameters(pattern, seed=0, mu=0.0, sigma=0.01)

Generates an array of initial parameters randomized according to a Gaussian distribution.

Parameters:

  • pattern (ndarray) – Pattern for correlation potential matrix.

  • seed (int, default: 0) – Seed for the random number generator.

  • mu (float, default: 0.0) – Mean (\(\mu\)) for the distribution.

  • sigma (float, default: 0.01) – Standard deviation (\(\sigma\)) for the distribution.

Returns:

ndarray – Array of random numbers.

static correlation_potential_pattern(pattern, parameters)

Constructs the correlation potential matrix from the correlation potential matrix pattern and the parameters array.

Parameters:

  • pattern (ndarray) – Correlation potential matrix pattern.

  • parameters (ndarray) – Array of parameter values.

Returns:

ndarray – Correlation potential matrix.

Examples

>>> pattern = numpy.array(
...    [
...        [1, 0, None, None, None, None],
...        [0, 1, None, None, None, None],
...        [None, None, 1, 0, None, None],
...        [None, None, 0, 1, None, None],
...        [None, None, None, None, 1, 0],
...        [None, None, None, None, 0, 1],
...    ]
... )
>>> DMETRHF.correlation_potential_pattern(pattern, [0.5, -0.5])
array([[-0.5,  0.5,  0. ,  0. ,  0. ,  0. ],
       [ 0.5, -0.5,  0. ,  0. ,  0. ,  0. ],
       [ 0. ,  0. , -0.5,  0.5,  0. ,  0. ],
       [ 0. ,  0. ,  0.5, -0.5,  0. ,  0. ],
       [ 0. ,  0. ,  0. ,  0. , -0.5,  0.5],
       [ 0. ,  0. ,  0. ,  0. ,  0.5, -0.5]])
energy(fragments)

Extracting the total energy from the fragment solvers.

Note

This function must be called after run(…).

Parameters:

fragments (list[Union[DMETRHFFragment, DMETRHFFragmentDirect]]) – List of fragment solvers.

Returns:

float – The total energy.

static pattern_from_locations(size, locations)

Convert locations to patterns, see correlation_potential_pattern().

Parameters:

  • size (int) – Size of the correlation potential matrix.

  • locations (list[list[tuple[int, int]]]) – For each parameter it stores the i, j indices in the correlation potential matrix.

Returns:

ndarray – Correlation potential pattern matrix.

Examples

>>> locations = [[(0,1), (1,0), (2,3), (3,2), (4,5), (5,4)], [(0,0), (1,1), (2,2), (3,3), (4,4), (5,5)]]
>>> DMETRHF.pattern_from_locations(6, locations)
array([[ 1,  0, -1, -1, -1, -1],
       [ 0,  1, -1, -1, -1, -1],
       [-1, -1,  1,  0, -1, -1],
       [-1, -1,  0,  1, -1, -1],
       [-1, -1, -1, -1,  1,  0],
       [-1, -1, -1, -1,  0,  1]])
>>> DMETRHF.correlation_potential_pattern(DMETRHF.pattern_from_locations(6, locations), [0.5, -0.5])
array([[-0.5,  0.5,  0. ,  0. ,  0. ,  0. ],
       [ 0.5, -0.5,  0. ,  0. ,  0. ,  0. ],
       [ 0. ,  0. , -0.5,  0.5,  0. ,  0. ],
       [ 0. ,  0. ,  0.5, -0.5,  0. ,  0. ],
       [ 0. ,  0. ,  0. ,  0. , -0.5,  0.5],
       [ 0. ,  0. ,  0. ,  0. ,  0.5, -0.5]])
run(fragments, parameter_pattern=None, initial_parameters=None, initial_chemical_potential=0.0)

Runs the DMET self-consistency calculation.

Parameters:

  • fragments (list[Union[DMETRHFFragment, DMETRHFFragmentDirect]]) – List of fragment solvers.

  • parameter_pattern (Optional[ndarray], default: None) – Parameter pattern matrix for the correlation potential.

  • initial_parameters (Optional[ndarray], default: None) – Initial parameters (if None, it is randomly generated).

  • initial_chemical_potential (float, default: 0.0) – Initial chemical potential.

Returns:

tuple[float, Optional[float], Optional[ndarray]] – Energy, chemical potential, parameters defined by the DMET method.

run_one(fragments, chemical_potential=0.0)

Runs the DMET at a particular chemical_potential when all the correlation potentials are zero.

Parameters:
Returns:

float – The total energy at a particular chemical potential.

class DMETRHFFragment(dmet, mask, name=None)

Bases: BaseDMETRHFFragment

Fragment class for DMET RHF.

This class is used to specify an individual fragment within a fragmentation scheme for DMET. Orbitals are specified with a mask, as described below.

This class does not contain logic for solving energetics of the system, as this will typically require an interface to a classical chemistry package. Instead, it forms a base from which fragment classes including this logic may subclass, with the abstract solve() method being implemented. These subclasses may be user-written, or may be provided by InQuanto extensions. For further details, please see the InQuanto user guide.

Parameters:

  • dmet (DMETRHF) – Instance of DMETRHF object that uses this fragment.

  • mask (ndarray) – Array of boolean, indices correspond to the spatial orbitals of the total system. If the corresponding orbital is in the fragment, then the boolean should be True - else it should be False.

  • name (Optional[str], default: None) – Name of the fragment.

static compute_fragment_energy(rdm1, rdm2, one_body, two_body, veff, mask)

Computes the fragment energy with symmetrization.

Parameters:

  • mask (ndarray) – Fragment orbitals boolean mask.

  • rdm1 (ndarray) – One-body density matrix in the fragment basis.

  • rdm2 (ndarray) – Two-body density matrix in the fragment basis.

  • one_body (ndarray) – One-body integrals in the fragment basis.

  • two_body (ndarray) – Two-body integrals in the fragment basis.

  • veff (ndarray) – Fock matrix in the fragment basis.

Returns:

float – Fragment energy.

abstract solve(hamiltonian_operator, n_electron)

This is an abstract method.

The subclass implementation must return an accurate solution of the embedding system (fragment and bath) that includes the energy and one- and two-particle reduced density matrices (1-RDM and 2-RDM).

Parameters:
Returns:

tuple[float, ndarray, ndarray] – Energy, 1-RDM, 2-RDM of the embedding system (fragment and bath).

class DMETRHFFragmentActive(dmet, mask, name=None, frozen=None)

Bases: DMETRHFFragmentDirect

This is a base class for fragments that reduce the fragment problem for an active space.

This class is used to specify an individual fragment within a fragmentation scheme for DMET. Orbitals are specified with a mask, as described below.

This class does not contain logic for solving energetics of the system, as this will typically require an interface to a classical chemistry package. Instead, it forms a base from which fragment classes including this logic may subclass, with the abstract solve_active() method being implemented. These subclasses may be user-written, or may be provided by InQuanto extensions. For further details, please see the InQuanto user guide.

Parameters:

  • dmet (DMETRHF) – Instance of DMETRHF object that uses this fragment.

  • mask (ndarray) – Array of boolean, indices correspond to the spatial orbitals of the total system, the fragment is masked with True.

  • name (Optional[str], default: None) – Name of the fragment.

  • frozen (Optional[list[int]], default: None) – List of indices of frozen spatial orbitals.

static construct_fragment_energy_operator(one_body, two_body, veff, mask)

Computes the fragment energy with symmetrization.

Parameters:

  • mask (ndarray) – Fragment orbitals boolean mask.

  • one_body (ndarray) – One-body integrals in the fragment basis.

  • two_body (ndarray) – Two-body integrals in the fragment basis.

  • veff (ndarray) – Fock matrix in the fragment basis.

Returns:

ChemistryRestrictedIntegralOperator – Fragment energy operator based on democratic mixing defined by DMET.

solve(hamiltonian_operator, fragment_energy_operator, n_electron)

Solves the fragment system.

This method first runs an RHF for the fragment system, then for the active space it calls the solve_active() method.

Parameters:
Returns:

tuple[float, float, RestrictedOneBodyRDM] – Energy, fragment_energy, 1-RDM of the embedding system (fragment and bath).

solve_active(hamiltonian_operator, fragment_energy_operator, fermion_space, fermion_state)

This abstract method requires an implementation to solve the active space problem of the embedding system.

The subclass implementation must return the energy, fragment energy, and the one-particle reduced density matrix (1-RDM) for the active space problem.

Note

This must be implemented by the child class.

Parameters:
Returns:

tuple[float, float, RestrictedOneBodyRDM] – Energy, fragment energy, 1-RDM of the active space of the embedding system (fragment and bath).

class DMETRHFFragmentDirect(dmet, mask, name=None)

Bases: BaseDMETRHFFragment

Fragment class for DMET RHF with direct Fragment energy evaluation.

This class is used to specify an individual fragment within a fragmentation scheme for DMET. Orbitals are specified with a mask, as described below.

This class does not contain logic for solving energetics of the system, as this will typically require an interface to a classical chemistry package. Instead, it forms a base from which fragment classes including this logic may subclass, with the abstract solve() method being implemented. These subclasses may be user-written, or may be provided by InQuanto extensions. For further details, please see the InQuanto user guide.

Parameters:

  • dmet (DMETRHF) – Instance of DMETRHF object that uses this fragment.

  • mask (ndarray) – Array of boolean, indices correspond to the spatial orbitals of the total system, the fragment is masked with True.

  • name (Optional[str], default: None) – Name of the fragment.

static construct_fragment_energy_operator(one_body, two_body, veff, mask)

Computes the fragment energy with symmetrization.

Parameters:

  • mask (ndarray) – Fragment orbitals boolean mask.

  • one_body (ndarray) – One-body integrals in the fragment basis.

  • two_body (ndarray) – Two-body integrals in the fragment basis.

  • veff (ndarray) – Fock matrix in the fragment basis.

Returns:

ChemistryRestrictedIntegralOperator – Fragment energy operator based on democratic mixing defined by DMET.

abstract solve(hamiltonian_operator, fragment_energy_operator, n_electron)

This is an abstract method.

The subclass implementation must return an accurate solution of the embedding system (fragment and bath) which includes the energy, the fragment energy and 1-RDM.

Parameters:
Returns:

tuple[float, float, RestrictedOneBodyRDM] – Energy, fragment_energy, 1-RDM of the embedding system (fragment and bath).

class DMETRHFFragmentUCCSDVQE(dmet, mask, name=None, frozen=None, backend=None)

Bases: DMETRHFFragmentActive

This is a UCCSD VQE Fragment solver for DMETRHF.

Note: This fragment solver is limited to statevector VQE, if you wish to have a more advanced

quantum algorithm it is recommended you subclass DMETRHFFragmentActive or DMETRHFFragmentPySCFActive and implement the corresponding solve_active() method with the custom quantum algorithm.

Parameters:

  • dmet (DMETRHF) – Instance of DMETRHF object that uses this fragment.

  • mask (ndarray) – Array of boolean, indices correspond to the spatial orbitals of the total system, the fragment is masked with True.

  • name (Optional[str], default: None) – Name of the fragment.

  • frozen (Optional[list[int]], default: None) – List of indices of frozen spatial orbitals.

  • backend (Optional[Backend], default: None) – A statevector backend.

static construct_fragment_energy_operator(one_body, two_body, veff, mask)

Computes the fragment energy with symmetrization.

Parameters:

  • mask (ndarray) – Fragment orbitals boolean mask.

  • one_body (ndarray) – One-body integrals in the fragment basis.

  • two_body (ndarray) – Two-body integrals in the fragment basis.

  • veff (ndarray) – Fock matrix in the fragment basis.

Returns:

ChemistryRestrictedIntegralOperator – Fragment energy operator based on democratic mixing defined by DMET.

solve(hamiltonian_operator, fragment_energy_operator, n_electron)

Solves the fragment system.

This method first runs an RHF for the fragment system, then for the active space it calls the solve_active() method.

Parameters:
Returns:

tuple[float, float, RestrictedOneBodyRDM] – Energy, fragment_energy, 1-RDM of the embedding system (fragment and bath).

solve_active(hamiltonian_operator, fragment_energy_operator, fermion_space, fermion_state)

This method runs a UCCSD VQE calculation to solve the active space problem for the embedding system.

The implementation uses a statevector backend, and it returns the energy, fragment energy, and the one-particle reduced density matrix (1-RDM) for the active space problem.

Parameters:
Returns:

tuple[float, float, RestrictedOneBodyRDM] – Energy, fragment energy, rdm1 of the active space of the embedding system (fragment and bath).

class ImpurityDMETROHF(hamiltonian_operator, one_body_rdm_rhf, occupation_rtol=1e-5, occupation_atol=1e-8, check_unitary=False, check_unitary_atol=1e-10)

Bases: object

Basic Impurity ROHF-DMET class to drive the Impurity DMET computations given the single impurity fragment solver.

All density matrices are represented in spatial orbitals.

Parameters:

  • hamiltonian_operator (ChemistryRestrictedIntegralOperator) – Hamiltonian in orthogonal localized basis.

  • one_body_rdm_rhf (Union[ndarray, RestrictedOneBodyRDM]) – RHF RDM in orthogonal localized basis.

  • occupation_rtol (float, default: 1e-5) – Relative tolerance (isclose) to check orbital occupation.

  • occupation_atol (float, default: 1e-8) – Absolute tolerance (isclose) to check orbital occupation.

  • check_unitary (bool, default: False) – Whether to perform the check for unitarity of the rotation matrix before fragment rotation basis change.

  • check_unitary_atol (float, default: 1e-10) – Absolute tolerance of unitarity check.

run(fragment)

Runs the impurity DMET calculation.

Parameters:

fragment (Union[ImpurityDMETROHFFragment, ImpurityDMETROHFFragmentWithoutRDM]) – Impurity fragment solver.

Returns:

float – DMET ground state energy.

class ImpurityDMETROHFFragment(dmet, mask, name=None, multiplicity=1)

Bases: BaseImpurityDMETROHFFragment

Fragment class for ImpurityDMETROHF.

This class is used to specify an individual fragment solver within a fragmentation scheme for DMET. Orbitals are specified with a mask, as described below.

This class does not contain logic for solving energetics of the system, as this will typically require an interface to a classical chemistry package. Instead, it forms a base from which fragment classes including this logic may subclass, with the abstract solve() method being implemented. These subclasses may be user-written, or may be provided by InQuanto extensions. For further details, please see the InQuanto user guide.

Parameters:

  • dmet (ImpurityDMETROHF) – Instance of ImpurityDMETROHF object that uses this fragment.

  • mask (ndarray) – Array of boolean, indices correspond to the spatial orbitals of the total system, the fragment is masked with True.

  • name (Optional[str], default: None) – Name of the fragment.

  • multiplicity (int, default: 1) – Multiplicity for the fragment ROHF.

abstract solve(hamiltonian_operator, n_electron)

This is an abstract method.

The subclass implementation must return an accurate solution of the embedding system (fragment and bath) that includes the energy and the 1-RDM.

Parameters:
Returns:

Any – Energy, 1-RDM of the embedding system (fragment and bath).

class ImpurityDMETROHFFragmentActive(dmet, mask, name=None, multiplicity=1, frozen=None)

Bases: ImpurityDMETROHFFragmentWithoutRDM

This is a base class for fragments that reduce the fragment problem for an active space.

This class is used to specify an individual fragment within a fragmentation scheme for DMET. Orbitals are specified with a mask, as described below.

This class does not contain logic for solving energetics of the system, as this will typically require an interface to a classical chemistry package. Instead, it forms a base from which fragment classes including this logic may subclass, with the abstract solve_active() method being implemented. These subclasses may be user-written, or may be provided by InQuanto extensions. For further details, please see the InQuanto user guide.

Parameters:

  • dmet (ImpurityDMETROHF) – Instance of ImpurityDMETROHF object that uses this fragment.

  • mask (ndarray) – Array of boolean, indices correspond to the spatial orbitals of the total system, the fragment is masked with True.

  • name (Optional[str], default: None) – Name of the fragment.

  • multiplicity (int, default: 1) – Multiplicity for the fragment ROHF.

  • frozen (Any, default: None) – List of indices of frozen spatial orbitals.

solve(hamiltonian_operator, n_electron)

Solves the fragment system.

This method first runs an ROHF for the fragment system, then for the active space it calls the solve_active() method.

Parameters:
Returns:

float – Energy of the embedding system (fragment and bath).

solve_active(hamiltonian_operator, fermion_space, fermion_state)

This is an abstract method.

The subclass implementation must return an accurate ground state energy of the active space of the embedding system (fragment and bath).

Parameters:

  • hamiltonian_operator (ChemistryRestrictedIntegralOperator) – Hamiltonian operator for the active space of the fragment system.

  • fermion_space (FermionSpace) – Fermion space object for the active space of the fragment system.

  • fermion_state (FermionState) – Fock state for the active space of the fragment system.

Returns:

float – Energy of the embedding system (fragment and bath).

class ImpurityDMETROHFFragmentED(dmet, mask, name=None)

Bases: ImpurityDMETROHFFragmentWithoutRDM

Exact diagonalization impurity solver for the Impurity DMET method.

This class is used to specify an individual fragment solver within a fragmentation scheme for DMET. Orbitals are specified with a mask, as described below.

Parameters:

  • dmet (ImpurityDMETROHF) – Instance of ImpurityDMETROHF object that uses this fragment.

  • mask (ndarray) – Array of boolean, indices correspond to the spatial orbitals of the total system, the fragment is masked with True.

  • name (Optional[str], default: None) – Name of the fragment.

solve(hamiltonian_operator, n_electron)

This method returns the exact ground state energy of the embedding system (fragment and bath).

Note

This method should be used only for small fragments, the computational cost grows exponentially with fragment size.

Parameters:
Returns:

float – Energy of the embedding system (fragment and bath).

class ImpurityDMETROHFFragmentWithoutRDM(dmet, mask, name=None, multiplicity=1)

Bases: BaseImpurityDMETROHFFragment

RDM free fragment class solver for ImpurityDMETROHF.

The notable difference from the base fragment solver is that this fragment solver does not require the computation of a 1-RDM in its solve() method.

This class is used to specify an individual fragment within a fragmentation scheme for DMET. Orbitals are specified with a mask, as described below.

It may be used with a fragment solver (e.g. a quantum algorithm) for which direct rdm1 calculation is difficult.

This class does not contain logic for solving energetics of the system, as this will typically require an interface to a classical chemistry package. Instead, it forms a base from which fragment classes including this logic may subclass, with the abstract solve() method being implemented. These subclasses may be user-written, or may be provided by InQuanto extensions. For further details, please see the InQuanto user guide.

Parameters:

  • dmet (ImpurityDMETROHF) – Instance of ImpurityDMETROHF object that uses this fragment.

  • mask (ndarray) – Array of boolean, indices correspond to the spatial orbitals of the total system, the fragment is masked with True.

  • name (Optional[str], default: None) – Name of the fragment.

  • multiplicity (int, default: 1) – Multiplicity for the fragment ROHF.

abstract solve(hamiltonian_operator, n_electron)

This is an abstract method.

The subclass implementation must return an accurate ground state energy of the embedding system (fragment and bath).

Parameters:
Returns:

float – Energy of the embedding system (fragment and bath).