Enum LaError 

#[non_exhaustive]
pub enum LaError {
    Singular {
        pivot_col: usize,
    },
    NonFinite {
        row: Option<usize>,
        col: usize,
    },
    Unrepresentable {
        index: Option<usize>,
        reason: UnrepresentableReason,
    },
    DeterminantScaleOverflow {
        dim: usize,
        min_exponent: i32,
    },
    UnsupportedDimension {
        requested: usize,
        max: usize,
    },
    IndexOutOfBounds {
        row: usize,
        col: usize,
        dim: usize,
    },
    InvalidTolerance {
        value: f64,
    },
    Asymmetric {
        row: usize,
        col: usize,
        dim: usize,
    },
    NotPositiveSemidefinite {
        pivot_col: usize,
        value: f64,
    },
}

Linear algebra errors.

This enum is #[non_exhaustive] — downstream match arms must include a wildcard (_) pattern to compile, allowing new variants to be added in future minor releases without breaking existing code.

Examples

use la_stack::prelude::*;

let err = LaError::unrepresentable(None, UnrepresentableReason::RequiresRounding);
assert!(err.requires_rounding());

match LaError::unsupported_dimension(8, MAX_STACK_MATRIX_DISPATCH_DIM) {
    LaError::UnsupportedDimension { requested, max } => {
        assert_eq!((requested, max), (8, MAX_STACK_MATRIX_DISPATCH_DIM));
    }
    _ => unreachable!("constructor returns the requested variant"),
}

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Singular

The matrix is (numerically) singular.

Fields

pivot_col: usize

The factorization column/step where a suitable pivot/diagonal could not be found.

NonFinite

A non-finite value (NaN/∞) was encountered.

The (row, col) coordinate follows a consistent convention across the crate:

• row: Some(r), col: c — the non-finite value is tied to a matrix/factor cell at (r, c), either because a stored input/factor cell is already non-finite or because factorization computed a non-finite value for that cell before storing it.
• row: None, col: c — the non-finite value is tied to a vector entry, determinant product, solve accumulator, or other scalar/intermediate that has no matrix row coordinate.

Fields

row: Option<usize>

Row of the non-finite entry for a stored matrix cell, or None for a vector-input entry or a computed intermediate. See the variant docs for the full convention.

col: usize

Column index (stored cell), vector index, or factorization/solve step where the non-finite value was detected.

Unrepresentable

An exact result cannot satisfy the requested finite f64 conversion.

Returned by Matrix::det_exact_f64 and Matrix::solve_exact_f64 (requires the exact feature) when the exact rational value is too large, too small, or would require rounding in binary64. Also returned by the rounded exact-to-f64 APIs when the rounded result would be NaN or infinite.

Fields

index: Option<usize>

For vector results (e.g. solve_exact_f64), the index of the component that failed conversion. None for scalar results.

reason: UnrepresentableReason

Why the requested conversion cannot return a finite f64.

DeterminantScaleOverflow

Exact determinant scaling overflowed the internal exponent representation.

Fields

dim: usize

Matrix dimension D.

min_exponent: i32

Minimum decomposed f64 exponent among non-zero matrix entries.

UnsupportedDimension

A requested runtime matrix dimension has no stack-dispatch arm.

Fields

requested: usize

Runtime dimension requested by the caller.

max: usize

Largest runtime dimension supported by the dispatch helper.

IndexOutOfBounds

A matrix index is outside the D×D storage domain.

Fields

row: usize

Requested row index.

col: usize

Requested column index.

dim: usize

Matrix dimension D; valid row and column indices are < dim.

InvalidTolerance

A tolerance value is not finite and non-negative.

Fields

value: f64

Raw tolerance supplied by the caller.

Asymmetric

A matrix required to be symmetric has an asymmetric off-diagonal pair.

Fields

row: usize

Row index of the first asymmetric pair.

col: usize

Column index of the first asymmetric pair.

dim: usize

Matrix dimension D.

NotPositiveSemidefinite

A symmetric matrix failed the positive-semidefinite LDLT domain check.

Fields

pivot_col: usize

Factorization column/step where a negative LDLT diagonal was found.

value: f64

Negative diagonal value observed at that step.

Implementations

impl LaError

pub const fn non_finite_cell(row: usize, col: usize) -> Self

Construct a LaError::NonFinite pinpointing a stored matrix cell at (row, col).

Use this for non-finite values read from a stored Matrix entry or factorization cell, and for non-finite factorization updates that would be stored at (row, col) if accepted. The resulting error has row: Some(row), col, matching the matrix/factor-cell convention documented on NonFinite. For vector-input entries or scalar intermediates without a matrix row coordinate, use non_finite_at.

Examples

use la_stack::prelude::*;

assert_eq!(
    LaError::non_finite_cell(1, 2),
    LaError::NonFinite {
        row: Some(1),
        col: 2,
    }
);

pub const fn non_finite_at(col: usize) -> Self

Construct a LaError::NonFinite pinpointing a vector-input entry or computed scalar/intermediate at index col.

