cartan 0.1.7__tar.gz

cartan-0.1.7/Cargo.toml

@@ -0,0 +1,36 @@
+[workspace]
+resolver = "2"
+members = [
+    "cartan",
+    "cartan-core",
+    "cartan-manifolds",
+    "cartan-optim",
+    "cartan-geo",
+    "cartan-dec",
+]
+exclude = ["experiments", "cartan-py"]
+
+[workspace.package]
+version = "0.1.7"
+edition = "2024"
+rust-version = "1.85"
+license = "MIT"
+repository = "https://github.com/alejandro-soto-franco/cartan"
+keywords = ["riemannian", "manifold", "optimization", "geometry", "geodesic"]
+categories = ["mathematics", "science", "algorithms"]
+
+[workspace.dependencies]
+nalgebra = { version = "0.33", default-features = false }
+rand = { version = "0.9", default-features = false }
+rand_distr = { version = "0.5", default-features = false }
+rayon = { version = "1" }
+thiserror = { version = "2", default-features = false }
+serde = { version = "1", features = ["derive"], default-features = false }
+serde_json = { version = "1", default-features = false }
+approx = { version = "0.5", default-features = false }
+hashbrown = { version = "0.15", default-features = false }
+
+[profile.release]
+opt-level = 3
+lto = "thin"     # fat LTO was causing OOM on 30 GB machine; thin cuts linker peak ~5-10x
+codegen-units = 4  # default is 16; lower = less parallel RAM, better optimization

cartan-0.1.7/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: cartan
+Version: 0.1.7
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Dist: numpy>=1.20
+Requires-Dist: scipy>=1.7 ; extra == 'dec'
+Requires-Dist: pytest ; extra == 'dev'
+Requires-Dist: hypothesis ; extra == 'dev'
+Requires-Dist: scipy>=1.7 ; extra == 'dev'
+Provides-Extra: dec
+Provides-Extra: dev
+Summary: Python bindings for the cartan Riemannian geometry library
+License: MIT
+Requires-Python: >=3.9

cartan-0.1.7/cartan-core/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "cartan-core"
+description = "Core traits for Riemannian geometry: Manifold, Retraction, ParallelTransport, Curvature"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+keywords = ["riemannian", "manifold", "geometry", "traits", "geodesic"]
+categories = ["mathematics", "science", "algorithms"]
+documentation = "https://docs.rs/cartan-core"
+homepage = "https://cartan.sotofranco.dev"
+
+[features]
+default = ["std"]
+std = ["alloc", "rand/std"]
+alloc = ["rand/alloc"]
+
+[dependencies]
+rand = { workspace = true, default-features = false }
+# libm provides `sqrt` and other float math in no_std environments.
+# Always present; only used when `std` feature is disabled.
+libm = { version = "0.2", default-features = false }
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

cartan-0.1.7/cartan-core/src/connection.rs

