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

\[h(\boldsymbol\lambda)=h+\sum_k\lambda_k V_k, \qquad \frac{\partial E}{\partial\lambda_k}=D_{\mathrm{relaxed}}:V_k,\]

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:

\[M_{x^a y^b z^c}=\sum_A Z_A(X_A-O_x)^a(Y_A-O_y)^b(Z_A-O_z)^c -\frac{\partial E}{\partial\lambda_{x^a y^b z^c}}.\]

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

\[P_{a,Ab}=\frac{\partial\mu_a}{\partial R_{Ab}},\qquad \frac{\partial\mu}{\partial Q_k}=P M^{-1/2}L_k.\]

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.