Skip to main content

cartan_matfree/
lib.rs

1//! Matrix-free Galerkin Hodge mass operators and Krylov solvers.
2//!
3//! The assembled route builds `M_k` as a sparse matrix and factorises it. On an
4//! evolving Regge background the metric changes every step, so that route pays a
5//! fresh assembly and a fresh factorisation per step, and the factorisation is
6//! cubic in the number of interior degrees of freedom.
7//!
8//! This crate replaces both with an element-by-element application. The element
9//! matrices are computed once per metric and applied repeatedly by a conjugate
10//! gradient iteration. A Galerkin mass matrix is spectrally equivalent to its
11//! diagonal with a mesh-independent constant, so Jacobi-preconditioned CG
12//! converges in a number of iterations that does not grow with the mesh, and the
13//! element matrices are amortised over those iterations.
14//!
15//! # Layering
16//!
17//! [`MassBackend`] states every vector operation the iteration needs, so
18//! [`pcg`] runs wherever the vectors live. [`HostMass`] is the reference
19//! implementation on host memory, and it is what correctness is measured
20//! against. A device backend implements the same trait and keeps its vectors
21//! resident, which matters because a Krylov iteration that copies its vectors
22//! across PCIe every step spends more time on the copies than on the operator.
23//!
24//! ```no_run
25//! use cartan_matfree::{HostMass, Interior, MassBackend, pcg};
26//! # fn demo(topology: &simplicial::topology::complex::Complex,
27//! #         geometry: &simplicial::geometry::metric::mesh::MeshLengthsSq,
28//! #         rhs: &[f64]) {
29//! let interior = Interior::boundary_constrained(topology, 1);
30//! let mass = HostMass::restricted(topology, geometry, &interior);
31//! let mut x = vec![0.0; mass.ndofs()];
32//! let report = pcg(&mass, rhs, &mut x, 1e-12, 1000);
33//! assert!(report.converged);
34//! # }
35//! ```
36
37mod cg;
38mod gather;
39mod mass;
40mod restrict;
41
42pub use cg::{CgReport, MassBackend, pcg};
43pub use gather::GatherMap;
44pub use mass::HostMass;
45pub use restrict::Interior;