Struct OuterCapability 

pub struct OuterCapability {
    pub gradient: Derivative,
    pub hessian: DeclaredHessianForm,
    pub n_params: usize,
    pub psi_dim: usize,
    pub fixed_point_available: bool,
    pub barrier_config: Option<BarrierConfig>,
    pub prefer_gradient_only: bool,
    pub disable_fixed_point: bool,
}

Fields

gradient: Derivative

hessian: DeclaredHessianForm

Declared shape of the analytic Hessian (or its absence). Replaces the binary Derivative so the planner can route between dense ARC and matrix-free trust-region before seed evaluation. See DeclaredHessianForm.

n_params: usize

Number of smoothing (+ any auxiliary hyper-) parameters being optimized.

psi_dim: usize

Number of ψ (design-moving) coordinates among the extended hyperparameter coordinates. When 0, all coords are penalty-like and pure EFS is eligible (given fixed_point_available). When > 0, hybrid EFS is eligible instead: EFS for ρ + preconditioned gradient for ψ.

Hybrid EFS strategy (when psi_dim > 0)

Enabled when psi_dim > 0, n_params > SMALL_OUTER_BFGS_MAX_PARAMS, and fixed_point_available. Combines:

• Standard EFS multiplicative fixed-point updates for ρ coordinates
• Safeguarded preconditioned gradient steps for ψ coordinates: Δψ = -α G⁺ g_ψ where G is the trace Gram matrix

Mathematically necessary because no EFS-type fixed-point iteration exists for indefinite B_ψ (see response.md Section 2). The structural requirement for EFS is H^{-1/2} B_d H^{-1/2} ≽ 0 (PSD) plus fixed nullspace — exactly what penalty-like coords satisfy and design-moving coords do not.

The hybrid is O(1) H⁻¹ solves per iteration (same as pure EFS), compared to O(dim(θ)) for BFGS.

fixed_point_available: bool

Whether the objective actually implements eval_efs() for fixed-point plans. Structural eligibility (psi_dim == 0 / psi_dim > 0) is not sufficient by itself: if this is false, the planner must stay on Newton/BFGS-style plans even when EFS or Hybrid-EFS would otherwise be mathematically admissible.

barrier_config: Option<BarrierConfig>

Optional log-barrier configuration for structural monotonicity constraints. When present, EFS is still eligible at plan time, but the EFS iteration loop performs a quantitative check each step: if barrier_curvature_is_significant(β, ref_diag, threshold) fires, EFS is abandoned and the fallback ladder routes to a first-order joint optimizer.

Previously this was a binary barrier_active: bool that unconditionally blocked EFS. The quantitative check allows EFS when constraints exist but the barrier curvature is negligible (coefficients far from their bounds).

prefer_gradient_only: bool

Policy hint for derivative-free auxiliary optimizers only. Primary REML optimization ignores this flag when an analytic Hessian exists: exact second-order geometry must not be hidden behind a quasi-Newton policy.

disable_fixed_point: bool

Policy hint: even when the objective implements eval_efs() and the coordinate structure is penalty-like, the planner must NOT select EFS/HybridEfs for this problem.

Set by the caller for problem classes where the Wood-Fasiolo structural property (H^{-1/2} B_k H^{-1/2} ≽ 0 plus parameter-independent nullspace) is known not to hold — e.g. GAMLSS/location-scale families where the joint Hessian is β-dependent and cross-block smoothers induce non-diagonal curvature that the EFS multiplicative fixed-point cannot resolve. Also set by the automatic fallback cascade when an EFS/HybridEfs attempt failed to converge, so the next attempt falls back to analytic-gradient BFGS rather than retrying EFS.

Implementations

impl OuterCapability

pub const fn theta_layout(&self) -> OuterThetaLayout

pub fn validate_layout(&self, context: &str) -> Result<(), EstimationError>

pub const fn all_penalty_like(&self) -> bool

True when all coordinates are penalty-like (no ψ coords).

pub const fn has_psi_coords(&self) -> bool

True when ψ (design-moving) coordinates are present.

Trait Implementations

impl Clone for OuterCapability

fn clone(&self) -> OuterCapability

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for OuterCapability

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

Formats the value using the given formatter.