Expand description
basin — a numerical optimization library.
The framework lives in core: problem traits the user implements
(CostFunction, Gradient, BoxConstraints,
LinearInequalityConstraints, LinearEqualityConstraints), state shapes
solvers iterate over (State, GradientState, SimplexState),
the Solver trait, and a pluggable termination layer
(TerminationCriterion). Concrete solvers are in solver;
line searches in line_search.
Start at Executor for the user-facing driver, or core for the
trait taxonomy and the iteration-loop contract.
See AGENTS.md at the repo root for the design tenets that shape
these APIs (notably tenet 3 on framework-level termination, tenet 4
on first-class constraints, and tenet 5 on backend tiering).
§Example
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, GradientTolerance};
struct Sphere;
impl CostFunction for Sphere {
type Param = Vec<f64>;
type Output = f64;
fn cost(&self, x: &Vec<f64>) -> f64 {
x.iter().map(|xi| xi * xi).sum()
}
}
impl Gradient for Sphere {
type Param = Vec<f64>;
type Gradient = Vec<f64>;
fn gradient(&self, x: &Vec<f64>) -> Vec<f64> {
x.iter().map(|xi| 2.0 * xi).collect()
}
}
let result = Executor::new(Sphere, GradientDescent::new(0.1), BasicState::new(vec![1.0, 1.0]))
.max_iter(1_000)
.terminate_on(GradientTolerance(1e-8))
.run();
assert!(result.cost() < 1e-12);Re-exports§
pub use crate::core::augmented_lagrangian::AugmentedLagrangian;pub use crate::core::barrier::LogBarrier;pub use crate::core::constraint::BoxConstraints;pub use crate::core::constraint::LinearEqualityConstraints;pub use crate::core::constraint::LinearInequalityConstraints;pub use crate::core::executor::run_loop;pub use crate::core::executor::Executor;pub use crate::core::executor::OptimizationResult;pub use crate::core::executor::StepOutcome;pub use crate::core::executor::Stepper;pub use crate::core::inner::InnerExecutor;pub use crate::core::inner::WarmStart;pub use crate::core::math::AddDiagonalInPlace;pub use crate::core::math::AddDiagonalVectorInPlace;pub use crate::core::math::BoxAffineScaling;pub use crate::core::math::ClampInPlace;pub use crate::core::math::DenseMatrix;pub use crate::core::math::DenseMatrixFromFn;pub use crate::core::math::Dot;pub use crate::core::math::GramMatrix;pub use crate::core::math::LinearSolveError;pub use crate::core::math::LinearSolveSpd;pub use crate::core::math::MatTransposeVec;pub use crate::core::math::MatVec;pub use crate::core::math::MaxDiagonal;pub use crate::core::math::NegInPlace;pub use crate::core::math::NormInfinity;pub use crate::core::math::NormSquared;pub use crate::core::math::SampleUniformBox;pub use crate::core::math::ScaledAdd;pub use crate::core::math::VectorIndex;pub use crate::core::numdiff::central_difference_gradient;pub use crate::core::numdiff::central_difference_hessian;pub use crate::core::numdiff::central_difference_jacobian;pub use crate::core::numdiff::forward_difference_gradient;pub use crate::core::numdiff::forward_difference_hessian;pub use crate::core::numdiff::forward_difference_jacobian;pub use crate::core::numdiff::FiniteDiff;pub use crate::core::numdiff::Method;pub use crate::core::problem::CostFunction;pub use crate::core::problem::Gradient;pub use crate::core::problem::Hessian;pub use crate::core::problem::Jacobian;pub use crate::core::problem::Residual;pub use crate::core::solver::Solver;pub use crate::core::state::QuasiNewtonState;pub use crate::core::state::BasicPopulationState;pub use crate::core::state::BasicSimplexState;pub use crate::core::state::BasicState;pub use crate::core::state::GradientState;pub use crate::core::state::IntoInitialSimplex;pub use crate::core::state::LbfgsState;pub use crate::core::state::PopulationState;pub use crate::core::state::SimplexState;pub use crate::core::state::State;pub use crate::core::termination::CostTolerance;pub use crate::core::termination::GradientTolerance;pub use crate::core::termination::MaxCostEvals;pub use crate::core::termination::MaxGradientEvals;pub use crate::core::termination::MaxIter;pub use crate::core::termination::MaxTime;pub use crate::core::termination::ParamTolerance;pub use crate::core::termination::ProjectedGradientTolerance;pub use crate::core::termination::RelativeCostTolerance;pub use crate::core::termination::RelativeGradientTolerance;pub use crate::core::termination::RelativeParamTolerance;pub use crate::core::termination::SimplexTolerance;pub use crate::core::termination::TerminationCriterion;pub use crate::core::termination::TerminationReason;pub use crate::line_search::Backtracking;pub use crate::line_search::Constant;pub use crate::line_search::LineSearch;pub use crate::line_search::LineSearchResult;pub use crate::line_search::MoreThuente;pub use crate::line_search::Wolfe;pub use crate::solver::lbfgs::LBFGS;pub use crate::solver::lbfgs::LBFGSB;pub use crate::solver::BFGS;pub use crate::solver::AugmentedLagrangianMethod;pub use crate::solver::BarrierMethod;pub use crate::solver::BoundedCmaEs;pub use crate::solver::BoundedCmaInject;pub use crate::solver::Brent;pub use crate::solver::ClosureInner;pub use crate::solver::CmaEs;pub use crate::solver::CmaInject;pub use crate::solver::GaussNewton;pub use crate::solver::GradientDescent;pub use crate::solver::LevenbergMarquardt;pub use crate::solver::MaLsChCma;pub use crate::solver::MaLsChState;pub use crate::solver::MemeticInner;pub use crate::solver::NelderMead;pub use crate::solver::ProjectedGradientDescent;pub use crate::solver::RandomSearch;pub use crate::solver::Ssga;pub use crate::solver::Trf;
Modules§
- core
- Framework: traits, state shapes, the iteration driver, and the termination layer. The slot taxonomy is:
- line_
search - Line searches: produce a step size
αalong a caller-supplied descent direction. Used by first-order solvers (gradient descent, BFGS). - problems
problems - Catalogue of test problems used by the example tests and benchmarks. Standard optimization test problems.
- solver
- Concrete solver implementations.