Canonical CCSD and CCSD(T)

Canonical coupled cluster is the small-molecule accuracy reference in vibe-qc. method="ccsd" runs closed-shell DF-CCSD; method="ccsd(t)" adds the standard perturbative triples correction. The same choice can be made explicitly with triples="none" or triples="(t)".

At a glance

High-level entry point

run_job(method="ccsd", triples=...)

Low-level entry point

run_ccsd(molecule, basis, rhf_result, CCSDOptions(...))

Reference

closed-shell RHF

Integral form

density-fitted molecular integrals

Scope

dense O(N^6) small-molecule pilot

Validation

in-repo spin-orbital/FCI anchors; PySCF DF-CCSD cross-checks when PySCF is installed

Quick start

import vibeqc as vq

mol = vq.Molecule(
    [
        vq.Atom(8, [0.000, 0.000, 0.000]),
        vq.Atom(1, [0.000, 1.499, -1.160]),
        vq.Atom(1, [0.000, -1.499, -1.160]),
    ],
)

result = vq.run_job(mol, basis="cc-pvdz", method="ccsd(t)", output="h2o_ccsd_t")
print(result.ccsd.e_ccsd_correlation)
print(result.ccsd.e_t)
print(result.energy_total)

run_job writes the usual .out / citation sidecars and attaches the post-SCF result as result.ccsd.

Triples selector

The high-level driver accepts a triples= selector for the perturbative triples mode:

vq.run_job(mol, basis="cc-pvdz", method="ccsd", triples="none")
vq.run_job(mol, basis="cc-pvdz", method="ccsd", triples="(t)")

method="ccsd(t)" is equivalent to method="ccsd", triples="(t)". Passing triples="none" disables the perturbative correction even when the method keyword is ccsd(t), and the output / citation method label follows the effective choice.

The selector recognizes the planned variants A-CCSD(T), CCSD[T], and CCSD+T(CCSD) so unsupported inputs fail with a clear NotImplementedError. The current numerical kernel implements plain CCSD and the standard Raghavachari (T) correction only.

AutoCI-style selector

run_job also accepts the shared citype= spelling planned for the single-reference CI/CC ladder:

vq.run_job(mol, basis="sto-3g", method="ci", citype="cisd")
vq.run_job(mol, basis="cc-pvdz", method="ci", citype="ccsd(t)")

Supported values are cisd, ccsd, and ccsd(t). The selector recognizes roadmap names such as ccd, qcisd, and cepa(0), but raises NotImplementedError until those kernels land.

For CISD, pass cisd_options=vq.CISDOptions(nroots=..., max_det=...) to request multiple roots or raise the determinant-space guard.

Low-level API

Use the low-level API when you already have a converged RHF reference or need explicit iteration controls:

import vibeqc as vq

basis = vq.BasisSet(mol, "cc-pvdz")
hf = vq.run_rhf(mol, basis, vq.RHFOptions())

opts = vq.CCSDOptions(
    triples="(t)",
    n_frozen_core=vq.chemical_core_orbital_count(mol),
    conv_tol_energy=1e-10,
    conv_tol_residual=1e-9,
)
cc = vq.run_ccsd(mol, basis, hf, opts)
print(cc.e_ccsd_t)

If opts.aux_basis is empty and density_fit=True, run_ccsd auto-resolves the matching RI auxiliary basis for the orbital basis. The legacy boolean compute_triples remains supported on CCSDOptions; the triples property is the human-readable front end to the same setting.

Result Fields

CCSDResult exposes:

  • e_hf

  • e_ccsd_correlation

  • e_ccsd

  • e_t

  • e_ccsd_t

  • e_total

  • n_iter, converged

  • t1_norm, t2_norm

  • cc_trace

The per-iteration cc_trace entries are CCSDIteration records with energy, energy change, residual norms, and the active DIIS subspace.

Limits

The current canonical engine is deliberately conservative:

  • RHF closed-shell references only.

  • Dense pilot implementation for small molecules.

  • Density fitting is the supported production path.

  • Frozen occupied cores are supported; frozen virtuals are not.

  • UHF-CCSD and the nonstandard triples variants remain roadmap items.