Geometry optimization, transition states and IRC validation
CCpy’s ccpy.optimize interface connects native energy/gradient calculations
to pysisyphus. It provides optimize_geometry for minima,
optimize_transition_state for first-order saddles,
fd_energy_and_gradient for energy-only functions, and make_calculator
for direct pysisyphus use. run_irc is exported by both ccpy and
ccpy.optimize; it integrates an Euler predictor-corrector IRC and returns
native endpoint molecules, trajectories and branch diagnostics.
Build the native molecule with symmetry=False. Geometry changes and finite differences preserve the supplied Cartesian frame and atom order; symmetry detection/reorientation would invalidate that assumption. Use a separate working directory for each optimizer/IRC calculation, since the external algorithms write trajectories, logs and Hessian data.
Installation and units
pysisyphus is listed as a CCpy runtime dependency. If it is missing from an existing environment, install it in that same environment:
python -m pip install pysisyphus
The native CCpy calculator does not need an external QC executable. A missing
.pysisyphusrc notice from pysisyphus does not itself prevent this Python
calculator from running.
Molecule defaults to angstrom for text input. Native stored coordinates and
pysisyphus Cartesian arrays are bohr. Calculator energies are hartree;
gradients are Eh/bohr and Cartesian Hessians are Eh/bohr squared. The bridge
converts gradients into negative Cartesian forces. Do not negate the gradient
in your callback. get_normal_modes applies masses and projects rigid motions
before reporting signed vibrational wavenumbers in inverse centimeters.
Minimize an electronic method directly
from ccpy import Molecule, RHF, CCSD
from ccpy.optimize import optimize_geometry
mol = Molecule("O 0 0 .12; H 0 .80 -.47; H 0 -.78 -.45",
"6-31g", 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)
minimum = optimize_geometry(cc, coord_type="redund", thresh="gau_tight",
max_cycles=100, hessian_init="fischer")
print(minimum.converged, minimum.energy, minimum.ncycles)
print(minimum.molecule.atoms) # optimized coordinates in bohr
This creates a pysisyphus rational-function optimizer and evaluates
cc.at_geometry(mol).energy_and_gradient() at requested geometries. It chooses
analytic gradients where available and otherwise uses the method’s finite
differences. The originally supplied cc object remains the template; its
stored molecule and amplitudes are not the optimized result. Reconstruct with
cc.at_geometry(minimum.molecule) for final properties.
Configure nfrozen, solver thresholds, FNO policy and correction variant on
the template. Geometry copies reproduce that constructor chain. For example,
optimize_geometry(CRCC23(cc, variant="A")) minimizes the analytic-A surface;
variant D instead uses a numerical gradient. An MP2/ADC/FNO template may require
many energy evaluations per optimizer step because it lacks an eligible
analytic derivative. See Analytic gradients and finite differences before choosing a costly model.
A completed optimizer run is not necessarily converged. Inspect
result.converged and verify the final gradient. The wrapper does not
universally reject every unconverged inner electronic iterate. For explicit
control over SCF, CC and left-state convergence, use a callback.
Use a callback for custom calculations
from ccpy import CCSD, CRCC23, RHF
def energy_and_gradient(molecule):
mf = RHF(molecule, verbose=0, e_tol=1.e-12, d_tol=1.e-10)
cc = CCSD(mf, nfrozen=1, amp_convergence=1.e-10,
energy_convergence=1.e-12)
corrected = CRCC23(cc, variant="A")
energy, gradient = corrected.energy_and_gradient()
if not (mf.converged and cc.converged and corrected.converged
and corrected.left.converged):
raise RuntimeError("Unconverged electronic calculation")
return float(energy), gradient
minimum = optimize_geometry(mol, energy_and_gradient, thresh="gau_tight")
The callback contract is callable(Molecule) -> (float, array(natoms,3)).
Do not pass gradient_and_dipole here: its return is (g,mu), not (E,g).
Use the native Hessian/IR helpers in Multipole moments and harmonic IR intensities for dipole intensities.
It lets you select correction variants, check convergence, target an excited
state, or define a custom scalar composite energy consistently. Pass either a
method or a molecule plus callback, not both method and callback.
For an energy-only calculation:
from ccpy import MP2
from ccpy.optimize import fd_energy_and_gradient
def energy_only(molecule):
method = MP2(RHF(molecule, verbose=0), nfrozen=1)
return method.energy()
numerical = fd_energy_and_gradient(energy_only, step=1.e-3, npoints=4)
minimum = optimize_geometry(mol, numerical, thresh="gau_tight")
make_calculator caches the last Cartesian geometry’s energy and gradient,
so an energy request followed by a force request at identical coordinates
needs one callback evaluation. This is not a persistent calculation cache or
an orbital/amplitude warm start. Energy-only requests still invoke the combined
callback and can therefore calculate a gradient.
Optimization controls and result fields
Setting |
Default |
Meaning |
|---|---|---|
|
|
Redundant internals. Also supports the installed pysisyphus |
|
|
Named convergence preset; |
|
100 |
Maximum optimizer cycles, separate from electronic iterations. |
|
|
Model Hessian; |
|
|
Finite-difference Hessian from calculator gradients. |
|
0 |
Lowest Hessian mode followed uphill; not an electronic-state root. |
|
None |
Periodic Hessian recomputation interval; otherwise uses the optimizer’s updates. |
|
5e-3 bohr |
Cartesian gradient-difference displacement for the Hessian. |
Extra keyword arguments go to RFOptimizer or RSPRFOptimizer. Check the
installed pysisyphus signatures before passing advanced controls; the wrapper
already supplies dump=False, so do not pass dump a second time.
verbose=False suppresses bridge messages, not necessarily all external
optimizer output. optimize_geometry does not expose a separate
hessian_step parameter: use make_calculator and the external optimizer
directly to customize that minimum Hessian displacement.
OptimizationResult exposes molecule, energy, converged,
ncycles and optimizer (the external optimizer/history).
hessian_eigenvalues is filled only by the TS wrapper. It contains raw
unweighted Cartesian Hessian eigenvalues, not vibrational frequencies or
projected mass-weighted mode eigenvalues. The minimum wrapper does not perform
a final frequency calculation automatically.
Hessian evaluation and cost
CCpy’s calculator computes a Cartesian Hessian by two-point differences of
Cartesian gradients at +/- hessian_step, then symmetrizes it. This requires
6N displaced gradients for N atoms, plus a central energy/force request as
needed. There is no analytic molecular Hessian exposed by this bridge.
With numerical gradients, the Hessian is a nested finite difference and its
cost is quadratic in atom count times the scalar energy cost. fd_step /
fd_npoints control the inner energy gradient, while hessian_step
controls the outer gradient derivative. Tight electronic convergence and
step-size checks are essential when distinguishing weak imaginary modes from
noise. A model Hessian is useful to start minimization; it is not a final
vibrational characterization.
Find a transition state
Supply a chemically plausible near-saddle guess. The following ammonia inversion example starts close to planar and follows the umbrella mode:
from ccpy.optimize import optimize_transition_state
guess = Molecule("N 0 0 .10; H .95 0 0; H -.475 .8227 0; H -.475 -.8227 0",
"6-31g", auxiliary_basis="def2-universal-jkfit",
symmetry=False)
method = CCSD(RHF(guess, verbose=0, e_tol=1.e-12, d_tol=1.e-10),
nfrozen=1, amp_convergence=1.e-10, energy_convergence=1.e-12)
ts = optimize_transition_state(
method, root=0, coord_type="redund", thresh="gau_tight",
hessian_init="calc", hessian_recalc=5, hessian_step=5.e-3,
max_cycles=100,
)
print(ts.converged, ts.energy, ts.hessian_eigenvalues)
The wrapper uses restricted-step partitioned RFO, maximizing along one mode
and minimizing the others. root=0 is appropriate when the lowest relevant
mode is the desired reaction coordinate. A poor starting guess can have no
negative mode, several negative modes or the wrong unstable motion. Inspect
mode displacements rather than accepting a converged optimizer flag as proof
of the intended transition state.
After the search the wrapper always computes a final finite-difference
Cartesian Hessian, even if optimization did not converge. Check ts.converged
first, then characterize its projected vibrational modes and verify the chemical
motion. Do not count tiny negative raw Cartesian eigenvalues as separate
imaginary vibrations; translations/rotations and numerical noise can contribute.
Projected vibrational analysis
See Computing vibrational frequencies for a complete minimum-frequency calculation, mode displacements, isotope substitution, Hessian reuse and numerical convergence.
Use public pysisyphus objects with CCpy’s calculator, on the same electronic surface and basis as the optimization:
import numpy as np
from pysisyphus.Geometry import Geometry
from ccpy.integrals.atom_data import Z_TO_ATOM_SYMBOL
from ccpy.optimize import make_calculator
def at_geometry(molecule):
calculation = method.at_geometry(molecule)
energy, gradient = calculation.energy_and_gradient()
if not calculation.converged:
raise RuntimeError("Unconverged electronic state")
return float(energy), gradient
atoms = [Z_TO_ATOM_SYMBOL[int(z)] for z in ts.molecule.atomic_charges]
coords = np.array([xyz for _, xyz in ts.molecule.atoms]).ravel()
geom = Geometry(atoms, coords, coord_type="cart")
geom.set_calculator(make_calculator(ts.molecule, at_geometry,
hessian_step=5.e-3, verbose=False))
frequencies, eigenvalues, mass_weighted_modes, cartesian_modes = geom.get_normal_modes()
print(frequencies) # cm^-1; negative values denote imaginary modes
get_normal_modes mass-weights the Hessian and projects rigid motions. A
nonlinear isolated molecule has 3N-6 vibrational modes (3N-5 if linear), with
special handling needed for atomic/degenerate limits. A minimum should have
no significant imaginary vibration; a first-order saddle should have exactly
one. The associated displacement must follow the proposed chemical reaction.
Low-frequency negative values require numerical checks rather than an arbitrary
universal cutoff. The runnable example uses -20 cm^-1 only as a practical
small-molecule demonstration threshold.
This standalone analysis computes a Hessian again because the CCpy TS result
stores only its eigenvalues. The resulting geom retains the Hessian cache
and can serve as the initial geometry for direct pysisyphus use. Keep atom order, charge,
spin, isotopic masses and coordinate frame consistent when reusing Hessians.
Run both IRC branches with run_irc
Use the converged TS molecule and the same scalar electronic callback used for the saddle search:
from ccpy import run_irc
result = run_irc(
ts.molecule, at_geometry, forward=True, backward=True,
hessian_init="calc", root=0, hessian_step=5.e-3,
step_length=0.05, max_cycles=150, rms_grad_thresh=5.e-4,
displ="length", displ_length=0.1,
out_dir="irc", prefix="reaction", verbose=False,
)
print(result.converged, result.start_energy)
for direction, branch in result.branches.items():
print(direction, branch.converged, branch.energy_converged,
branch.energy_increased, branch.gradient_rms, branch.ncycles)
Alternatively pass a method rebuilt on the saddle geometry:
result = run_irc(method.at_geometry(ts.molecule), out_dir="method-irc")
This repeats the method’s configured scalar energy/gradient calculation at each
geometry and checks its convergence flag. For an excited-state method select
its returned electronic root with state:
result = run_irc(eom_template.at_geometry(ts.molecule), state=1, root=0,
out_dir="excited-irc")
Here state=1 is passed to the method’s energy(root=1) and
gradient(root=1); root=0 selects the Hessian mode. An array-valued energy
without an explicit scalar state raises a clear error before computing the
method gradient. With a molecule/callback input, select the state inside the
callback instead of passing state. The wrapper checks that every energy is
a finite real scalar and every gradient has finite real shape (natoms,3).
It does not implement universal electronic root tracking; keep the state-following
checks discussed below.
The result types IRCResult and IRCBranch are also exported by CCpy:
start_moleculeandstart_energydescribe the input geometry.branchesmaps requested directions toIRCBranchobjects.Each branch stores
coordinatesin Cartesian bohr with shape(npoints,natoms,3),energiesin hartree, andgradientsin Eh/bohr. Points run from the initial displacement toward the last stored endpoint; the separate starting TS is not prepended to each branch.branch.moleculeis the native molecule at the last stored point;result.endpointsmaps directions to these molecules.convergedmeans all requested branches met the external integrator’s convergence criteria. A cycle-limited path returnsFalse; it does not silently become a validated connection.gradient_rmsis evaluated at the last stored branch point.ncyclesis the external cycle index plus one.result.ircexposes the original pysisyphus object for complete histories, mass-weighted coordinates and additional diagnostics.
Both directions are enabled by default. Disable one with forward=False or
backward=False. downhill=True instead returns a single "downhill"
branch and ignores those two switches. At least one direction is required when
not running downhill. Extra keyword arguments are passed to pysisyphus
EulerPC/IRC, including initial-displacement settings, energy_thresh,
hessian_recalc and dump_every. A saved Hessian path can be supplied as
hessian_init; verify matching geometry, atom order, units and electronic
surface before reusing it. The native wrapper starts from a molecule, so it
calculates its own Hessian unless a file is supplied; it does not implicitly
reuse the standalone geom object’s cache from the frequency example.
EulerPC integrates the reaction path in mass-weighted coordinates, starting in
opposite directions along the transition vector. Here displ_length is the
initial mass-weighted displacement (sqrt(amu) bohr). step_length is a
separate integrator step control; the installed EulerPC measures its target
integration length in unweighted Cartesian coordinates. Do not confuse either
with hessian_step or a finite-difference gradient displacement.
max_cycles applies per branch. These explicit values are an example, not a
universal converged IRC protocol. Reduce the integration step and tighten
thresholds to check path/endpoint stability.
A branch may terminate through energy-change criteria rather than a small final
gradient. Inspect the per-branch flags, cycle counts and actual endpoint gradients.
Reaching max_cycles is not validation. downhill=True is a different
single downhill trajectory from a nonstationary starting point; it does not
replace both branches from a stationary saddle.
The interface writes pysisyphus trajectories, logs and Hessian/HDF5 data;
prefix and out_dir control the IRC files, while some external outputs
can still be relative to the process working directory. Run in a dedicated
directory. pysisplot --irc can visualize the saved IRC data; consult the
installed pysisyphus command help for file arguments and output conventions.
Optimize and validate the endpoints
run_irc returns the last stored geometries without optimizing or
vibrationally characterizing them. Minimize its native endpoint molecules
on the same energy surface:
endpoints = {}
for direction, endpoint in result.endpoints.items():
relaxed = optimize_geometry(endpoint, at_geometry, thresh="gau_tight")
if not relaxed.converged:
raise RuntimeError("Endpoint optimization did not converge")
endpoints[direction] = relaxed
print(direction, relaxed.energy, ts.energy - relaxed.energy)
Use the projected frequency procedure on both relaxed endpoints and check that they are minima. Then compare their bonding, structures, atom mapping and state character with the intended reactant/product basins. Both should lie below the saddle on that same surface; otherwise inspect optimization, convergence or state tracking. A single imaginary TS frequency alone does not establish a connection to the desired pair of minima.
Forward/backward labels are arbitrary: the unstable eigenvector can change sign. Symmetric reactions may lead to symmetry-equivalent endpoints rather than different chemical connectivities. For ammonia inversion the preserved N/H atom labels allow comparing the signed N height relative to the ordered H plane: opposite signs distinguish the two umbrella minima. Do not require two arbitrary, unsuperimposed Cartesian coordinate arrays to be equal when matching geometries.
Electronic excited states and custom surfaces
Use a scalar root-aware callback instead of passing a multiroot EOM method directly to the wrappers:
from ccpy import EOMCCSD
eom_template = EOMCCSD(method)
eom_template.initial_guess(method="cisd", multiplicity=1, nacto=2, nactu=2,
roots_per_irrep={"A": 3}, roots=[0, 2])
def excited_surface(molecule):
eom = eom_template.at_geometry(molecule)
energy, gradient = eom.energy_and_gradient(root=1)
if not (eom.converged and eom.cc.converged and eom.root_converged[1]):
raise RuntimeError("Unconverged target")
return float(energy), gradient
excited_minimum = optimize_geometry(eom_template.molecule, excited_surface)
Here the selected electronic state is returned root 1, seeded by guess index 2.
The TS/IRC root instead selects a Hessian mode. Root-specific callbacks also
work for corrected EOM/ADC energies if their gradient route and state identity
are appropriate. Generic at_geometry repeats guesses; it does not implement
universal electronic root tracking across crossings. Inspect amplitudes,
overlap and neighboring energies along the path. Near degeneracies, a
single smooth adiabatic surface and ordinary first-order saddle/IRC description
can fail; the interface does not supply nonadiabatic couplings or crossing
optimization automatically.
FNO cutoffs and adaptive selected spaces can change discretely along a path. Use the smoothness checks in Analytic gradients and finite differences and consistent parent/target completion conventions. Numerical differentiation of an FNO-completed energy includes the rebuilt low-level correction; it does not make a cutoff-discontinuous surface differentiable.
Runnable end-to-end examples
python examples/methods_api/geometry_workflows.py --task minimum --method ccsd \
--basis sto-3g --out-dir minimum-run
python examples/methods_api/geometry_workflows.py --task minimum --method mp2 \
--basis sto-3g --out-dir numerical-minimum
python examples/methods_api/geometry_workflows.py --task ts --method rhf \
--basis sto-3g --out-dir ts-run
python examples/methods_api/geometry_workflows.py --task irc --method rhf \
--basis sto-3g --out-dir irc-run
--finite-difference explicitly replaces analytic gradients by displaced
energies. --method crcc23a selects the deterministic analytic-A correction.
The IRC task searches for the ammonia inversion saddle, checks its projected
frequencies, integrates both branches, relaxes the endpoints and checks their
frequencies and opposite umbrella signs. summary.json records the results.
These small-basis examples validate wiring and conventions, not quantitative
reaction energetics. Do not assume a successful RHF path establishes a CC or
excited-state path without repeating that surface’s calculations.
Validation of the shipped example
The examples were run with pysisyphus 1.0.0, native DF-RHF/CCSD and the default STO-3G / def2-universal-jkfit demonstration setup. CCSD analytic versus four-point energy-difference gradients at distorted water differed by about 6.1e-11 Eh/bohr. The optimized CCSD water had three positive vibrational modes. The RHF ammonia saddle had one imaginary mode near -1081.5 cm^-1; both IRC branches relaxed to positive-frequency minima near -55.4555641 Eh, below the saddle near -55.4378011 Eh, with opposite signed umbrella heights. These are sanity checks for the runnable example, not reference-quality reaction data or a guarantee of a CCSD IRC from an RHF path.
tests/scf/test_irc_interface.py additionally exercises the public wrapper
on both ammonia branches, native endpoint relaxation, single-branch and
cycle-limited results, electronic-state selection and invalid inputs.
The existing direct-method optimization test in
tests/methods/test_method_gradients.py::test_optimize_geometry_with_a_method
also checks the CCpy-object-to-pysisyphus wrapper. Larger methods, basis sets,
excited states and arbitrary reactions require their own validation.
External documentation and version checks
The examples were checked against the locally installed pysisyphus API. Record your installed version and inspect signatures when transferring a workflow:
import inspect
from importlib.metadata import version
from pysisyphus.irc.EulerPC import EulerPC
from pysisyphus.irc.IRC import IRC
print(version("pysisyphus"))
print(inspect.signature(EulerPC.__init__))
print(inspect.signature(IRC.__init__))
See the primary pysisyphus IRC documentation and
public Geometry API. Online and
installed defaults can differ; the examples explicitly specify the important
path controls. CCpy bridge signatures are in
ccpy/optimize/pysisyphus_interface.py.