cartan
⌥

Changelog

Release history for the cartan crate and this documentation site.

v0.3.0: 2026-04-10

Active nematohydrodynamics framework. Major additions to cartan-dec for active nematohydrodynamics on arbitrary manifolds.

cartan-dec

Mesh Quality (mesh_quality)

  • is_delaunay, is_well_centered: mesh quality predicates
  • quality_report: full quality audit (min/max angles, non-Delaunay edges, non-well-centred simplices)
  • make_delaunay: intrinsic Delaunay restoration via edge flips
  • make_well_centered: Lloyd/CVT smoothing for well-centredness

Mesh Generators (mesh_gen)

  • icosphere(manifold, level, well_centered): icosahedral subdivision of the unit sphere
  • torus(manifold, R, r, n_major, n_minor, well_centered): parametric torus in

Circumcentric Hodge Star

  • HodgeStar::from_mesh_circumcentric: proper circumcentric dual cell areas, preserving primal-dual orthogonality. Requires well-centred mesh.

Complex Line Bundles (line_bundle)

  • Section<K>: complex section of the line bundle for k-atic fields (K=1 vectors, K=2 nematics, K=4 tetratics, K=6 hexatics)
  • ConnectionAngles: discrete Levi-Civita connection on primal and dual edges
  • BochnerLaplacian<K>: sparse Hermitian complex Laplacian with connection transport phases
  • defect_charges: exact discrete topological charge per face (Poincare-Hopf holds exactly)
  • section_to_q_components, q_components_to_section: Veronese map interop

Extrinsic Operators (extrinsic)

  • FaceData: per-face normals, areas, tangent projectors, FEM gradients
  • ExtrinsicOperators: assembled Killing operator, DIV, GRAD, viscosity Laplacian for triangle meshes in

Stokes Solver (stokes)

  • StokesSolverAL: augmented Lagrangian solver for incompressible Stokes flow on triangle meshes, with Killing vector projection and CG inner solve

References

  • Zhu, Saintillan, Chern. "Active nematic fluids on Riemannian 2-manifolds." arXiv:2405.06044, 2024.
  • Zhu, Saintillan, Chern. "Stokes flow of an evolving fluid film with arbitrary shape and topology." JFM 1003, R1, 2025.

v0.1.0: 2026-03-13

Initial release. Core trait system and first two manifolds.

Library (cartan)

Traits

  • Manifold: root trait with exp, log, dist, inner, project_tangent, project_point, random_point, random_tangent, check_point, check_tangent
  • Retraction: first-order retraction with blanket impl via Manifold::exp
  • Connection: Levi-Civita connection, covariant_derivative, christoffel
  • ParallelTransport: exact isometric transport along geodesics; blanket impl provides VectorTransport
  • VectorTransport: approximate transport for optimizers
  • Curvature: sectional, ricci_tensor, scalar_curvature
  • GeodesicInterpolation: geodesic(p, q, t) and midpoint

Manifolds

  • Sphere<N>: $(N-1)$-sphere in . Implements all 7 traits. Closed-form exp/log, exact parallel transport, constant curvature $K = 1$, numerical Taylor expansions for small angles and near-antipodal points.
  • Euclidean<N>: flat . Implements all 7 traits. Trivial formulas, zero curvature, infinite injectivity radius.

Error handling

  • CartanError enum: PointNotOnManifold, NotATangentVector, AntipodalPoints, DimensionMismatch, NumericalFailure

Sub-crates

  • cartan-core: trait definitions and CartanError
  • cartan-manifolds: Sphere, Euclidean implementations
  • cartan-interop: nalgebra and ndarray adaptors

Documentation site (cartan.sotofranco.dev)

  • Landing page with trait hierarchy diagram and manifold card grid
  • Getting Started guide with installation and first example
  • Concept pages: Manifold, Retraction, Transport, Connection, Curvature, Geodesic Interpolation, Error Handling
  • Manifold pages: Sphere (full), Euclidean (full), SO(N) / SPD(N) / Grassmann (geometry previews, coming soon)
  • KaTeX math rendering, Shiki syntax highlighting, light/dark theme
  • Docs layout with collapsible sidebar, table of contents, prev/next navigation

v0.1.5: 2026-03-25

Facade feature flags for embedded targets.

Library (cartan)

Facade (cartan)

  • full feature (default): includes cartan-dec (mesh/PDE layer, requires std). Disabling it yields a no_std-compatible facade that exposes only the geometry and optimization layers.
  • std feature: propagates std to all four sub-crates in one declaration.
  • alloc feature: propagates alloc to all four sub-crates for targets with a global allocator.
  • Feature hierarchy: full ⊇ std ⊇ alloc. Embedded users no longer need to list sub-crates individually.

Fixes

  • cartan-geo/src/jacobi.rs: unused-import warnings eliminated by threading std propagation through full.
  • README: em dashes removed for style consistency.

v0.1.4: 2026-03-25

no_std + alloc support for cartan-manifolds, cartan-geo, and cartan-optim.

Library (cartan)

