Module marginal_slope_shared 

Shared kernels and outer-evaluation infrastructure for the marginal-slope family of GAMs (BMS, survival, latent survival).

Outer-row subsampling

At large scale (n ≥ tens of thousands) the outer rho-gradient is a sum-over-rows trace whose per-row cost is dominated by the cubic cell-moment kernel. The pieces here — AutoOuterSubsampleOptions, auto_outer_score_subsample, maybe_install_auto_outer_subsample, and build_outer_score_subsample — implement a stratified Horvitz–Thompson estimator that replaces the full row sum with an unbiased sample, gated by crate::custom_family::BlockwiseFitOptions::auto_outer_subsample and enabled by default for large marginal-slope fits.

maybe_install_auto_outer_subsample is the entry point family impls call: it consults the per-family phase counter and the per-family last-ρ mutex (used to detect distinct outer steps), installs a stratified mask for the first BMS_AUTO_SUBSAMPLE_PHASE1_BUDGET (or family analog) outer evaluations, and reverts to full data afterward so the BFGS/ARC convergence target outer_tol is reached on exact gradients rather than chasing the stochastic noise floor.

This subsampling is complementary to the trace-estimator tier system documented at the top of solver::reml::reml_outer_engine (exact / Hutchinson multi-target / Hutch++ single-target). They operate on orthogonal axes — the trace estimators reduce work within the Hessian structure for a fixed row set; subsampling reduces the row set itself for the family-specific row-trace path.

Structs

AutoOuterKChoice

Outcome of AutoOuterSubsampleOptions::target_k_detailed: the chosen K, the underlying noise-only choice, the work-budget cap, and which constraint won.

AutoOuterSubsampleOptions

Configuration for the automatic outer-score subsampler.

MarginalSlopeExactNewtonPsiWorkspace

Generic exact-Newton joint-ψ workspace shared by the marginal-slope families. Owns the σ-auxiliary dispatch skeleton and delegates every family-specific operation to its MarginalSlopePsiFamily impl.

Enums

AutoOuterCapReason

Reason the auto schedule chose the reported K. Used by the [family auto-subsample] log line so operators can tell whether the noise model, the work budget, the MIN_K_FLOOR, or n itself determined the subsample size.

OuterRowIter

Row-index iteration choice for outer-only score/gradient passes.

Constants

AUTO_OUTER_MIN_K_FLOOR

Absolute floor on K chosen by the auto schedule. Even when the work budget would drive K to a handful of rows the stratified mask cannot usefully shrink below MIN_K_FLOOR without collapsing entire deciles of z-strata. Set so the resulting gradient noise (~3 %) is still usable for BFGS Phase 1 progress when the family is very expensive.

AUTO_OUTER_WORK_BUDGET

Half-billion outer-derivative work units per evaluation. Picked so the rigid survival marginal-slope pilot Newton cycle (which previously ran ~57 min at n≈2e5 with K=19_661) finishes in a minute or two on commodity hardware once K is capped by this budget.

Traits

MarginalSlopePsiFamily

Family-specific ψ-calculus hooks for the shared exact-Newton joint-ψ workspace.

Functions

add_scaled_coeff4

auto_outer_score_subsample

Build a stratified outer-score subsample automatically from problem characteristics. Returns None for problems too small to benefit (the caller should fall back to the full-data path).

bail_if_cached_beta_non_finite

Canonical non-finite guard on a cached inner beta.

build_outer_score_subsample

Build a deterministic stratified row subsample of size ≥ k from (z, stratum_secondary).

eval_coeff4_at

feasible_step_fraction

Shared monotonicity line-search safeguard for time-block linear inequality constraints A·beta >= b.

make_beta_seed_validator

Canonical inner-cache beta_seed validator passed to the generic outer-engine (optimize_spatial_length_scale_exact_joint).

maybe_install_auto_outer_subsample

Two-phase auto-subsample guard shared across marginal-slope families.

outer_row_indices

Choose the row-iteration strategy for an outer-only pass. When opts.outer_score_subsample is Some, returns the subsample mask; otherwise returns the full range 0..n.

outer_row_weights_by_index

Dense-by-row HT weights of length n. Masked rows carry their HT weight; unmasked rows default to 1.0 so that callers who index by row regardless of subsampling still get a valid scalar (the consumer is expected to iterate only over outer_row_indices).

outer_weighted_rows

Per-row HT-weighted iteration: returns one WeightedOuterRow per retained row when a subsample is active; otherwise returns (index, weight = 1.0, stratum = 0) for every row in 0..n.

probit_frailty_scale

scale_coeff4