Unitary Coupled Cluster Wave Function

class slowquant.unitary_coupled_cluster.ucc_wavefunction.WaveFunctionUCC(num_elec: int, cas: Sequence[int], mo_coeffs: ndarray, h_ao: ndarray, g_ao: ndarray, excitations: str, include_active_kappa: bool = False)

Initialize for UCC wave function.

Parameters:

num_elec – Number of electrons.
cas – CAS(num_active_elec, num_active_orbs), orbitals are counted in spatial basis.
mo_coeffs – Initial orbital coefficients.
h_ao – One-electron integrals in AO for Hamiltonian.
g_ao – Two-electron integrals in AO.
excitations – Unitary coupled cluster excitation operators.
include_active_kappa – Include active-active orbital rotations.

_calc_energy_optimization(parameters: list[float], theta_optimization: bool, kappa_optimization: bool) → float

Calculate electronic energy of UCC wave function.

\[E = \left<0\left|\hat{H}\right|0\right>\]

Parameters:

parameters – Sequence of all parameters. Ordered as orbital rotations, active-space singles, active-space doubles, …
theta_optimization – If used in theta optimization.
kappa_optimization – If used in kappa optimization.

Returns:

Electronic energy.

_calc_gradient_optimization(parameters: list[float], theta_optimization: bool, kappa_optimization: bool) → ndarray

Calculate electronic gradient.

Parameters:

parameters – Ansatz and orbital rotation parameters.
theta_optimization – If used in theta optimization.
kappa_optimization – If used in kappa optimization.

Returns:

Electronic gradient.

property c_mo: ndarray

Get molecular orbital coefficients.

Returns:: Molecular orbital coefficients.

check_orthonormality(overlap_integral: ndarray) → None

Check orthonormality of orbitals.

\[\boldsymbol{I} = \boldsymbol{C}_\text{MO}\boldsymbol{S}\boldsymbol{C}_\text{MO}^T\]

Parameters:: overlap_integral – Overlap integral in AO basis.

property ci_coeffs: ndarray

Get CI coefficients.

Returns:: State vector.

property energy_elec: float

Get the electronic energy.

Returns:: Electronic energy.

property g_mo: ndarray

Get two-electron Hamiltonian integrals in MO basis.

Returns:: Two-electron Hamiltonian integrals in MO basis.

property h_mo: ndarray

Get one-electron Hamiltonian integrals in MO basis.

Returns:: One-electron Hamiltonian integrals in MO basis.

property kappa: list[float]: Get orbital rotation parameters.

property rdm1: ndarray

Calculate one-electron reduced density matrix in the active space.

Returns:: One-electron reduced density matrix.

property rdm2: ndarray

Calculate two-electron reduced density matrix in the actice space.

Returns:: Two-electron reduced density matrix.

property rdm3: ndarray

Calculate three-electron reduced density matrix in the actice space.

Currently not utilizing the full symmetry.

Returns:: Three-electron reduced density matrix.

property rdm4: ndarray

Calculate four-electron reduced density matrix in the active space.

Currently not utilizing the full symmetry.

Returns:: Four-electron reduced density matrix.

run_wf_optimization_1step(optimizer_name: str, orbital_optimization: bool = False, tol: float = 1e-10, maxiter: int = 1000) → None

Run one step optimization of wave function.

Parameters:

optimizer_name – Name of optimizer.
orbital_optimization – Perform orbital optimization.
tol – Convergence tolerance.
maxiter – Maximum number of iterations.

run_wf_optimization_2step(optimizer_name: str, orbital_optimization: bool = False, tol: float = 1e-10, maxiter: int = 1000, is_silent_subiterations: bool = False) → None

Run two step optimization of wave function.

Parameters:

optimizer_name – Name of optimizer.
orbital_optimization – Perform orbital optimization.
tol – Convergence tolerance.
maxiter – Maximum number of iterations.
is_silent_subiterations – Silence subiterations.

save_wavefunction(filename: str, force_overwrite: bool = False) → None

Save the wave function to a compressed NumPy object.

Parameters:

filename – Filename of compressed NumPy object without file extension.
force_overwrite – Overwrite file if it already exists.

property thetas: list[float]

Get theta values.

Returns:: theta values.

slowquant.unitary_coupled_cluster.ucc_wavefunction.load_wavefunction(filename: str) → WaveFunctionUCC

Load wave function from a compressed NumPy object.

