UCC¶

class tencirchem.UCC(mol: Mole, init_method='mp2', active_space=None, mo_coeff=None, hcb=False, engine=None, run_hf=True, run_mp2=True, run_ccsd=True, run_fci=True)[source]¶

Bases: object

Base class for UCCSD.

__init__(mol: Mole, init_method='mp2', active_space=None, mo_coeff=None, hcb=False, engine=None, run_hf=True, run_mp2=True, run_ccsd=True, run_fci=True)[source]¶

Initialize the class with molecular input.

Parameters:

mol (Mole) – The molecule as PySCF Mole object.
init_method (str, optional) – How to determine the initial amplitude guess. Accepts "mp2" (default), "ccsd", "fe" and "zeros".
active_space (Tuple[int, int], optional) – Active space approximation. The first integer is the number of electrons and the second integer is the number or spatial-orbitals. Defaults to None.
mo_coeff (np.ndarray, optional) – Molecule coefficients. If provided then RHF is skipped. Can be used in combination with the init_state attribute. Defaults to None which means RHF orbitals are used.
hcb (bool, optional) – Whether force electrons to pair as hard-core boson (HCB). Default to False.
engine (str, optional) – The engine to run the calculation. See Engines for details.
run_hf (bool, optional) – Whether run HF for molecule orbitals. Defaults to True.
run_mp2 (bool, optional) – Whether run MP2 for initial guess and energy reference. Defaults to True.
run_ccsd (bool, optional) – Whether run CCSD for initial guess and energy reference. Defaults to True.
run_fci (bool, optional) – Whether run FCI for energy reference. Defaults to True.

apply_excitation(state: Any, ex_op: Tuple, engine: str | None = None) → Any[source]¶

Apply a given excitation operator to a given state.

Parameters:

state (Tensor) – The input state in statevector or CI vector form.
ex_op (tuple of ints) – The excitation operator.
engine (str, optional) – The engine to use. Defaults to None, which uses self.engine.

Returns:

tensor – The resulting tensor.

Return type:

Tensor

Examples

>>> from tencirchem import UCC
>>> from tencirchem.molecule import h2
>>> ucc = UCC(h2)
>>> ucc.apply_excitation([1, 0, 0, 0], (3, 1, 0, 2))
array([0, 0, 0, 1])

classmethod as_pyscf_solver(config_function: Callable | None = None, **kwargs)[source]¶

Converts the UCC class to a PySCF FCI solver.

Parameters:

config_function (callable) – A function to configure the UCC instance. Accepts the UCC instance and modifies it inplace before kernel() is called.
kwargs – Other arguments to be passed to the __init__() function such as engine.

Return type:

FCISolver

Examples

>>> from pyscf.mcscf import CASSCF
>>> from tencirchem import UCCSD
>>> from tencirchem.molecule import h8
>>> # normal PySCF workflow
>>> hf = h8.HF()
>>> round(hf.kernel(), 8)
-4.14961853
>>> casscf = CASSCF(hf, 2, 2)
>>> # set the FCI solver for CASSCF to be UCCSD
>>> casscf.fcisolver = UCCSD.as_pyscf_solver()
>>> round(casscf.kernel()[0], 8)
-4.16647335

civector(params: Any | None = None, engine: str | None = None) → Any[source]¶

Evaluate the configuration interaction (CI) vector.

Parameters:

params (Tensor, optional) – The circuit parameters. Defaults to None, which uses the optimized parameter and kernel() must be called before.
engine (str, optional) – The engine to use. Defaults to None, which uses self.engine.

Returns:

civector – Corresponding CI vector

Return type:

Tensor

See also

statevector: Evaluate the circuit state vector.
energy: Evaluate the total energy.
energy_and_grad: Evaluate the total energy and parameter gradients.

Examples

>>> from tencirchem import UCCSD
>>> from tencirchem.molecule import h2
>>> uccsd = UCCSD(h2)
>>> uccsd.civector([0, 0])  # HF state
array([1., 0., 0., 0.])

property civector_size: int¶: The size of the CI vector.

property e_ucc: float¶: Returns UCC energy

