Enum EstimationError 

pub enum EstimationError {
    InvalidStabilization(InvalidStabilization),
    BasisError(BasisError),
    CustomFamily(CustomFamilyError),
    LinearSystemSolveFailed(FaerLinalgError),
    EigendecompositionFailed(FaerLinalgError),
    PenaltySpectrumNonFinite {
        context: String,
        index: usize,
        value: f64,
    },
    PenaltySpectrumIndefinite {
        context: String,
        index: usize,
        value: f64,
        tolerance: f64,
        scale: f64,
    },
    ParameterConstraintViolation(String),
    PirlsDidNotConverge {
        max_iterations: usize,
        last_change: f64,
    },
    FixedLambdaNewtonDidNotConverge {
        context: String,
        reason: FixedLambdaStallReason,
        objective_value: f64,
        stationarity: FixedLambdaStationarityEvidence,
        checkpoint: FixedLambdaCheckpoint,
    },
    BlockOrthogonalRemlDidNotConverge {
        iterations: usize,
        max_score_residual: f64,
        score_tol: f64,
        min_profile_curvature: f64,
        profile_curvature_roundoff: f64,
        last_scale_step: f64,
        cycle_detected: bool,
        rho_checkpoint: Vec<f64>,
    },
    NegativeBinomialAlternationDidNotConverge {
        rounds: usize,
        theta_checkpoint: f64,
        rho_projected_grad_norm: f64,
        rho_stationarity_bound: f64,
        theta_score_residual: f64,
        theta_stationarity_bound: f64,
        rho_checkpoint: Vec<f64>,
    },
    PerfectSeparationDetected {
        iteration: usize,
        max_abs_eta: f64,
    },
    PrefitPerfectSeparationDetected {
        column_index: usize,
        threshold: f64,
        positive_above_threshold: bool,
    },
    PrefitLinearSeparationDetected {
        min_signed_margin: f64,
        num_unpenalized_columns: usize,
        column_indices: Vec<usize>,
    },
    PrefitRankDeficientDesignDetected {
        rank: usize,
        num_unpenalized_columns: usize,
        min_eigenvalue: f64,
        tolerance: f64,
        column_indices: Vec<usize>,
    },
    PrefitNearDegenerateDesignDetected {
        num_unpenalized_columns: usize,
        condition_number: f64,
        min_eigenvalue: f64,
        max_eigenvalue: f64,
        tolerance: f64,
        column_indices: Vec<usize>,
    },
    MultinomialSeparationDetected {
        iteration: usize,
        max_abs_eta: f64,
        active_class_index: usize,
        row_index: usize,
    },
    HessianNotPositiveDefinite {
        min_eigenvalue: f64,
    },
    RemlOptimizationFailed(String),
    OuterObjectiveEvaluationFailed {
        context: String,
        source: Box<EstimationError>,
    },
    RemlDidNotConverge {
        context: String,
        reason: String,
        iterations: usize,
        final_value: f64,
        projected_grad_norm: Option<f64>,
        stationarity_bound: f64,
        stationarity_bound_rung: Option<StationarityRung>,
        rho_checkpoint: Vec<f64>,
    },
    FitDidNotConverge {
        inner_status: String,
        outer_status: String,
        outer_iterations: usize,
        final_value: f64,
        stationarity_residual: Option<f64>,
        stationarity_bound: Option<f64>,
        step_residual: Option<f64>,
        step_bound: Option<f64>,
        rho_checkpoint: Vec<f64>,
        resume_token: Option<String>,
    },
    GradientUnavailable {
        context: &'static str,
        mode: &'static str,
    },
    LayoutError(String),
    ModelOverparameterized {
        num_coeffs: usize,
        num_samples: usize,
        intercept_coeffs: usize,
        binary_main_coeffs: usize,
        primary_smooth_coeffs: usize,
        aux_main_coeffs: usize,
        binary_primary_interaction_coeffs: usize,
        aux_interaction_coeffs: usize,
    },
    ModelIsIllConditioned {
        condition_number: f64,
    },
    InvalidInput(String),
    InverseLinkDomainViolation {
        link: &'static str,
        eta: f64,
        lower: f64,
        upper: f64,
    },
    PirlsRowGeometryUnrepresentable {
        row: usize,
        quantity: &'static str,
        eta: f64,
        value: f64,
    },
    ExactTweedieSeriesWorkLimit {
        row: usize,
        required_terms_lower_bound: f64,
        budget: usize,
    },
    LogStrengthDomainViolation {
        coordinate: usize,
        value: f64,
        lower: f64,
        upper: f64,
    },
    MonotoneRoot(MonotoneRootError),
    CalibratorTrainingFailed(String),
    InvalidSpecification(String),
    PredictionError,
}