Parameters:: filename – Filename of compressed NumPy object without file extension.
Returns:: Wave function object.

class slowquant.unitary_coupled_cluster.ups_wavefunction.WaveFunctionUPS(num_elec: int, cas: Sequence[int], mo_coeffs: ndarray, h_ao: ndarray, g_ao: ndarray, ansatz: str, ansatz_options: dict[str, Any] | None = None, include_active_kappa: bool = False)

Initialize for UPS wave function.

Parameters:

num_elec – Number of electrons.
cas – CAS(num_active_elec, num_active_orbs), orbitals are counted in spatial basis.
mo_coeffs – Initial orbital coefficients.
h_ao – One-electron integrals in AO for Hamiltonian.
g_ao – Two-electron integrals in AO.
ansatz – Name of ansatz.
ansatz_options – Ansatz options.
include_active_kappa – Include active-active orbital rotations.

_calc_energy_optimization(parameters: list[float], theta_optimization: bool, kappa_optimization: bool) → float

Calculate electronic energy.

Parameters:

parameters – Ansatz and orbital rotation parameters.
theta_optimization – If used in theta optimization.
kappa_optimization – If used in kappa optimization.

Returns:

Electronic energy.

_calc_gradient_optimization(parameters: list[float], theta_optimization: bool, kappa_optimization: bool) → ndarray

Calculate electronic gradient.

Parameters:

parameters – Ansatz and orbital rotation parameters.
theta_optimization – If used in theta optimization.
kappa_optimization – If used in kappa optimization.

Returns:

Electronic gradient.

property c_mo: ndarray

Get molecular orbital coefficients.

Returns:: Molecular orbital coefficients.

check_orthonormality(overlap_integral: ndarray) → None

Check orthonormality of orbitals.

\[\boldsymbol{I} = \boldsymbol{C}_\text{MO}\boldsymbol{S}\boldsymbol{C}_\text{MO}^T\]

Parameters:: overlap_integral – Overlap integral in AO basis.

property energy_elec: float

Get the electronic energy.

Returns:: Electronic energy.

property g_mo: ndarray

Get two-electron Hamiltonian integrals in MO basis.

Returns:: Two-electron Hamiltonian integrals in MO basis.

property h_mo: ndarray

Get one-electron Hamiltonian integrals in MO basis.

Returns:: One-electron Hamiltonian integrals in MO basis.

property kappa: list[float]: Get orbital rotation parameters.

property rdm1: ndarray

Calculate one-electron reduced density matrix in the active space.

Returns:: One-electron reduced density matrix.

property rdm2: ndarray

Calculate two-electron reduced density matrix in the active space.

Returns:: Two-electron reduced density matrix.

property rdm3: ndarray

Calculate three-electron reduced density matrix in the actice space.

Currently not utilizing the full symmetry.

Returns:: Three-electron reduced density matrix.

property rdm4: ndarray

Calculate four-electron reduced density matrix in the active space.

Currently not utilizing the full symmetry.

Returns:: Four-electron reduced density matrix.

run_wf_optimization_1step(optimizer_name: str, orbital_optimization: bool = False, tol: float = 1e-10, maxiter: int = 1000) → None

Run one step optimization of wave function.

Parameters:

optimizer_name – Name of optimizer.
orbital_optimization – Perform orbital optimization.
tol – Convergence tolerance.
maxiter – Maximum number of iterations.

run_wf_optimization_2step(optimizer_name: str, orbital_optimization: bool = False, tol: float = 1e-10, maxiter: int = 1000, is_silent_subiterations: bool = False) → None

Run two step optimization of wave function.

Parameters:

optimizer_name – Name of optimizer.
orbital_optimization – Perform orbital optimization.
tol – Convergence tolerance.
maxiter – Maximum number of iterations.
is_silent_subiterations – Silence subiterations.

property thetas: list[float]

Get theta values.

Returns:: theta values.

class slowquant.unitary_coupled_cluster.sa_ups_wavefunction.WaveFunctionSAUPS(num_elec: int, cas: Sequence[int], mo_coeffs: ndarray, h_ao: ndarray, g_ao: ndarray, states: tuple[list[list[float]], list[list[str]]], ansatz: str, ansatz_options: dict[str, Any] | None = None, include_active_kappa: bool = False)

Initialize for SA-UPS wave function.

Parameters:

