Left states, densities, response and gradients
Left ground and excited states
Ground-state CC and EOM similarity-transformed Hamiltonians are non-Hermitian. Left states are needed for many corrections and response quantities, even though a right-state energy can be obtained without them.
from ccpy import LeftCCSD, LeftEOMCCSD
left_ground = cc.left.ensure_solved() # or LeftCCSD(cc).solve()
Lambda = left_ground.L
left_excited = eom.left.ensure_solved() # or LeftEOMCCSD(eom).solve()
left_vectors = left_excited.L
print(left_excited.omega, left_excited.LR)
LeftCCSD can start directly from SCF to create CCSD automatically.
LeftCCSDT and LeftCC3 use their corresponding ground-state defaults.
LeftCCSDT_P requires an upstream selected-triples CC method with its lists.
left.energy() returns the associated right-state energy; it is not a new
independent variational energy.
Exported excited left classes are LeftEOMCCSD, LeftEOMCCSDT,
LeftEOMCCSDT_P, LeftEOMCCSDTA, LeftIPEOM2, LeftIPEOM3,
LeftIPEOM3_P, LeftEAEOM2, LeftEAEOM3 and LeftEAEOM3_P.
They require an upstream EOM object. solver="davidson" is the default;
solver="jacobi" selects the left Jacobi route when the kernel supports it.
The wrapper normalizes each left vector to its paired right vector using the
sector’s overlap function. LR records the overlap before this rescaling;
inspect the printed right/left eigenvalue difference and converged as well.
Not every right method has a corresponding left implementation.
cc.left or eom.left raises NotImplementedError where the class does
not name a left method. Availability is listed in Complete methods API catalog; an inherited
base method such as rdm1 does not guarantee a density implementation at every
level.
CCSD densities and their frame
rdm1 = cc.rdm1() # solves CCSD and its Lambda state if necessary
rdm2 = cc.rdm2()
rdm2_slice = cc.left.rdm2_vvvv_slice(a=0, spin="a")
These CCSD densities are unrelaxed derivative densities in the T1-transformed
frame, conjugate to the stored Fock/two-body blocks of H(T1). They are not a
ready-made AO total-state RDM obtained by simply sandwiching a conventional MO
density with the SCF coefficients. The determinant contribution is separate,
and the full vvvv block is supplied by slices rather than stored densely.
Consult ccpy.density.ccsd_rdm before contracting these with operators or
using them in orbital optimizations.
ADC virtual_density(root=...) instead returns spin-resolved virtual blocks
of its unrelaxed second-order ISR state density, normalized from the full
reconstructed eigenvector. Those blocks are appropriate for ADC-FNO selection.
They are not full state RDMs, transition moments or oscillator strengths.
Ordinary STEOM returned singles likewise are not full property wavefunctions.
Relaxed moments and vibrational intensities
multipole_moments and gradient_and_dipole now use the relaxed analytic
gradient densities. The native Hessian helpers can differentiate dipoles and
compute harmonic IR intensities. See Multipole moments and harmonic IR intensities for units, nuclear signs,
combined gradient/property returns and a finite-field energy recipe for methods
without an analytic property path. These relaxed property helpers are distinct
from the unrelaxed T1-frame density getters above.
One-body operators and LRCCSD
LRCCSD accepts a first-order Integral operator in the same working
basis as its reference. property() returns the correlation contribution;
energy() returns the unperturbed ground CC energy.
from ccpy import LRCCSD
from ccpy.interfaces.scf_tools import get_multipole_integral
dipole_operators, reference_dipole = get_multipole_integral(1, cc.reference)
response = LRCCSD(cc, dipole_operators[2]) # z component
correlation_contribution = response.property()
total_component = reference_dipole[2] + correlation_contribution
print(response.T1) # first-order perturbed amplitudes, not the ground T1
get_multipole_integral returns positive position operators and their
electronic reference expectations, without nuclear moments or the electronic
charge sign. The example total is therefore an electronic position expectation;
for a physical dipole in atomic units use the nuclear charge-weighted positions
minus that electronic expectation. Higher multipoles need their corresponding
charge/sign and tensor conventions. For a custom
scalar AO operator:
operator = cc.reference.one_body_operator_from_ao(ao_matrix)
correlation_contribution = LRCCSD(cc, operator).property()
one_body_from_ao returns spin-resolved working matrices and can handle
leading component axes. one_body_operator_from_ao wraps a single scalar
matrix as a reference-bound Integral suitable for LRCCSD. The LR wrapper
checks spin block shapes, finiteness, reality and an operator’s reference
binding. Full-space operators must be rebuilt after FNO preparation; identical
dimensions alone do not prove that two MO bases are the same.
LRCCSD currently uses materialized equations and a legacy CCSD HBar. It is a first-order one-body property interface, not a general frequency-dependent response/absorption API. FNO energy completion does not add the missing-space contribution to densities or properties.
Gradients and finite differences
For the complete derivative guide and availability table, see Analytic gradients and finite differences. For pysisyphus minima, transition-state searches, frequencies and two-sided IRC validation, see Geometry optimization, transition states and IRC validation. Harmonic frequencies and normal modes are covered in Computing vibrational frequencies.
energy, gradient = cc.energy_and_gradient()
available = cc.has_analytic_gradient()
numerical = cc.fd_gradient()
gradient has shape (natoms, 3) and units Eh/bohr. It selects an analytic
kernel when the method and reference pass has_analytic_gradient; otherwise
it differentiates energy() with central finite differences. fd_step
(default 1e-3 bohr) and fd_npoints (default 4) control the stencil. To choose
finite differences explicitly, call fd_gradient; there is no general
gradient(analytic=False) switch.
The wrapper names analytic kernels for CCSD, EOMCCSD, CRCC23 variant A and
CREOMCC23 variant A. CCSDT(P) additionally checks availability of its selected
CC density module. Correction variants other than those explicitly supported,
stochastic correction instances, ROHF references, deleted virtuals and FNO
references use finite differences. These are dispatch conditions, not a claim
that every installed analytic kernel works for every physical case. Inspect
has_analytic_gradient on the actual object; a module import/runtime failure
inside an advertised kernel is not automatically converted to finite differences.
eom_total, excited_gradient = eom.energy_and_gradient(root=0)
fd_excited = eom.fd_gradient(root=0)
root is the returned-state index. The left and response quantities required
by analytic gradients are created on demand. zvector_tol is accepted by
analytic routes where applicable; numerical gradients instead use the method’s
finite-difference controls.
Geometry reconstruction
import numpy as np
xyz_bohr = np.array([xyz for _, xyz in cc.molecule.atoms])
xyz_bohr[1, 2] += 0.01
moved_molecule = cc.molecule.with_geometry(xyz_bohr, unit="bohr")
moved = cc.at_geometry(moved_molecule)
moved_total = moved.energy()
at_geometry reconstructs the recorded constructor chain, SCF type, reference
partition and guess setup. It is a new calculation, not a transfer of converged
orbitals/amplitudes or a persistent restart. FNO bases and low-level completion
are rebuilt at each geometry. AdaptiveCCPQ reuses recorded selected P spaces
for geometry copies. In general, discrete determinant spaces, symmetry changes,
occupation cutoffs and root crossings can make the numerical energy surface
nonsmooth; check state identity and threshold stability for derivatives.
Use Molecule.with_geometry’s explicit unit when supplying arrays from
external geometry packages. The native molecule stores Cartesian coordinates
in bohr, even if the original input was angstrom.