holos_tda/circular/
model.rs

1use crate::classes::CocycleTerm;
2use crate::cohomology::{CohomologyContinuation, CohomologyLimits, CohomologySpaceId};
3
4/// Numerical and topological limits for one circular coordinate.
5#[derive(Debug, Clone, Copy, PartialEq)]
6#[non_exhaustive]
7pub struct CircularCoordinateParams {
8    /// Largest accepted relative normal-equation residual.
9    pub tolerance: f64,
10    /// Largest conjugate-gradient iteration count.
11    pub max_iterations: usize,
12    /// Limits for the canonical fixed-scale cohomology computation.
13    pub cohomology: CohomologyLimits,
14}
15
16impl Default for CircularCoordinateParams {
17    fn default() -> Self {
18        Self {
19            tolerance: 1e-10,
20            max_iterations: 10_000,
21            cohomology: CohomologyLimits::default(),
22        }
23    }
24}
25
26impl CircularCoordinateParams {
27    /// Set the largest accepted relative normal-equation residual.
28    #[must_use]
29    pub fn with_tolerance(mut self, tolerance: f64) -> Self {
30        self.tolerance = tolerance;
31        self
32    }
33
34    /// Set the largest conjugate-gradient iteration count.
35    #[must_use]
36    pub fn with_max_iterations(mut self, max_iterations: usize) -> Self {
37        self.max_iterations = max_iterations;
38        self
39    }
40
41    /// Set the fixed-scale cohomology limits.
42    #[must_use]
43    pub fn with_cohomology_limits(mut self, cohomology: CohomologyLimits) -> Self {
44        self.cohomology = cohomology;
45        self
46    }
47}
48
49/// One nonzero coefficient of an integer cocycle on an oriented edge.
50#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
51pub struct IntegralCocycleTerm {
52    /// Lower endpoint. The edge is oriented from `u` to `v`.
53    pub u: usize,
54    /// Higher endpoint.
55    pub v: usize,
56    /// Nonzero integer coefficient.
57    pub coefficient: i64,
58}
59
60/// One nonzero coordinate in a canonical fixed-scale H1 basis.
61#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
62pub struct CircularClassTerm {
63    /// Position in the canonical cohomology basis.
64    pub basis_index: usize,
65    /// Coefficient in `1..modulus`.
66    pub coefficient: u32,
67}
68
69/// One checked harmonic circle-valued coordinate on graph vertices.
70#[derive(Debug, Clone, PartialEq)]
71pub struct CircularCoordinate {
72    /// Canonical fixed-scale cohomology space.
73    pub space: CohomologySpaceId,
74    /// Prime field of the selected source cocycle.
75    pub modulus: u32,
76    /// Fixed Rips scale.
77    pub scale: f64,
78    /// Multiplier applied before the finite-field cocycle was lifted.
79    pub field_multiplier: u32,
80    /// Selected class before the lift, in canonical quotient coordinates.
81    pub class: Vec<CircularClassTerm>,
82    /// Source cocycle before the lift, in ascending endpoint order.
83    pub source: Vec<CocycleTerm>,
84    /// Checked integer cocycle congruent to the multiplied source class.
85    pub integral: Vec<IntegralCocycleTerm>,
86    /// Divisibility of the integral cohomology class.
87    pub divisibility: u64,
88    /// Gauge-fixed real vertex potential.
89    pub potential: Vec<f64>,
90    /// Circle-valued vertex coordinate in `[0, 1)`.
91    pub phase: Vec<f64>,
92    /// Squared unweighted harmonic energy.
93    pub energy: f64,
94    /// Maximum absolute normal-equation residual.
95    pub max_residual: f64,
96    /// Maximum residual divided by the source infinity norm, floored at one.
97    pub relative_residual: f64,
98    /// Conjugate-gradient iterations used.
99    pub iterations: usize,
100    /// Residual tolerance required by the producer.
101    pub tolerance: f64,
102}
103
104/// Conservative circular-coordinate continuation to one changed graph.
105#[derive(Debug, Clone, PartialEq)]
106pub struct CircularCoordinateContinuation {
107    /// Exact fixed-scale class continuation.
108    pub topology: CohomologyContinuation,
109    /// New coordinate when the continuation is unique and nonzero.
110    pub coordinate: Option<CircularCoordinate>,
111}
112
113/// One harmonic coordinate computed from a checked source without a basis.
114#[derive(Debug, Clone, PartialEq)]
115pub(crate) struct SelectedCircularCoordinate {
116    pub(crate) modulus: u32,
117    pub(crate) scale: f64,
118    pub(crate) field_multiplier: u32,
119    pub(crate) integral: Vec<IntegralCocycleTerm>,
120    pub(crate) divisibility: u64,
121    pub(crate) potential: Vec<f64>,
122    pub(crate) phase: Vec<f64>,
123    pub(crate) energy: f64,
124    pub(crate) max_residual: f64,
125    pub(crate) relative_residual: f64,
126    pub(crate) iterations: usize,
127    pub(crate) tolerance: f64,
128}
holos_tda/circular/model.rs

holos_tda/circular/
model.rs