@@ -0,0 +1,73 @@
+// ~/cartan/cartan-core/src/connection.rs
+
+//! The `Connection` trait: Riemannian Hessian-vector products.
+//!
+//! The Levi-Civita connection on a Riemannian manifold provides a notion
+//! of "derivative of a vector field along a curve." For optimization, the
+//! key application is computing the Riemannian Hessian of a cost function,
+//! or more precisely, Hessian-vector products (HVPs) needed by second-order
+//! methods like Riemannian trust region and Riemannian Newton.
+//!
+//! ## Hessian-vector products
+//!
+//! Given a smooth cost function f: M -> R, the Riemannian Hessian at p
+//! is a symmetric bilinear form on T_pM. For trust region methods, we need
+//! H\[v\] = Hess f(p)\[v\], the action of the Hessian on a tangent vector v.
+//!
+//! For a Riemannian manifold embedded in Euclidean space, the Riemannian HVP
+//! can be computed from the Euclidean Hessian as:
+//!
+//!   Hess f(p)\[v\] = proj_T( D^2 f(p)\[v\] - II(grad f, v) )
+//!
+//! where II is the second fundamental form (shape operator), and proj_T is
+//! the projection onto the tangent space.
+//!
+//! Alternatively, for cost functions defined via retraction, one uses the
+//! differentiated retraction formula from Absil-Mahony-Sepulchre Ch. 5.
+//!
+//! ## References
+//!
+//! - Absil, Mahony, Sepulchre. "Optimization Algorithms on Matrix Manifolds."
+//!   Princeton, 2008. Chapter 5 (Riemannian Hessian and trust region).
+//! - Boumal. "An Introduction to Optimization on Smooth Manifolds."
+//!   Cambridge, 2023. Chapter 6 (connections and Hessian).
+//! - do Carmo. "Riemannian Geometry." Chapter 2 (Levi-Civita connection).
+
+use crate::{CartanError, Manifold};
+
+/// A manifold with a compatible Levi-Civita connection.
+///
+/// Implement this trait to enable second-order optimization methods
+/// (trust region, Newton) that require Riemannian Hessian-vector products.
+///
+/// # Supertraiting Manifold
+///
+/// Connection requires Self: Manifold to ensure that the manifold has
+/// the full geometric structure (exp, log, inner, project) before adding
+/// the connection. The Levi-Civita connection depends on the metric, so
+/// this dependency is semantically required, not just a convenience.
+pub trait Connection: Manifold {
+    /// Riemannian Hessian-vector product: Hess f(p)\[v\].
+    ///
+    /// Given:
+    /// - p: a point on the manifold
+    /// - grad_f: the Riemannian gradient of f at p (a tangent vector in T\_pM)
+    /// - v: a tangent vector in T\_pM (the direction for the HVP)
+    /// - hess_ambient: a callback that computes the Euclidean Hessian-vector
+    ///   product H\_eucl\[v\] = D^2 f(p)\[v\] in ambient coordinates
+    ///
+    /// Returns Hess f(p)\[v\] in T\_pM.
+    ///
+    /// The `hess_ambient` callback takes a tangent vector in ambient coordinates
+    /// and returns the ambient Euclidean HVP. This avoids the need to explicitly
+    /// construct the full Hessian matrix (which is expensive for large N).
+    ///
+    /// Ref: Absil-Mahony-Sepulchre, Chapter 5, Proposition 5.3.2.
+    fn riemannian_hessian_vector_product(
+        &self,
+        p: &Self::Point,
+        grad_f: &Self::Tangent,
+        v: &Self::Tangent,
+        hess_ambient: &dyn Fn(&Self::Tangent) -> Self::Tangent,
+    ) -> Result<Self::Tangent, CartanError>;
+}

cartan-0.1.7/cartan-core/src/curvature.rs

