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.

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.

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.