axiolid_numeric/lib.rs
1#![forbid(unsafe_code)]
2
3//! Shared numeric substrate: root finding, quadrature, dense linear algebra
4//! and least squares, and minimisation over `f64`.
5//!
6//! These are the general numeric routines geometry algorithms build on --
7//! curve and surface fitting, fairing, projection and inversion -- in one
8//! place instead of re-derived inline. The reference designs are OCCT's
9//! `math` package, QUADPACK, Brent (1973) and MINPACK.
10//!
11//! | Need | Routine |
12//! | --- | --- |
13//! | a root of `f` between two points of opposite sign | [`find_root`] |
14//! | every real root of a polynomial in an interval | [`Polynomial::real_roots`] |
15//! | `integral f` with an error estimate | [`integrate`] |
16//! | fixed Gauss rule for an integrand of known degree | [`GaussLegendre`] |
17//! | square system | [`Lu`] |
18//! | symmetric positive definite system | [`Cholesky`] |
19//! | linear least squares, rank | [`Qr`], [`least_squares`] |
20//! | least squares with equality constraints | [`constrained_least_squares`] |
21//! | nonlinear least squares, nonlinear equations | [`levenberg_marquardt`] |
22//! | minimum of `f` on an interval | [`minimize_scalar`] |
23//!
24//! # Contract
25//!
26//! - Non-finite input is refused by name ([`NumericError::NonFiniteInput`]),
27//! as is a non-finite value from a caller's function.
28//! - Every answer says how far it can be trusted: a bracket that contains
29//! the root, an error estimate, a condition estimate, or an explicitly
30//! unresolved region. Which of these is a proven bound and which is an
31//! estimate is stated on each field.
32//! - Iterative routines report a [`Status`]. One that ran out of budget
33//! still returns its best value and estimate; its `converged()` accessor
34//! turns that into [`NumericError::NotConverged`] for callers that only
35//! accept a met tolerance.
36//! - Singular, rank-deficient, non-symmetric and indefinite matrices are
37//! refused, never solved into infinities.
38//!
39//! There are no geometry types here and no dependencies: values are plain
40//! `f64` slices and a small row-major [`Matrix`].
41
42pub mod error;
43pub mod linalg;
44pub mod optimize;
45pub mod poly;
46pub mod quad;
47pub mod root;
48
49pub use error::{NumericError, NumericResult, Status};
50pub use linalg::{
51 constrained_least_squares, least_squares, Cholesky, ConstrainedSolution, LeastSquaresSolution,
52 LinearSolution, Lu, Matrix, Qr,
53};
54pub use optimize::{
55 levenberg_marquardt, minimize_scalar, LeastSquaresMinimum, LevenbergMarquardtOptions,
56 Residuals, ScalarMinimum, Termination,
57};
58pub use poly::{Polynomial, PolynomialRoot, RootKind};
59pub use quad::{integrate, GaussLegendre, Integral, IntegrationOptions};
60pub use root::{find_root, Root};