Class CC¶

Defined in File cc.hpp

Nested Relationships¶

Nested Types¶

Struct CC::Options

Class Documentation¶

class CC¶

CC is a derivation engine for the coupled-cluster method.

Public Types

enum class Ansatz¶

Values:

enumerator T¶: traditional ansatz

enumerator oT¶: traditional orbital-optimized (singles-free) ansatz

enumerator U¶: unitary ansatz

enumerator oU¶: unitary orbital-optimized (singles-free) ansatz

enum class HbarExpansion¶

Values:

enumerator BCH¶: standard Baker-Campbell-Hausdorff commutator expansion

enumerator Bernoulli¶: Bernoulli expansion, 10.1063/1.5030344 (U ansatz only)

Public Functions

explicit CC(size_t n)¶

constructs CC engine with default options (traditional ansatz, screening enabled, topological optimization enabled)

Parameters:: n – coupled cluster excitation rank

explicit CC(size_t n, const Options &opts)¶

constructs CC engine with custom options

See also

CC::Options

Parameters:

n – coupled cluster excitation rank
opts – configuration options

Throws:

Exception – if a unitary ansatz has no hbar_comm_rank, or if the Bernoulli expansion is requested with an ansatz other than Ansatz::U

Ansatz ansatz() const¶

Returns:: the type of ansatz

bool unitary() const¶

Returns:: true if the ansatz is unitary

std::optional<size_t> hbar_comm_rank() const¶

Returns:: the maximum of nested commutators in H̄; returns std::nullopt if not set

HbarExpansion hbar_expansion() const¶

Returns:: the choice of H̄ expansion

bool skip_singles() const¶

Returns:: true if singles amplitudes are excluded from \( \hat{T} \) and \( \hat{\Lambda} \)

bool screen() const¶

Returns:: whether screening is on or not

bool use_topology() const¶

Returns:: whether topological optimization is used in WickTheorem

ExprPtr hbar(std::optional<size_t> truncation_rank = std::nullopt) const¶

computes similarity transformed Hamiltonian, \( \bar{H} = e^{-\hat{\sigma}} \hat{H} e^{\hat{\sigma}} \). The form of \( \sigma \) depends on the Ansatz choice.

Note

For a non-unitary ansatz each commutator is represented as a connected product, \( (\hat{A}\hat{B})_c \), equivalent to \( [\hat{A},\hat{B}] \) only once operator connectivity is supplied downstream; this engine always supplies it, by handing ref_av default_op_connections() or a superset thereof. A unitary ansatz uses explicit commutators instead, and is handed empty connectivity.

Note

Under HbarExpansion::Bernoulli the result is tensor-level, so it takes op::tensor projectors and op::tensor::ref_av, not their op counterparts. That path never reaches CC::ref_av, so screen and use_topology have no effect on it.

Warning

Because of the above, the expression returned for a non-unitary ansatz is NOT self-contained: evaluating it with empty connectivity, e.g. op::ref_av(P(nₚ(2)) * cc.hbar(), {.connect = {}}), silently retains the disconnected terms that the commutator would have cancelled. Pass default_op_connections() (which op::ref_av/op::vac_av use when the options argument is omitted — note that passing {} instead gives empty connections), or build H̄ yourself with mbpt::lst(..., {})

if you need the explicit form. For a unitary ansatz the reverse holds: H̄ is already self-contained, so connectivity must be left empty. See the “Using H̄

outside the CC class” section of the user guide.

Parameters:: truncation_rank – maximum order of nested commutators to include in the expansion; if not specified, will use the value of member hbar_comm_rank. If that is also not specified, will use 4 as the default value. If provided, will override all defaults.

ExprPtr energy(std::optional<size_t> comm_rank = std::nullopt) const¶

derives the CC energy expression \( \langle 0|\bar{H}|0 \rangle \) at the requested commutator truncation, WITHOUT deriving the projected amplitude equations (avoids deriving the full t() manifold just to read t().at(0)).

