Solver controls, diagnostics and custom calculations

Shared correlated-method options

Pass options as constructor keywords. Unknown keywords are rejected, which helps catch legacy Driver spellings accidentally used with this API.

from ccpy import CCSD, EOMCCSD

cc = CCSD(mf, nfrozen=1, maximum_iterations=120,
          amp_convergence=1.e-8, energy_convergence=1.e-9,
          diis_size=8, denominator="mp", energy_shift=0.)
eom = EOMCCSD(cc, davidson_max_subspace_size=40,
              davidson_selection_method="overlap")
Defaults in MethodBase

Option

Default

Meaning

maximum_iterations

80

Iteration limit for iterative solvers; ADC applies it to inner/outer loops.

amp_convergence

1e-7

Residual/amplitude convergence tolerance.

energy_convergence

1e-7

Energy/eigenvalue change tolerance, in hartree.

energy_shift

0.0

Shift used by kernels that support shifted iterative denominators.

denominator

"mp"

Ground-CC update denominator scheme; supported schemes depend on the level.

diis_size

6

DIIS history; ground CC uses -1 to disable DIIS.

diis_out_of_core

False

Disk storage for DIIS vectors in solvers that implement it.

RHF_symmetry

None

Automatic closed-shell spin-block shortcut; not the spatial symmetry switch.

amp_print_threshold

0.09

Threshold for amplitude printing, not amplitude truncation.

davidson_max_subspace_size

30

Maximum Davidson basis size before restarting.

davidson_solver

"standard"

Standard sequential EOM or "multiroot" block EOM; ADC supports standard only.

davidson_selection_method

"overlap"

Ritz selection by starting-vector overlap or "energy" proximity.

davidson_out_of_core

False

Disk-backed Davidson vectors where supported.

fd_step

1e-3

Finite-difference displacement, bohr.

fd_npoints

4

Central finite-difference stencil size (2, 4 or 6).

The wrapper automatically disables ground DIIS on very small spaces when no explicit history size was given. SCF has separate defaults and uses diis_size=0 to disable SCF DIIS. Shared option names do not imply that every kernel uses every option. EOMCC3 is nonlinear DIIS; STEOM has separate auxiliary and final solvers; MBPT is noniterative.

CCSD, CCSDT and CCSDT_P accept denominator="mp", "epstein-nesbet", "quasilinear" or "newton" in their ground-state updates. Other levels default to MP and reject unsupported schemes. These select iterative updates/preconditioning; they are not interchangeable with correction variant A/B/C/D or ADC’s perturbation partition.

Convergence and result inspection

energy = cc.energy()
print(cc.converged, cc.version, cc.is_current())
print(cc.reference_energy, cc.correlation_energy)
print(cc.T.a.shape, cc.T.ab.shape)

totals = eom.energy()
print(eom.root_converged, eom.root_irreps, eom.omega)
print(eom.guess_energy, eom.guess_irreps)

Do not infer convergence from the fact that energy() returned a number. Most CC/EOM wrappers preserve convergence flags even on failure, and some can return the last iterate. ADC and STEOM have additional fail-fast checks. For repeated or suspicious EOM roots, inspect state amplitudes and overlap, not just energy ordering. Tightening only the downstream tolerance does not resolve an unconverged or inaccurate upstream CC calculation.

To restart ground CC from its current amplitudes:

cc.options["maximum_iterations"] = 160
cc.options["amp_convergence"] = 1.e-9
cc.converged = False
cc.solve()

An explicit solve() also reruns without setting converged=False. Dependency tracking is version based; arbitrary in-place changes to T, orbital matrices or dictionaries are not automatically detected. After changing amplitudes or options, explicitly solve the affected upstream object before requesting downstream results. After changing orbitals, build a consistent reference and chain rather than mutating a live calculation’s basis.

Flexible combinations and HBar choices

from ccpy import CCSD, EOMCCSD, HBarCCSD, HBarCCSDLegacy

