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 cartan_manifolds::Sphere;
25//! use cartan_optim::{minimize_rgd, RGDConfig};
26//!
27//! let s2 = Sphere::<3>;
28//! let config = RGDConfig::default();
29//!
30//! // Minimize f(p) = -p[0] (find the "north pole") on S²
31//! let result = minimize_rgd(
32//! &s2,
33//! |p| -p[0],
34//! |p| s2.project_tangent(p, &SVector::from([1.0, 0.0, 0.0])),
35//! p0,
36//! &config,
37//! );
38//! ```
39//!
40//! ## References
41//!
42//! - Absil, Mahony, Sepulchre. "Optimization Algorithms on Matrix Manifolds."
43//! Princeton, 2008.
44//! - Boumal. "An Introduction to Optimization on Smooth Manifolds."
45//! Cambridge, 2023.
46
47pub mod frechet;
48pub mod rcg;
49pub mod result;
50pub mod rgd;
51pub mod rtr;
52
53pub use frechet::{FrechetConfig, frechet_mean};
54pub use rcg::{CgVariant, RCGConfig, minimize_rcg};
55pub use result::OptResult;
56pub use rgd::{RGDConfig, minimize_rgd};
57pub use rtr::{RTRConfig, minimize_rtr};