Computing vibrational frequencies
Harmonic vibrational frequencies come from the mass-weighted molecular
Hessian, with translations and rotations projected out. CCpy provides
Cartesian energies/gradients and the finite-difference Hessian through
make_calculator; pysisyphus performs the mass weighting, projection and
normal-mode analysis. There is no separate method-object frequencies() call or analytic
molecular Hessian exposed by this interface. CCpy also supplies native
fd_hessian, harmonic_analysis and vibrational_analysis helpers,
including IR intensities when dipoles are supplied; see Multipole moments and harmonic IR intensities.
Native frequency and IR helpers
ccpy.gradients.hessian.vibrational_analysis(molecule, energy=callback)
computes an energy-only Hessian using second differences.
vibrational_analysis(molecule, gradient=callback) instead differences the
gradient, accepting g or (E,g). With dipole=True the callback must
return (g,mu) or (E,g,mu) and native analysis additionally reports IR
intensities. These are distinct callback contracts; see Multipole moments and harmonic IR intensities for
a complete example and finite-field alternatives.
The native helper’s default step is 2.5e-3 bohr, while the pysisyphus
calculator below defaults to hessian_step=5e-3. Native results are a dictionary,
with modes shaped (nvib,natoms,3), reduced masses, force constants and a
positive-real-mode ZPE; pysisyphus returns the arrays described below. Match mass
tables and numerical steps when comparing them.
A complete optimized-geometry example
The following computes a CCSD minimum and its harmonic frequencies using native DF integrals, analytic CCSD gradients and a numerically differentiated Hessian:
import numpy as np
from ccpy import Molecule, RHF, CCSD
from ccpy.integrals.atom_data import Z_TO_ATOM_SYMBOL
from ccpy.optimize import optimize_geometry, make_calculator
from pysisyphus.Geometry import Geometry
mol = Molecule("O 0 0 .12; H 0 .80 -.47; H 0 -.78 -.45", "sto-3g",
auxiliary_basis="def2-universal-jkfit", symmetry=False)
template = 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)
minimum = optimize_geometry(template, thresh="gau_tight", verbose=False)
if not minimum.converged:
raise RuntimeError("Optimize the geometry before characterizing its vibrations")
def energy_and_gradient(molecule):
calculation = template.at_geometry(molecule)
energy, gradient = calculation.energy_and_gradient()
if not (calculation.converged and calculation.reference.scf.converged
and calculation.left.converged):
raise RuntimeError("Unconverged electronic calculation")
return float(energy), gradient
optimized = minimum.molecule
atoms = [Z_TO_ATOM_SYMBOL[int(z)] for z in optimized.atomic_charges]
xyz_bohr = np.array([xyz for _, xyz in optimized.atoms])
geom = Geometry(atoms, xyz_bohr.ravel(), coord_type="cart")
geom.set_calculator(make_calculator(optimized, energy_and_gradient,
hessian_step=5.e-3, verbose=False))
hessian = geom.cart_hessian # shape (3N,3N), Eh/bohr^2; cached on geom
frequencies, eigenvalues, mw_modes, cart_modes = geom.get_normal_modes()
print("Harmonic frequencies (cm^-1):", frequencies)
np.savetxt("frequencies_cm-1.txt", frequencies)
np.save("cartesian_hessian.npy", hessian)
np.save("cartesian_normal_modes.npy", cart_modes)
STO-3G here keeps the demonstration small; choose an appropriate basis and
converge the electronic model for scientific use. Build with symmetry=False
so displaced geometries retain their frame and atom order. Input geometry text
defaults to angstrom, but stored coordinates and pysisyphus arrays are bohr.
Use the same electronic method, frozen core, correction variant and state at
the optimization and Hessian geometries unless deliberately defining a
mixed-level protocol.
Reading the returned arrays
get_normal_modes() returns four arrays:
frequencies: signed vibrational wavenumbers in cm^-1. Negative values denote imaginary frequencies; they are not negative real vibrational energies.eigenvalues: eigenvalues of the projected mass-weighted Hessian, before conversion to wavenumbers. These are not the raw Cartesian Hessian eigenvalues.mw_modes: mass-weighted Cartesian mode vectors in columns.cart_modes: Cartesian displacement vectors in columns, each normalized to unit Euclidean norm by the external routine. Shape is(3N,nvib).
An isolated nonlinear molecule has 3N-6 vibrational modes, and a linear molecule
has 3N-5. Atomic and degenerate geometries require appropriate special handling.
Water therefore has three modes. Do not manually discard the first six values
from frequencies: rigid motions have already been projected out.
The raw hessian still has all 3N Cartesian directions.
The normal modes solve the projected version of
The routine performs the unit conversion; do not reinterpret raw Cartesian
eigenvalues as frequencies or apply a second mass weighting. In particular,
optimize_transition_state(...).hessian_eigenvalues are unweighted Cartesian
values and cannot be used directly as cm^-1 frequencies.
For a minimum, expect no significant imaginary vibrational mode. For a first-order transition state, expect exactly one, with displacement along the intended reaction coordinate. An unconverged geometry, loose electronic thresholds, an unsuitable displacement, root switching or a nonsmooth FNO selection can produce misleading negative modes. There is no universal frequency cutoff that distinguishes noise from a physical instability.
Inspect a mode displacement
k = 0 # mode column; inspect frequencies[k] first
displacement = cart_modes[:, k].reshape(-1, 3)
amplitude_bohr = 0.1
plus = optimized.with_geometry(xyz_bohr + amplitude_bohr * displacement,
unit="bohr")
minus = optimized.with_geometry(xyz_bohr - amplitude_bohr * displacement,
unit="bohr")
These are geometries displaced in opposite directions along the normalized mode for visualization or follow-up calculations. The arbitrary amplitude is not a thermal or zero-point normal-coordinate amplitude. For a TS, inspect the imaginary mode and then follow both IRC branches; see Geometry optimization, transition states and IRC validation.
Displacement size, cost and accuracy
hessian_step (default 5e-3 bohr) controls the two-point central difference
of gradients used to build the Hessian. It is independent of the optimizer’s
step size and the fd_step / fd_npoints controls used when the gradient
itself comes from displaced energies. For N atoms a complete Cartesian Hessian
requires 6N displaced gradients, plus a central energy/force request as needed.
When analytic gradients are unavailable, the resulting nested finite
differences are substantially more expensive.
Compare, for example, Hessians built using steps 5e-3 and 2.5e-3 bohr on the
same optimized geometry with equally tight electronic convergence. Create a
fresh Geometry/calculator for the second step: changing a variable after
geom.cart_hessian was cached does not recompute the Hessian. Check stability
of weak modes, not just large stretching frequencies. Symmetrization of the
computed Hessian does not remove finite-difference or electronic noise.
geom.get_normal_modes(cart_hessian=H) can analyze an explicitly supplied
Cartesian Hessian without recomputing it. To reuse the saved one:
saved_hessian = np.load("cartesian_hessian.npy")
frequencies_again, _, _, _ = geom.get_normal_modes(cart_hessian=saved_hessian)
Verify geometry, frame, atom order, shape, units and electronic surface before reusing a Hessian. A Hessian from another geometry does not characterize the current stationary point.
Isotopes and other electronic surfaces
pysisyphus selects its default atomic masses from its mass table. To request an isotope, construct another Geometry with zero-based atom-index/mass pairs:
deuterated = Geometry(atoms, xyz_bohr.ravel(), coord_type="cart",
isotopes=[(1, 2), (2, 2)])
isotope_frequencies, _, _, _ = deuterated.get_normal_modes(cart_hessian=hessian)
An integer requests an isotope mass number; a floating-point value supplies a mass directly in atomic mass units. Within the Born-Oppenheimer harmonic model, isotopic substitution changes the mass weighting, so the same electronic Cartesian Hessian can be reused. Recompute the projection/modes with the new masses; do not rescale all frequencies by one global factor.
For an excited state, make the scalar callback call
energy_and_gradient(root=selected_returned_root). Select and follow the same
physical root at all displaced geometries. For FNO or selected-space methods,
verify smoothness of the truncated space and completed energy as described in
Analytic gradients and finite differences. The calculator uses the callback’s actual gradient route; a
DF energy method does not automatically have an analytic gradient.
Harmonic frequencies alone are not intensities. The native
vibrational_analysis(..., dipole=True) path now supplies dipole derivatives
and double-harmonic IR intensities; see Multipole moments and harmonic IR intensities. This does not provide
Raman activities, anharmonic corrections, empirical scaling or a complete
temperature/pressure-dependent thermochemistry calculation. Native harmonic
analysis reports a positive-real-mode ZPE; additional thermochemistry needs
an appropriate treatment.
Run the shipped example
python examples/methods_api/geometry_workflows.py --task minimum --method ccsd \
--basis sto-3g --out-dir water-frequencies
The example optimizes water and includes projected frequencies in
water-frequencies/summary.json. Its --task ts and --task irc modes
also characterize the ammonia saddle; the IRC task characterizes the relaxed
endpoints as well. The default CCSD water demonstration gave three positive
modes near 2043, 3575 and 3815 cm^-1. These values verify the small-basis workflow,
not agreement with experimental fundamentals.