Multipole moments and harmonic IR intensities
The derivative-density machinery now supplies relaxed state multipole moments and combined nuclear gradients/dipoles. Differences of the dipoles along nuclear displacements give an atomic polar tensor and double-harmonic IR intensities. This chapter distinguishes static moments, electronic energy perturbations and vibrational intensities; none is automatically an electronic transition strength or a Raman spectrum.
Analytic property derivatives
For an electronic one-body perturbation
V is a real AO matrix (nao,nao) or component stack
(ncomp,nao,nao). The analytic gradient kernels use orbital-relaxed density
and response information for this derivative as well as for nuclear gradients.
The operator holds the nuclei and AO basis positions fixed during the field
variation.
from ccpy import Molecule, RHF, CCSD
from ccpy.gradients.derivative_integrals import multipole_integrals
mol = Molecule("O 0 .05 .1173; H 0 .7572 -.4692; H .1 -.7572 -.4692",
"sto-3g", auxiliary_basis="def2-universal-jkfit", symmetry=False)
cc = CCSD(RHF(mol, verbose=0, e_tol=1.e-12, d_tol=1.e-10), nfrozen=1,
amp_convergence=1.e-10, energy_convergence=1.e-12)
labels, V = multipole_integrals(mol, order=2, origin=(0., 0., 0.))
derivatives = cc.gradient(perturbation=V) # (ncomp,), electronic dE/dlambda
nuclear_gradient, derivatives = cc.gradient(properties=V)
The three forms of gradient have different returns:
gradient(): nuclear gradient(natoms,3), Eh/bohr.gradient(perturbation=V): property derivatives(ncomp,).gradient(properties=V):(nuclear_gradient, property_derivatives)from one analytic response calculation.
Use properties= on gradient, not energy_and_gradient: the latter
passes kwargs to energy as well, and property-integral kwargs are not energy
arguments. Use either perturbation or properties according to the desired
return. For EOM or an excited correction, pass root=... to select one
returned state. Matching the energy variant matters, e.g. CRCC23/CREOMCC23
analytic property paths are available for variant A under their normal
reference restrictions. See Analytic gradients and finite differences for eligibility and convergence.
State moments, units and origin
moments = cc.multipole_moments(order=3, origin=(0.1, -0.2, 0.3))
print(moments["x"], moments["xy"], moments["xyz"])
gradient, dipole = cc.gradient_and_dipole() # dipole (3,), ordered x,y,z
multipole_moments returns a dictionary of all Cartesian moments through
order: 3 dipole components for order 1; those plus 6 quadrupole components
for order 2; those plus 10 octupole components for order 3. origin is in
bohr and defaults to the coordinate origin. Keys follow
x,y,z,xx,xy,xz,yy,yz,zz,xxx,xxy,xxz,xyy,xyz,xzz,yyy,yyz,yzz,zzz.
These are primitive Cartesian charge moments, not traceless tensors or
spherical multipoles, with units e bohr, e bohr squared and e bohr cubed.
The helper returns the total physical charge moment, nuclear minus the electronic position-moment derivative:
Do not negate or add the nuclear part again. By comparison,
get_multipole_integral used by LRCC returns positive position operators and
an electronic reference expectation; that is a different return convention.
Charged dipoles depend on the origin, and higher moments generally do too.
Neutral dipoles are origin invariant. Keep a fixed origin when differentiating
moments across geometries.
gradient_and_dipole uses the coordinate origin and returns no energy.
Its kwargs select gradient options such as an electronic root; it does not
expose an origin argument. For a custom origin build V explicitly and use
gradient(properties=V) plus the charge-moment conversion helper.
Analytic convenience versus a generic finite-field route
The convenience methods above currently call gradient with a property
request. When no analytic property gradient is available,
gradient(perturbation=...) and gradient(properties=...) raise
NotImplementedError; they do not automatically differentiate energies
with respect to fields. This includes methods with a numerical nuclear-gradient
fallback. The existence of a nuclear finite-difference gradient does not itself
provide a finite-field moment.
For any method for which a consistent scalar energy can be rebuilt in a field,
the finite-field route is available: recompute SCF and the complete correlated
calculation for each strength, differentiate the electronic total energy and
add the nuclear moment with the helper above. A runnable example callback,
finite_field_moments, is provided in
examples/methods_api/multipole_ir.py. It is an example function rather than
an additional exported MethodBase method:
import numpy as np
from ccpy.gradients.derivative_integrals import multipole_integrals, multipole_moments
from ccpy.gradients.finite_difference import finite_difference
def finite_field_moments(molecule, scalar_energy, order=1, origin=None, field_step=1.e-3):
labels, operators = multipole_integrals(molecule, order=order, origin=origin)
xyz = np.array([xyz for _, xyz in molecule.atoms])
def energy_in_field(strengths):
field_molecule = molecule.with_geometry(xyz, unit="bohr")
h = field_molecule.ints_hcore() + np.einsum("k,kmn->mn", strengths, operators)
field_molecule.ints_hcore = lambda: h
return scalar_energy(field_molecule) # create fresh SCF and correlation here
dE = finite_difference(energy_in_field, np.zeros(len(labels)),
step=field_step, npoints=4)
return multipole_moments(dE, molecule, order=order, origin=origin)
For instance scalar_energy can instantiate MP2 or another energy-only
method on RHF(field_molecule) and return its energy(). An excited
callback must configure guesses and return energy(root=...) for the chosen
physical state. Do not reuse a zero-field solved reference or merely perturb
integrals after SCF: orbital relaxation requires re-solving SCF in every field.
Construct the field on each fresh molecule; an arbitrary monkey-patched
ints_hcore is not automatically preserved by MethodBase.at_geometry.
Field strengths are in atomic units conjugate to the selected operator. Check field-step and electronic-tolerance convergence; cancellation amplifies energy noise. If FNOs, CIM or selected spaces are used, ensure consistent energy completion, fixed domains/selections as appropriate and smooth state tracking. The analytic helpers retain their existing reference/variant limitations; this finite-field recipe is the general scalar-energy path, not a claim that every method/reference combination is already validated.
Compute frequencies and IR intensities together
Use the native Hessian/vibrational helpers with an optimized molecule:
from ccpy.gradients.hessian import vibrational_analysis
optimized = minimum.molecule # from a converged, consistently defined optimization
def gradient_and_dipole_at(molecule):
method = cc.at_geometry(molecule)
g, mu = method.gradient_and_dipole()
if not (method.converged and method.reference.scf.converged):
raise RuntimeError("Unconverged displaced calculation")
return g, mu
result = vibrational_analysis(optimized, gradient=gradient_and_dipole_at,
dipole=True, step=2.5e-3)
print(result["frequencies"]) # cm^-1
print(result["ir_intensities"]) # km/mol, same mode ordering
print(result["atomic_polar_tensor"].shape) # (3,3*natoms)
With dipole=True the callback must return (gradient,dipole) or
(energy,gradient,dipole). Supplying the ordinary (energy,gradient) pair
has the wrong meaning. The dipole must be the total physical dipole including
the nuclear contribution, in atomic units, not an electronic position vector.
With dipole=False, the ordinary gradient or (energy,gradient) callback
remains valid. dipole=True requires a callback providing dipoles;
energy=... alone cannot supply intensities automatically.
The same +/- nuclear displacements give the Hessian and atomic polar tensor
IR intensity is proportional to the squared norm of this mode dipole derivative
and is converted to km/mol. The code uses mass-normalized vibrational
coordinates for this contraction; do not contract P (units e) with the separately
Euclidean-normalized display modes without restoring their normalization.
For a charge q, the translational sum rule is
sum_A P[a,A,b] = q*delta[a,b]. This is a useful sign/nuclear-term diagnostic,
subject to finite-difference error.
All Hessians here are numerical derivatives, even when the gradient and dipole
at each displacement are analytic. A generic numerical callback can instead
return a finite-difference nuclear gradient and a finite-field total dipole.
The shipped --mode finite-field example implements that construction for
MP2 as well as CCSD/CRCC23_A. It costs many more energy evaluations; there are
separate nuclear-gradient, field and Hessian step sizes to converge. Finite
fields on the existing analytic nuclear gradient are not a substitute: moving
AO multipole operators require additional nuclear derivative terms that the
ordinary field-free gradient contraction does not add automatically.
Saved tensors, isotope reanalysis and intensity scope
To separate derivative generation from harmonic analysis:
from ccpy.gradients.hessian import fd_hessian, harmonic_analysis
H, P = fd_hessian(optimized, gradient=gradient_and_dipole_at,
dipole=True, step=2.5e-3)
result = harmonic_analysis(H, optimized, dipole_derivatives=P)
np.savez("vibrations_ir.npz", **result, hessian=H, atomic_polar_tensor=P)
harmonic_analysis accepts an optional masses array in amu for isotope
substitution. Recompute both frequencies and intensities from the same H/P
with the new masses; no new electronic derivatives are needed within this
harmonic Born-Oppenheimer treatment. Native default masses are the most
abundant isotopes through Kr, with a fallback atomic mass beyond that table;
this can differ slightly from external pysisyphus mass-table defaults.
Native results contain normal_modes with shape (nvib,natoms,3),
reduced_masses (amu), force_constants (mdyn/angstrom), eigenvalues
(Eh/(bohr squared amu)), and zpe (Eh, positive real modes only), as well
as frequencies. With dipoles they also contain mode dipole_derivatives
(nvib,3) in e/sqrt(amu) and ir_intensities. The convenience
vibrational_analysis additionally stores hessian and
atomic_polar_tensor. Native mode arrays differ in layout from pysisyphus’
column-vector return, documented in Computing vibrational frequencies.
The implemented intensities are electric-dipole, double-harmonic vibrational IR intensities. Higher Cartesian moments can be computed but do not by themselves provide quadrupole/octupole absorption intensities, Raman activities or electronic transition oscillator strengths. No anharmonic corrections or spectral line broadening are implied. Do not interpret a TS imaginary mode as an ordinary absorption line.
Run the examples and inspect validation
python examples/methods_api/multipole_ir.py --task moments --method ccsd --order 3 \
--mode analytic --out-dir analytic-moments
python examples/methods_api/multipole_ir.py --task ir --method ccsd \
--mode analytic --out-dir ccsd-ir
python examples/methods_api/multipole_ir.py --task ir --method mp2 \
--mode finite-field --out-dir mp2-ir
The IR tasks first optimize the demonstration water molecule and save
summary.json and harmonic_ir.npz. These use a small default basis to
illustrate the interface; basis, step-size and electronic-model convergence
remain necessary for quantitative spectra. Existing checks in
test_property_gradients.py compare relaxed derivatives against finite-field
energies, and test_ir_intensities.py checks the atomic polar tensor against
energy derivatives, charge sum rules and CO2 IR selection rules. These checks
cover particular references and methods, not all possible method combinations.