surge_sparse/
error.rs

1// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
2use thiserror::Error;
3
4pub type SparseResult<T> = Result<T, SparseError>;
5
6#[derive(Debug, Error, Clone, PartialEq)]
7pub enum SparseError {
8    #[error("matrix must be square, found {nrows}x{ncols}")]
9    MatrixNotSquare { nrows: usize, ncols: usize },
10    #[error("empty matrices are not supported by this operation")]
11    EmptyMatrix,
12    #[error("CSC column pointer length must be ncols + 1 = {expected}, found {found}")]
13    InvalidColPtrLen { expected: usize, found: usize },
14    #[error("CSC column pointers must start at 0, found {found}")]
15    ColPtrMustStartAtZero { found: usize },
16    #[error(
17        "CSC column pointers must be nondecreasing, but col_ptrs[{index}]={current} < col_ptrs[{prev_index}]={previous}"
18    )]
19    ColPtrNotMonotonic {
20        index: usize,
21        current: usize,
22        prev_index: usize,
23        previous: usize,
24    },
25    #[error("CSC final column pointer {found} must equal nnz {expected}")]
26    InvalidColPtrEnd { expected: usize, found: usize },
27    #[error("CSC row index {row} at position {index} is out of bounds for {nrows} rows")]
28    RowIndexOutOfBounds {
29        index: usize,
30        row: usize,
31        nrows: usize,
32    },
33    #[error(
34        "CSC row indices must be strictly increasing within each column; column {col} has {previous} followed by {current}"
35    )]
36    RowIndicesNotStrictlyIncreasing {
37        col: usize,
38        previous: usize,
39        current: usize,
40    },
41    #[error("triplet ({row}, {col}) is out of bounds for matrix {nrows}x{ncols}")]
42    TripletOutOfBounds {
43        row: usize,
44        col: usize,
45        nrows: usize,
46        ncols: usize,
47    },
48    #[error("{what} {value} exceeds i32::MAX required by SuiteSparse KLU")]
49    IndexTooLarge { what: &'static str, value: usize },
50    #[error("value buffer length {found} does not match expected nnz {expected}")]
51    ValueCountMismatch { expected: usize, found: usize },
52    #[error("RHS length {found} does not match matrix dimension {expected}")]
53    RhsLengthMismatch { expected: usize, found: usize },
54    #[error("KLU factorization has not been computed yet")]
55    NotFactorized,
56    #[error("matrix pattern does not match the solver's analyzed sparsity pattern")]
57    PatternMismatch,
58    #[error("size overflow while computing {what}")]
59    SizeOverflow { what: &'static str },
60    #[error("SuiteSparse KLU symbolic analysis failed")]
61    KluAnalyzeFailed,
62    #[error("SuiteSparse KLU numeric factorization failed")]
63    KluFactorFailed,
64    #[error("SuiteSparse KLU numeric refactorization failed")]
65    KluRefactorFailed,
66    #[error("SuiteSparse KLU reciprocal condition estimate failed")]
67    KluRcondFailed,
68    #[error(
69        "SuiteSparse KLU factorization is ill-conditioned: rcond={rcond:.3e} below strict threshold {threshold:.3e}"
70    )]
71    KluIllConditioned { rcond: f64, threshold: f64 },
72    #[error("SuiteSparse KLU solve failed")]
73    KluSolveFailed,
74    #[error("Y-bus is missing diagonal entry ({index}, {index})")]
75    MissingDiagonal { index: usize },
76}
surge_sparse/error.rs

surge_sparse/
error.rs