@@ -0,0 +1,142 @@
+// ~/cartan/cartan-core/src/curvature.rs
+
+//! The `Curvature` trait: Riemann curvature tensor and derived quantities.
+//!
+//! Riemannian curvature measures how much the manifold deviates from being
+//! flat. It appears in:
+//! - Geodesic deviation (Jacobi equation)
+//! - Error bounds for optimization algorithms (convergence rates depend on
+//!   sectional curvature bounds)
+//! - Comparison geometry (Toponogov's theorem, Bishop-Gromov volume comparison)
+//!
+//! ## Curvature quantities
+//!
+//! Starting from the Riemann curvature tensor R(X, Y)Z (a (1,3)-tensor),
+//! one derives:
+//!
+//! - **Sectional curvature** K(sigma) for a 2-plane sigma = span{X, Y}:
+//!   K(sigma) = <R(X,Y)Y, X> / (<X,X><Y,Y> - <X,Y>^2).
+//!   Controls geodesic spreading: K > 0 makes geodesics converge (sphere),
+//!   K < 0 makes them diverge (hyperbolic space), K = 0 flat (Euclidean).
+//!
+//! - **Ricci curvature** Ric(X, Y): trace of Z -> R(Z, X)Y.
+//!   Appears in volume comparison and Ricci flow.
+//!
+//! - **Scalar curvature** s: trace of the Ricci tensor.
+//!
+//! ## Known values for v0.1 manifolds
+//!
+//! - Sphere S^{N-1}: K = 1 (constant sectional curvature)
+//! - Hyperbolic H^N: K = -1 (constant sectional curvature)
+//! - SO(N) (bi-invariant): K(X,Y) = (1/4)||\[X,Y\]||^2 / (||X||^2 ||Y||^2 - <X,Y>^2)
+//! - SPD(N) (affine-invariant): K <= 0 (non-positive, Cartan-Hadamard manifold)
+//! - Grassmann Gr(n,k): 0 <= K <= 2 (between 0 and 2)
+//! - Euclidean R^N: K = 0 everywhere
+//!
+//! ## References
+//!
+//! - do Carmo. "Riemannian Geometry." Chapter 4 (curvature tensor), Chapter 5 (sectional).
+//! - Milnor. "Curvatures of Left-Invariant Metrics on Lie Groups." Advances in Math, 1976.
+//! - Bhatia. "Positive Definite Matrices." Princeton, 2007. Chapter 6 (curvature of SPD).
+
+use crate::Real;
+use crate::connection::Connection;
+
+/// A manifold with explicitly computable Riemannian curvature.
+///
+/// This trait provides the Riemann curvature tensor and derived scalar
+/// quantities. It is useful for:
+/// - Theoretical analysis (verifying curvature bounds for convergence proofs)
+/// - Geodesic deviation simulation (Jacobi fields)
+/// - Visualization (sectional curvature plots)
+///
+/// # Supertraiting Connection
+///
+/// Curvature requires Self: Connection because the curvature tensor is defined
+/// via the Levi-Civita connection: R(X,Y)Z = nabla_X nabla_Y Z - nabla_Y nabla_X Z
+/// - nabla_{\[X,Y\]} Z. Without the connection, curvature cannot be defined.
+pub trait Curvature: Connection {
+    /// The Riemann curvature tensor: R(u, v)w.
+    ///
+    /// Takes three tangent vectors u, v, w at p and returns a tangent vector
+    /// at p. Defined via the Levi-Civita connection as:
+    ///
+    ///   R(u,v)w = nabla_u nabla_v w - nabla_v nabla_u w - nabla_{\[u,v\]} w
+    ///
+    /// Properties:
+    /// - Anti-symmetry: R(u,v)w = -R(v,u)w
+    /// - First Bianchi identity: R(u,v)w + R(v,w)u + R(w,u)v = 0
+    /// - Symmetry: <R(u,v)w, z> = <R(w,z)u, v>
+    ///
+    /// Ref: do Carmo, Chapter 4, Definition 1.
+    fn riemann_curvature(
+        &self,
+        p: &Self::Point,
+        u: &Self::Tangent,
+        v: &Self::Tangent,
+        w: &Self::Tangent,
+    ) -> Self::Tangent;
+
+    /// Sectional curvature of the 2-plane spanned by u and v at p.
+    ///
+    /// K(u, v) = <R(u,v)v, u>_p / (<u,u>_p <v,v>_p - <u,v>_p^2)
+    ///
+    /// The denominator is the squared area of the parallelogram spanned by u, v.
+    /// This quantity is well-defined only when u and v are linearly independent.
+    ///
+    /// The default implementation computes this from riemann_curvature() and inner().
+    /// Manifolds with closed-form sectional curvature (sphere, hyperbolic) should
+    /// override this with a direct formula to avoid the overhead of computing the
+    /// full curvature tensor.
+    fn sectional_curvature(&self, p: &Self::Point, u: &Self::Tangent, v: &Self::Tangent) -> Real {
+        // Numerator: <R(u,v)v, u>_p
+        // This is the standard formula for sectional curvature.
+        let r_uvv = self.riemann_curvature(p, u, v, v);
+        let numerator = self.inner(p, u, &r_uvv);
+
+        // Denominator: ||u||^2 ||v||^2 - <u,v>^2
+        // This is the squared area of the parallelogram (= 0 iff u,v are parallel).
+        let uu = self.inner(p, u, u);
+        let vv = self.inner(p, v, v);
+        let uv = self.inner(p, u, v);
+        let denominator = uu * vv - uv * uv;
+
+        // Guard against degenerate planes: if u and v are (nearly) parallel,
+        // the 2-plane is degenerate and sectional curvature is undefined.
+        // Return 0.0 instead of NaN/Inf to avoid poisoning downstream computations.
+        // Callers who need to distinguish this case should check the denominator
+        // (area of the parallelogram) before calling sectional_curvature.
+        if denominator.abs() < 1e-20 {
+            return 0.0;
+        }
+
+        numerator / denominator
+    }
+
+    /// Ricci curvature tensor applied to tangent vectors u and v: Ric(u, v).
+    ///
+    /// The Ricci tensor is the trace of the full curvature tensor:
+    ///   Ric(u, v) = sum_{i=1}^{n} <R(e_i, u)v, e_i>
+    /// where {e_i} is an orthonormal basis for T_p M.
+    ///
+    /// Implementations should compute this directly for each manifold
+    /// rather than summing over an explicit basis (which requires O(n)
+    /// curvature evaluations).
+    ///
+    /// Known values:
+    /// - Sphere S^{N-1}: Ric(u,v) = (N-2) <u,v>
+    /// - SO(N): Ric(u,v) = (N-2)/4 * <u,v>  (for N >= 3)
+    /// - Euclidean: Ric = 0
+    fn ricci_curvature(&self, p: &Self::Point, u: &Self::Tangent, v: &Self::Tangent) -> Real;
+
+    /// Scalar curvature at p.
+    ///
+    /// The scalar curvature is the trace of the Ricci tensor:
+    ///   s(p) = sum_{i=1}^{n} Ric(e_i, e_i)
+    /// where {e_i} is an orthonormal basis for T_p M.
+    ///
+    /// Known values (dimension n):
+    /// - Sphere S^{N-1} (n = N-1): s = (N-1)(N-2)
+    /// - Euclidean: s = 0
+    fn scalar_curvature(&self, p: &Self::Point) -> Real;
+}