A comprehensive error type for the model estimation process.

Variants

InvalidStabilization(InvalidStabilization)

BasisError(BasisError)

CustomFamily(CustomFamilyError)

LinearSystemSolveFailed(FaerLinalgError)

EigendecompositionFailed(FaerLinalgError)

PenaltySpectrumNonFinite

Fields

context: String

index: usize

value: f64

PenaltySpectrumIndefinite

Fields

context: String

index: usize

value: f64

tolerance: f64

scale: f64

ParameterConstraintViolation(String)

PirlsDidNotConverge

Fields

max_iterations: usize

last_change: f64

FixedLambdaNewtonDidNotConverge

Fields

context: String

Which fixed-λ Newton entry stalled (e.g. the multinomial softmax or independent-binomial vector-GLM solve, or the Firth refit lane).

reason: FixedLambdaStallReason

Why the solver stopped without its convergence certificate.

objective_value: f64

Final value of the solver’s minimized criterion. For ordinary vector GLMs this is -log L + penalty; for the Firth lane it also includes the negative Jeffreys 0.5 log det(I) contribution.

stationarity: FixedLambdaStationarityEvidence

Exact first-order residual and the bound it failed to clear.

checkpoint: FixedLambdaCheckpoint

Last accepted coefficients and cumulative iteration count. This is work-preservation state, not a fitted model, and carries no covariance or prediction surface.

BlockOrthogonalRemlDidNotConverge

Fields

iterations: usize

Outer alternation passes executed before exhaustion.

max_score_residual: f64

Largest per-block |dV/drho| at the final iterate, normalized by the score’s natural magnitude d * max(1, rank).

score_tol: f64

Tolerance the residual had to meet for the convergence certificate.

min_profile_curvature: f64

Smallest eigenvalue of the analytic rho Hessian after profiling out the exact conditional scale block.

profile_curvature_roundoff: f64

Dimension-scaled eigensolver roundoff allowed below zero when certifying positive semidefiniteness.

last_scale_step: f64

Last max |Δ log scale-precision| fixed-point movement (evidence of whether the alternation was still moving or had stalled).

cycle_detected: bool

The alternation revisited an earlier (rho, scale) state exactly; as a deterministic map it can never certify, so it stopped early.

rho_checkpoint: Vec<f64>

Per-block log-lambda iterates at exhaustion; feed back through the entry point’s init_rhos to resume rather than restart.

NegativeBinomialAlternationDidNotConverge

Fields

rounds: usize

Joint block-coordinate rounds executed before exhaustion.

theta_checkpoint: f64

Conditional theta coordinate at the best measured checkpoint.

rho_projected_grad_norm: f64

KKT-projected rho-gradient norm at that checkpoint.

rho_stationarity_bound: f64

Bound the rho residual had to clear.

theta_score_residual: f64

Curvature-normalized log-theta score residual at that checkpoint.

theta_stationarity_bound: f64

Bound the theta residual had to clear.

rho_checkpoint: Vec<f64>

Best measured log-smoothing checkpoint for warm-started resume.

PerfectSeparationDetected

Fields

iteration: usize

max_abs_eta: f64

PrefitPerfectSeparationDetected

Fields

column_index: usize

threshold: f64

positive_above_threshold: bool

PrefitLinearSeparationDetected

Fields

min_signed_margin: f64

num_unpenalized_columns: usize

column_indices: Vec<usize>

PrefitRankDeficientDesignDetected

Fields

rank: usize

num_unpenalized_columns: usize

min_eigenvalue: f64

tolerance: f64

column_indices: Vec<usize>

PrefitNearDegenerateDesignDetected

Fields

num_unpenalized_columns: usize

condition_number: f64

min_eigenvalue: f64

max_eigenvalue: f64

tolerance: f64

column_indices: Vec<usize>

MultinomialSeparationDetected

Fields

iteration: usize

max_abs_eta: f64

active_class_index: usize

row_index: usize

HessianNotPositiveDefinite

Fields

min_eigenvalue: f64

RemlOptimizationFailed(String)

OuterObjectiveEvaluationFailed

Fields

context: String

source: Box<EstimationError>

RemlDidNotConverge

Fields

context: String

Fit context label (the same string the outer runner logs under).

reason: String

Which certificate failed: budget exhaustion, line-search collapse, non-stationary cost stall, or a failed post-solve stationarity certificate.

iterations: usize

Outer iterations executed across all solver restarts.

final_value: f64

Objective value at the abandoned best iterate.

projected_grad_norm: Option<f64>

