Architecture#

rgmin follows a metatensor-style hourglass: solvers live in Rust, C sees a small ABI, C++ is a header wrapper.

Layer diagram#

+-----------------------------------------------+
|  C++ wrapper                                  |
|  include/xts/optimize.hpp                     |
|  include/xts/xtensor.hpp                      |
+-----------------------------------------------+
|  C ABI (cbindgen + hand headers)              |
|  include/xts.h                                |
|  rgmin_solver_t create/step/free                |
|  rgmin_minimize over dlpk tensors               |
|  set_qn_step / set_accept / set_manifold      |
+-----------------------------------------------+
|  Rust core                                    |
|  Solver / Lbfgs / NLCG / BFGS / Newton        |
|  Manifold (Euclidean, RigidQuotient, MwRigid) |
|  Sphere / SO3 / Stiefel / SE3 embeddings      |
|  LineSearch (Brent, Armijo, Goldstein, Wolfe) |
|  eindir DifferentiableObjective               |
+-----------------------------------------------+

Objects#

Lbfgs: Persistent pair history, two-loop recursion, strong Wolfe. Hopping chains hold this type (anneal WarmLbfgs is a handle).
Solver: Method-agnostic session. One step is one outer iteration. The C type rgmin_solver_t is a pointer to this.
minimize_method: Cold-start dispatch for every Method.
LineSearch::Wolfe: Nocedal-Wright 3.5 / 3.6. Default production choice for quasi-Newton directions.
Oracle: Closure adapter that implements DifferentiableObjective for a fused (f, g) function.
ecnoise: Moré–Wild difference table for the noise in an energy or in one projection of the gradient, plus the 2012 forward and gradient steps (Algorithm 5.1, not the noise table). One uniform projection has variance tr(Σ) / n. Control::noise_floor stops at c * sqrt(n_free) * eps_g with Status::NoiseFloor, after the gtol test. The same stop fires when a line search finds no trial whose decrease clears c * eps_f.
rgmin_solver_create / rgmin_solver_step / rgmin_solver_free: Stateful C waist. Callbacks are per step. abi_major 1, abi_minor 9, layout_revision 2. Compatibility checks major and layout only.
ManifoldKind: Embedded geometry. Euclidean is the identity. Sphere, SO(3), Stiefel St(n,1), and SE(3) implement project / retract / transport.
rgmin_minimize: First-order / quasi-Newton C entry. CPU f64 tensors only; other devices return RGMIN_UNSUPPORTED_DEVICE.
rgmin_minimize_hess: Newton / RFO C entry. Caller supplies a dense row-major Hessian. This is a different solver, not an L-BFGS option.
Solver::set_precon / rgmin_solver_set_precon: Exp, Lindh, the bonded metric, or select_precon. ABI minor 32.
rgmin_solver_set_quickmin_variant: Quick-min options from C: RGMIN_QUICKMIN_RGMIN, RGMIN_QUICKMIN_EON, RGMIN_QUICKMIN_PER_ATOM. ABI minor 33. rgmin_solver_precon_scale is μ after the sine probe.
select_precon: L-BFGS and CG: Exp at 100 atoms for bulk, surface, and a metal cluster (ASE PreconLBFGS). Lindh for a covalent molecule or cluster up to N_LINDH. Bonded metric when that caller has a force field and every element is covalent. FIRE auto is the identity.

C kind	Rust	role
`RGMIN_PRECON_EXP`	`PreconSpec::Exp`	`H_0 = P^{-1}` for L-BFGS, metric for CG and FIRE
`RGMIN_PRECON_LINDH`	`PreconSpec::Lindh`	model Hessian, same solve
`RGMIN_PRECON_FF`	`PreconSpec::Ff`	bonded metric, harmonic terms on the C struct
`RGMIN_PRECON_AUTO`	`select_precon`	the session method plus the how-to table
`RGMIN_PRECON_NONE`	`clear_precon`	drop the metric

What does not live here#

Simulated annealing, basin hopping, and catalogue logic stay in anneal.
Objective algebra stays in eindir.
Sketch-map style collective variables stay in landfold.