cartan-0.1.7/cartan-core/src/error.rs

@@ -0,0 +1,134 @@
+// ~/cartan/cartan-core/src/error.rs
+
+//! Error types for cartan operations.
+//!
+//! CartanError covers all failure modes in Riemannian geometry computations:
+//! logarithmic map failures at cut loci, numerical breakdowns in matrix
+//! decompositions, constraint violations, and optimizer convergence failures.
+
+use core::fmt;
+
+use crate::Real;
+
+/// The unified error type for all cartan operations.
+///
+/// Each variant captures a specific class of failure with enough context
+/// to diagnose the problem. Mathematical operations that can fail (log map,
+/// parallel transport across cut locus, Cholesky of near-singular matrix)
+/// return Result<T, CartanError>.
+///
+/// Under `no_alloc`, message fields are `&'static str` (no heap).
+/// Under `alloc` or `std`, message fields are `String` (rich formatting).
+#[derive(Debug, Clone)]
+pub enum CartanError {
+    /// Log map failed: point is on or near the cut locus.
+    ///
+    /// On the sphere, this means the two points are nearly antipodal.
+    /// On SO(n), this means the rotation angle is near pi.
+    /// On Cartan-Hadamard manifolds (SPD, Hyperbolic), this should
+    /// never occur since the cut locus is empty.
+    CutLocus {
+        #[cfg(feature = "alloc")]
+        message: alloc::string::String,
+        #[cfg(not(feature = "alloc"))]
+        message: &'static str,
+    },
+
+    /// A matrix decomposition or numerical computation failed.
+    ///
+    /// Examples: Cholesky on a matrix that lost positive-definiteness
+    /// due to roundoff, SVD that did not converge, matrix logarithm
+    /// of a matrix with negative eigenvalues.
+    NumericalFailure {
+        #[cfg(feature = "alloc")]
+        operation: alloc::string::String,
+        #[cfg(feature = "alloc")]
+        message: alloc::string::String,
+        #[cfg(not(feature = "alloc"))]
+        operation: &'static str,
+        #[cfg(not(feature = "alloc"))]
+        message: &'static str,
+    },
+
+    /// Point does not satisfy the manifold constraint.
+    ///
+    /// The `constraint` field describes what was checked (e.g., "||p|| = 1"
+    /// for the sphere), and `violation` gives the magnitude of the deviation.
+    NotOnManifold {
+        #[cfg(feature = "alloc")]
+        constraint: alloc::string::String,
+        #[cfg(not(feature = "alloc"))]
+        constraint: &'static str,
+        violation: Real,
+    },
+
+    /// Tangent vector is not in the tangent space at the given point.
+    ///
+    /// The `constraint` field describes the tangent space condition
+    /// (e.g., "p^T v = 0" for the sphere).
+    NotInTangentSpace {
+        #[cfg(feature = "alloc")]
+        constraint: alloc::string::String,
+        #[cfg(not(feature = "alloc"))]
+        constraint: &'static str,
+        violation: Real,
+    },
+
+    /// Line search failed to find a step size satisfying the Armijo condition.
+    LineSearchFailed { steps_tried: usize },
+
+    /// Optimizer did not converge within the maximum number of iterations.
+    ConvergenceFailure {
+        iterations: usize,
+        gradient_norm: Real,
+    },
+}
+
+impl fmt::Display for CartanError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            CartanError::CutLocus { message } => {
+                write!(f, "cut locus: {}", message)
+            }
+            CartanError::NumericalFailure { operation, message } => {
+                write!(f, "numerical failure in {}: {}", operation, message)
+            }
+            CartanError::NotOnManifold {
+                constraint,
+                violation,
+            } => {
+                write!(
+                    f,
+                    "point not on manifold: {} violated by {}",
+                    constraint, violation
+                )
+            }
+            CartanError::NotInTangentSpace {
+                constraint,
+                violation,
+            } => {
+                write!(
+                    f,
+                    "tangent vector not in tangent space: {} violated by {}",
+                    constraint, violation
+                )
+            }
+            CartanError::LineSearchFailed { steps_tried } => {
+                write!(f, "line search failed after {} steps", steps_tried)
+            }
+            CartanError::ConvergenceFailure {
+                iterations,
+                gradient_norm,
+            } => {
+                write!(
+                    f,
+                    "optimizer did not converge after {} iterations (gradient norm: {:.2e})",
+                    iterations, gradient_norm
+                )
+            }
+        }
+    }
+}
+
+#[cfg(feature = "std")]
+impl std::error::Error for CartanError {}

