argmin/lib.rs
1// Copyright 2018-2024 argmin developers
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
5// http://opensource.org/licenses/MIT>, at your option. This file may not be
6// copied, modified, or distributed except according to those terms.
7
8//! argmin is a numerical optimization library written entirely in Rust.
9//!
10//! Its goal is to offer a wide range of optimization algorithms with a consistent interface.
11//! It is type-agnostic by design, meaning that any type and/or math backend, such as
12//! `nalgebra` or `ndarray`, can be used -- even your own.
13//!
14//! Observers allow one to track the progress of iterations, either by using one of the provided
15//! ones for logging to screen or disk or by implementing your own.
16//!
17//! An optional checkpointing mechanism helps to mitigate the negative effects of crashes in
18//! unstable computing environments.
19//!
20//! Due to Rusts powerful generics and traits, most features can be exchanged by your own tailored
21//! implementations.
22//!
23//! argmin is designed to simplify the implementation of optimization algorithms and as such can
24//! also be used as a toolbox for the development of new algorithms. One can focus on the algorithm
25//! itself, while the handling of termination, parameter vectors, populations, gradients, Jacobians
26//! and Hessians is taken care of by the library.
27//!
28//! For an introduction on how to use argmin, please also have a look at the
29//! [book](https://www.argmin-rs.org/book/).
30//!
31//! # Highlights
32//!
33//! * [Checkpointing](`crate::core::checkpointing`)
34//! * [Observers](`crate::core::observers`)
35//!
36//!
37//! # Algorithms
38//!
39//! - [Line searches](`crate::solver::linesearch`)
40//! - [Backtracking line search](`crate::solver::linesearch::BacktrackingLineSearch`)
41//! - [More-Thuente line search](`crate::solver::linesearch::MoreThuenteLineSearch`)
42//! - [Hager-Zhang line search](`crate::solver::linesearch::HagerZhangLineSearch`)
43//!
44//! - [Trust region method](`crate::solver::trustregion::TrustRegion`)
45//! - [Cauchy point method](`crate::solver::trustregion::CauchyPoint`)
46//! - [Dogleg method](`crate::solver::trustregion::Dogleg`)
47//! - [Steihaug method](`crate::solver::trustregion::Steihaug`)
48//!
49//! - [Steepest descent](`crate::solver::gradientdescent::SteepestDescent`)
50//!
51//! - [Conjugate gradient methods](`crate::solver::conjugategradient`)
52//! - [Conjugate gradient method](`crate::solver::conjugategradient::ConjugateGradient`)
53//! - [Nonlinear conjugate gradient method](`crate::solver::conjugategradient::NonlinearConjugateGradient`)
54//!
55//! - [Newton methods](`crate::solver::newton`)
56//! - [Newton's method](`crate::solver::newton::Newton`)
57//! - [Newton-CG](solver/newton/newton_cg/struct.NewtonCG.html)
58//!
59//! - [Quasi-Newton methods](`crate::solver::quasinewton`)
60//! - [BFGS](`crate::solver::quasinewton::BFGS`)
61//! - [L-BFGS](`crate::solver::quasinewton::LBFGS`)
62//! - [DFP](`crate::solver::quasinewton::DFP`)
63//! - [SR1](`crate::solver::quasinewton::SR1`)
64//! - [SR1-TrustRegion](`crate::solver::quasinewton::SR1TrustRegion`)
65//!
66//! - [Gauss-Newton methods](`crate::solver::gaussnewton`)
67//! - [Gauss-Newton method](`crate::solver::gaussnewton::GaussNewton`)
68//! - [Gauss-Newton method with linesearch](`crate::solver::gaussnewton::GaussNewtonLS`)
69//!
70//! - [Golden-section search](`crate::solver::goldensectionsearch::GoldenSectionSearch`)
71//!
72//! - [Landweber iteration](`crate::solver::landweber::Landweber`)
73//!
74//! - [Brent's methods](`crate::solver::brent`)
75//! - [Brent's minimization method](`crate::solver::brent::BrentOpt`)
76//! - [Brent's root finding method](`crate::solver::brent::BrentRoot`)
77//!
78//! - [Nelder-Mead method](`crate::solver::neldermead::NelderMead`)
79//!
80//! - [Simulated Annealing](`crate::solver::simulatedannealing::SimulatedAnnealing`)
81//!
82//! - [Particle Swarm Optimization](`crate::solver::particleswarm::ParticleSwarm`)
83//!
84//! ## External solvers compatible with argmin
85//!
86//! External solvers which implement the `Solver` trait are compatible with argmins `Executor`,
87//! and as such can leverage features like checkpointing and observers.
88//!
89//! - [egobox](https://crates.io/crates/egobox-ego)
90//! - [cobyla](https://crates.io/crates/cobyla)
91//!
92//! # License
93//!
94//! Licensed under either of
95//!
96//! * Apache License, Version 2.0,
97//! ([LICENSE-APACHE](https://github.com/argmin-rs/argmin/blob/main/LICENSE-APACHE) or
98//! <http://www.apache.org/licenses/LICENSE-2.0>)
99//! * MIT License ([LICENSE-MIT](https://github.com/argmin-rs/argmin/blob/main/LICENSE-MIT) or
100//! <http://opensource.org/licenses/MIT>)
101//!
102//! at your option.
103//!
104//! ## Contribution
105//!
106//! Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion
107//! in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above,
108//! without any additional terms or conditions.
109
110#![warn(missing_docs)]
111#![allow(unused_attributes)]
112// Explicitly disallow EQ comparison of floats. (This clippy lint is denied by default; however,
113// this is just to make sure that it will always stay this way.)
114#![deny(clippy::float_cmp)]
115// Some types just are complex
116#![allow(clippy::type_complexity)]
117
118#[macro_use]
119pub mod core;
120
121/// Solvers
122pub mod solver;
123
124#[cfg(test)]
125#[cfg(feature = "_ndarrayl")]
126mod tests;