Basin

A numerical optimization library for Rust, inspired by argmin. It pairs a generic core, problem traits you implement, solver-owned convergence settings, and a driver loop (Executor), with a set of solvers spanning first-order, derivative-free, nonlinear least-squares, and evolutionary methods. Solvers are generic over the linear-algebra backend, constraints are first-class, and the default build compiles to wasm32-unknown-unknown with no BLAS/LAPACK or threads. A direct scalar root-finding API covers bracketed equations without forcing their signed function values through the optimization state model.

Narrative documentation lives at basin.rs/docs; the rustdoc reference is at docs.rs/basin. There is also an in-browser solver visualizer and a benchmarks site comparing Basin against competing crates and across backends and solvers.

To port an existing Argmin project, see Migrating from Argmin.

cargo add basin

Basin works on plain Vec<f64> out of the box. Linear-algebra backends are opt-in. Use a moving alias to follow the newest supported release:

cargo add basin --features nalgebra_latest  # or: ndarray_latest, faer_latest

Exact version features, such as nalgebra_v0_34, keep dependency resolution stable. Basin's package minimum supported Rust version (MSRV) is 1.87.0. The one exception is nalgebra 0.35: nalgebra_v0_35 and nalgebra_latest require Rust 1.89. The development environment uses Rust 1.89, while CI checks the Rust 1.87-compatible feature set separately.

Implement CostFunction (and Gradient, when the solver needs derivatives), then hand the problem, a solver, and an initial state to the Executor:

use basin::{
    BasicState, CostFunction, Executor, Gradient, GradientDescent,
};
use std::convert::Infallible;

struct Rosenbrock;

fn main() {
    impl CostFunction for Rosenbrock {
        type Param = Vec<f64>;
        type Output = f64;
        type Error = Infallible;

        fn cost(&self, x: &Vec<f64>) -> Result<f64, Self::Error> {
            Ok((1.0 - x[0]).powi(2) + 100.0 * (x[1] - x[0].powi(2)).powi(2))
        }
    }

    impl Gradient for Rosenbrock {
        type Gradient = Vec<f64>;

        fn gradient(&self, x: &Vec<f64>) -> Result<Vec<f64>, Self::Error> {
            Ok(vec![
                -2.0 * (1.0 - x[0]) - 400.0 * x[0] * (x[1] - x[0].powi(2)),
                200.0 * (x[1] - x[0].powi(2)),
            ])
        }
    }

    let result = Executor::new(
        Rosenbrock,
        (GradientDescent::new(1e-3)).with_absolute_gradient_tolerance(1e-6),
        BasicState::new(vec![-1.2, 1.0]),
    )
    .max_iter(50_000)
    .run()
    .unwrap();

    println!(
        "x = {:?}, f = {}, stopped: {:?}",
        result.param(),
        result.cost(),
        result.reason
    );
}

Configure convergence on the solver and execution budgets on the executor. Optional tolerance setters accept a scalar or None; enabled tests usually combine with OR. The old criterion API is deprecated until Basin 2.0. See the convergence migration guide for replacements and numerical conventions.

• First-order, quasi-Newton, and Newton: gradient descent (with momentum and pluggable line searches), SGD, BFGS, L-BFGS, L-BFGS-B, and a Newton trust-region method.
• Derivative-free: Nelder-Mead; Brent, Brent-with-derivatives, and golden-section search (1D); Powell's model-based family (NEWUOA, BOBYQA, LINCOA, COBYLA); and MADS (OrthoMADS).
• Nonlinear least squares: Gauss-Newton, Levenberg-Marquardt, trust-region reflective.
• Global and stochastic: Globalized Bounded Nelder-Mead, simulated annealing, random search, CMA-ES, differential evolution, a steady-state genetic algorithm, and memetic combinations (MA-LS-Chain, plus CMA-ES and DE injection wrappers).
• Constrained: box bounds via projected gradient descent, bounded Nelder-Mead, Globalized Bounded Nelder-Mead, L-BFGS-B, and bounded CMA-ES; LINCOA for linear constraints and COBYLA for nonlinear inequalities; log-barrier and augmented Lagrangian wrappers for more general constraints.
• Root finding: Brent's bracketed scalar method through the direct BrentRoot::solve API.