cartan-0.1.7/cartan-core/src/geodesic.rs

@@ -0,0 +1,76 @@
+// ~/cartan/cartan-core/src/geodesic.rs
+
+//! The `GeodesicInterpolation` trait: sampling points along geodesics.
+//!
+//! Geodesic interpolation provides a way to move continuously between
+//! two points on a manifold along the shortest path (minimizing geodesic).
+//! This is the manifold analogue of linear interpolation in Euclidean space.
+//!
+//! ## Definition
+//!
+//! Given points p, q in M and parameter t in [0, 1], the geodesic
+//! interpolation gamma(p, q, t) is defined as:
+//!
+//!   gamma(p, q, t) = Exp_p(t * Log_p(q))
+//!
+//! Properties:
+//!   gamma(p, q, 0) = p
+//!   gamma(p, q, 1) = q
+//!   d/dt gamma(p, q, t)|_{t=0} = Log_p(q)  (initial velocity)
+//!
+//! ## Applications
+//!
+//! - Frechet mean computation (iterative: barycenter in T_pM)
+//! - Geodesic grid generation for visualization
+//! - Midpoint computation (t = 0.5) for Riemannian bisection
+//! - Slerp generalization (spherical: reduces to standard slerp)
+//!
+//! ## Failure modes
+//!
+//! Like Log_p(q), geodesic interpolation fails at the cut locus. The
+//! method returns an error rather than panicking, allowing callers to
+//! detect and handle this case (e.g., by using a retraction-based fallback).
+//!
+//! ## References
+//!
+//! - do Carmo. "Riemannian Geometry." Chapter 3 (geodesics).
+//! - Pennec, Fillard, Ayache. "A Riemannian Framework for Tensor Computing."
+//!   IJCV, 2006. Section 3.2 (geodesic interpolation for SPD matrices).
+
+use crate::{CartanError, Manifold};
+
+/// A manifold with geodesic interpolation between points.
+///
+/// The geodesic interpolation gamma(p, q, t) = Exp_p(t * Log_p(q))
+/// parameterizes the unique minimizing geodesic from p to q (when it exists).
+///
+/// # Supertraiting Manifold
+///
+/// GeodesicInterpolation requires Self: Manifold because it is defined
+/// via exp and log. A default implementation could be provided here using
+/// self.exp(p, self.log(p, q)? * t), but we leave it as an abstract method
+/// to allow manifolds to provide more numerically stable implementations
+/// (e.g., direct formula on the sphere using sin/cos).
+pub trait GeodesicInterpolation: Manifold {
+    /// Interpolate along the geodesic from p to q at parameter t.
+    ///
+    /// For t = 0: returns p.
+    /// For t = 1: returns q.
+    /// For t = 0.5: returns the geodesic midpoint.
+    /// For t outside \[0,1\]: extrapolates along the geodesic (valid if
+    ///   t * dist(p, q) < injectivity_radius(p)).
+    ///
+    /// Fails if Log_p(q) fails (p and q are at or beyond the cut locus).
+    ///
+    /// # Arguments
+    ///
+    /// - `p`: starting point
+    /// - `q`: ending point
+    /// - `t`: interpolation parameter (0 = start, 1 = end, 0.5 = midpoint)
+    fn geodesic(
+        &self,
+        p: &Self::Point,
+        q: &Self::Point,
+        t: crate::Real,
+    ) -> Result<Self::Point, CartanError>;
+}

