cartan_optim/lib.rs
1// ~/cartan/cartan-optim/src/lib.rs
2
3//! # cartan-optim
4//!
5//! Riemannian optimization algorithms for the cartan library.
6//!
7//! This crate implements first- and second-order optimization algorithms that
8//! operate on any manifold implementing the `Manifold` trait from `cartan-core`.
9//!
10//! ## Algorithms
11//!
12//! | Algorithm | Struct/function | Trait requirements |
13//! |-----------|----------------|--------------------|
14//! | Riemannian Gradient Descent | [`minimize_rgd`] | `Manifold + Retraction` |
15//! | Riemannian Conjugate Gradient | [`minimize_rcg`] | `+ ParallelTransport` |
16//! | Fréchet Mean (Karcher flow) | [`frechet_mean`] | `Manifold` |
17//! | Riemannian Trust Region | [`minimize_rtr`] | `+ Connection` |
18//!
19//! ## Usage pattern
20//!
21//! ```rust,ignore
22//! use cartan_manifolds::Sphere;
23//! use cartan_optim::{minimize_rgd, RGDConfig};
24//!
25//! let s2 = Sphere::<3>;
26//! let config = RGDConfig::default();
27//!
28//! // Minimize f(p) = -p[0] (find the "north pole") on S²
29//! let result = minimize_rgd(
30//! &s2,
31//! |p| -p[0],
32//! |p| s2.project_tangent(p, &SVector::from([1.0, 0.0, 0.0])),
33//! p0,
34//! &config,
35//! );
36//! ```
37//!
38//! ## References
39//!
40//! - Absil, Mahony, Sepulchre. "Optimization Algorithms on Matrix Manifolds."
41//! Princeton, 2008.
42//! - Boumal. "An Introduction to Optimization on Smooth Manifolds."
43//! Cambridge, 2023.
44
45pub mod frechet;
46pub mod rcg;
47pub mod result;
48pub mod rgd;
49pub mod rtr;
50
51pub use frechet::{frechet_mean, FrechetConfig};
52pub use rcg::{minimize_rcg, CgVariant, RCGConfig};
53pub use result::OptResult;
54pub use rgd::{minimize_rgd, RGDConfig};
55pub use rtr::{minimize_rtr, RTRConfig};