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:
- 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:
- 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 (ifNone
, 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:
fragments (
list
[Union
[DMETRHFFragment
,DMETRHFFragmentDirect
]]) – List of fragment solvers.chemical_potential (
float
, default:0.0
) – Chemical potential.
- 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:
- 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:
hamiltonian_operator (
ChemistryRestrictedIntegralOperator
) – Hamiltonian of the embedding system (fragment and bath).n_electron (
int
) – Number of electrons in the embedding system.
- 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:
- 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:
hamiltonian_operator (
ChemistryRestrictedIntegralOperator
) – Hamiltonian operator of the fragment system.fragment_energy_operator (
ChemistryRestrictedIntegralOperator
) – Fragment energy operator of the fragment system.n_electron (
int
) – Number of electrons in the fragment system.
- 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:
hamiltonian_operator (
ChemistryRestrictedIntegralOperator
) – Hamiltonian operator for the active space of the fragment system.fragment_energy_operator (
ChemistryRestrictedIntegralOperator
) – Fragment energy 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:
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:
- 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:
hamiltonian_operator (
ChemistryRestrictedIntegralOperator
) – Hamiltonian of the embedding system (fragment and bath).fragment_energy_operator (
ChemistryRestrictedIntegralOperator
) – Fragment energy operator of the embedding system (fragment and bath).n_electron (
int
) – Number of electrons in the embedding system.
- 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
orDMETRHFFragmentPySCFActive
and implement the correspondingsolve_active()
method with the custom quantum algorithm.
- Parameters:
dmet (
DMETRHF
) – Instance ofDMETRHF
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.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:
hamiltonian_operator (
ChemistryRestrictedIntegralOperator
) – Hamiltonian operator of the fragment system.fragment_energy_operator (
ChemistryRestrictedIntegralOperator
) – Fragment energy operator of the fragment system.n_electron (
int
) – Number of electrons in the fragment system.
- 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:
hamiltonian_operator (
ChemistryRestrictedIntegralOperator
) – Hamiltonian operator for the active space of the fragment system.fragment_energy_operator (
ChemistryRestrictedIntegralOperator
) – Fragment energy 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:
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 ofImpurityDMETROHF
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.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:
hamiltonian_operator (
ChemistryRestrictedIntegralOperator
) – Hamiltonian of the embedding system (fragment and bath)n_electron (
int
) – Number of electrons in the embedding system
- 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 ofImpurityDMETROHF
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.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:
hamiltonian_operator (
ChemistryRestrictedIntegralOperator
) – Hamiltonian operator of the fragment system.n_electron (
int
) – Number of electrons in the fragment system.
- 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 ofImpurityDMETROHF
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.
- 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:
hamiltonian_operator (
ChemistryRestrictedIntegralOperator
) – Hamiltonian of the embedding system (fragment and bath).n_electron (
int
) – Number of electrons in the embedding system.
- 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 ofImpurityDMETROHF
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.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:
hamiltonian_operator (
ChemistryRestrictedIntegralOperator
) – Hamiltonian of the embedding system (fragment and bath).n_electron (
int
) – Number of electrons in the embedding system.
- Returns:
float
– Energy of the embedding system (fragment and bath).