Molecules, references and composing calculations

Geometry, integrals and SCF

from ccpy import Molecule, RHF, ROHF, UHF, Reference

mol = Molecule(
    "O 0 0 0; H 0 0 .97", "cc-pvdz",
    auxiliary_basis="cc-pvdz-rifit",
    charge=0, multiplicity=2, unit="angstrom", symmetry=True,
)
mf = ROHF(mol, e_tol=1.e-10, d_tol=1.e-8, maxiter=150)
mf.run()
assert mf.converged
ref = Reference(mf, nfrozen=1)
print(ref.system.point_group, ref.system.reference_symmetry)
print(ref.system.orbital_symmetries)

Molecule accepts semicolon/newline XYZ or Z-matrix text. basis and auxiliary_basis can be names, basis files, or per-atom dictionaries, e.g. {"O": "cc-pvtz", "default": "cc-pvdz"}. With a string orbital basis, omitting the auxiliary basis selects <basis>-autoaux. Supply an auxiliary basis explicitly with a dictionary orbital basis. cartesian=False uses spherical functions. overlap_tol controls removal of AO linear dependencies; df_metric_tol optionally controls DF metric orthogonalization. df_direct=True makes SCF Coulomb/exchange builds and SCF gradients recompute the three-center integrals instead of storing the B tensor (the default switches to this when B would exceed 4 GB); correlated methods still build B when they need it.

cholesky_tei=True, cholesky_tol=1.e-6 selects pivoted AO Cholesky instead of auxiliary-basis fitting. The correlated interfaces still receive three-index factors. Auxiliary basis and Cholesky thresholds affect the Hamiltonian itself; they are independent of the later FNO occupation cutoff.

Choose RHF for closed-shell restricted orbitals, ROHF for a common restricted open-shell spatial basis, or UHF for independent alpha/beta orbitals. Molecular multiplicity describes the reference determinant, not the target EOM spin. Native SCF accepts guess="minao" (default) or "hcore", diis_size, diis_start, level_shift and level_shift_thresh. UHF accepts a pair of spin-specific level shifts. SCF uses maxiter/e_tol/d_tol; correlated methods use maximum_iterations/energy_convergence/amp_convergence.

With symmetry enabled, SCF can accept target_symmetry or irrep_occupations={irrep: electrons} / {irrep: (nalpha, nbeta)}. Unlisted irreps in an occupation dictionary are left empty. These configure the reference occupations; they are not EOM root selections. Inspect the detected point group and orbital labels rather than assuming a particular orientation and irrep assignment.

RHF, UHF, RKS and UKS switch from DIIS to the trust-region augmented Hessian (TRAH) second-order solver when DIIS stalls after trah_after=15 iterations; trah_after=0 uses TRAH from the start and None disables it (ROHF always uses DIIS). mf.stability() returns the lowest orbital-Hessian eigenvalues and the SCF object; external=True tests a restricted solution for RHF -> UHF (RKS -> UKS) instability, and follow=True rotates along a negative mode and reconverges, returning the new unrestricted object in the external case. Only rotations that preserve the point-group symmetry are tested, so run with symmetry=False to find symmetry-breaking solutions.

Kohn-Sham DFT uses the same options plus the functional name (any libxc functional, through PySCF’s bundled libxc) and the grid:

from ccpy import RKS, UKS

mf = RKS(mol, xc="wb97x")        # LDA, GGA, meta-GGA, hybrid, range-separated
mf.kernel()
grad = mf.gradient()             # analytic, without grid-weight derivatives

The default grid is PySCF’s level 3 (Treutler-Ahlrichs radial, Lebedev angular, Becke partitioning, NWChem pruning); grid=(nradial, nangular) sets one grid for all atoms and prune=False disables pruning. VV10 nonlocal correlation and Laplacian-dependent meta-GGAs are not implemented.

