Reference#

Public Rust types#

C ABI (feature capi)#

include/rgsaddle.h. RGSADDLE_ABI_MAJOR is 1. Status codes include RGSADDLE_OK, RGSADDLE_SHAPE, RGSADDLE_SURFACE_FAILED, RGSADDLE_ABI_MISMATCH. Methods on the wire: FIRE, L-BFGS, quick-min, and ODE12r (RGSADDLE_METHOD_ODE12R, minor 22); rgsaddle_band_set_exp_precon (minor 22) installs the per-image exponential metric on the band solver, ODE12r-Exp with that method. Min-mode kinds: dimer and Lanczos. Index-1 entries: rgsaddle_nichols_step, rgsaddle_prfo_step, rgsaddle_hessian_powell, rgsaddle_hessian_bofill, rgsaddle_cap_max_abs, and rgsaddle_index1_step. Band cache entries: rgsaddle_band_restart, rgsaddle_band_evaluation (RGSADDLE_NO_EVALUATION when nothing is cached at the band’s positions). Min-mode reuse: rgsaddle_minmode_set_position, rgsaddle_minmode_set_mode, rgsaddle_minmode_estimate. A Lanczos estimate advances one Hessian action and keeps the Krylov basis until set_position, set_mode, or reset; the basis grows to the free dimension, the mode after k actions lies in the k + 1 Lanczos vectors (its curvature is the Ritz value of the k), and a dimer estimate is the full rotation. Dimer Polak-Ribiere history survives set_position and is cleared by set_mode and reset; a failed callback leaves it unchanged. rgsaddle_minmode_config_t.difference picks RGSADDLE_DIFFERENCE_FORWARD or _CENTRAL, and rotation_angle_tol stops a dimer rotation whose optimal angle falls under it (radians; the Rust default is five degrees, 0 off, and a C config stores the value it is given). Both fields are read only from a config whose version minor is 5 or newer. RGSADDLE_ABI_MINOR is 23. Request flags: RGSADDLE_REQ_ONE_IMAGE (bit 0) and, from a band config at minor 22, RGSADDLE_REQ_CLIMBING_IMAGE (bit 1) on the refinement’s one-image requests, with image the climbing image’s band index. rgsaddle_idpp_path writes the image-dependent pair potential initial path, endpoints included, and takes a row-major cell or NULL. rgsaddle_ocineb_step reports the hand-off phase (band, tangent alignment, or minimum-mode translation). rgsaddle_connect runs that search to completion: the host passes two endpoint arrays and a surface that writes energy and the Cartesian gradient for one image; rgsaddle_connect_report_t returns energy, the Euclidean gradient norm, kind (s, u, or f), the Hessian index, and the evaluation count. Finite differences that decide a step or an index are included; the Lanczos acceptance does not build a dense Hessian. RGSADDLE_BAND_CI_AFTER (band flag bit 2) arms the climbing image under ci_trigger_force or ci_trigger_factor times the first force, either of which may be 0; RGSADDLE_BAND_NO_MIN_MODE (band flag bit 3, minor 21) turns off the min-mode refinement of the climbing image, which is otherwise on and reports its curvature in rgsaddle_report_t.curvature; RGSADDLE_STALLED reports a band step that left the band unchanged above force_tol. RGSADDLE_METHOD_QUICKMIN runs quick-min on the band. rgsaddle_band_set_quickmin_variant selects RGSADDLE_QUICKMIN_RGMIN, _EON or _PER_ATOM. A min-mode session returns null for that code. rgsaddle_band_create_solid builds a solid-state band; rgsaddle_band_step_solid steps it on an rgsaddle_solid_surface_fn whose rgsaddle_solid_surface_request_t carries cells in and Cauchy stresses out; rgsaddle_band_cells and rgsaddle_band_solid_jacobian read it back. The report’s evaluations field took the place of reserved at minor 5. cargo cinstall installs include/rgsaddle.h as written.

Python package#

The importable package is rgsaddle. rgsaddle._core is the nanobind extension. import rgsaddle does not import ASE.

Name

Role

ForceGate, HessUpdate, IrcKind, MinModeKind, EigenDevice, ExpandKind, CellChart, RestrictedKind

enum.IntEnum controls. Names and values match the previous module

NumericalError

ArithmeticError for RGSADDLE_NON_FINITE

last_error

Thread-local text reserved for the C ABI last-error call. Empty unless an error text was set. raise_status reads it and then clears the slot

raise_status

Map an rgsaddle_status_t value. The message is the stored text, or the status name when that text is empty. RGSADDLE_OK returns true

rgsaddle.ase.SurfaceAdapter

list[Atoms] evaluated as (ids, x) -> (energies, gradients) request rows. Optional extra ase

rgsaddle.Stencil

Point search. point, step, run, positions, mode, curvature. band raises ValueError with the zoom seam

rgsaddle.connect

Run-to-completion double-ended search. surface(x) is the one-image (energy, gradient) callback. ConnectReport holds the geometry, energy, gradient norm, kind, Hessian index, and evaluation count

rgsaddle.ase.Point

ASE Optimizer driver for one point preset. run(fmax, steps) is ASE’s own loop

SurfaceAdapter keeps get_forces(apply_constraint=False) on raw_forces. The returned gradient is minus get_forces() after constraints. The adapter evaluates the given rows in order on the calling thread. owners() and reentrant() are what a driver uses to group. A second call while the first holds the adapter raises RuntimeError.

Tests that pin the contract#

  • tests/ocineb.rs — the hand-off waits for a stable climbing image, restores it when the curvature is positive, and reaches the same double-well saddle as a climbing-image band. tests/ocineb_abi.rs runs tests/c/ocineb_abi.c

  • tests/connect_driver.rs — two-barrier toy, the C ABI, LJ38 pair 0 and pair 39, and ignored release samples of the 51-pair connect score and the CI-NEB templates on 20 pairs

  • tests/double_well.rs — band finds the origin saddle, endpoints pinned

  • tests/autoneb.rs — ASE AutoNEB decisions and the Müller-Brown insertion sequence. tests/autoneb_gate.rs hashes the insertion list and the trajectory at 1, 2, 3 and 8 threads, and an ignored release run compares AutoNEB with CI-NEB at one force-call budget. Strong scaling of a full AutoNEB run is an ignored test in the crate.

  • tests/minmode_saddle.rs — dimer / Lanczos

  • tests/nichols_saddle.rs — Nichols step against i-PI on the same Hessian and gradient, Muller-Brown saddles, quadratic saddle

  • tests/prfo_saddle.rs — partitioned RFO against the augmented Hessian, trust sphere changes the mode ratio

  • tests/c_abi.rs — header and symbols with capi

  • tests/solid_bain_lj.rs — tests/c/solid_bain_lj.c runs the solid-state band from bcc to fcc for switched LJ on the two-atom tetragonal cell through rgsaddle_band_create_solid; the climbing image matches the relaxed scan of validation/bain_lj_reference.py in c/a within 2.5e-4 and in barrier within 1.2e-6 eV/atom, and every image keeps a diagonal tetragonal cell and its fractional coordinates

  • validation/ — sympy and sollya checks of the dimer rotation, the Lanczos residual bound, and the finite-difference curvature; bain_lj_reference.py (numpy, scipy) scans the relaxed Bain path that tests/c/solid_bain_lj.c checks against, and ssneb_bain_cell.py (sympy) checks its strain parametrisation and Jacobian