1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
use std::fmt;
/// A recoverable input, configuration or result error.
///
/// Match variants to handle errors; the human-readable messages are not a stable
/// serialization format. Additional variants may be added as algorithms arrive.
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub enum Error {
/// A supplied simplex or filtered-complex contract is invalid.
InvalidComplex {
/// Input simplex or traversal position, when available.
cell: Option<usize>,
/// Violated constraint.
reason: &'static str,
},
/// Stored distances violate at least one triangle inequality.
InvalidMetric {
/// Original vertex IDs of the offending triple, in increasing order.
vertices: [usize; 3],
},
/// A square matrix violates its structural contract.
InvalidMatrix {
/// Row of the offending entry.
row: usize,
/// Column of the offending entry.
column: usize,
/// Violated constraint.
reason: &'static str,
},
/// An edge violates the graph contract.
InvalidGraph {
/// Edge position (input order except duplicate checks, which use sorted order).
edge: usize,
/// Violated constraint.
reason: &'static str,
},
/// The requested scale exceeds the source construction's known range.
IncompleteFiltration {
/// Requested scale.
requested: f64,
/// Last available scale.
through: f64,
},
/// A Rips skeleton omits dimensions needed to compute the requested homology.
InsufficientSkeleton {
/// Largest requested homology dimension.
requested_homology_dimension: usize,
/// Largest dimension requested during explicit construction.
constructed_simplex_dimension: usize,
},
/// A cooperative computation was cancelled.
Cancelled,
/// A declared work limit was reached before the next work unit.
WorkLimitExceeded {
/// Maximum permitted work units.
limit: u64,
},
/// A Betti-curve grid is not finite and strictly increasing.
InvalidGrid {
/// Position of the first invalid grid value.
index: usize,
/// Constraint that was violated.
reason: &'static str,
},
/// A query extends beyond a diagram's known range.
QueryOutsideCoverage {
/// Position of the query in its grid.
index: usize,
/// Requested scale.
value: f64,
/// Last known scale.
through: f64,
},
/// A fallible memory reservation failed.
AllocationFailed {
/// Buffer being grown.
context: &'static str,
},
/// An internal construction violated an algorithm invariant.
InternalInvariant {
/// Invariant that was violated.
reason: &'static str,
},
/// A numerical computation overflowed or underflowed a required quantity.
NumericalFailure {
/// Computation that failed.
context: &'static str,
},
/// A buffer does not match its declared shape.
ShapeMismatch {
/// Name of the input buffer.
input: &'static str,
/// Required number of elements.
expected: usize,
/// Supplied number of elements.
actual: usize,
},
/// A shape cannot be represented by `usize`.
SizeOverflow {
/// Operation whose result overflowed.
operation: &'static str,
},
/// A scalar or buffer element is NaN or infinite.
NonFiniteValue {
/// Name of the value or input buffer.
field: &'static str,
/// Buffer position, or `None` for a scalar.
index: Option<usize>,
},
/// A value required to be nonnegative is negative.
NegativeValue {
/// Name of the value or input buffer.
field: &'static str,
/// Buffer position, or `None` for a scalar.
index: Option<usize>,
},
/// A configuration value violates a parameter constraint.
InvalidParameter {
/// Name of the parameter.
parameter: &'static str,
/// Constraint that was violated.
reason: &'static str,
},
/// A computation was requested in an unsupported dimension.
UnsupportedDimension {
/// Requested maximum homology dimension.
requested: usize,
/// Largest dimension supported by this computation.
max_supported: usize,
},
/// Interval endpoints are inconsistent.
InvalidInterval {
/// Constraint that was violated.
reason: &'static str,
},
/// An interval conflicts with the diagram's computation range.
InconsistentDiagram {
/// Position in the supplied, unsorted interval vector.
interval: usize,
/// Constraint that was violated.
reason: &'static str,
},
/// A dimension lies outside those recorded as computed.
DimensionNotComputed {
/// Dimension requested or supplied by the caller.
requested: usize,
/// Largest computed dimension; lower dimensions may be absent.
computed_max: usize,
},
/// A full-diagram operation requires complete filtration coverage.
IncompleteDiagram {
/// Last scale through which the diagram is known.
through: f64,
},
/// Computation contexts do not describe compatible diagram coordinates.
IncompatibleDiagramContext {
/// Context constraint that was violated.
reason: &'static str,
},
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::InvalidComplex { cell, reason } => {
write!(f, "invalid complex at {cell:?}: {reason}")
}
Self::InvalidMetric { vertices } => {
write!(f, "triangle inequality violated at {vertices:?}")
}
Self::InvalidMatrix {
row,
column,
reason,
} => write!(f, "matrix[{row},{column}]: {reason}"),
Self::InvalidGraph { edge, reason } => write!(f, "edge[{edge}]: {reason}"),
Self::IncompleteFiltration { requested, through } => write!(
f,
"requested scale {requested} exceeds construction through {through}"
),
Self::InsufficientSkeleton {
requested_homology_dimension,
constructed_simplex_dimension,
} => write!(
f,
"H{requested_homology_dimension} requires cofaces beyond simplex dimension {constructed_simplex_dimension}"
),
Self::Cancelled => f.write_str("computation cancelled"),
Self::WorkLimitExceeded { limit } => write!(f, "work limit {limit} reached"),
Self::InvalidGrid { index, reason } => write!(f, "grid[{index}]: {reason}"),
Self::QueryOutsideCoverage {
index,
value,
through,
} => {
write!(
f,
"grid[{index}] = {value} exceeds coverage through {through}"
)
}
Self::AllocationFailed { context } => write!(f, "allocation failed for {context}"),
Self::InternalInvariant { reason } => write!(f, "internal invariant failed: {reason}"),
Self::NumericalFailure { context } => write!(f, "numerical failure in {context}"),
Self::ShapeMismatch {
input,
expected,
actual,
} => {
write!(f, "{input}: expected {expected} elements, got {actual}")
}
Self::SizeOverflow { operation } => write!(f, "size overflow in {operation}"),
Self::NonFiniteValue { field, index } => {
write_location(f, field, *index)?;
f.write_str(" must be finite")
}
Self::NegativeValue { field, index } => {
write_location(f, field, *index)?;
f.write_str(" must be nonnegative")
}
Self::InvalidParameter { parameter, reason } => write!(f, "{parameter}: {reason}"),
Self::UnsupportedDimension {
requested,
max_supported,
} => {
write!(
f,
"homology dimension {requested} is unsupported; maximum is {max_supported}"
)
}
Self::InvalidInterval { reason } => write!(f, "invalid interval: {reason}"),
Self::InconsistentDiagram { interval, reason } => {
write!(
f,
"interval {interval} conflicts with the diagram: {reason}"
)
}
Self::DimensionNotComputed {
requested,
computed_max,
} => {
write!(
f,
"dimension {requested} is absent from the computed dimensions (maximum {computed_max})"
)
}
Self::IncompleteDiagram { through } => {
write!(
f,
"full-diagram distance requires complete coverage; known through {through}"
)
}
Self::IncompatibleDiagramContext { reason } => {
write!(f, "incompatible diagram contexts: {reason}")
}
}
}
}
fn write_location(f: &mut fmt::Formatter<'_>, field: &str, index: Option<usize>) -> fmt::Result {
f.write_str(field)?;
if let Some(index) = index {
write!(f, "[{index}]")?;
}
Ok(())
}
impl std::error::Error for Error {}
/// The result type returned by fallible Cocycle operations.
pub type Result<T> = std::result::Result<T, Error>;