Struct AutoOuterSubsampleOptions 

pub struct AutoOuterSubsampleOptions {
    pub min_n_for_auto: usize,
    pub min_k: usize,
    pub target_fraction: f64,
    pub seed: u64,
    pub outer_work_per_k_unit: u64,
    pub min_k_floor: usize,
}

Configuration for the automatic outer-score subsampler.

At large scale (n ≥ tens of thousands) the marginal-slope outer rho-gradient computes a sum-over-rows trace tr(F Fᵀ M_k) = Σ_i row_i(k) whose per-row work is dominated by the cell-moment kernel. Stratified Horvitz–Thompson subsampling replaces the full sum with an unbiased estimator using K of N rows; the trace cost drops from O(N · cell_work) to O(K · cell_work).

Math

Estimator T̂ = Σ_{i∈S} w_i · row_i with HT weights w_i = N_h / K_h (per-stratum) is unbiased: E[T̂] = T.

Variance under stratified SRS without replacement: Var(T̂) = Σ_h N_h² (1 − K_h/N_h) S_h² / K_h where S_h² is the within-stratum variance of per-row contributions. With proportional allocation K_h = K · N_h/N, the standard deviation of T̂ relative to T is roughly σ(T̂)/T ≈ (1/√K) · √(1 − K/N) · cv_within where cv_within is the within-stratum coefficient of variation.

The defaults are tuned so that the relative gradient-noise σ stays below ≈ 1 % across realistic n ∈ [30 000, 300 000+], assuming cv_within ≲ 1 (which holds for marginal-slope contributions because the z-decile stratification absorbs the dominant inhomogeneity).

Fields

min_n_for_auto: usize

Below this n, the auto-subsampler always returns None (use full data). Default 30 000.

min_k: usize

Floor on K, so the relative gradient noise stays bounded even when the target fraction would round to a smaller K. K = max(min_k, round(n · target_fraction)). Default 10 000 gives σ/T ≤ 1 % for cv_within ≤ 1 and any n ≥ min_n_for_auto.

target_fraction: f64

Target ratio K / n once n ≫ min_k. Default 0.10.

seed: u64

RNG seed for stratified mask construction. Default 0xA075_8AMP_LE_5UB5 (deterministic across runs at the same n, so CRN holds across BFGS iterations).

outer_work_per_k_unit: u64

Family-supplied per-unit-of-K outer-derivative work cost.

Despite the historical name, this is not a per-row quantity. It is predicted_outer_gradient_work / K evaluated at the family’s reference operating point — i.e. how many work units each additional row in the K-subsample contributes summed over all n. The auto schedule caps K by K_work = AUTO_OUTER_WORK_BUDGET / outer_work_per_k_unit, guaranteeing a single outer evaluation never exceeds AUTO_OUTER_WORK_BUDGET work units regardless of the noise-only target. Default 1 (no effective work cap beyond K ≤ n); families with measurable per-K cost (survival marginal-slope, BMS) overwrite at the call site.

Calibration recipe: from a profiled run, outer_work_per_k_unit = predicted_gradient_work / K. For the large-scale survival marginal-slope reference (predicted_gradient_work ≈ 4.33×10⁹ at K=19_661), this gives ~220_000; we use 250_000 as a conservative upper bound. With AUTO_OUTER_WORK_BUDGET = 5×10⁸ that caps K at ~2_000.

min_k_floor: usize

Absolute floor on the chosen K after the noise/work caps are combined. Default AUTO_OUTER_MIN_K_FLOOR.

Implementations

impl AutoOuterSubsampleOptions

pub fn target_k(&self, n: usize) -> Option<usize>

Compute the K that this configuration would pick for a given n. Returns None if n < min_n_for_auto (caller should not subsample).

pub fn target_k_detailed(&self, n: usize) -> Option<AutoOuterKChoice>

Same as [target_k] but also reports the noise-only K, the work-budget cap, and which constraint set the final value. Used by maybe_install_auto_outer_subsample to surface a cap_reason in the auto-subsample log line.

Trait Implementations

impl Clone for AutoOuterSubsampleOptions

fn clone(&self) -> AutoOuterSubsampleOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AutoOuterSubsampleOptions

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

Formats the value using the given formatter.

impl Default for AutoOuterSubsampleOptions

fn default() -> Self

Returns the “default value” for a type.