Parameters:: comm_rank – optional H̄ commutator-truncation override, forwarded to hbar (defaults to the engine’s hbar_comm_rank, else 4).
Returns:: the energy expression \( \langle 0|\bar{H}|0 \rangle \)

std::vector<ExprPtr> t(size_t pmax = std::numeric_limits<size_t>::max(), size_t pmin = 0) const¶

derives t amplitude equations, \( \langle P|\bar{H}|0 \rangle = 0 \)

Parameters:

pmax – highest particle rank of the projector manifold \f \langle P | \f; the default value is to use the cluster operator rank of this engine
pmin – lowest particle rank of the projector manifold \f \langle P | \f; the default value is 0

Returns:

vector of t amplitude equations, with element k containing equation \( \langle k |\bar{H}|0 \rangle = 0 \) for k in the [pmin,pmax] range, and null value otherwise

std::vector< ExprPtr > λ () const

derives λ amplitude equations, \( \langle 0| (1 + \hat{\Lambda}) \frac{d \bar{H}}{d \hat{T}_P} |0 \rangle = 0 \)

Returns:: vector of λ amplitude equations, with element k containing equation \( \langle 0| (1 + \hat{\Lambda}) \frac{d \bar{H}}{d \hat{T}_k} |0 \rangle = 0 \) for k in the [1,N] range; element 0 contains the λ pseudoenergy, computed as the CC energy with \( \hat{T} \) replaced by \( \hat{\Lambda}^{\dagger} \)

std::vector< ExprPtr > tʼ (size_t rank=1, size_t order=1, std::optional< size_t > nbatch=std::nullopt) const

derives perturbed t amplitude equations

Parameters:

rank – rank of perturbation operator. r = 1 means one-body perturbation operator
order – order of perturbation
nbatch – optional batching index rank for perturbation operators

Pre:

rank==1 && order==1, only first order perturbation and one-body perturbation operator is supported now

Returns:

std::vector of perturbed t amplitude equations

std::vector< ExprPtr > λʼ (size_t rank=1, size_t order=1, std::optional< size_t > nbatch=std::nullopt) const

derives perturbed λ amplitude equations

Parameters:

rank – rank of perturbation operator. r = 1 means one-body perturbation operator
order – order of perturbation
nbatch – optional batching index rank for perturbation operators

Pre:

rank==1 && order==1, only first order perturbation and one-body perturbation operator is supported now

Returns:

std::vector of perturbed λ amplitude equations

std::vector< ExprPtr > eom_r (nₚ np, nₕ nh, const std::vector< std::size_t > &block_ranks={}) const

derives right-side sigma equations for EOM-CC

Parameters:

np – number of particle creators in R operator
nh – number of hole creators in R operator
block_ranks – optional per-block H̄ commutator truncation ranks: a different H̄ in each block of the secular matrix instead of one uniform H̄ everywhere. For singles+doubles the matrix is | H_SS H_SD | e.g. | 2 1 | | H_DS H_DD | | 1 0 | read row by row, i.e. {2,1,1,0}: H_SS through the double commutator [[H,σ],σ], H_SD and H_DS through the single [H,σ], H_DD the bare Hamiltonian integrals (no commutators). Under Bernoulli a rank is the Bernoulli order H̄^k instead, whose commutators are in V alone. These are that paper’s Bernoulli qUCCSD ranks, UCCSD[2|2,1,0] of 10.1063/5.0062090 Eqs. (29), (41), (44), (48); its BCH scheme instead needs F one rank above V, which one number per block cannot express. K manifolds give a row-major K×K matrix ordered by ASCENDING manifold rank, so one set of numbers serves EE, IP and EA (read S as 1h/1p and D as 2h1p/1h2p; 10.1021/acs.jctc.5c01991 Fig. 1 carries the IP/EA ranks). Empty (the default) fills every block with hbar_comm_rank. Which form gets built depends on the expansion: Bernoulli always uses the blocked form, BCH uses it only when a matrix is given and builds a commutator otherwise. The BCH forms differ by off-diagonal amplitude-residual terms unless those residuals vanish.

