Getting Started

cartan is a Riemannian geometry library for Rust. It provides a backend-agnostic trait system over const-generic manifolds, correct numerics near singularities, and an optional discrete exterior calculus layer for covariant PDE solvers.

Installation

Add cartan to your Cargo.toml:

[dependencies]
cartan = "0.1"

Or use cargo add:

cargo add cartan

Requires Rust 1.80+ (const generics + RPITIT stabilization).

The Prelude

use cartan::prelude::*;

The prelude re-exports the core traits and every manifold so you can import them in one line:

First Example: Geodesic Roundtrip on the 2-Sphere

use cartan::prelude::*;
use cartan::manifolds::Sphere;
 
fn main() {
    let s2 = Sphere::<3>;      // 2-sphere S² embedded in R³
    let mut rng = rand::rng();
 
    // Sample a random base point and tangent vector.
    let p = s2.random_point(&mut rng);
    let v = s2.random_tangent(&p, &mut rng);
 
    // Walk along the geodesic: q = exp_p(v).
    let q = s2.exp(&p, &v);
 
    // Recover the tangent: log_p(q) should equal v to machine precision.
    let v_recovered = s2.log(&p, &q).unwrap();
    assert!((v; v_recovered).norm() < 1e-10);
 
    println!("Roundtrip error: {:.2e}", (v; v_recovered).norm());
}

The const generic Sphere::<3> encodes the ambient dimension; the manifold dimension is N; 1 = 2. No heap allocation, no runtime type dispatch.

Handling antipodal points

log returns None when p and q are antipodal (the log map is undefined at the cut locus). Always match the result or use unwrap_or:

match s2.log(&p, &antipodal) {
    Some(v) => { /* proceed */ }
    None    => { /* p and q are antipodal; choose alternate path */ }
}

Trait Hierarchy

The six core traits layer capabilities from basic geometry to full curvature:

Manifold — tangent space, exp, log, dist, inner

Every manifold type implements Manifold. The remaining traits are optional extensions:

Retraction — first-order retract replacing exp for cheap optimization steps. A blanket implementation is provided via Manifold::exp.

Connection — covariant_derivative and christoffel_symbols. Required by Curvature.

ParallelTransport — exact parallel_transport along geodesics. Automatically provides VectorTransport via a blanket impl.

VectorTransport — vector_transport, the approximate analogue. Cheaper than ParallelTransport; used in Riemannian Adam and conjugate gradient.

Curvature — sectional, ricci_tensor, and scalar_curvature. Requires Connection.

The diagram on the home page shows the dependency arrows at a glance. Visit Concepts → for full mathematical definitions.

Crate Structure

cartan is a thin meta-crate that re-exports from focused sub-crates:

You can depend on individual sub-crates to avoid pulling in unused code:

[dependencies]
cartan-core      = "0.1"
cartan-manifolds = "0.1"

Next Steps