no_std + alloc

  • cartan-manifolds, cartan-geo, cartan-optim: all compile with default-features = false, features = ["alloc"] on any target with a global allocator. Float arithmetic falls back to libm when std is absent.
  • Available without std: Euclidean<N>, Sphere<N>, SpecialOrthogonal<N>, SpecialEuclidean<N>, Grassmann<N,K>, all cartan-optim algorithms, Geodesic, CurvatureQuery, integrate_jacobi.
  • nalgebra/libm enabled unconditionally in cartan-manifolds and cartan-geo so that f64: RealField is satisfied in no_std mode without a separate simba dependency.

Changed

  • cartan-manifolds: qtensor, frame_field, corr, spd, and sym modules reclassified from alloc-gated to std-gated. These require symmetric_eigen() (Jacobi iteration), which depends on std float behavior. grassmann remains alloc-gated since it uses DMatrix/SVD but not eigendecomposition.
  • cartan-geo: disclination and holonomy modules reclassified from alloc-gated to std-gated (std::collections dependency via HashMap, HashSet, VecDeque).
  • CI: no-std-check job added, building cartan-core, cartan-manifolds, and cartan-geo under --no-default-features --features alloc on each PR, pinned to Rust 1.85.

Note: cartan-dec has no no_std support and is not planned to gain it. It depends on rayon and operates on heap-allocated mesh structures. Embedded users must use the facade with default-features = false, features = ["alloc"], or depend on the sub-crates directly.

v0.1.3: 2026-03-22

Nematic geometry, disclination tracking, and release profile.

Library (cartan)

New: Q-tensor manifold and frame fields (cartan-manifolds)

  • QTensor3: manifold of traceless symmetric 3x3 Q-tensors for nematic order parameters; exp, log, projection, random sampling
  • FrameField: director frame field on a discrete lattice; stores Q-tensor at each site and computes local orientation angle
  • Holonomy-based defect detection: detect_defects integrates the parallel transport around plaquette loops and classifies ±1/2 disclination charges

New: Disclination module (cartan-geo)

  • DisclincationScanner: scans a frame field for disclination segments using per-edge winding-angle thresholds
  • DisclincationLinker: connects detected segments into continuous disclination lines with junction-handling (current limitation: junctions above valence 2 are resolved greedily)
  • DisclincationEvent: tracks creation, annihilation, and reconnection events across time steps

Other

  • [profile.release] added to workspace: opt-level=3, lto=thin, codegen-units=4 (thin LTO avoids OOM on 30 GB machines)
  • Fix broken cartan-optim lib doctest (missing SVector import, Manifold trait in scope, and p0 definition)
  • Remove unused Retraction imports from test_spd and test_corr

v0.1.2: 2026-03-18

no_std support across all crates and generic DEC mesh.

Library (cartan)

no_std / embedded support

  • cartan-core, cartan-manifolds, cartan-optim: all ported to no_std + alloc; std feature flag re-enables std::error::Error impls and format strings; libm used for sqrt in no_std builds
  • cartan-geo: alloc feature gates Vec-returning APIs; bare no_std path uses fixed-size arrays only
  • Workspace deps set default-features = false; hashbrown added as no_std-compatible hash map

cartan-dec

  • Generic Mesh<M, K, B> refactor: mesh is now generic over metric M, cochain coefficient type K, and boundary operator B; removes the previous monomorphic SimplexMesh
  • Full-tensor vertex callbacks for Ricci curvature; scalar curvature option replaced with the correct tensor-valued API

Fixes

  • riemannian_hessian_vector_product: add missing Weingarten correction for curved manifolds
  • Doctests: replace bare ignore with no_run or runnable examples throughout

v0.1.1: 2026-03-14

Crates.io publication, test suite, and SO/SPD/Corr/Grassmann manifolds.

Library (cartan)

New manifolds (cartan-manifolds)

  • SpecialOrthogonal<N> (SO(N)): bi-invariant metric, matrix exp/log, Cayley retraction, exact parallel transport, sectional curvature K = 1/4
  • SpecialEuclidean<N> (SE(N)): rigid motions; left-invariant metric, left Jacobian / inverse for exp/log, parallel transport
  • Spd<N> (SPD(N)): symmetric positive definite matrices with the affine-invariant metric; Cartan-Hadamard manifold (K ≤ 0)
  • Corr<N>: correlation matrix manifold; flat geometry (K = 0), linear geodesics, nearest-correlation projection
  • Grassmann<N, K> (Gr(k, N)): thin-QR retraction, canonical metric, sectional curvature in [0, 1]
  • cartan-nalgebra interop crate collapsed into cartan-manifolds

cartan-dec: new crate with DEC scaffold (simplicial complexes, chains, cochains, exterior derivative, Hodge star skeleton)

Tests: comprehensive numerical test suite covering all manifolds and optimizer convergence for SPD, SO, Grassmann, Sphere, Euclidean, Corr

Publishing

  • All crates published to crates.io at v0.1.1
  • docs.rs metadata added ([package.metadata.docs.rs]) across all crates
  • GitHub Actions CI: Rust test + rustdoc build to gh-pages
  • Internal path dependencies carry explicit version = "0.1" constraints

Roadmap

Active development

  • Riemannian Adam and conjugate gradient convergence tuning (cartan-optim)
  • Fréchet mean via Karcher flow and geodesic splines (cartan-geo)
  • Well-centered Delaunay meshes and diagonal Hodge stars (cartan-dec)
  • Covariant Laplacian for PDE solvers (cartan-dec)