Reference currently accepts native SCFBase objects, not PySCF SCF objects. The older Driver.from_pyscf workflow is separate. Reference creation runs SCF when e_tot is absent and checks the determinant energy against the DF Hamiltonian. It warns if explicitly given an unconverged SCF; verify mf.converged before trusting correlated results.

Frozen core and working orbitals

nfrozen counts lowest core spatial orbitals removed from correlation in both spins. ndelete deletes highest virtuals; it is a fixed orbital deletion, with no automatic missing-space correction. These partition settings belong to the reference. The determinant energy still contains the frozen electrons.

from ccpy import CCSD, EOMCCSD

ref = Reference(mf, nfrozen=1)
cc = CCSD(ref)
eom = EOMCCSD(cc)
assert eom.reference is cc.reference

Do not change nfrozen or ndelete downstream. An explicitly conflicting value raises an error. Start a new chain from SCF or another full reference for a different partition. FNO selection also creates a new working basis; see FNOs, active spaces and selected determinants before constructing orbital-indexed inputs.

The working dimensions are system.noccupied_alpha, system.noccupied_beta, system.nunoccupied_alpha and system.nunoccupied_beta. Frozen/deleted orbitals are excluded. Under FNO, these are already the reduced dimensions; equation kernels do not carry a second full-space dimension.

Short form and explicit composition

from ccpy import CCSD, CRCC23, LeftCCSD, EOMCCSD, CREOMCC23

# Out of the box: creates CCSD, the required HBar and Lambda automatically.
result = CRCC23(mf, nfrozen=1, variant="D").energy()

# Explicit reusable chain.
cc = CCSD(mf, nfrozen=1)
cc.energy()
hbar = cc.hbar                   # builds on demand
left = cc.left.ensure_solved()   # LeftCCSD
correction = CRCC23(left, variant="D")
result_again = correction.energy()

eom = EOMCCSD(cc)
eom.initial_guess(method="cis", multiplicity=2,
                  roots_per_irrep={ref.system.reference_symmetry: 1})
totals = eom.energy()
corrected_totals = CREOMCC23(eom, variant="D").energy()

The example above uses the open-shell reference of this chapter, hence target multiplicity 2. Closed-shell singlet examples elsewhere use multiplicity 1. Excited-state corrections require an EOM or left-EOM object; they cannot infer target states from SCF alone. Left-EOM methods also require an EOM object.

Passing an existing method with .cc generally reuses that CC object. It does not automatically replace it with the new method’s nominal default CC level. For example, an EOM class whose default parent is CCSDT will reuse an explicitly supplied CC object. This makes custom equation/HBar combinations possible, but the caller must choose a scientifically compatible parent and amplitudes. Use Complete methods API catalog to see the standard dependencies and Excitation, attachment, ionization, ADC and STEOM for known standard chains.

hbar_class=... deliberately overrides the EOM similarity-transformed Hamiltonian. It is useful for CCSD(T)(a)* chains, not an instruction to perform an arbitrary missing ground-state calculation. HBars are cached by class; building a legacy HBar does not overwrite the cached DF HBar or bare integrals.

Options and restart ownership

Explicit solver options propagate into automatically created dependencies. When a method is built on another method, its explicit solver settings are inherited unless overridden locally. Inheriting a tolerance does not mutate an already existing upstream object; configure that object directly if it also needs tighter convergence. RHF_symmetry is recomputed from the reference rather than blindly inherited, and EOM/left wrappers adjust it for their spin sector.

Repeated energy() calls use cached results. solve() explicitly reruns and increments version. Ground CC restarts from its current T. Downstream objects track versions of their dependencies and rebuild stale HBars, guesses, left states and corrections. If changing a solver option in options after convergence, explicitly call solve() or mark the method unconverged; changing a dictionary entry alone is not a new dependency version. There is no general persistent disk checkpoint/restart API in this layer. Out-of-core solver files are working storage, not durable checkpoints.