How-to#

Step a band from C#

Enable capi. The header is rgsaddle.h. ABI major 1. Every wire struct opens with rgsaddle_version_t. The host:

  1. creates a session

  2. calls step until the report says converged, or until host policy stops

  3. reads rgsaddle_band_evaluation for the energies and forces at the new band instead of evaluating it again

  4. calls rgsaddle_band_restart to restart the optimizer on the same surface, rgsaddle_band_reset at a surface-epoch boundary

  5. frees

rgsaddle_band_set_positions with the band the host read back (even wrapped into its cell) costs no evaluation; only moved rows retire the cached values. rgsaddle_report_t.evaluations counts the image evaluations of each step.

There is no run-to-completion C entry point. Units are the caller’s. Positions are unwrapped Cartesian, image-major, stride 3 * n_atoms.

Grow the band with AutoNEB#

howto/autoneb is the AutoNEB loop: insert where the resolution is worst, relax a local window, and climb. The tuning sits on BandConfig::autoneb. A weighted spring supplied by the host is refused for now; zoom-NEB will recompute it.

Pick tangents, springs, projections#

Kind

Variants

TangentKind

Simple (Mills–Jónsson–Schenter), Improved (Henkelman–Jónsson)

SpringKind

Uniform { k }, energy-weighted, Onsager–Machlup

ProjectionKind

plain elastic band, Neb, Dneb

Defaults: improved tangent, uniform spring k = 5, NEB projection, climbing image with trigger factor 0.5.

Step one point with a stencil#

howto/stencil builds Stencil::point for a minimiser, the dimer, Lanczos, ART, or eigen following. Stencil::band is the feat/band-methods-zoom seam. The C names are rgsaddle_stencil_* and rgsaddle_last_error. Python is rgsaddle.Stencil.point and rgsaddle.ase.Point.

Minimum-mode instead of a band#

MinModeSession refreshes the lowest curvature mode (dimer rotation or Lanczos on finite-difference Hessian actions), inverts the force along it, and takes one solver step. Same host loop. PointSurface evals a single geometry.

A host that climbs with its own optimizer keeps one session for the whole search: set_position (rgsaddle_minmode_set_position) with the gradient it already has, then estimate_mode (rgsaddle_minmode_estimate). The previous mode seeds the next rotation, so a mode that still holds costs one evaluation. The dimer’s Polak-Ribiere force and direction survive that move; set_mode and reset clear them, and a failed callback leaves them unchanged. Lanczos through the C estimate advances one Hessian action and keeps the Krylov basis until set_position, set_mode, or reset. The basis grows to the free dimension. After k actions the mode also takes its component on the residual direction, from the Lanczos polynomials at an extrapolated lowest eigenvalue, at no extra surface call; the reported curvature is the Ritz value of the k vectors. MinModeSession::estimate_mode and step still finish the residual test before a translation. A dimer estimate is the full rotation.

Index-1 Newton#

Index1Session takes a restricted-step partitioned RFO step on a dense Hessian and updates it with Powell or Bofill. Pass an initial Hessian, or leave it empty and the first step builds one by central differences. Index1Config is non-exhaustive. with_sparse_pattern builds that seed from a distance-2 colouring instead. The flag stays off unless set. The trust radius is the Euclidean bound on the Cartesian step. See the sparse Hessian how-to.

From C, rgsaddle_index1_create / rgsaddle_index1_step follow the same loop. The vector length is 3 * n_atoms; a bead polymer passes n_atoms * n_beads. A host that owns the Hessian calls rgsaddle_prfo_step. rgsaddle_nichols_step is the i-PI shift on a spectrum (nmode may be smaller than n when external modes were dropped). rgsaddle_hessian_bofill or rgsaddle_hessian_powell updates the Hessian. The gradient on the wire is dE/dx.

Do not keep solver history across a potential change#

Call reset after any model update. That is the documented boundary. A host that skips it mixes two surfaces in one L-BFGS memory. restart is the optimizer-only reset for the same surface; it keeps the cached endpoint energies and the last evaluation.