Struct UnifiedFitResult 

pub struct UnifiedFitResult {

    pub blocks: Vec<FittedBlock>,
    pub log_lambdas: Array1<f64>,
    pub lambdas: Array1<f64>,
    pub likelihood_family: Option<LikelihoodSpec>,
    pub likelihood_scale: LikelihoodScaleMetadata,
    pub log_likelihood_normalization: LogLikelihoodNormalization,
    pub log_likelihood: f64,
    pub deviance: f64,
    pub reml_score: f64,
    pub stable_penalty_term: f64,
    pub penalized_objective: f64,
    pub used_device: bool,
    pub outer_iterations: usize,
    pub outer_converged: bool,
    pub outer_gradient_norm: Option<f64>,
    pub standard_deviation: f64,
    pub covariance_conditional: Option<Array2<f64>>,
    pub covariance_corrected: Option<Array2<f64>>,
    pub inference: Option<FitInference>,
    pub fitted_link: FittedLinkState,
    pub geometry: Option<FitGeometry>,
    pub block_states: Vec<ParameterBlockState>,
    pub beta: Array1<f64>,
    pub pirls_status: PirlsStatus,
    pub max_abs_eta: f64,
    pub constraint_kkt: Option<ConstraintKktDiagnostics>,
    pub artifacts: FitArtifacts,
    pub inner_cycles: usize,
    pub outer_cost_evals: usize,
    pub inner_pirls_solves: usize,
}

Unified fit result for all model types (standard GAM, GAMLSS, survival).

Standard models have a single block; GAMLSS and survival models have multiple blocks with different roles.

Fields

blocks: Vec<FittedBlock>

Coefficient blocks (1 for standard GAM, N for GAMLSS/survival).

log_lambdas: Array1<f64>

Log-smoothing parameters (all blocks concatenated in block order).

lambdas: Array1<f64>

Smoothing parameters (exp of log_lambdas).

likelihood_family: Option<LikelihoodSpec>

Explicit engine-level family, when the fit uses a built-in family.

likelihood_scale: LikelihoodScaleMetadata

Fixed-scale metadata for the fitted likelihood.

log_likelihood_normalization: LogLikelihoodNormalization

Whether log_likelihood includes response-only normalization constants.

log_likelihood: f64

Log-likelihood at the converged mode.

deviance: f64

Explicit deviance reported by the fitting path.

reml_score: f64

Complete REML/LAML objective value used for smoothing selection.

stable_penalty_term: f64

Stable quadratic penalty term βᵀSβ, including any solver ridge quadratic.

penalized_objective: f64

Public objective value reported for the fit. For REML/LAML fits this is the same complete objective as reml_score, not -ℓ + penalty + reml_score.

used_device: bool

Whether the converged fit used a GPU execution path for its final inner solve.

outer_iterations: usize

Number of outer (smoothing parameter) iterations.

outer_converged: bool

Whether the outer optimization converged.

outer_gradient_norm: Option<f64>

Final gradient norm of the outer optimization. None when no gradient was measured at termination — cache-hit short-circuit (the prior fit’s converged ρ was loaded from disk), gradient-free solver, or a degenerate early-exit path where no outer ran. outer_converged is the authoritative convergence signal.

standard_deviation: f64

Residual scale on the response scale.

Contract: Gaussian identity models store residual standard deviation sigma here. Non-Gaussian families keep the response-scale summary used by their explicit likelihood-scale metadata.

covariance_conditional: Option<Array2<f64>>

Vb: Bayesian/conditional covariance Var(β | λ) = H⁻¹ * φ̂ for the joint coefficient vector.

covariance_corrected: Option<Array2<f64>>

Vp: Bayesian covariance with smoothing-parameter uncertainty correction.

inference: Option<FitInference>

Inference quantities from the inner solver (EDF, Hessian, etc.).

fitted_link: FittedLinkState

Fitted link parameters (SAS, BetaLogistic, Mixture).

geometry: Option<FitGeometry>

Working-set geometry at convergence (for ALO diagnostics and saved-model covariance reconstruction).

block_states: Vec<ParameterBlockState>

Internal block states from custom-family paths.

beta: Array1<f64>

Joint coefficient vector (first block for standard GAMs, concatenated for multi-block).

pirls_status: PirlsStatus

Inner solver convergence status. Required at decode time: a missing field on an older-schema or corrupted saved model previously decoded as Converged via a default, silently promoting non-converged β̂ through warm-start propagation, predict-time confidence intervals, and outer-loop convergence semantics. With the MODEL_PAYLOAD_VERSION gate in place, older schemas are rejected before this field is read, so requiring the field here is safe and strictly removes the silent default.

max_abs_eta: f64

Maximum absolute linear predictor value at convergence.

constraint_kkt: Option<ConstraintKktDiagnostics>

Constraint KKT diagnostics (monotone-constrained fits).

artifacts: FitArtifacts

Solver artifacts (e.g. cached PIRLS result for ALO).

inner_cycles: usize

Inner cycle count (blockwise path).

outer_cost_evals: usize