embed_rdm_cas(rdm_cas)[source]¶: Embed CAS RDM into RDM of the whole system

energy(params: Any | None = None, engine: str | None = None) → float[source]¶

Evaluate the total energy.

Parameters:

params (Tensor, optional) – The circuit parameters. Defaults to None, which uses the optimized parameter and kernel() must be called before.
engine (str, optional) – The engine to use. Defaults to None, which uses self.engine.

Returns:

energy – Total energy

Return type:

float

See also

civector: Get the configuration interaction (CI) vector.
statevector: Evaluate the circuit state vector.
energy_and_grad: Evaluate the total energy and parameter gradients.

Examples

>>> from tencirchem import UCCSD
>>> from tencirchem.molecule import h2
>>> uccsd = UCCSD(h2)
>>> round(uccsd.energy([0, 0]), 8)  # HF state
-1.11670614

energy_and_grad(params: Any | None = None, engine: str | None = None) → Tuple[float, Any][source]¶

Evaluate the total energy and parameter gradients.

Parameters:

params (Tensor, optional) – The circuit parameters. Defaults to None, which uses the optimized parameter and kernel() must be called before.
engine (str, optional) – The engine to use. Defaults to None, which uses self.engine.

Returns:

energy (float) – Total energy
grad (Tensor) – The parameter gradients

See also

civector: Get the configuration interaction (CI) vector.
statevector: Evaluate the circuit state vector.
energy: Evaluate the total energy.

Examples

>>> from tencirchem import UCCSD
>>> from tencirchem.molecule import h2
>>> uccsd = UCCSD(h2)
>>> e, g = uccsd.energy_and_grad([0, 0])
>>> round(e, 8)
-1.11670614
>>> g  
array([..., ...])

classmethod from_integral(int1e: ndarray, int2e: ndarray, n_elec: int, e_core: float = 0, ovlp: ndarray | None = None, **kwargs)[source]¶

Construct UCC classes from electron integrals.

Parameters:

int1e (np.ndarray) – One-body integral in spatial orbital.
int2e (np.ndarray) – Two-body integral, in spatial orbital, chemists’ notation, and without considering symmetry.
n_elec (int) – The number of electrons
e_core (float, optional) – The nuclear energy or core energy if active space approximation is involved. Defaults to 0.
ovlp (np.ndarray) – The overlap integral. Defaults to None and identity matrix is used.
kwargs – Other arguments to be passed to the __init__() function such as engine.

Returns:

ucc – A UCC instance

Return type:

UCC

get_addr(bitstring: str) → int[source]¶

Get the address (index) of a CI bitstring in the CI vector.

Parameters:: bitstring (str) – The bitstring such as "0101".
Returns:: address – The bitstring address.
Return type:: int

Examples

>>> from tencirchem import UCCSD, PUCCD
>>> from tencirchem.molecule import h2
>>> uccsd = UCCSD(h2)
>>> uccsd.get_addr("0101")  # the HF state
0
>>> uccsd.get_addr("1010")
3
>>> puccd = PUCCD(h2)
>>> puccd.get_addr("01")  # the HF state
0
>>> puccd.get_addr("10")
1

get_ci_strings(strs2addr: bool = False) → ndarray[source]¶

Get the CI bitstrings for all configurations in the CI vector.

Parameters:

strs2addr (bool, optional.) – Whether return the reversed mapping for one spin sector. Defaults to False.

Returns:

cistrings (np.ndarray) – The CI bitstrings.
string_addr (np.ndarray) – The address of the string in one spin sector. Returned when strs2addr is set to True.

Examples

>>> from tencirchem import UCCSD, PUCCD
>>> from tencirchem.molecule import h2
>>> uccsd = UCCSD(h2)
>>> uccsd.get_ci_strings()
array([ 5,  6,  9, 10], dtype=uint64)
>>> [f"{bin(i)[2:]:0>4}" for i in uccsd.get_ci_strings()]
['0101', '0110', '1001', '1010']
>>> uccsd.get_ci_strings(True)[1]  # only one spin sector
array([0, 0, 1, 0], dtype=uint64)

get_circuit(params: Any | None = None, decompose_multicontrol: bool = False, trotter: bool = False) → Circuit[source]¶