See Solvers for which backends each one supports.

Parameters and linear algebra are generic over the backend. Vec<f64> needs no features. Each external backend has exact version features and a *_latest alias that tracks the newest supported release:

The original features remain frozen for compatibility: nalgebra selects 0.34, ndarray selects 0.17, and faer selects 0.24. If dependency feature unification enables several releases of the same backend, Basin implements the newest enabled release. First-order and derivative-free solvers run on any backend; linear-algebra-heavy solvers may require a specific one and say so in their docs.

Every nalgebra feature includes its matching nalgebra-sparse release: 0.32/0.9, 0.33/0.10, 0.34/0.11, and 0.35/0.12. Exact acceleration features follow the same naming scheme—nalgebra_v0_34-lapack and ndarray_v0_16-blas, for example. The moving aliases are nalgebra_latest-lapack and ndarray_latest-blas; the original acceleration features remain frozen at nalgebra 0.34 and ndarray 0.17.

BLAS/LAPACK acceleration is off by default and is not wasm-compatible. These features expect you to supply the BLAS/LAPACK symbols at link time. The default build remains wasm-friendly and single-threaded; parallelism is behind the opt-in parallel feature.

If you use Basin in your research, please cite the paper:

Larsson, J. (2026). Basin: Efficient and Extensible Numerical Optimization in Rust (arXiv:2608.11279). arXiv. https://doi.org/10.48550/arXiv.2608.11279

@misc{larsson2026basin,
  title         = {Basin: Efficient and Extensible Numerical Optimization in {{Rust}}},
  shorttitle    = {Basin},
  author        = {Larsson, Johan},
  year          = {2026},
  month         = aug,
  number        = {arXiv:2608.11279},
  eprint        = {2608.11279},
  primaryclass  = {cs.LG},
  publisher     = {arXiv},
  doi           = {10.48550/arXiv.2608.11279},
  archiveprefix = {arXiv}
}

@online{larsson2026basin,
  title       = {Basin: Efficient and Extensible Numerical Optimization in {{Rust}}},
  shorttitle  = {Basin},
  author      = {Larsson, Johan},
  date        = {2026-08-11},
  eprint      = {2608.11279},
  eprinttype  = {arXiv},
  eprintclass = {cs.LG},
  doi         = {10.48550/arXiv.2608.11279},
  pubstate    = {prepublished}
}

CITATION.cff carries the same reference in machine-readable form, and basin.rs/docs renders it in APA, BibTeX, and BibLaTeX.

Basin owes a substantial intellectual debt to argmin: the overall shape of the crate: the Executor driver loop, the Solver/Problem trait split, and per-solver State are borrowed from it, and several solver implementations and test-problem conventions were modeled on argmin's. Thanks to the argmin authors and contributors for a library that is a pleasure to learn from.

The Powell-family derivative-free solvers (COBYLA, NEWUOA, BOBYQA, LINCOA) are derived from PRIMA, Zaikun Zhang's modern-Fortran reference implementation of M. J. D. Powell's methods, used as the authoritative source for the exact formulas and as the cross-validation oracle. PRIMA is distributed under the BSD 3-Clause License; its notice is retained in COPYRIGHT.

The bound-constrained L-BFGS-B solver is a port of the L-BFGS-B version 3.0 Fortran code by Ciyou Zhu, Richard H. Byrd, Peihuang Lu, and Jorge Nocedal (ACM TOMS Algorithm 778), with the v3.0 improvements by José Luis Morales and Jorge Nocedal. It is released under the New BSD (BSD 3-Clause) License; its notice is likewise retained in COPYRIGHT.

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your convenience.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.