Module core 

Framework: traits, state shapes, the iteration driver, and the convergence and execution controls. The slot taxonomy is:

• problem: what the user implements about their objective: CostFunction, Gradient, MiniBatchGradient (finite-sum, for mini-batch SGD), Residual/Jacobian (least squares), and Hessian (second order). Future: operators (matrix-free).
• numdiff: finite-difference derivative synthesis and analytic checks. DerivativeChecker checks gradients and Jacobians with optional bounds and directional probes. The FiniteDiff wrapper adds Gradient/Jacobian/ Hessian to a problem that only exposes function values.
• constraint: constraint markers carried on the problem (tenet 4 in CONTRIBUTING.md): BoxConstraints, LinearInequalityConstraints, LinearEqualityConstraints, and NonlinearInequalityConstraints. The standalone aggregators LinearConstraints and NonlinearConstraints supply the full forms for LINCOA and COBYLA, respectively; COBYLA consumes the latter through FoldedConstraints.
• barrier: the LogBarrier adapter that rewrites a linearly-constrained problem as the unconstrained log-barrier objective consumed by the BarrierMethod.
• state: what a solver carries between iterations: State for the minimum, GradientState/ SimplexState when a solver carries richer info that convergence checks can read.
• solver: the Solver trait every concrete solver implements. Lifecycle is init once, then repeated next_iter, with an optional terminate hook.
• convergence: shared fixed slots for solver-owned optional checks. Enabled checks require only their minimum state and backend capabilities.
• run_control: execution budgets, targets, stalls, and application hooks.
• termination: stopping reasons and the deprecated Basin 1.x criterion facility, scheduled for removal in Basin 2.0.
• observer: read-only side-effect hooks fired around the loop (Observe + ObserverMode).
• checkpoint: solver-aware snapshots for exact continuation. State-only warm-start files remain an observer concern.
• executor: the driver: Executor/ Stepper/run_loop_with_control, plus the cooperative CancellationToken. The canonical iteration ordering is documented on the executor module.
• inner: the composition adapter: InnerExecutor wraps run_loop_with_control for outer solvers that drive an inner solver per outer iteration. See CONTRIBUTING.md “Solver composition” for the contracts.
• math: the small shared math layer (ScaledAdd, NormSquared, …) that backend-generic solvers depend on. Per tenet 5, this stays honest: only ops every backend can implement well live here. LA-heavy ops will live in a separate tier when the first solver wants them.

Modules

augmented_lagrangian

Augmented-Lagrangian adapter for linear equality constraints.

barrier

Log-barrier adapter for linear inequality constraints.

checkpoint

Solver-aware checkpoints for exact continuation.

constraint

Constraint markers carried on the problem (tenet 4 in CONTRIBUTING.md). BoxConstraints (interval bounds, consumed by projection-based solvers), LinearInequalityConstraints (A x ≤ b, consumed by the log-barrier method), LinearEqualityConstraints (A x = b, consumed by the augmented-Lagrangian method), and NonlinearInequalityConstraints (c(x) ≤ 0 for an arbitrary vector-valued c, consumed by COBYLA).

convergence

Solver-owned convergence settings with compile-time backend capabilities.

executor

Iteration driver. The high-level entry point is Executor; Stepper exposes one-iteration-at-a-time control, and run_loop_with_control is the borrowed-problem variant used by composed solvers.

inner

Composition adapter: drive an inner solver from inside an outer solver’s next_iter.

least_squares

Robust objectives for nonlinear least squares.

math

Math abstraction the solvers depend on.

numdiff

Finite-difference derivative synthesis and analytic derivative checks.

observer

Read-only side effects fired around the iteration loop.

problem

Problem traits the user implements about their objective. Solvers bind on whichever subset they need (e.g. gradient descent requires CostFunction and Gradient; Nelder-Mead only needs CostFunction).

rng

Seedable, wasm-safe RNG used by stochastic solvers.

run_control

Execution budgets and application stopping conditions.

solver

The Solver trait every concrete solver implements. See the trait contract for the lifecycle (init once, then repeated next_iter, with an optional terminate hook) and the executor module for the canonical iteration ordering.

state

Solver state shapes.

termination

Stopping reasons and the deprecated Basin 1.x criterion facility.