num_elec – Number of electrons.
cas – CAS(num_active_elec, num_active_orbs), orbitals are counted in spatial basis.
mo_coeffs – Initial orbital coefficients.
h_ao – One-electron integrals in AO for Hamiltonian.
g_ao – Two-electron integrals in AO.
states – States to include in the state-averaged expansion. Tuple of lists containing weights and determinants. Each state in SA can be constructed of several dets.
ansatz – Name of ansatz.
ansatz_options – Ansatz options.
include_active_kappa – Include active-active orbital rotations.

_calc_energy_optimization(parameters: list[float], theta_optimization: bool, kappa_optimization: bool, return_all_states: bool = False) → float | list[float]

Calculate electronic energy of SA-UPS wave function.

\[E = \left<0\left|\hat{H}\right|0\right>\]

Parameters:

parameters – Ansatz and orbital rotation parameters.
theta_optimization – If used in theta optimization.
kappa_optimization – If used in kappa optimization.

Returns:

State-averaged electronic energy.

_calc_gradient_optimization(parameters: list[float], theta_optimization: bool, kappa_optimization: bool) → ndarray

Calculate electronic gradient.

For theta part,

10.48550/arXiv.2303.10825, Eq. 17-21 (appendix - v1)

Parameters:

parameters – Ansatz and orbital rotation parameters.
theta_optimization – If used in theta optimization.
kappa_optimization – If used in kappa optimization.

Returns:

State-averaged electronic gradient.

_do_state_ci() → None

Do subspace diagonalisation.

10.1103/PhysRevLett.122.230401, Eq. 2

property c_mo: ndarray

Get orbital coefficients.

Returns:: Orbital coefficients.

check_orthonormality(overlap_integral: ndarray) → None

Check orthonormality of orbitals.

\[\boldsymbol{I} = \boldsymbol{C}_\text{MO}\boldsymbol{S}\boldsymbol{C}_\text{MO}^T\]

Parameters:: overlap_integral – Overlap integral in AO basis.

property ci_coeffs: list[ndarray]

Get CI coefficients.

Returns:: State vector.

property energy_states: ndarray

Get state specific energies.

Returns:: State specific energies.

property excitation_energies: ndarray

Get excitation energies.

\[\varepsilon_n = E_n - E_0\]

Returns:: Excitation energies.

property g_mo: ndarray

Get two-electron Hamiltonian integrals in MO basis.

Returns:: Two-electron Hamiltonian integrals in MO basis.

get_oscillator_strenghts(dipole_integrals: Sequence[ndarray]) → ndarray

Get oscillator strengths between ground state and excited states.

\[f_n = \frac{2}{3}\varepsilon_n\left|\left<0\left|\hat{\boldsymbol{\mu}}\right|n\right>\right|^2\]

Parameters:: dipole_integrals – Dipole integrals in AO basis.
Returns:: Oscillator strengths.

get_transition_property(ao_integral: ndarray) → ndarray

Get transition property with one-electron operator.

\[t_n = \left<0\left|\hat{O}\right|n\right>\]

Parameters:: ao_integral – Operator integrals in AO basis.
Returns:: Transition property.

property h_mo: ndarray

Get one-electron Hamiltonian integrals in MO basis.

Returns:: One-electron Hamiltonian integrals in MO basis.

property kappa: list[float]: Get orbital rotation parameters.

property rdm1: ndarray

Calculate one-electron reduced density matrix in the active space.

Returns:: One-electron reduced density matrix.

property rdm2: ndarray

Calculate two-electron reduced density matrix in the active space.

Returns:: Two-electron reduced density matrix.

run_wf_optimization_1step(optimizer_name: str, orbital_optimization: bool = False, tol: float = 1e-10, maxiter: int = 1000) → None

Run one step optimization of wave function.

Parameters:

optimizer_name – Name of optimizer.
orbital_optimization – Perform orbital optimization.
tol – Convergence tolerance.
maxiter – Maximum number of iterations.

run_wf_optimization_2step(optimizer_name: str, orbital_optimization: bool = False, tol: float = 1e-10, maxiter: int = 1000, is_silent_subiterations: bool = False) → None

Run two step optimization of wave function.

Parameters:

optimizer_name – Name of optimizer.
orbital_optimization – Perform orbital optimization.
tol – Convergence tolerance.
maxiter – Maximum number of iterations.
is_silent_subiterations – Silence subiterations.

property sa_energy: float

Get the state-averaged electronic energy.

Returns:: State-averaged electronic energy.

property thetas: list[float]

Get theta values.

Returns:: theta values.