Enum LaError 

#[non_exhaustive]
pub enum LaError {
    #[non_exhaustive]
    Singular {
        pivot_col: usize,
        reason: SingularityReason,
    },
    #[non_exhaustive]
    NonFinite {
        location: NonFiniteLocation,
        origin: NonFiniteOrigin,
    },
    #[non_exhaustive]
    Unrepresentable {
        index: Option<usize>,
        reason: UnrepresentableReason,
    },
    #[non_exhaustive]
    DeterminantScaleOverflow {
        dim: usize,
        min_exponent: i32,
    },
    #[non_exhaustive]
    UnsupportedDimension {
        requested: usize,
        max: usize,
    },
    #[non_exhaustive]
    IndexOutOfBounds {
        row: usize,
        col: usize,
        dim: usize,
    },
    #[non_exhaustive]
    InvalidTolerance {
        value: f64,
        reason: InvalidToleranceReason,
    },
    #[non_exhaustive]
    Asymmetric {
        row: usize,
        col: usize,
        dim: usize,
        upper: f64,
        lower: f64,
        allowed_abs_diff: f64,
    },
    #[non_exhaustive]
    NotPositiveSemidefinite {
        pivot_col: usize,
        violation: PositiveSemidefiniteViolation,
    },
}

Linear algebra errors.

This enum and each struct-style variant are #[non_exhaustive] so downstream matches must retain a wildcard for future error categories and fields.

Examples

use la_stack::prelude::*;

match LaError::singular_exact(2) {
    LaError::Singular {
        pivot_col,
        reason: SingularityReason::Exact,
        ..
    } => assert_eq!(pivot_col, 2),
    _ => unreachable!("constructor returns an exact singularity"),
}

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.

#[non_exhaustive]

Singular

A matrix is exactly or numerically singular.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

pivot_col: usize

Factorization column or step where a usable pivot was unavailable.

reason: SingularityReason

Typed reason for the singularity classification.

#[non_exhaustive]

NonFinite

A caller input or arithmetic result is NaN or infinite.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

location: NonFiniteLocation

Typed location of the value.

origin: NonFiniteOrigin

Whether the value came from input or a particular computation.

#[non_exhaustive]

Unrepresentable

An exact result cannot satisfy the requested finite-f64 conversion.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

index: Option<usize>

Failed vector component, or None for a scalar result.

reason: UnrepresentableReason

Reason the conversion contract cannot be satisfied.

#[non_exhaustive]

DeterminantScaleOverflow

Exact determinant scaling overflowed the internal exponent representation.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

dim: usize

Matrix dimension D.

min_exponent: i32

Minimum decomposed binary64 exponent among non-zero entries.

#[non_exhaustive]

UnsupportedDimension

A runtime matrix dimension has no stack-dispatch arm.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

requested: usize

Runtime dimension requested by the caller.

max: usize

Largest dimension supported by the dispatch helper.

#[non_exhaustive]

IndexOutOfBounds

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

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

row: usize

Requested row.

col: usize

Requested column.

dim: usize

Matrix dimension D; valid indices are less than this value.

#[non_exhaustive]

InvalidTolerance

A raw tolerance is negative or non-finite.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

value: f64

Raw value supplied by the caller.

reason: InvalidToleranceReason

Typed reason the value violates the tolerance invariant.

#[non_exhaustive]

Asymmetric

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

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

row: usize

Row of the upper-triangular entry.

col: usize

Column of the upper-triangular entry.

dim: usize

Matrix dimension D.

upper: f64

Observed entry at (row, col).

lower: f64

Observed entry at (col, row).

allowed_abs_diff: f64

Maximum absolute difference allowed by the symmetry check.

#[non_exhaustive]

NotPositiveSemidefinite

A computed LDLT pivot violates the no-pivot positive-semidefinite factorization requirements.

This diagnoses a binary64 factorization rejection; it is not an exact certificate that the stored matrix is indefinite.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

pivot_col: usize

LDLT pivot column or step where the violation was detected.

violation: PositiveSemidefiniteViolation

Typed PSD-domain violation.

Implementations

impl LaError

pub const fn singular_exact(pivot_col: usize) -> Self

Construct a LaError::Singular error proving that the pivot at pivot_col is exactly zero.

pub const fn singular_numerical( pivot_col: usize, factorization: FactorizationKind, pivot_magnitude: f64, tolerance: f64, ) -> Self

Construct a LaError::Singular error for a pivot rejected by a factorization tolerance, preserving the factorization, pivot magnitude, and tolerance in SingularityReason::Numerical.

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

Construct a LaError::NonFinite input error located at matrix cell (row, col).

pub const fn non_finite_input_vector(index: usize) -> Self

Construct a LaError::NonFinite input error located at vector entry index.

pub const fn non_finite_input_scalar() -> Self

Construct a LaError::NonFinite input error for a scalar without an index or matrix coordinate.

pub const fn non_finite_computation_matrix( operation: ArithmeticOperation, row: usize, col: usize, ) -> Self

Construct a LaError::NonFinite computation error at matrix cell (row, col), retaining the originating operation.

pub const fn non_finite_computation_step( operation: ArithmeticOperation, index: usize, ) -> Self

Construct a LaError::NonFinite computation error at index, retaining the originating operation.

pub const fn non_finite_computation_scalar( operation: ArithmeticOperation, ) -> Self

Construct a scalar LaError::NonFinite computation error retaining the originating operation.

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

Construct a LaError::Unrepresentable conversion failure for a scalar (index = None) or vector component (index = Some(_)).

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

Return the typed exact-to-f64 conversion reason, or None for every other error variant.

pub const fn requires_rounding(&self) -> bool

Return whether this is a RequiresRounding conversion failure for which retrying with an explicit rounded API may succeed.

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

Construct a LaError::DeterminantScaleOverflow retaining the matrix dimension and minimum decomposed entry exponent.

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

Construct a LaError::UnsupportedDimension retaining the requested and maximum supported dimensions.

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

Construct a LaError::IndexOutOfBounds retaining the requested matrix coordinates and dimension.

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

Construct an invalid-tolerance error and classify its typed reason.

This low-level constructor assumes value has already failed the tolerance invariant; raw caller input should normally be parsed through crate::Tolerance::try_new. Non-finiteness takes precedence over negativity, so negative infinity is classified as InvalidToleranceReason::NotFinite.

pub const fn asymmetric( row: usize, col: usize, dim: usize, upper: f64, lower: f64, allowed_abs_diff: f64, ) -> Self

Construct a LaError::Asymmetric error for the pair (row, col) and (col, row), retaining both observed values and the effective absolute difference bound.

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

Construct a LaError::NotPositiveSemidefinite error for a computed negative LDLT diagonal pivot.

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

Construct a LaError::NotPositiveSemidefinite error for a computed zero LDLT diagonal with a non-zero coupling at row, distinguishing the observed factorization violation from an uncoupled singular pivot.

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for LaError