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 before both the primal and tangent step-deltas met 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; a value at or below tol means the primal had converged and the tangent (which starts at zero and converges on its own schedule) was the stream still iterating. 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.