Module diagnostics 

Analytic diagnostic helpers for LAML/REML optimization.

Production diagnostics inspect analytic invariants only. Runtime fitting, prediction, and diagnostic APIs must consume quantities the optimizer already computes. This module implements diagnostic strategies that identify root causes of gradient pathologies from those analytic quantities:

1. KKT Audit (Envelope Theorem Check): Detects violations of the stationarity assumption used in implicit differentiation.

2. Spectral Bleed Trace: Detects when truncated eigenspace corrections are inconsistent with the penalty’s energy in that subspace.

3. Dual-Ridge Consistency Check: Verifies that the ridge used by the inner solver (PIRLS) matches what the outer gradient calculation assumes.

Structs

DiagnosticConfig

Configuration for gradient diagnostics

DualRidgeResult

Result of dual-ridge consistency check

EnvelopeAudit

Result of envelope theorem (KKT) audit

GradientDiagnosticReport

Complete diagnostic report for a gradient evaluation

PredictionDiagnostics

Residual diagnostics for observed values and predicted means.

SpectralBleedResult

Result of spectral bleed trace diagnostic

Enums

KktRefusalDiagnosis

Three-way classification of why the cert refused, computed from the H_pen spectrum and the projected residual at the refusing iterate. RankDeficientHPen is the regression canary the nullspace lead’s smooth-construction rework is intended to eliminate; keep this variant intact when extending — it doubles as the user-facing signal for “an unconstrained polynomial null space slipped past absorption.”

Constants

MIN_EIG_DIAG_EVERY

Repeat period within a magnitude bucket for the Hessian-minimum-eigenvalue diagnostic: after the first emission for a bucket, every Nth subsequent invocation also emits.

MIN_EIG_DIAG_THRESHOLD

Threshold below which a positive Hessian minimum eigenvalue is treated as nearly-singular and routed through the rate-limited diagnostic.

Statics

H_MIN_EIG_LOG_BUCKET

Rate-limited diagnostic for Hessian minimum eigenvalue warnings

H_MIN_EIG_LOG_COUNT

Count of should_emit_h_min_eig_diag invocations that have ever been considered for emission; used together with H_MIN_EIG_LOG_BUCKET to rate-limit one diagnostic per decade-magnitude bucket and per MIN_EIG_DIAG_EVERY repeats within the same bucket.

Functions

compute_dualridge_check

Check consistency between the ridge used in different stages of computation.

compute_envelopeaudit

Compute the inner KKT residual to detect envelope theorem violations.

diagnostics_from_predictions

Compute prediction residual diagnostics from observed values and predicted means.

format_top_abs

Diagnostic formatter shared across the outer optimizer and the custom-family fitter: shows the max_items entries of values with largest absolute value, formatted as label=[i:value, ...].

should_emit_h_min_eig_diag

Rate-limited check for Hessian minimum eigenvalue diagnostics. Returns true if this eigenvalue warrants a diagnostic message.