cc = CCSD(mf, nfrozen=1)
factorized = cc.get_hbar(HBarCCSD)
materialized = cc.get_hbar(HBarCCSDLegacy)
custom_eom = EOMCCSD(cc, hbar_class=HBarCCSD)

get_hbar ensures the parent is solved and returns a built HBar wrapper; its actual integral object is .H and its associated amplitudes are .T. Available HBars include HBarCC2, HBarCC3, HBarCCSD, HBarCCSDLegacy, HBarCCSDT, HBarCCSDT1, HBarCCSDTA and HBarCCSDT_P. Use the HBar specified by the scientific model. Different HBar classes may require amplitudes of different rank or selected lists; construction is not a generic type-compatibility proof.

For ordinary runs, use the method’s default HBar and left class. Advanced combinations are useful when deliberately defining an approximation, but should be tested against a standard chain or independent oracle. Reusing a CCSD parent in a higher-rank EOM class does not automatically supply converged CCSDT amplitudes. A correction object is not a replacement right-state wavefunction: building EOM on it generally reuses its underlying CC method, not a fictitious corrected T operator.

Implementing another method level

A ground-state CC level can subclass CCBase and select its equation module, operator order, HBar and left class. The module must provide the update protocol expected by the chosen solver; inspect a nearby implementation before adding one. A minimal definition is:

from ccpy.methods.cc import CCBase
from ccpy.methods.hbar import HBarCCSD

class MyCCLevel(CCBase):
    module = "my_package.my_cc_equations"
    order = 2
    hbar_class = HBarCCSD
    left_class = None
    requires_df_port = True

This is a protocol sketch; it cannot run until the named update module exists. Declare requires_df_port truthfully. DF references prohibit accidental full vvvv access by default; a legacy kernel needs materialization or a proper DF port. If the model has a gradient, name gradient_module and gradient_function and implement the correct scheme-specific invocation.

An EOM level chooses the relevant EE/SF/Fock base, module containing HR and update, parent/HBar classes and operator dimensions. Selected-space levels also need their list keys, spin conventions and solver extra arguments. Override _guess_arguments only when the new method requires a different Hamiltonian/guess protocol, as ADC and STEOM do. InitialGuessMixin owns spin/irrep/root configuration; avoid inventing an incompatible root numbering scheme for a new family.

FNO preparation belongs to MethodBase/Reference. New correlation kernels should use the ordinary working dimensions and remain unaware of the original virtual count. Apply composite energy shifts at reporting boundaries, not inside CC/EOM residuals or iterative denominators. A new low-level FNO model can use the provider contract in FNOs, active spaces and selected determinants and Frozen natural orbitals.

Troubleshooting common setup mistakes

Symptoms and next checks

Symptom

Check

Expected native SCF object

Use CCpy RHF/ROHF/UHF; PySCF objects belong to the legacy interface.

Unknown option

Check constructor signature; do not use Driver option names such as nact_occupied in initial_guess.

Call initial_guess before solving

Ordinary EOM/ADC need a configured guess pool and root selection.

Missing irrep or unavailable root

Inspect point group, guess dimensions, active counts, spin and actual guess_irreps.

Conflicting nfrozen / FNO settings

Start a fresh chain from SCF/full Reference instead of changing a shared basis downstream.

Selected list exceeds dimensions

Regenerate after FNO preparation; use one-based particle-first rows.

Property operator belongs to another reference

Transform the AO operator with the current reference.

Folded ADC pole / no primary character

Select formulation=”full” and suitable CISd guesses for the target.

DFPortWarning / unexpected memory use

The selected method materializes four-index equations; inspect the catalog/registry.

Repeated EOM states

Check overlaps/character, enlarge or change guesses, and consider multiroot where supported.

Unexpected FNO gap correction

Ground completion cancels from gaps; state-specific ADC completion needs matching targets.

Expensive gradient

Inspect has_analytic_gradient(); FNO and unsupported reference/variant combinations use finite differences.