Number of outer REML cost-only evaluations the fit executed (each trust-region / line-search probe drives one, paying an inner P-IRLS solve). Diagnostic only — guards regressions in outer work (#1575) and is not part of the statistical contract. Zero for paths that do not run the standard external REML optimizer.

inner_pirls_solves: usize

Number of actual full-n inner P-IRLS solves the fit performed (the cache-missing solves across the seed-grid prepass, screening, multistart, and finalize). This is the true #1575 cost metric — distinct from, and typically ~2× larger than, outer_cost_evals, which counts outer requests including single-slot cache hits. Diagnostic only; not part of the statistical contract. Zero for paths that do not run the standard external REML optimizer.

Implementations

impl UnifiedFitResult

pub fn try_from_parts( parts: UnifiedFitResultParts, ) -> Result<Self, EstimationError>

pub fn validate_numeric_finiteness(&self) -> Result<(), EstimationError>

impl UnifiedFitResult

pub fn new_for_test_unchecked(parts: UnifiedFitResultParts) -> Self

impl UnifiedFitResult

pub fn beta_covariance(&self) -> Option<&Array2<f64>>

Get the conditional Bayesian covariance matrix (Vb) if available.

Contract: Vb = H^{-1} * phi, scaled by the fitted dispersion. This is the Wood/mgcv Vb (Bayesian/conditional) covariance.

pub fn beta_covariance_ve(&self) -> Option<&Array2<f64>>

Get the frequentist sandwich covariance (Ve) if available.

Wood/mgcv Ve = H⁻¹ X'WX H⁻¹ * φ̂.

pub fn coefficient_influence(&self) -> Option<&Array2<f64>>

Get coefficient-space influence matrix F = H^{-1}X'WX if available.

pub fn weighted_gram(&self) -> Option<&Array2<f64>>

Get the original-basis weighted Gram X'WX = H − S(λ) if available — the symmetric PSD matrix the Wood–Pya–Säfken corrected-EDF correction pairs with the smoothing-parameter uncertainty covariance (issue #1027).

pub fn dispersion(&self) -> Option<Dispersion>

Dispersion used to scale covariance matrices.

pub fn dispersion_phi(&self) -> f64

Canonical residual dispersion φ̂ — the response-level observation noise (Gaussian σ̂², Gamma 1/shape, Beta 1/(1+φ), fixed-scale families 1). This is the predictive observation-noise scale used to widen prediction observation intervals; it is NOT the coefficient-covariance scale (see Self::coefficient_covariance_scale). For families whose IRLS working weight already carries 1/φ, the two differ: the coefficient covariance is H⁻¹ (scale 1) while this dispersion stays 1/shape (#679).

Unlike Self::dispersion, which reads the cached inference block, this is computed from fields that always survive serialization (likelihood_family, likelihood_scale, standard_deviation). That matters for deployment-time consumers operating on a saved model whose inference block was dropped (e.g. core_saved_fit_result stores inference: None): the cached dispersion() is then None, but the scale is still recoverable and identical to the value used at fit time. When the cached block is present its dispersion is preferred verbatim so the two paths never diverge.

pub fn coefficient_covariance_scale(&self) -> f64

Multiplier that turns the stored unscaled inverse penalized Hessian H⁻¹ into the reported coefficient covariance Vb = H⁻¹·scale.

This is the deployment-time / serialized-model counterpart of GlmLikelihoodSpec::coefficient_covariance_scale, used wherever the full stored beta_covariance() is unavailable and Vb must be reconstructed from the factorized Hessian (large-model predict path). It returns the profiled residual variance σ̂² for the scale-free profiled Gaussian and 1.0 for every family whose IRLS working weight already carries the dispersion / full Fisher information (Gamma, Tweedie, Beta, Negative-Binomial, Poisson, Binomial) — see #679. For custom/GAMLSS paths with no engine-level family it falls back to 1.0.

pub fn beta_covariance_corrected(&self) -> Option<&Array2<f64>>

Get the smoothing-parameter-corrected beta covariance (Vp) if available.

Wood/mgcv name for the smoothing-parameter-corrected covariance Vp.

pub fn beta_standard_errors(&self) -> Option<&Array1<f64>>

Get beta standard errors (conditional) if available.

pub fn beta_standard_errors_corrected(&self) -> Option<&Array1<f64>>

Get smoothing-corrected beta standard errors if available.

pub fn bias_correction_beta(&self) -> Option<&Array1<f64>>

Get the O(n⁻¹) bias-correction vector b̂ = H⁻¹ S(λ̂) β̂ in the original coefficient basis, if available.

pub fn penalized_hessian(&self) -> Option<&Array2<f64>>

Get the penalized Hessian if available.

Boundary accessor: returns &Array2<f64> so out-of-scope consumers (CLI, GPU, families) keep their pre-newtype call shape. Use Self::penalized_hessian_unscaled when the caller wants the [UnscaledPrecision] newtype to enforce the dispersion-ownership invariant.

pub fn penalized_hessian_unscaled(&self) -> Option<&UnscaledPrecision>

Get the penalized Hessian as the [UnscaledPrecision] newtype if available. Use this when constructing newtype-aware APIs (HMC whitening, sampling) so the dispersion convention is enforced at the type level.

pub fn beta_covariance_phi_scaled(&self) -> Option<&PhiScaledCovariance>

Get the φ-scaled posterior covariance as the [PhiScaledCovariance] newtype if available, sourced from FitInference::beta_covariance.

Prefer this over Self::beta_covariance in inference-internal code so the φ-scaled invariant is type-enforced.

pub fn working_weights(&self) -> Option<&Array1<f64>>

Get working weights if available.

pub fn working_response(&self) -> Option<&Array1<f64>>

Get working response if available.

pub fn smoothing_correction(&self) -> Option<&Array2<f64>>

Smoothing-parameter uncertainty covariance contribution J·Var(ρ)·Jᵀ in coefficient space, on the same dispersion scale as the conditional covariance Vb = φ·H⁻¹. This is the exact ρ-uncertainty term assembled from the IFT dβ̂/dρ and the outer Hessian at the fit optimum; the model-comparison machinery divides it by φ to recover the H⁻¹-scale ρ-covariance needed for the Wood–Pya–Säfken corrected EDF.

pub fn edf_total(&self) -> Option<f64>

Total effective degrees of freedom.

pub fn edf_by_block(&self) -> &[f64]

EDF by block.

pub fn penalty_block_trace(&self) -> &[f64]

Raw per-penalty-block trace tr_kk = λ_kk·tr(H⁻¹ S_kk), aligned 1:1 with lambdas. Empty when the producing path did not record traces (issue #1219); callers must treat an empty slice as “unavailable”.

pub fn per_term_edf( &self, coeff_range: Range<usize>, penalty_cursor: usize, k: usize, ) -> f64

Per-term effective degrees of freedom over a smooth/random-effect term’s coefficient block, defined as the trace of the linear-smoother influence matrix F = H⁻¹X'WX restricted to that block:

edf_term = Σ_{j ∈ coeff_range} F[j,j]
         = |coeff_range| − Σ_{kk ∈ term} tr_kk,   tr_kk = λ_kk·tr(H⁻¹ S_kk).

This is additive across terms and sums exactly to edf_total = p − Σ_all tr_kk, so a term’s EDF can never exceed the model total or the design column count. The legacy per-block EDF sum Σ_kk (rank(S_kk) − tr_kk) double-counts shared tensor coefficients for te/ti (and anisotropic / adaptive) smooths, where several penalty blocks span the same coefficient range and Σ_kk rank(S_kk) ≫ |coeff_range| (#1219, #1277).

penalty_cursor is the index of the term’s first penalty block in the flat lambdas / penalty_block_trace / edf_by_block layout, and k is the number of penalty blocks the term owns (0 for an unpenalised term).

Resolution order, each exact when available: the influence-matrix trace (the model’s own definition), then |coeff_range| − Σ tr_kk from the stored per-block traces (basis-invariant; exact even when F was never materialised for a large model), then — only when neither was recorded — the legacy block-sum as a last resort.

pub fn block_by_role(&self, role: BlockRole) -> Option<&FittedBlock>

Find a block by role.

pub fn beta_flat(&self) -> Array1<f64>

Flat coefficient vector (all blocks concatenated). This is equivalent to self.beta.clone().

pub fn beta_time(&self) -> Array1<f64>

Time/baseline-hazard coefficients (survival location-scale).

pub fn beta_threshold(&self) -> Array1<f64>

Threshold coefficients (survival location-scale).

pub fn beta_log_sigma(&self) -> Array1<f64>

Log-sigma coefficients (survival location-scale).

pub fn beta_link_wiggle(&self) -> Option<Array1<f64>>

Link-wiggle coefficients (survival location-scale, optional).

pub fn lambdas_time(&self) -> Array1<f64>

Smoothing parameters for time block.

pub fn lambdas_threshold(&self) -> Array1<f64>

Smoothing parameters for threshold block.

pub fn lambdas_log_sigma(&self) -> Array1<f64>

Smoothing parameters for log-sigma block.

pub fn lambdas_linkwiggle(&self) -> Option<Array1<f64>>

Smoothing parameters for link-wiggle block.

pub fn n_blocks(&self) -> usize

Number of coefficient blocks.

pub fn block_roles(&self) -> Vec<BlockRole>

Block roles.

pub fn fitted_link_state( &self, family: &LikelihoodSpec, ) -> Result<FittedLinkState, EstimationError>

Resolve the fitted link state for a given family.

For standard (non-adaptive) link families, no extra state is fitted, so this returns the bare FittedLinkState::Standard(None) payload — the concrete LinkFunction lives on the family/spec and is not duplicated into the fitted-link record. For adaptive links (SAS, BetaLogistic, Mixture, LatentCLogLog) it validates that the stored state matches the family and clones it out.

Trait Implementations

impl Clone for UnifiedFitResult

fn clone(&self) -> UnifiedFitResult

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for UnifiedFitResult

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for UnifiedFitResult

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for UnifiedFitResult

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.