cartan
⌥

Changelog

Release history for the cartan crate and this documentation site.

FEEC, Maxwell, and I/O: 2026-06-22

Five new crates published to crates.io: the dimension-generic FEEC stack and an I/O layer.

cartan-exterior 0.6.0 (new crate)

Numerical exterior algebra for runtime dimension and grade. Gramian, multi_gramian, ExteriorElement, and lexicographic basis enumeration. Adapted from luiswirth/formoniq with permission.

cartan-simplicial 0.6.0 (new crate)

Runtime dimension-generic simplicial topology and intrinsic Regge geometry. Signed boundary chain with , edge-length metric, Cayley-Menger volumes, realizability check, and Cartesian mesh generators.

cartan-feec 0.6.0 (new crate)

Finite element exterior calculus. Cochains, first-order Whitney forms, the Galerkin Hodge mass for any grade, and global sparse assembly. Validated against the closed-form reference element matrix and a Dirichlet-box Hodge-Laplace eigenvalue convergence.

cartan-maxwell 0.6.0 (new crate)

Maxwell evolution on a prescribed evolving Regge background. is a 1-cochain, is a 2-cochain, Faraday is metric-free and exact, and the magnetic Gauss residual stays below 1e-9 on static and FLRW backgrounds. The same evolver runs in 2D and 3D.

cartan-io 0.6.0 (new crate)

VTK XML writers (.vtu, .vtp, .pvd), CSV diagnostics, and Blender export (.obj and .mdd). RunWriter records a per-frame run directory consumed by the cartan-viz Python dashboard.

CI

The workspace clippy gate now lints all targets (cargo clippy --workspace --all-targets -- -D warnings). A release-crates.yml workflow publishes every member in dependency order on a v* tag.

v0.6.0: 2026-05-26

cartan-gpu splits out FFT; gpufft crate introduced.

cartan-gpu 0.6.0

cartan-gpu now ships wgpu compute primitives only: Device, GpuBuffer<T>, Kernel. All FFT code has been removed from this crate.

  • cartan-gpu-sys has been deleted. There is no replacement in the cartan workspace; FFT users depend on gpufft directly.
  • The fft feature on cartan-gpu re-exports gpufft as cartan_gpu::gpufft for convenience.

gpufft 0.1 (new crate)

gpufft is a standalone crate providing a backend-agnostic FFT trait surface:

  • Traits: Backend, Device, BufferOps, C2cPlanOps, R2cPlanOps, C2rPlanOps, Scalar, Shape, Direction, PlanDesc.
  • vulkan feature: VkFFT 1.3.4 backend (VulkanBackend).
  • cuda feature: cuFFT backend (CudaBackend).
  • shared feature (Linux only): zero-copy Vulkan↔CUDA shared memory via SharedFftBuffer + execute_shared.

Migration

# Before (0.5.x)
[dependencies]
cartan-gpu = { version = "0.5", features = ["vkfft", "cufft"] }
 
# After (0.6)
[dependencies]
cartan-gpu = { version = "0.6" }                          # wgpu compute only
gpufft     = { version = "0.1", features = ["vulkan", "cuda"] }  # FFT backends
// Before
use cartan_gpu::{VkFftBackend, CuFftBackend, FftDirection};
 
// After
use gpufft::{vulkan::VulkanBackend, cuda::CudaBackend, Direction};

v0.5.1: 2026-05-17

GPU compute stack lands. First crates.io release of cartan-gpu and cartan-gpu-sys, plus a Moulinec-Suquet spectral homogenisation solver in cartan-homog driven by the new GPU FFT.

cartan-gpu (new on crates.io)

Unified Fft trait with associated Buffer type. Both backends implement the same surface and guarantee forward ∘ inverse = identity regardless of where the work runs.

  • VkFftBackend: Vulkan path through VkFFT 1.3.4 (vendored). Default backend, cross-platform.
  • CuFftBackend: CUDA path through cudarc::cufft. Inverse is post-scaled by 1/N on-device via cublasSscal_v2 so the identity semantics match VkFFT exactly.
  • UniFftBackend + UniBuffer: runtime backend selection via enum dispatch; the buffer variant is locked to the engine at allocation time, and mismatched pairs surface as GpuError::BackendMismatch.

Zero-copy Vulkan ↔ CUDA interop (Linux, vkfft + cufft). SharedFftBuffer exports VkDeviceMemory via VK_KHR_external_memory_fd, imports it into CUDA via cuImportExternalMemory, and lets both backends operate on the same physical allocation.

  • Same-physical-GPU UUID gate: compares VkPhysicalDeviceIDProperties.deviceUUID against cuDeviceGetUuid_v2 before opening the import; mismatches return GpuError::GpuUuidMismatch instead of producing silently non-shared mappings.
  • Cross-backend round-trip verified on NVIDIA RTX 5060 Laptop: Vulkan Forward → CUDA Inverse on the same allocation, L-inf = 9.02 × 10⁻⁷.

Bench suite: cargo bench --features "vkfft cuda cufft" --bench fft_compare compares VkFFT, cuFFT, and rustfft (CPU) on identical inputs.

cartan-homog

Spectral full-field solver (gpu-fft feature). Alternative to the FEM full-field path; runs Moulinec-Suquet fixed-point iteration on the periodic gradient field, driven by cartan-gpu's FFT backend.

  • SpectralFullField::new(resolution).homogenize_voxel(&grid, &k_per_phase) accepts any VoxelGrid the FEM path already produces.
  • Three forward + three inverse FFTs per iteration (one per polarisation component).
  • Reference medium κ⁰ = arithmetic mean of κ over voxels; DC coefficient pinned so the macroscopic mean of ε matches the applied unit gradient exactly.
  • Order2 (scalar conductivity) only in this release; Order4 elasticity is on the follow-up list.
  • Validated on the homogeneous-medium invariant κ_eff = κ·I; heterogeneous validation against the existing FEM path is in progress.

Workspace

  • Per-subcrate README coverage filled in (cartan-gpu, cartan-gpu-sys, cartan-stochastic, cartan-py, cartan facade).
  • Device and CudaDevice are now Clone (both wrap Arc-internal handles, so clones are cheap).
  • cartan-gpu re-exports wgpu so downstream crates don't need a separate wgpu dependency just for BufferUsages.

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)