Frequencies sub-step and <HESSIAN – scope and design#

Goal#

Two related additions to the ORCA plug-in:

  1. A Frequencies sub-step (a subclass of Energy) that runs ORCA’s Freq (analytic AnFreq) or NumFreq (numerical) second derivatives and reports the Hessian, harmonic vibrational frequencies, IR intensities, and the thermochemistry (zero-point energy, enthalpy, entropy, Gibbs free energy) at a chosen temperature. Imaginary frequencies are reported and flagged.

  2. A custom ``<HESSIAN`` MDI command on the ORCA MDI engine that returns the analytic Cartesian Hessian, so a driver holding a warm engine can pull the Hessian without a fresh process launch.

The immediate driver is the normal_mode_sampling_step plug-in, which samples the normal-mode space of a molecule and needs the Hessian at the optimized monomer. It obtains that Hessian through seamm_mdi.MDIEngine: an analytic Hessian over <HESSIAN when the engine offers one, otherwise a finite-difference of the forces over the same warm engine.

The Frequencies sub-step#

Freq/NumFreq appended to the Energy input; ORCA writes the mass-weighted Hessian to orca.hess and the vibrational analysis to orca.out. Beyond the frequencies and IR intensities, the step reports the largest of the 5 or 6 nominally-zero translation/rotation frequencies as a gauge of the numerical quality of the Hessian – computed from the raw, un-projected orca.hess (ORCA prints those modes as exactly 0.00, which hides the real residual). It writes frequencies.csv and an IR_spectrum.graph (stick + Lorentzian-broadened trace), and honours the standard Structure-handling options.

The <HESSIAN MDI command#

The bundled engine data/orca_mdi.py answers <HESSIAN by running an ! AnFreq job for the current geometry, parsing orca.hess, and sending the 3N x 3N Cartesian Hessian in hartree/bohr^2, row-major. The result is cached and invalidated when the geometry, charge, or multiplicity changes, so repeated requests at one point are free.

Truthful capability advertising (the key design decision)#

MDI has no standard Hessian node, so a driver must discover the capability at run time (MDI_Check_Command_Exists / MDIEngine.supports("<HESSIAN")). For that discovery to be trustworthy, the engine advertises ``<HESSIAN`` only when ORCA genuinely has an analytic Hessian for the method:

  • get_mdi_engine_command passes --hessian yes/no from method_has_analytic_hessian();

  • HF, MP2, and the ordinary DFT functionals have an analytic Hessian -> advertise;

  • double hybrids (e.g. revDSD-PBEP86-D4) have an analytic gradient but no analytic Hessian (they need NumFreq) -> do not advertise;

  • (DLPNO-)CCSD(T) and the non-self-consistent double hybrids have neither -> do not advertise.

An earlier iteration advertised <HESSIAN unconditionally and let <HESSIAN degrade to a numerical Hessian when no analytic one existed. That was a bad design: the capability check lied, and a driver expecting a cheap analytic Hessian could unknowingly trigger a ruinously expensive NumFreq (catastrophic for coupled cluster). The engine now never silently falls back to NumFreq over MDI – if it does not advertise <HESSIAN, the driver sees supports() return False and finite-differences the forces itself (its own explicit, visible choice). Use the Frequencies sub-step when a numerical Hessian is actually wanted.

Cross-repo pieces (all released 2026-07-15/16)#

  • orca_step 2026.7.15 – Frequencies sub-step + the <HESSIAN engine command (this campaign); 2026.7.16 – structure handling, kJ/mol units, the zero-mode residual, the IR-spectrum graph.

  • seamm-mdi 2026.7.15 – consumer side: MDIEngine.supports(command) and MDIEngine.hessian() (returns the 3N x 3N Hessian; raises NotImplementedError when <HESSIAN is not advertised).

  • normal_mode_sampling_step 2026.7.15 – the driver: gates on supports("<HESSIAN") and uses the analytic Hessian, else FD of the forces.

Back-pointers#

  • Science spec: ~/Sites/mlff-training/2026-07-15_water-mlff-training-plan/ (decision #2), which now records that the sampling step and this Hessian path are released.

  • Consumer design: the normal_mode_sampling_step campaign (docs/developer_guide/campaigns/2026-07-15/ in that repo).