Get the circuit as TensorCircuit Circuit object

Parameters:

params (Tensor, optional) – The circuit parameters. Defaults to None, which uses the optimized parameter. If kernel() is not called before, the initial guess is used.
decompose_multicontrol (bool, optional) – Whether decompose the Multicontrol gate in the circuit into CNOT gates. Defaults to False.
trotter (bool, optional) – Whether Trotterize the UCC factor into Pauli strings. Defaults to False.

Returns:

circuit – The quantum circuit.

Return type:

tc.Circuit

get_energy_dataframe() → DataFrame[source]¶: Returns energy information dataframe

get_ex1_ops(t1: ndarray | None = None) → Tuple[List[Tuple], List[int], List[float]][source]¶

Get one-body excitation operators.

Parameters:

t1 (np.ndarray, optional) – Initial one-body amplitudes based on e.g. CCSD

Returns:

ex_op (List[Tuple]) – The excitation operators. Each operator is represented by a tuple of ints.
param_ids (List[int]) – The mapping from excitations to parameters.
init_guess (List[float]) – The initial guess for the parameters.

See also

get_ex2_ops: Get two-body excitation operators.
get_ex_ops: Get one-body and two-body excitation operators for UCCSD ansatz.

get_ex2_ops(t2: ndarray | None = None) → Tuple[List[Tuple], List[int], List[float]][source]¶

Get two-body excitation operators.

Parameters:

t2 (np.ndarray, optional) – Initial two-body amplitudes based on e.g. MP2

Returns:

ex_op (List[Tuple]) – The excitation operators. Each operator is represented by a tuple of ints.
param_ids (List[int]) – The mapping from excitations to parameters.
init_guess (List[float]) – The initial guess for the parameters.

See also

get_ex1_ops: Get one-body excitation operators.
get_ex_ops: Get one-body and two-body excitation operators for UCCSD ansatz.

get_ex_ops(t1: ndarray | None = None, t2: ndarray | None = None)[source]¶: Virtual method to be implemented

get_excitation_dataframe() → DataFrame[source]¶

get_init_state_dataframe(coeff_epsilon: float = 1e-12) → DataFrame[source]¶

Returns initial state information dataframe.

Parameters:: coeff_epsilon (float, optional) – The threshold to screen out states with small coefficients. Defaults to 1e-12.
Return type:: pd.DataFrame

See also

init_state: The circuit initial state before applying the excitation operators.

Examples

>>> from tencirchem import UCC
>>> from tencirchem.molecule import h2
>>> ucc = UCC(h2)
>>> ucc.init_state = [0.707, 0, 0, 0.707]
>>> ucc.get_init_state_dataframe()   
     configuration  coefficient
0          0101        0.707
1          1010        0.707

get_opt_function(with_time: bool = False) → Callable | Tuple[Callable, float][source]¶

Returns the cost function in SciPy format for optimization. The gradient is included. Basically a wrapper to energy_and_grad().

Parameters:

with_time (bool, optional) – Whether return staging time. Defaults to False.

Returns:

opt_function (Callable) – The optimization cost function in SciPy format.
time (float) – Staging time. Returned when with_time is set to True.

property h_fermion_op: FermionOperator¶: Hamiltonian as openfermion.FermionOperator

property h_qubit_op: QubitOperator¶: Hamiltonian as openfermion.QubitOperator, mapped by Jordan-Wigner transformation.

property init_state: Any¶

The circuit initial state before applying the excitation operators. Usually RHF.

See also

get_init_state_dataframe: Returns initial state information dataframe.

kernel() → float[source]¶

The kernel to perform the VQE algorithm. The L-BFGS-B method in SciPy is used for optimization and configuration is possible by setting the self.scipy_minimize_options attribute.

Returns:: e – The optimized energy
Return type:: float

make_rdm1(statevector: Any | None = None, basis: str = 'AO') → ndarray[source]¶

Evaluate the spin-traced one-body reduced density matrix (1RDM).

\[\textrm{1RDM}[p,q] = \langle p_{\alpha}^\dagger q_{\alpha} \rangle + \langle p_{\beta}^\dagger q_{\beta} \rangle\]

