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 hbar_comm_rank is not set for a unitary ansatz or when the reference differs from the Wick vacuum (the context at construction decides), if an orbital-optimized ansatz includes singles, if the Bernoulli expansion is requested with an ansatz other than Ansatz::U, or if a positive hbar_singles_comm_rank is used with a non-unitary ansatz, Bernoulli, or excluded singles

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

template<typename F> inline CC with(F &&mutate) const¶

returns a validated copy with mutate applied to its options

Parameters:: mutate – callable taking Options&
Returns:: the mutated copy

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

When the reference differs from the Wick vacuum the amplitude operators do not commute with each other, so the expansion does not terminate and grows exponentially with the rank (CCSD amplitudes at rank 4 exceed several GB); the constructor therefore requires hbar_comm_rank there, as for a unitary ansatz.

Note

The returned expression depends on the ansatz and expansion:

When the reference is the Wick vacuum, a non-unitary ansatz represents each commutator as a connected product, \( (\hat{A}\hat{B})_c \). It is equivalent to \( [\hat{A},\hat{B}] \) only when operator connectivity is supplied downstream. With a differing reference it uses explicit commutators.
A unitary BCH ansatz uses explicit commutators and empty connectivity.
HbarExpansion::Bernoulli returns a tensor-level expression for use with op::tensor projectors and op::tensor::ref_av. It never reaches CC::ref_av, so screen and use_topology have no effect.

Note

ref_av requires empty connect and do_not_connect when the reference differs from the Wick vacuum and the vacuum is not MultiProduct.

Warning

A connected-product H̄ is not self-contained: evaluated with empty connectivity, e.g. op::ref_av(P(nₚ(2)) * cc.hbar()), it retains disconnected terms. An explicit-commutator H̄ (unitary ansatz, or a reference that differs from the Wick vacuum) is self-contained, and imposing connectivity on it drops terms that must survive. Pass hbar_connections() as EVOptions::connect; it is correct for every ansatz and reference. 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. The optional singles-only transform is applied afterward regardless of this rank.
Pre:: for HbarExpansion::Bernoulli, the reference is the Wick vacuum

OpConnections<std::wstring> hbar_connections() const¶

Returns:: the connectivity that, passed as EVOptions::connect to ref_av/vac_av, makes hbar() equal to the commutator expansion: default_op_connections() when H̄ is built from connected products (non-unitary ansatz, reference equal to the Wick vacuum), empty otherwise. The class uses it, or a superset, for its own equations.

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} \)
Pre:: the reference is the Wick vacuum (enforced in every build)

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

Throws:

Exception – if hbar_singles_comm_rank is positive

Pre:

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

Pre:

the reference is the Wick vacuum (enforced in every build)

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

Pre:

the reference is the Wick vacuum (enforced in every build)

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

Note

UCC always uses Hamiltonian-matrix assembly. Traditional CC uses its connected H̄R product and does not support block ranks.

Parameters:

np – number of particle creators in R operator
nh – number of hole creators in R operator
block_ranks – optional per-block H̄ truncation ranks:
- A K×K matrix is read row by row in ascending manifold rank. For singles+doubles it is | H_SS H_SD | e.g. | 2 1 | | H_DS H_DD | | 1 0 | Thus {2,1,1,0} uses [[H,σ],σ] for H_SS, [H,σ] for H_SD and H_DS, and zeroth-order H̄ for H_DD. With a positive hbar_singles_comm_rank, even a rank-0 block includes the additional singles-only transform.
- The same ordering serves EE, IP, and EA: read S as 1h/1p and D as 2h1p/1h2p (10.1021/acs.jctc.5c01991, Fig. 1).
- Under Bernoulli, each rank is a Bernoulli order H̄^k whose commutators are in V alone. These are the Bernoulli qUCCSD ranks UCCSD[2|2,1,0] of 10.1063/5.0062090, Eqs. (29), (41), (44), (48). Its BCH scheme needs F one rank above V, which one rank per block cannot express.
- Empty uses the configured H̄ rank for every block.

Throws:

Exception – if non-empty block_ranks is used with a traditional ansatz, or if block_ranks is not K×K

Pre:

the reference is the Wick vacuum (enforced in every build)

Returns:

projected sigma equations in a vector of size min(np, nh) + 1, indexed by the smaller particle/hole count of each projection manifold:

Element 0 is null iff np == nh.
With UCC Hamiltonian-matrix assembly, each diagonal subtracts the scalar carried by the same temporary \( \bar{H}^{(k)} \) used for that block, leaving the per-block normal-ordered components of Eq. (10), not distinct physical energy zeros.

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

Pre:

the reference is the Wick vacuum (enforced in every build)

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.

Throws:

Exception – if hbar_singles_comm_rank is positive

Pre:

the reference is the Wick vacuum (enforced in every build)

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 for a unitary ansatz or when the reference differs from the Wick vacuum, since the expansion does not terminate in either case. Otherwise defaults to 4, which is exact for a two-body Hamiltonian.

size_t hbar_singles_comm_rank = 0¶: maximum order of the additional singles-only similarity transform applied to H̄ using \( \sigma_1 = T_1 - T_1^\dagger \). Zero disables the transform; a positive rank requires a unitary BCH ansatz with singles amplitudes enabled

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()