KKT-projected gradient norm at the best iterate, when the solver measured a gradient there (None for gradient-free exits).

stationarity_bound: f64

Bound the projected gradient had to clear for the stationarity certificate.

stationarity_bound_rung: Option<StationarityRung>

Which rung of the ladder produced stationarity_bound (#2458).

None means the refusing route does not record its rung — which is itself the finding, not a gap in the message: it marks exactly the routes whose stationarity standard is still unobservable.

rho_checkpoint: Vec<f64>

Best (lowest-objective feasible) outer iterate at exhaustion. This is work-preservation evidence for resume — it is NOT a fit and no fitted-model API is reachable from it.

FitDidNotConverge

Fields

inner_status: String

Diagnostic inner-solver terminal status. This is deliberately a string at the neutral problem layer; concrete solver status enums live in downstream fitting crates.

outer_status: String

Outer terminal/certificate verdict.

outer_iterations: usize

Completed outer iterations at the rejected checkpoint.

final_value: f64

Objective value at the best available checkpoint.

stationarity_residual: Option<f64>

Exact analytic first-order gradient or root-equivalent fixed-point residual, when it was measured.

stationarity_bound: Option<f64>

Bound the first-order residual had to clear.

step_residual: Option<f64>

Final accepted-step residual, when the solver exported it.

step_bound: Option<f64>

Bound the step residual had to clear.

rho_checkpoint: Vec<f64>

Work-preserving smoothing checkpoint; this is not a fit.

resume_token: Option<String>

Opaque durable-cache resume token, when checkpoint persistence was enabled for the failed run.

GradientUnavailable

Fields

context: &'static str

mode: &'static str

LayoutError(String)

ModelOverparameterized

Fields

num_coeffs: usize

num_samples: usize

intercept_coeffs: usize

binary_main_coeffs: usize

primary_smooth_coeffs: usize

aux_main_coeffs: usize

binary_primary_interaction_coeffs: usize

aux_interaction_coeffs: usize

ModelIsIllConditioned

Fields

condition_number: f64

InvalidInput(String)

InverseLinkDomainViolation

Fields

link: &'static str

eta: f64

lower: f64

upper: f64

PirlsRowGeometryUnrepresentable

Fields

row: usize

quantity: &'static str

eta: f64

value: f64

ExactTweedieSeriesWorkLimit

Fields

row: usize

required_terms_lower_bound: f64

budget: usize

LogStrengthDomainViolation

Fields

coordinate: usize

value: f64

lower: f64

upper: f64

MonotoneRoot(MonotoneRootError)

CalibratorTrainingFailed(String)

InvalidSpecification(String)

PredictionError

Implementations

impl EstimationError

pub fn fatal_outer_evaluation( context: impl Into<String>, source: EstimationError, ) -> EstimationError

Preserve a thrown outer-objective failure across seed, solver, and fallback-plan orchestration. Trial-domain refusals must be represented as a finite API outcome (+inf / OuterEval::infeasible); an Err means the evaluation artifact itself could not be constructed and must never be retried as another numerical point.

pub fn is_fatal_outer_evaluation(&self) -> bool

pub fn is_inner_solve_retreat(&self) -> bool

Classifies inner-solve failures that the outer REML loop should treat as a soft retreat (return +inf cost / infeasible outer-eval) rather than propagate as a hard error.

Why: when the penalised Hessian becomes effectively singular at the current rho, when P-IRLS hits a perfect-separation diagnostic, or when it exhausts its iteration budget, the outer optimiser’s correct response is to back away from this rho — not to terminate the fit. All three variants encode “the inner problem at this rho is too hard to evaluate, try a different rho”.

Trait Implementations

impl Debug for EstimationError

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

Formats the value using the given formatter.

impl Display for EstimationError

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

Formats the value using the given formatter.

impl Error for EstimationError

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 From<BasisError> for EstimationError

fn from(source: BasisError) -> EstimationError

Converts to this type from the input type.

impl From<CustomFamilyError> for EstimationError

fn from(source: CustomFamilyError) -> EstimationError

Converts to this type from the input type.

impl From<IndexedLogStrengthDomainError> for EstimationError

fn from(error: IndexedLogStrengthDomainError) -> EstimationError

Converts to this type from the input type.

impl From<InvalidStabilization> for EstimationError

fn from(source: InvalidStabilization) -> EstimationError

Converts to this type from the input type.

impl From<LinalgError> for EstimationError

fn from(error: LinalgError) -> EstimationError

Converts to this type from the input type.

impl From<MonotoneRootError> for EstimationError

fn from(source: MonotoneRootError) -> EstimationError

Converts to this type from the input type.