Use this for non-finite values in a Vector input, determinant scalar, tolerance-scale accumulator, or solve accumulator that overflowed during forward/back substitution. The resulting error has row: None, col, matching the vector/scalar-intermediate convention documented on NonFinite. For stored matrix cells or computed factorization updates tied to a matrix cell, use non_finite_cell.

Examples

use la_stack::prelude::*;

assert_eq!(
    LaError::non_finite_at(2),
    LaError::NonFinite { row: None, col: 2 }
);

pub const fn unrepresentable( index: Option<usize>, reason: UnrepresentableReason, ) -> Self

Construct a LaError::Unrepresentable for exact-to-f64 conversion.

Examples

use la_stack::prelude::*;

assert_eq!(
    LaError::unrepresentable(Some(2), UnrepresentableReason::RequiresRounding),
    LaError::Unrepresentable {
        index: Some(2),
        reason: UnrepresentableReason::RequiresRounding,
    }
);

pub const fn unrepresentable_reason(&self) -> Option<UnrepresentableReason>

Return the reason for an exact-to-f64 conversion failure.

This is a concise alternative to matching the full LaError::Unrepresentable variant when callers only need the conversion reason.

Examples

use la_stack::prelude::*;

let err = LaError::unrepresentable(None, UnrepresentableReason::RequiresRounding);
assert_eq!(
    err.unrepresentable_reason(),
    Some(UnrepresentableReason::RequiresRounding)
);
assert_eq!(LaError::Singular { pivot_col: 0 }.unrepresentable_reason(), None);

pub const fn requires_rounding(&self) -> bool

Return true when strict exact-to-f64 conversion only failed because rounding would be required.

This is useful at the call site that wants to retry with an explicit rounded exact-to-f64 API while still propagating non-finite conversion failures.

Examples

use la_stack::prelude::*;

let err = LaError::unrepresentable(None, UnrepresentableReason::RequiresRounding);
assert!(err.requires_rounding());

let err = LaError::unrepresentable(None, UnrepresentableReason::NotFinite);
assert!(!err.requires_rounding());

pub const fn determinant_scale_overflow(dim: usize, min_exponent: i32) -> Self

Construct a LaError::DeterminantScaleOverflow for exact determinant scaling.

Examples

use la_stack::prelude::*;

assert_eq!(
    LaError::determinant_scale_overflow(3, -1074),
    LaError::DeterminantScaleOverflow {
        dim: 3,
        min_exponent: -1074,
    }
);

pub const fn unsupported_dimension(requested: usize, max: usize) -> Self

Construct a LaError::UnsupportedDimension for runtime stack dispatch.

Examples

use la_stack::prelude::*;

assert_eq!(
    LaError::unsupported_dimension(8, MAX_STACK_MATRIX_DISPATCH_DIM),
    LaError::UnsupportedDimension {
        requested: 8,
        max: MAX_STACK_MATRIX_DISPATCH_DIM,
    }
);

pub const fn index_out_of_bounds(row: usize, col: usize, dim: usize) -> Self

Construct a LaError::IndexOutOfBounds for a D×D matrix index.

Examples

use la_stack::prelude::*;

assert_eq!(
    LaError::index_out_of_bounds(2, 0, 2),
    LaError::IndexOutOfBounds {
        row: 2,
        col: 0,
        dim: 2,
    }
);

pub const fn invalid_tolerance(value: f64) -> Self

Construct a LaError::InvalidTolerance for a raw tolerance value.

Examples

use la_stack::prelude::*;

assert_eq!(
    LaError::invalid_tolerance(-1.0),
    LaError::InvalidTolerance { value: -1.0 }
);

pub const fn asymmetric(row: usize, col: usize, dim: usize) -> Self

Construct a LaError::Asymmetric for a D×D matrix.

Examples

use la_stack::prelude::*;

assert_eq!(
    LaError::asymmetric(0, 1, 3),
    LaError::Asymmetric {
        row: 0,
        col: 1,
        dim: 3,
    }
);

pub const fn not_positive_semidefinite(pivot_col: usize, value: f64) -> Self

Construct a LaError::NotPositiveSemidefinite for LDLT factorization.

Examples

use la_stack::prelude::*;

assert_eq!(
    LaError::not_positive_semidefinite(1, -3.0),
    LaError::NotPositiveSemidefinite {
        pivot_col: 1,
        value: -3.0,
    }
);

pub const fn validate_tolerance(value: f64) -> Result<Tolerance, Self>

Parse a raw tolerance into a finite, non-negative Tolerance.

Examples

use la_stack::prelude::*;

assert_eq!(LaError::validate_tolerance(1e-12)?.get(), 1e-12);

let raw = 0.0;
let tol = LaError::validate_tolerance(raw)?;
let _lu = Matrix::<2>::identity().lu(tol)?;

assert_eq!(
    LaError::validate_tolerance(-1.0),
    Err(LaError::InvalidTolerance { value: -1.0 })
);

Errors

Returns LaError::InvalidTolerance when value is NaN, infinite, or negative.

Trait Implementations

impl Clone for LaError

fn clone(&self) -> LaError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for LaError

impl Debug for LaError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for LaError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for LaError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl PartialEq for LaError

fn eq(&self, other: &LaError) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for LaError