Enum Error 

#[non_exhaustive]
pub enum Error {
    InvalidParam(&'static str),
    AupdFailed {
        info: i32,
        iters: usize,
        nconv: usize,
        n_matvec: usize,
    },
    EupdFailed {
        info: i32,
        iters: usize,
        nconv: usize,
        n_matvec: usize,
    },
    UnexpectedIdo(i32),
    MaxIterReached {
        iters: usize,
        nconv: usize,
        n_matvec: usize,
    },
    NoShiftsApplied {
        iters: usize,
        nconv: usize,
        n_matvec: usize,
    },
    ArnoldiFactorizationFailed {
        iters: usize,
        factorization_size: usize,
        n_matvec: usize,
    },
}

Errors raised by the safe ARPACK wrappers.

Documented ARPACK info codes are interpreted into named variants so a non-expert consumer sees the meaning rather than a bare number, while the raw info is retained as a field on the catch-all variants so an ARPACK expert can still match it against the Users’ Guide. Each variant also carries the iparam writeback counters (iters, nconv, n_matvec) describing the run that produced it.

Most documented codes are never observed here: the wrapper validates n / nev / ncv / max_iter / which and hardcodes bmat, mode, and ishift before the FFI call, so the parameter-misuse band (info = -1..-7, -10..-13, the howmny codes) cannot be returned by ARPACK. The reachable non-success *aupd_c codes are info = 1 (Error::MaxIterReached / partial Ok), info = 3 (Error::NoShiftsApplied), info = -9999 (Error::ArnoldiFactorizationFailed), and the rare internal failures -8 / -9 (catch-all Error::AupdFailed).

info = 1 from *aupd_c (max_iter reached before all nev Ritz pairs converged) splits two ways depending on the converged count reported in iparam[4]:

• nconv == 0: no usable Ritz pair. Mapped to Error::MaxIterReached with the diagnostic counters preserved so the caller can retry with a larger budget. The wrapper does not call *eupd_c in this case (symmetric *seupd would quick-return with d/z untouched; complex *neupd would return info = -14).
• 0 < nconv < nev: partial extraction. Mapped to Ok(MultiEigSolution { nconv, .. }) carrying the nconv converged pairs ARPACK was able to produce. This branch is only reachable from the multi-eigenpair drivers (eigenpairs_*); the nev = 1 wrappers cannot observe it because there is no integer strictly between 0 and 1.

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.

InvalidParam(&'static str)

A wrapper-side parameter check failed before any FFI call.

AupdFailed

*aupd_c returned a non-zero info code that is not separately modelled — a rare internal failure such as info = -8 (error from the LAPACK eigenvalue calculation) or info = -9 (a degenerate starting vector). The raw info is retained for expert diagnosis; the iparam writeback counters describe the run.

Fields

info: i32

The raw *aupd_c info code (always non-zero, and not one of the separately modelled values 1 / 3 / -9999).

iters: usize

iparam[2] writeback — restart iterations performed.

nconv: usize

iparam[4] writeback — converged Ritz value count.

n_matvec: usize

iparam[8] writeback — operator applications performed.

EupdFailed

*eupd_c (eigenvector extraction) returned a non-zero info code. Extraction failures are rare internal LAPACK and converged-count-consistency errors whose numeric codes differ between the real-symmetric and complex families, so they are surfaced generically with the raw info retained rather than modelled per code.

Fields

info: i32

The raw *eupd_c info code (always non-zero).

iters: usize

iparam[2] writeback — restart iterations performed.

nconv: usize

iparam[4] writeback — converged Ritz value count.

n_matvec: usize

iparam[8] writeback — operator applications performed.

UnexpectedIdo(i32)

*aupd_c requested an ido value the wrapper does not support (currently ido = 2, which only occurs for generalized eigenproblems with bmat = 'G').

MaxIterReached

*aupd_c returned info = 1 AND iparam[4] == 0: the iteration hit max_iter with zero converged Ritz pairs, so no eigenpair could be extracted. The iparam writeback counters are preserved so the caller can retry with a larger max_iter. The partial-extraction case (0 < nconv < nev) is reported through Ok(MultiEigSolution { nconv, .. }) instead and never via this variant.

Fields

iters: usize

iparam[2] writeback — restart iterations performed (equals Options::max_iter when the cap was hit).

nconv: usize

iparam[4] writeback — converged Ritz value count. Always 0 when this variant is returned (positive nconv routes through Ok instead).

n_matvec: usize

iparam[8] writeback — operator applications performed.

NoShiftsApplied

*aupd_c returned info = 3: no shifts could be applied during a cycle of the Implicitly Restarted Arnoldi/Lanczos iteration, so the restart stalled before convergence. The usual remedy is to increase ncv relative to nev. The iparam writeback counters are preserved.

Fields

iters: usize

iparam[2] writeback — restart iterations performed.

nconv: usize

iparam[4] writeback — converged Ritz value count.

n_matvec: usize

iparam[8] writeback — operator applications performed.

ArnoldiFactorizationFailed

*aupd_c returned info = -9999: ARPACK could not build an Arnoldi factorization of the requested size within max_iter. Increasing max_iter or ncv may help. The iparam writeback counters are preserved.

Fields

iters: usize

iparam[2] writeback — restart iterations performed.

factorization_size: usize

iparam[4] writeback — for this code, IPARAM(5) returns the size of the Arnoldi factorization ARPACK did manage to build. Named distinctly from the nconv (converged Ritz count) field on the other variants because the same slot means a different thing here.

n_matvec: usize

iparam[8] writeback — operator applications performed.

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

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.