Struct OuterScoreSubsample 

pub struct OuterScoreSubsample {
    pub mask: Arc<Vec<usize>>,
    pub rows: Arc<Vec<WeightedOuterRow>>,
    pub n_full: usize,
    pub weight_scale: f64,
    pub seed: u64,
}

Stratified row index subsample shared across outer-loop evaluations.

mask is sorted, deduplicated, and never empty in practice (enforced by build_outer_score_subsample).

Per-row inverse-inclusion weights w_i = N_h / k_h (where h is the row’s stratum) are stored alongside the mask in rows. The Horvitz–Thompson estimator for any linear-in-row functional T = Σ_i f_i is T̂ = Σ_{i ∈ mask} w_i · f_i, which is unbiased even when per-stratum sampling fractions differ (the ceil(k * N_h / n).max(1) rule in the stratified builder makes rare strata oversample relative to the bulk, so a single global rescale n_full / |mask| is biased in those strata).

weight_scale is retained as a diagnostic (mean of w_i across the mask). It equals n_full / |mask| when all rows share a uniform inclusion probability (the caller-supplied-mask case represented by OuterScoreSubsample::from_uniform_inclusion_mask); it can drift from that value under the stratified builder’s rare-stratum boost. It is not the per-row scaling factor — consumers must read rows[i].weight for HT correctness.

Horvitz–Thompson contract

Per-row weight rows[i].weight = 1 / π_i, where π_i is the inclusion probability of row i under the stratified sampler. Any outer-only score/gradient routine that consumes this subsample must form Σ_{i ∈ mask} w_i · f_i so the resulting estimator is unbiased:

  E[ score_subsample ]  =  score_full.

The following families consume this subsample on their outer-loop hot paths: Gaussian-LS, Binomial-LS, the Wiggle variants, CTN, and Survival-LS. Each routes the rows[i].weight factor through its per-row accumulator (gradient, Hessian-action, trace probes).

Convergence warning

Subsampled gradients are noisy by construction. The outer driver must never declare convergence on a subsampled gradient — near convergence it switches back to the full-data score so that the KKT stopping test sees the unbiased, low-variance signal. New consumers adding subsampled paths must preserve this invariant.

Fields

mask: Arc<Vec<usize>>

rows: Arc<Vec<WeightedOuterRow>>

n_full: usize

weight_scale: f64

seed: u64

Implementations

impl OuterScoreSubsample

pub fn from_uniform_inclusion_mask( mask: Vec<usize>, n_full: usize, seed: u64, ) -> Self

Wrap a precomputed mask sampled with a uniform inclusion probability, assigning each selected row the inverse-inclusion weight n_full / m. The caller is responsible for sortedness and uniqueness; build_outer_score_subsample remains the stratified per-row HT builder.

pub fn with_uniform_weight( mask: Vec<usize>, n_full: usize, seed: u64, weight: f64, ) -> Self

Wrap a precomputed mask with an explicit uniform per-row weight. Useful for tests that need the unrescaled (weight = 1.0) sum over a custom mask, and for callers that already know the desired rescaling factor and don’t want the constructor to derive it from n_full / |mask|.

pub fn from_weighted_rows( rows: Vec<WeightedOuterRow>, n_full: usize, seed: u64, ) -> Self

Wrap a vector of (index, weight, stratum) triples. The mask is derived as the sorted/dedup’d index list. Used by the stratified builder to install per-row HT weights.

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn has_variable_weights(&self) -> bool

True when at least two retained rows have different per-row weights. Consumers that previously applied a single post-sum scalar must switch to per-row weighting whenever this returns true.

Trait Implementations

impl Clone for OuterScoreSubsample

fn clone(&self) -> OuterScoreSubsample

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for OuterScoreSubsample

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

Formats the value using the given formatter.