If active space approximation is employed, returns the full RDM of all orbitals.

Parameters:

statevector (Tensor, optional) – Custom system state. Could be CI vector or state vector. Defaults to None, which uses the optimized state by civector().
basis (str, optional) – One of "AO" or "MO". Defaults to "AO", which is for consistency with PySCF.

Returns:

rdm1 – The spin-traced one-body RDM.

Return type:

np.ndarray

See also

make_rdm2: Evaluate the spin-traced two-body reduced density matrix (2RDM).

make_rdm2(statevector: Any | None = None, basis: str = 'AO') → ndarray[source]¶

Evaluate the spin-traced two-body reduced density matrix (2RDM).

\[\begin{split}\begin{aligned} \textrm{2RDM}[p,q,r,s] & = \langle p_{\alpha}^\dagger r_{\alpha}^\dagger s_{\alpha} q_{\alpha} \rangle + \langle p_{\beta}^\dagger r_{\alpha}^\dagger s_{\alpha} q_{\beta} \rangle \\ & \quad + \langle p_{\alpha}^\dagger r_{\beta}^\dagger s_{\beta} q_{\alpha} \rangle + \langle p_{\beta}^\dagger r_{\beta}^\dagger s_{\beta} q_{\beta} \rangle \end{aligned}\end{split}\]

If active space approximation is employed, returns the full RDM of all orbitals.

Parameters:

statevector (Tensor, optional) – Custom system state. Could be CI vector or state vector. Defaults to None, which uses the optimized state by civector().
basis (str, optional) – One of "AO" or "MO". Defaults to "AO", which is for consistency with PySCF.

Returns:

rdm2 – The spin-traced two-body RDM.

Return type:

np.ndarray

See also

make_rdm1: Evaluate the spin-traced one-body reduced density matrix (1RDM).

Examples

>>> import numpy as np
>>> from tencirchem import UCC
>>> from tencirchem.molecule import h2
>>> ucc = UCC(h2)
>>> state = [1, 0, 0, 0]  ## HF state
>>> rdm1 = ucc.make_rdm1(state, basis="MO")
>>> rdm2 = ucc.make_rdm2(state, basis="MO")
>>> e_hf = ucc.int1e.ravel() @ rdm1.ravel() + 1/2 * ucc.int2e.ravel() @ rdm2.ravel()
>>> np.testing.assert_allclose(e_hf + ucc.e_nuc, ucc.e_hf, atol=1e-10)

property n_params: int¶: The number of parameter in the ansatz/circuit.

property no: int¶: The number of occupied orbitals.

property nv: int¶: The number of virtual (unoccupied orbitals).

property param_ids: List[int]¶: The mapping from excitations operators to parameters.

property param_to_ex_ops¶

property params: Any¶: The circuit parameters.

print_ansatz()[source]¶

print_circuit()[source]¶: Prints the circuit information. If you wish to print the circuit diagram, use get_circuit() and then call draw() such as print(ucc.get_circuit().draw()).

print_energy()[source]¶

print_excitations()[source]¶

print_init_state()[source]¶

print_summary(include_circuit: bool = False)[source]¶

Print a summary of the class.

Parameters:: include_circuit (bool) – Whether include the circuit section.

statevector(params: Any | None = None, engine: str | None = None) → Any[source]¶

Evaluate the circuit state vector.

Parameters:

params (Tensor, optional) – The circuit parameters. Defaults to None, which uses the optimized parameter and kernel() must be called before.
engine (str, optional) – The engine to use. Defaults to None, which uses self.engine.

Returns:

statevector – Corresponding state vector

Return type:

Tensor

See also

civector: Evaluate the configuration interaction (CI) vector.
energy: Evaluate the total energy.
energy_and_grad: Evaluate the total energy and parameter gradients.

Examples

>>> from tencirchem import UCCSD
>>> from tencirchem.molecule import h2
>>> uccsd = UCCSD(h2)
>>> uccsd.statevector([0, 0])  # HF state
array([0., 0., 0., 0., 0., 1., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.])

property statevector_size: int¶: The size of the statevector.