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//! | large sparse symmetric positive definite system | [`conjugate_gradient`] on a [`SparseMatrix`] |
20//! | linear least squares, rank | [`Qr`], [`least_squares`] |
21//! | least squares with equality constraints | [`constrained_least_squares`] |
22//! | nonlinear least squares, nonlinear equations | [`levenberg_marquardt`] |
23//! | minimum of `f` on an interval | [`minimize_scalar`] |
24//!
25//! # Contract
26//!
27//! - Non-finite input is refused by name ([`NumericError::NonFiniteInput`]),
28//! as is a non-finite value from a caller's function.
29//! - Every answer says how far it can be trusted: a bracket that contains
30//! the root, an error estimate, a condition estimate, or an explicitly
31//! unresolved region. Which of these is a proven bound and which is an
32//! estimate is stated on each field.
33//! - Iterative routines report a [`Status`]. One that ran out of budget
34//! still returns its best value and estimate; its `converged()` accessor
35//! turns that into [`NumericError::NotConverged`] for callers that only
36//! accept a met tolerance.
37//! - Singular, rank-deficient, non-symmetric and indefinite matrices are
38//! refused, never solved into infinities.
39//!
40//! There are no geometry types here and no dependencies: values are plain
41//! `f64` slices, a small row-major [`Matrix`] and a compressed-row
42//! [`SparseMatrix`].
43
44pub mod error;
45pub mod linalg;
46pub mod optimize;
47pub mod poly;
48pub mod quad;
49pub mod root;
50pub mod sparse;
51
52pub use error::{NumericError, NumericResult, Status};
53pub use linalg::{
54 constrained_least_squares, least_squares, Cholesky, ConstrainedSolution, LeastSquaresSolution,
55 LinearSolution, Lu, Matrix, Qr,
56};
57pub use optimize::{
58 levenberg_marquardt, minimize_scalar, LeastSquaresMinimum, LevenbergMarquardtOptions,
59 Residuals, ScalarMinimum, Termination,
60};
61pub use poly::{Polynomial, PolynomialRoot, RootKind};
62pub use quad::{integrate, GaussLegendre, Integral, IntegrationOptions};
63pub use root::{find_root, Root};
64pub use sparse::{
65 conjugate_gradient, ConjugateGradientOptions, ConjugateGradientSolution, SparseMatrix,
66};