Enum PiggybackError 

#[non_exhaustive]
pub enum PiggybackError {
    PrimalDivergence {
        iteration: usize,
        last_norm: f64,
    },
    TangentDivergence {
        iteration: usize,
        last_norm: f64,
    },
    AdjointDivergence {
        iteration: usize,
        last_norm: f64,
    },
    IterationsExhaustedTangent {
        iteration: usize,
        z_norm: f64,
    },
    IterationsExhaustedAdjoint {
        iteration: usize,
        lam_norm: f64,
    },
    IterationsExhaustedForwardAdjoint {
        iteration: usize,
        z_norm: f64,
        lam_norm: f64,
    },
    DimensionMismatch {
        field: &'static str,
        expected: usize,
        actual: usize,
    },
}

Reason a piggyback solve failed to converge.

Marked #[non_exhaustive] so future variants can be added without breaking exhaustive matches. Numeric fields use f64 (cast via Float::to_f64) for uniform diagnostic output regardless of the solver’s F type.

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.

PrimalDivergence

The primal z_{k+1} = G(z_k, x) produced a non-finite norm (relative-norm ||z_new - z||/(1 + ||z||) is NaN/Inf), or the primal vector itself contained non-finite components in the forward-adjoint loop. last_norm is the primal-delta relative norm at the detecting iteration: non-finite when detection came from the norm check (the usual case); finite — and itself diagnostic — when detection came from the componentwise finite check (primal vector overflowed mid-iteration while the step-to-step delta stayed bounded).

Fields

iteration: usize

last_norm: f64

TangentDivergence

Primal stayed finite but the tangent ż_{k+1} = G_z · ż_k + G_x · ẋ produced non-finite values. Catches the ratio-converging case where the primal norm remains bounded while individual tangent components overflow. last_norm is the primal-delta relative norm at the detecting iteration — finite by construction here (the tangent-only divergence path takes the norm-finite branch before the componentwise check fires); surfacing it tells the caller the primal iteration was bounded while the JVP overflowed.

Fields

iteration: usize

last_norm: f64

AdjointDivergence

Adjoint λ_{k+1} = G_z^T · λ_k + z̄ produced non-finite values (norm or individual components). last_norm is the adjoint-delta relative norm at the detecting iteration: non-finite when detection came from the norm check; finite when it came from the componentwise lambda_new check.

Fields

iteration: usize

last_norm: f64

IterationsExhaustedTangent

piggyback_tangent_solve reached max_iter without meeting tol. z_norm is the final iteration’s relative primal-delta norm (||z_new - z|| / (1 + ||z||)) — a value just over tol signals proximity to convergence; many orders over signals stagnation. iteration equals max_iter.

Fields

iteration: usize

z_norm: f64

IterationsExhaustedAdjoint

piggyback_adjoint_solve reached max_iter without meeting tol. lam_norm is the final iteration’s relative adjoint- delta norm (||λ_new - λ|| / (1 + ||λ||)).

Fields

iteration: usize

lam_norm: f64

IterationsExhaustedForwardAdjoint

piggyback_forward_adjoint_solve reached max_iter without meeting tol on both norms simultaneously. Each field is the final iteration’s relative norm for the corresponding stream.

Fields

iteration: usize

z_norm: f64

lam_norm: f64

DimensionMismatch

A runtime-supplied vector argument to a public *_solve fn had an unexpected length. field names the argument (e.g. "z_dot", "z_bar"), expected is the length the API requires (typically num_states or x.len()), actual is the length the caller supplied.

Note: tape-shape contract mismatches (validate_step_tape) and step-fn argument mismatches (piggyback_tangent_step[_with_buf]) continue to panic — those are programmer-contract violations, not recoverable runtime failures.

Fields

field: &'static str

expected: usize

actual: usize

Trait Implementations

impl Clone for PiggybackError

fn clone(&self) -> PiggybackError

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PiggybackError

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

Formats the value using the given formatter.

impl Display for PiggybackError

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

Formats the value using the given formatter.

impl Error for PiggybackError

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.