Skip to main content

tpt_math_numeric/
report.rs

1//! A common summary of an iterative solve, shared by the solver crates.
2
3/// How an iterative solve ended.
4#[derive(Clone, Copy, Debug, PartialEq, Eq)]
5#[non_exhaustive]
6pub enum SolveStatus {
7    /// The residual met the requested tolerance.
8    Converged,
9    /// The iteration budget ran out before the tolerance was met.
10    NotConverged,
11    /// The method hit a numerical breakdown and could not continue.
12    Breakdown,
13}
14
15impl SolveStatus {
16    /// `true` only for [`SolveStatus::Converged`].
17    #[must_use]
18    pub fn is_converged(self) -> bool {
19        self == SolveStatus::Converged
20    }
21}
22
23impl core::fmt::Display for SolveStatus {
24    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
25        let text = match self {
26            SolveStatus::Converged => "converged",
27            SolveStatus::NotConverged => "not converged",
28            SolveStatus::Breakdown => "breakdown",
29        };
30        f.write_str(text)
31    }
32}
33
34/// The outcome of an iterative solve: how it ended, how many iterations it
35/// took, and the residual it reached.
36///
37/// `residual` is the solver's own measure, normally the absolute residual norm
38/// `‖b − A x‖` at the last iterate. Check the solver's documentation for its
39/// exact definition.
40#[derive(Clone, Copy, Debug, PartialEq)]
41pub struct SolveReport<T> {
42    /// How the solve ended.
43    pub status: SolveStatus,
44    /// Iterations performed.
45    pub iterations: usize,
46    /// Residual at the last iterate.
47    pub residual: T,
48}
49
50#[cfg(test)]
51mod tests {
52    use super::*;
53
54    #[test]
55    fn only_converged_is_converged() {
56        assert!(SolveStatus::Converged.is_converged());
57        assert!(!SolveStatus::NotConverged.is_converged());
58        assert!(!SolveStatus::Breakdown.is_converged());
59    }
60}