Module rho_optimizer 

Central authority for outer smoothing-parameter optimization strategy.

Every path that optimizes smoothing parameters (standard REML, link-wiggle, GAMLSS custom family, spatial kappa, etc.) declares its derivative capability here and receives an OuterPlan that determines which solver and Hessian source to use.

Design invariant

The planner never synthesizes numerical Hessians. If a path cannot provide an analytic Hessian, that fact is visible in its OuterCapability declaration and in the resulting OuterPlan, which falls back to BFGS or an EFS variant instead of synthesizing second-order curvature numerically.

Re-exports

pub use crate::model_types::CriterionCertificate;

Structs

ClosureObjective

Closure-based adapter for OuterObjective.

EfsEval

Result bundle returned by the EFS (extended Fellner–Schall) evaluation path. Pure data: families compute the additive step and the optional curvature/gradient diagnostics; the solver consumes them.

OuterCapability

OuterEval

Shared outer-objective result used by optimizer-facing objective implementations.

OuterGradientFdAudit

Result of a component-by-component finite-difference audit of an outer REML/LAML gradient at a fixed θ, plus the outer-Hessian eigenvalues.

OuterGradientFdComponent

Per-θ component of an outer-gradient finite-difference audit.

OuterPlan

The outer optimization plan. Produced by plan, consumed by the runner.

OuterProblem

Declarative outer-problem builder. Produces both the OuterCapability (what the objective can provide) and the [OuterConfig] (how the runner should behave) from a small set of high-level declarations.

OuterResult

Result of a completed outer optimization.

OuterThetaLayout

Enums

DeclaredHessianForm

Capability-time declaration of what shape the outer Hessian takes. Replaces the binary Derivative for the Hessian field on OuterCapability: callers that know the shape upfront declare it here, and the planner routes between dense ARC and matrix-free trust-region before seed evaluation rather than dynamically branching on seed_eval.hessian at runtime.

Derivative

Whether an analytic derivative is available for a given order.

FallbackPolicy

Whether outer_strategy should automatically derive a retry ladder from the primary capability, or disable retries entirely.

HessianResult

Explicit Hessian result replacing Option<Array2<f64>>.

HessianSource

How the Hessian will be obtained for the outer optimizer.

OuterEvalOrder

Requested derivative order for an outer objective evaluation.

OuterHessianMaterialization

Exact dense-materialization route exposed by an outer Hessian operator.

OuterStrategyError

Typed error for the outer-strategy Hessian-operator surface.

SeedOutcome

Outcome of OuterObjective::seed_inner_state.

Solver

Which solver algorithm to use for the outer optimization.

Traits

OuterHessianOperator

Matrix-free outer Hessian operator.

OuterObjective

Common interface for outer smoothing-parameter objectives.

Functions

arm_outer_wall_clock_deadline

Arm the global outer wall-clock deadline for the current fit. pub so FFI fit entries (the SAE manifold fit is orchestrated from the gam-pyffi crate) can bound their outer search the same way the in-crate survival entry does (see survival/marginal_slope/fit_entry.rs).

cache_entry_would_help_outer

clear_outer_wall_clock_deadline

Clear the armed deadline. Call on EVERY exit path of the arming fit. pub for the same FFI-entry reason as arm_outer_wall_clock_deadline.

log_plan

Log the outer optimization plan. Called once per fit at the start of outer optimization so the user can see what strategy was selected and why.

outer_gradient_fd_audit

Run a component-by-component central finite-difference audit of an outer REML/LAML gradient at a fixed θ₀.

outer_wall_clock_deadline_exceeded

True once an armed deadline has passed; false when none is armed, so every path that does not opt in is byte-for-byte unchanged.

plan

Select the outer optimization strategy from the declared capability.