Ground states and energy corrections
For the experimental cim=CIMOptions(...) dispatch on supported ground
levels, see Cluster-in-molecule local correlation. It returns a local-correlation wrapper, not an ordinary
global CC amplitude object; its restrictions and validation status differ.
MPn and coupled-cluster levels
For any ordinary ground-state level, instantiate it on native SCF or a
Reference and call energy(). Additional required inputs are listed below.
from ccpy import MP2, CCSD, CCSDT, CCSDpT, CRCC23
mp2 = MP2(mf, nfrozen=1)
e_mp2 = mp2.energy()
cc = CCSD(mf, nfrozen=1)
e_ccsd = cc.energy()
e_ccsdt = CCSDT(mf, nfrozen=1).energy()
e_ccsd_t = CCSDpT(cc).energy()
e_cr = CRCC23(cc, variant="D").energy()
Each energy includes the SCF determinant energy. correlation_energy is the
raw correlated contribution, not a second total energy. raw_energy() omits
FNO completion. For CC, T contains the converged excitation amplitudes.
total_energy is a reporting property and does not itself trigger a fresh
solve; use energy() when the method may be unsolved.
Class |
Equations / inputs |
Implementation notes |
|---|---|---|
|
Second-order MP energy; native DF occupied-pair contractions. |
Handles internal semicanonicalization and Fov singles for general references. |
|
Third-/fourth-order MP energies. |
Materialized four-index kernels. |
|
Doubles CC. |
Materialized equations; no default HBar or left method. |
|
Approximate second-order CC. |
Materialized equations; default |
|
Singles and doubles CC. |
Native DF; default |
|
Approximate iterative triples. |
Materialized; stored operator order 2, with triples handled by the kernel. |
|
Full singles, doubles and triples. |
Materialized; stored order 3, |
|
Approximate quadruples model. |
Materialized; stored order 3; explicitly restricted to closed-shell RHF. |
|
Full singles through quadruples. |
Materialized; no default HBar/left method exposed by this wrapper. |
|
Full T1/T2 plus selected T3; requires |
Native DF CC solve; downstream HBar/left equations can be materialized. |
|
Require |
Materialized; no default HBar/left method. |
|
Requires |
Materialized selected-triples approximate coupled-pair equations. |
|
Requires |
Materialized; external T3/T4 are held fixed during CCSD-like iterations. |
Higher excitation rank can rapidly increase memory and cost even for small
molecules. The operator rank is not always the formal perturbative level:
CC3 and CC4 are examples. Use the equation descriptions and method name,
not T.order alone, to identify the model.
Approximate coupled-pair and external correction inputs
from ccpy import ACCSD, ECCC2
acp = ACCSD(mf, acparray=[1., 1., 0., 0., 1.], nfrozen=1)
acp_total = acp.energy()
external = ECCC2(mf, ci_vectors_file="ci_wavefunction.dat", nfrozen=1)
external_total = external.energy()
The example scaling vector is a selectable diagram model, not a universal
recommended setting. ECCC2 uses
ccpy.extcorr.external_correction.cluster_analysis’s headerless text format.
Each line contains an identifier, a floating-point CI coefficient, then the
occupied spin-orbital labels of that determinant. For example, in a correlated
two-electron space:
1 0.98 1 2
2 -0.10 1 4
Spin-orbital labels are one based with alpha odd and beta even: spatial orbital
p has alpha label 2*p-1 and beta label 2*p. Frozen electrons are excluded
and correlated orbital labels restart at one. Include the sorted HF determinant
with a nonzero coefficient; the reader uses it for intermediate normalization.
It processes excitations through quadruples. Do not insert headers, comments
or blank records into this parser’s input. A generic coefficient vector without
determinant labels is insufficient.
The CI determinants, orbital ordering, frozen core and basis must match the working reference. FNO rotation requires a CI wavefunction already expressed in the reduced working basis. This wrapper does not rotate external CI data.
Ground-state noniterative corrections
Corrections are separate objects so that the same CC, HBar and left state can
be reused. energy() is the corrected total, while deltas contains the
additive increments by variant. Most wrappers default to variant D; the
catalog gives the exact variant tuple and default for each class.
Correction |
Standard parent |
Important settings / meaning |
|---|---|---|
|
|
CCSD(T); A only; bare Hamiltonian, no left state or HBar needed. |
|
|
CR-CC(2,3); A/B/C/D; native DF; optional semi-stochastic evaluation. |
|
active |
CC(t;3); |
|
|
CC(P;3); default two-body approximation, optional full selected-triples HBar/left. |
|
|
CR-CC(2,4), materialized quadruples correction. |
|
|
CR-CC(3,4), RHF kernel; default A. Do not assume every inherited variant is implemented. |
|
default |
Requires |
cr = CRCC23(cc, variant="D")
total = cr.energy()
print(cr.deltas) # e.g. A/B/C/D increments
print(cr.cc is cc) # reuse the parent
Changing variant among computed supported keys changes reporting; it does
not require solving CC again. Scientific kernel restrictions can be narrower
than inherited wrapper options. In particular, inspect returned deltas
before assuming a high-rank correction supplies every A/B/C/D variant.
FNO completion is included once in the final total, in addition to the
high-level correction.
Selected triples, CC(t;3), and CC(P;3)
from ccpy import (Reference, CCSDT_P, CCT3, CCP3,
get_active_triples_pspace)
ref = Reference(mf, nfrozen=1)
ref.system.set_active_space(nact_occupied=2, nact_unoccupied=2)
triples = get_active_triples_pspace(ref.system, num_active=1)
ccp = CCSDT_P(ref, triples)
e_p = ccp.energy()
e_t3 = CCT3(ccp, num_active=1, nacto=2, nactu=2).energy()
e_pq_2ba = CCP3(ccp, two_body_approx=True).energy()
e_pq_full = CCP3(ccp, two_body_approx=False).energy()
CCT3’s active counts configure the correction’s System; they do not
retroactively generate the right CC triples. Supply a consistent selected-triples
parent or explicit t3_excitations. CCP3 can also accept
target_irrep; high_memory selects the high-memory full correction only
when two_body_approx=False. Full and two-body-approximation corrections use
different HBars/left states and need not give the same energy.
CCP4 requires an explicit t4_excitations dictionary with keys
aaaa, aaab, aabb, abbb and bbbb and rows
[a,b,c,d,i,j,k,l] in the expected selected-space convention. The helper
get_quadruples_pspace_from_cipsi reads the supported external CIPSI format;
its signature and file convention should be inspected before using external
lists. It does not create a CCSDTQ(P) parent: no such ground-state wrapper is
exported here. Selected-space conventions are detailed in FNOs, active spaces and selected determinants.
Adaptive CC(P;Q)
from ccpy import AdaptiveCCPQ
adaptive = AdaptiveCCPQ(
mf, nfrozen=1, percentage=[0., 1., 2.],
energy_tolerance=1.e-4,
)
total = adaptive.energy()
print(adaptive.ccp_energies, adaptive.ccpq_energies)
print(adaptive.adaptive_converged, adaptive.ccpq_errors)
The percentages specify successive P-space sizes relative to all triples in
the reference symmetry. Each macroiteration solves CCSDT(P), constructs a
CCSD-like HBar/left state for the two-body approximation, and selects new triples
from CC(P;3) moment contributions. The final macroiteration computes the
correction without further growth. Without percentage, growth uses
selection_factor times a singles or singles+doubles base
(base_growth="ccsd" by default), for up to
maximum_macroiterations + 1 macroiterations.
Controls include n_det_max, buffer_factor, minimum_threshold and
reset_amplitudes. Explicit pspaces=[...] replays prescribed spaces.
pspaces, timings and extrapolated record the selection history,
wall times and Goodson extrapolations. adaptive_converged distinguishes
meeting the adaptive energy criterion from merely finishing the prescribed
schedule. This wrapper is ground-state AdaptiveCCPQ; legacy adaptive excited
state drivers are separate APIs.
Semi-stochastic triples corrections
CRCC23, CCT3 and two-body CCP3 accept:
stochastic = CRCC23(cc, stochastic={"target_error": 1.e-5, "seed": 7})
total = stochastic.energy()
print(stochastic.errors, stochastic.stochastic_info)
errors reports one-standard-deviation estimates by variant. These are
sampling uncertainties, not estimates of basis-set, FNO or truncation errors.
stochastic=True uses the algorithm defaults; the complete controls live in
ccpy.moments.stochastic_triples.DEFAULT_OPTIONS. Unsupported correction
classes reject stochastic evaluation. Full CCP3 requires deterministic
operation.
AdaptiveCCPQ(stochastic=..., convergence_z=1.96) uses stochastic corrections
for convergence decisions while determinant selection remains deterministic.
Its stopping criterion includes the uncertainty of consecutive energies:
The statistical target must be small enough to resolve that tolerance; the wrapper checks this. Analytic gradients are disabled for stochastic correction instances; numerical differentiation of sampled energies needs its own noise assessment.
State-universal multireference CC
SUMRCCSD(mf, n, m) solves the Jeziorski-Monkhorst SU-MRCCSD equations in the
complete model space CAS(n, m) of RHF/ROHF orbitals, with the m active orbitals
right above the core. Each model-space determinant (all spin states with the
reference’s \(M_s\)) is a reference with its own CCSD-like cluster operator, and
energy() returns the eigenvalues of the effective Hamiltonian, one per determinant:
mr = SUMRCCSD(mf, 2, 2, nfrozen=1)
roots = mr.energy() # ascending; mr.energy(0) is the lowest
mr.heff, mr.coefficients # effective Hamiltonian, model-space eigenvectors
SUMRCCSD1(mf, 2, 2).energy() # core-virtual amplitudes at first-order MRMBPT
A general (incomplete) model space is given as a list of determinants instead, each
listing the \(N_\alpha\) occupied alpha and then the \(N_\beta\) occupied beta
correlated orbitals, numbered from 1 (as in ccpy.models.hilbert.Determinant), e.g.
a CAS with a determinant that causes convergence problems removed:
# H2, CAS(2,2) without the doubly excited determinant
mr = SUMRCCSD(mf, determinants=[[1, 1], [1, 2], [2, 1]])
Orbitals occupied (empty) in every determinant are core (virtual). Amplitudes of the internal excitations, which take one reference into another, follow the C conditions of Li and Paldus [J. Chem. Phys. 119, 5320 (2003)]: internal singles vanish, internal doubles are \(-\mathcal{A}\,t_1 t_1\), and internal excitations of higher rank (at most the number of active electrons) carry amplitudes equal to minus their disconnected clusters. These enter the effective Hamiltonian and the coupling terms, keeping both connected, and the direct terms, where the internal triples and quadruples add their CCSDT/CCSDTQ contributions to the singles and doubles equations (higher ranks cannot reach them). In a complete model space all internal amplitudes vanish.
Such determinants can also be dropped automatically: prune_intruders=gap removes
determinants, highest energy first, until every single or double of the remaining ones
lies at least gap (Eh) above the highest of them, at the orbital-energy estimate used
for the intruder warning (0.0 removes exactly what the warning flags). A positive gap is
necessary for the Jacobi iterations to converge but no value guarantees it; for H4/6-31G,
CAS(4,4) converged from a gap of about 0.3 Eh. The removed determinants are printed, and
their states are no longer computed.
mr = SUMRCCSD(mf, 4, 4, prune_intruders=0.3)
mr.model_space.determinants # the determinants kept
Noniterative triples corrections from the method of moments of the SU-MRCC equations,
MM-SUCC(2,3) [Piecuch and Kowalski, Int. J. Mol. Sci. 3, 676 (2002)], are available as
mr.mmsucc23() (energies of all roots, or mr.mmsucc23(root)):
where \(\Gamma_3(p)\) are the triples moments of the SU-MRCC equations of each reference (direct and coupling terms) and the trial wave function is the multireference analog of CR-CCSD(T), \(\Psi_\mu = \sum_q c_{q\mu}(1 + T_1 + T_2 + Z_3)(q)|\Phi_q\rangle\) with \(Z_3 = R_3[(V_N T_2)_C + (V_N T_1)_{DC}]\) from the converged amplitudes. For one reference the triples part reduces to CR-CCSD(T)’s. Everything is evaluated on the fly over the triples of each reference (no triples are stored), at a CR-CC(2,3)-like cost per reference plus the projections of the other references’ wave functions onto its triples.
The effective Hamiltonian elements and coupling terms are exact for any model space and any number of active electrons: both come from one primitive, the coefficient of each single or double of reference \(p\) in \(e^{T(q)}|\Phi_q\rangle\), evaluated by a recursion over the partitions of the excitation into cluster blocks (t1, t2, and the C-condition internal amplitudes), with array sizes set by the longest excitation present. The cost grows as the square of the number of determinants; pairs of references of different point-group symmetry are skipped, and in complete model spaces partitions without a core or virtual index in every block are pruned. To see the formula behind any element, list its terms:
from ccpy.mrcc.sumrcc import cluster_terms, format_cluster_terms
# alpha 1,2 -> 3,4 and beta 1 -> 3 relative to Phi_q (spin orbitals, 4 spatial orbitals)
print(format_cluster_terms(cluster_terms((0, 1, 4), (2, 3, 6), 4), 4))
# + t1(3a;1a) t1(4a;2a) t1(3b;1b)
# + t1(3a;1a) t2(4a,3b;2a,1b)
# ... Larger model spaces
are prone to intruder states, which are reported when an external determinant lies
below the highest reference. solver="auto" (default) runs Jacobi/DIIS and falls
back to Newton-Krylov; "jacobi" and "newton_krylov" select one. The equations
use the DF vectors directly: each reference stores its Fock matrix, Cholesky vectors and
only the two-body integrals with at most two unoccupied indices.