Pre:

if non-empty, requires a unitary ansatz; a non-unitary H̄ terminates and has nothing to truncate.

Pre:

block_ranks is either empty or K×K

Returns:

projected sigma equations in a vector of size min(np, nh) + 1, indexed by the smaller particle/hole count of each projection manifold. With per-block truncation, each diagonal subtracts the scalar carried by the same temporary \( \bar{H}^{(k)} \) used for that block. This leaves the blockwise normal-ordered components of Eq. (10), not distinct physical energy zeros. Element 0 is null iff np == nh

std::vector< ExprPtr > eom_l (nₚ np, nₕ nh) const

derives left-side sigma equations for EOM-CC

Parameters:

np – number of particle annihilators in L operator
nh – number of hole annihilators in L operator

Returns:

vector of left side sigma equations, element 0 is always null

ExprPtr rdm(size_t rank = 1, std::optional<size_t> comm_rank = std::nullopt) const¶

derives the reduced density matrix (RDM) of particle rank rank as the reference expectation value of a similarity-transformed replacement operator, whose free-index ordinals are fixed by op::ã. Traditional ansatz: \( \gamma^{p_1 \dots p_r}_{p_{r+1} \dots p_{2r}} = \langle 0| (1 + \hat{\Lambda}) e^{-\hat{T}} \{ \tilde{a}^{p_1 \dots p_r}_{p_{r+1} \dots p_{2r}} \} e^{\hat{T}} |0 \rangle \); unitary ansatz drops \( \hat{\Lambda} \) and uses \( e^{-\hat{\sigma}} \dots e^{\hat{\sigma}} \) with \( \hat{\sigma} = \hat{T} - \hat{T}^\dagger \).

Note

Only the correlation contribution is returned: op::ã is normal-ordered, so the reference contractions are absent.

Note

For rank >= 2 the result is not manifestly antisymmetric: the replacement operator carries no antisymmetrizer.

Note

For the traditional ansatz this is the linked density; the unitary ansatz uses no connectivity.

Parameters:

rank – particle rank of the RDM (1 = one-particle \( \gamma \), 2 = two-particle \( \Gamma \), …)
comm_rank – maximum order of nested commutators in the similarity transform of the replacement operator; if not specified, defaults to min(2*rank, rank + N) for the traditional ansatz (where the expansion terminates exactly) and to hbar_comm_rank for the unitary ansatz (where it does not). Pass an explicit value to truncate earlier.

Returns:

the RDM expression (Fermi-vacuum normal-ordered / correlation part)

struct Options¶

Configuration options for CC class.

Public Members

SEQUANT_DESIGNATED_INIT_ONLY

Ansatz ansatz = Ansatz::T ¶: type of CC ansatz. see CC::Ansatz

std::optional<bool> skip_singles = std::nullopt¶: if true, singles amplitudes are excluded from \( \hat{T} \) and \( \hat{\Lambda} \); if not specified, defaults to true for orbital-optimized ansätze (oT, oU) and false otherwise. Must be true for orbital-optimized ansätze.

bool screen = true¶: if true, uses Operator level screening before applying WickTheorem. This propagates to all ref_av() calls

bool use_topology = true¶: if true, uses topological optimizations in WickTheorem

std::optional<size_t> hbar_comm_rank = std::nullopt¶: maximum order of nested commutators in H̄; must be specified if unitary ansatz is used

std::optional<size_t> pertbar_comm_rank = std::nullopt¶: maximum order of nested commutators in the similarity transformed perturbation operator; must be specified if unitary ansatz is used in perturbed amplitude derivation

HbarExpansion hbar_expansion = HbarExpansion::BCH ¶: choice of H̄ expansion; Bernoulli requires the U ansatz, not merely a unitary one, and ignores screen and use_topology, see hbar()