The methods API: a calculation guide
This guide describes the object-oriented API exported by ccpy.methods and
re-exported by ccpy. It covers the implementation in this checkout, including
native DF-SCF, FNO preparation, ADC, EOMCC and STEOM. The older Driver.run_*
interface remains available, but its method strings, option names and state
indices must not be mixed with the interface described here.
Start with Molecules, references and composing calculations, choose a method from Ground states and energy corrections or Excitation, attachment, ionization, ADC and STEOM, then use Initial guesses, symmetry and choosing roots to select excited roots. FNOs, active spaces and selected determinants explains frozen cores, FNOs and selected determinants; Left states, densities, response and gradients covers left states, densities and response. Multipole moments and harmonic IR intensities covers relaxed moments and IR intensities, and Cluster-in-molecule local correlation explains the experimental local-correlation wrappers. Analytic gradients and finite differences details analytic and numerical derivatives; Geometry optimization, transition states and IRC validation covers minima, transition states and two-sided IRC validation through pysisyphus. Computing vibrational frequencies gives the full harmonic vibrational analysis workflow. Solver controls, diagnostics and custom calculations documents solver controls, restarts and extending the API. Complete methods API catalog lists every exported class and its actual constructor, dependencies and equation implementation.
- Molecules, references and composing calculations
- Ground states and energy corrections
- Excitation, attachment, ionization, ADC and STEOM
- Initial guesses, symmetry and choosing roots
- FNOs, active spaces and selected determinants
- Three different reductions
- Enable DF-MP2 FNOs at the start of a chain
- Automatic composite energy completion
- State-specific ADC-FNOs
- Multiple targets and root identities
- Protected orbitals and reference inspection
- Active and selected spaces after FNO preparation
- Custom FNO providers
- External determinant-space readers
- Cluster-in-molecule local correlation
- Left states, densities, response and gradients
- Multipole moments and harmonic IR intensities
- Analytic gradients and finite differences
- Geometry optimization, transition states and IRC validation
- Installation and units
- Minimize an electronic method directly
- Use a callback for custom calculations
- Optimization controls and result fields
- Hessian evaluation and cost
- Find a transition state
- Projected vibrational analysis
- Run both IRC branches with run_irc
- Optimize and validate the endpoints
- Electronic excited states and custom surfaces
- Runnable end-to-end examples
- Validation of the shipped example
- External documentation and version checks
- Computing vibrational frequencies
- Solver controls, diagnostics and custom calculations
- Complete methods API catalog
- Moller-Plesset perturbation theory
- Ground-state coupled cluster
- Equation-of-motion methods
- Algebraic-diagrammatic construction
- STEOM-CCSD
- Extended STEOM
- Noniterative and adaptive corrections
- Left ground and excited states
- Linear response
- State-universal multireference coupled cluster
- Similarity-transformed Hamiltonians
- References and materialization warnings
- Factorized Hamiltonian
- FNO policies, evaluations and preparation
- Experimental cluster-in-molecule local correlation
- Shared method protocol
- Preparation and registry functions
A complete first calculation
This example uses the native integrals and SCF implementation. No PySCF object is needed.
from ccpy import Molecule, RHF, CCSD, CRCC23, EOMCCSD
mol = Molecule(
"O 0 0 0; H 0 0 .96; H .93 0 -.24",
"cc-pvdz", auxiliary_basis="cc-pvdz-rifit",
)
mf = RHF(mol)
cc = CCSD(mf, nfrozen=1, amp_convergence=1.e-8,
energy_convergence=1.e-9)
ground_total = cc.energy()
corrected_ground_total = CRCC23(cc).energy()
eom = EOMCCSD(cc)
eom.initial_guess(method="cisd", multiplicity=1, nacto=2, nactu=2,
roots_per_irrep={"A": 3}, roots=[0, 2])
excited_totals = eom.energy()
print(ground_total, corrected_ground_total)
print(eom.omega, excited_totals, eom.root_converged)
With symmetry=False (the default), use the C1 irrep label "A".
All electronic energies are in hartree. Geometry input defaults to angstrom;
nuclear gradients and displacement arrays default to bohr conventions described
in Left states, densities, response and gradients.
Calling energy() triggers the required upstream calculations. Calling it
again reuses a converged, current result. Construction can itself run SCF;
FNO-enabled construction also prepares the low-level full and truncated spaces.
solve() explicitly runs the equations and returns the method object.
Inspect converged and, for excited methods, root_converged: ordinary CC/EOM
wrappers can return an unconverged iterate rather than raise an exception.
Native DF versus materialized equations
All native references start from factorized integrals. Some methods still run
four-index equations and materialize integrals, including vvvv. They issue
DFPortWarning. They can still benefit from FNO dimension reduction, but
are not fully DF implementations. Find the current class-level list with:
from ccpy import methods_requiring_df_port
print(methods_requiring_df_port())
The catalog records this flag and the underlying kernel. Instance options can
change it, notably CCP3(two_body_approx=False). A method being constructible
with a reference does not establish benchmarked accuracy or spin/reference
coverage for every equation kernel. Explicit restrictions and research-level
implementations are identified in the following chapters.
Runnable recipes and documentation maintenance
examples/methods_api/run_calculation.py provides small runnable ground,
neutral/charged EOM, ADC, FNO, selected-space, STEOM and response calculations.
Run from an installed checkout, for example:
python examples/methods_api/run_calculation.py --recipe fno --basis 6-31g
Regenerate the complete class catalog after changing API definitions:
python docs/methods/generate_catalog.py
python docs/methods/generate_catalog.py --check
The catalog is a source-derived inventory, not a claim that every possible combination has been numerically validated. The handwritten recipes explain compatible standard chains and the places where explicit choices matter.