cartan-0.1.7/cartan-core/src/lib.rs

@@ -0,0 +1,58 @@
+// ~/cartan/cartan-core/src/lib.rs
+
+//! # cartan-core
+//!
+//! Core trait definitions for Riemannian geometry.
+//!
+//! This crate defines the foundational traits that all cartan manifolds,
+//! optimizers, and tools depend on. It has minimal dependencies (only `rand`
+//! for the Rng trait bound) and can be used standalone by downstream crates
+//! that want to implement custom manifolds against the cartan trait system.
+//!
+//! ## Trait hierarchy
+//!
+//! ```text
+//! Manifold (base: exp, log, inner, project, validate)
+//!   |
+//!   +-- Retraction (cheaper exp approximation)
+//!   +-- ParallelTransport -> VectorTransport (blanket impl)
+//!   +-- Connection (Riemannian Hessian)
+//!   |     |
+//!   |     +-- Curvature (Riemann tensor, Ricci, scalar)
+//!   +-- GeodesicInterpolation (gamma(t) sampling)
+//! ```
+//!
+//! ## The `Real` type alias
+//!
+//! All floating-point computation uses `Real`, currently aliased to `f64`.
+//! This exists so that a future version can generify over `T: Scalar`
+//! with a mechanical find-and-replace refactor.
+
+#![cfg_attr(not(feature = "std"), no_std)]
+
+#[cfg(feature = "alloc")]
+extern crate alloc;
+
+pub mod connection;
+pub mod curvature;
+pub mod error;
+pub mod geodesic;
+pub mod manifold;
+pub mod retraction;
+pub mod transport;
+
+/// The floating-point type used throughout cartan.
+///
+/// Currently f64. Designed so that replacing this alias with a generic
+/// type parameter `T: Scalar` is a mechanical refactor when f32 support
+/// is needed. All structs and functions use `Real` instead of `f64` directly.
+pub type Real = f64;
+
+// Re-exports for convenience.
+pub use connection::Connection;
+pub use curvature::Curvature;
+pub use error::CartanError;
+pub use geodesic::GeodesicInterpolation;
+pub use manifold::Manifold;
+pub use retraction::Retraction;
+pub use transport::{ParallelTransport, VectorTransport};