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