Struct SeedProtocol

pub struct SeedProtocol { /* private fields */ }

Expand description

The seed protocol attached to a study: the fan width, the pairing and the aggregate.

The default is single-seed — tune_seeds = 1, no fan — so a study that never touches this type behaves exactly as it did before the protocol existed. See the module documentation for the seed formulas.

Implementations§

§

impl SeedProtocol

pub const fn new() -> Self

The single-seed default: tune_seeds = 1, no test seeds, Paired, Mean.

A study built with this protocol runs one evaluation per trial and takes the fast, fan-free path — byte-for-byte the behaviour of a study with no protocol at all.

pub const fn with_tune_seeds(self, tune_seeds: u32) -> Self

Sets the fan width k (the number of tune seeds per trial).

k <= 1 means “no fan”: fans stays false and the study takes the single-evaluation path. k = 0 is treated as k = 1 rather than being an error — a documented total, not a panic.

pub const fn with_test_seeds(self, test_seeds: u32) -> Self

Sets the number of disjoint seeds the final re-evaluation stage uses.

0 (the default) disables the stage.

pub const fn with_pairing(self, pairing: Pairing) -> Self

Sets the pairing.

pub const fn with_aggregate(self, aggregate: Aggregate) -> Self

Sets the aggregate.

pub const fn tune_seeds(&self) -> u32

The configured fan width, verbatim (0 is possible).

pub const fn test_seeds(&self) -> u32

The number of test seeds; 0 when the re-evaluation stage is off.

pub const fn pairing(&self) -> Pairing

The pairing.

pub const fn aggregate(&self) -> Aggregate

The aggregate.

pub const fn effective_tune_seeds(&self) -> usize

The effective fan width: at least 1 (a tune_seeds of 0 counts as one single evaluation).

pub const fn fans(&self) -> bool

true if this protocol produces a fan of more than one replicate.

When this is false the study loop takes the fan-free path and produces exactly the same trace it would with no protocol at all.

pub const fn has_test_stage(&self) -> bool

true if the final test-seed re-evaluation stage is enabled.

pub fn is_single_seed_default(&self) -> bool

true if this is the single-seed default (SeedProtocol::new).

A persisted StudyConfig tests this to keep the default protocol out of its serialized form: a fan-free study is written byte-for-byte as it was before the protocol became a config field, so on-disk goldens are unchanged. A non-default protocol is serialized in full and restored on resume.

pub const fn tune_seed( &self, study_seed: u64, trial_number: u64, replicate: u32, ) -> u64

The tune seed of replicate replicate in trial trial_number.

See the module documentation for the exact formula. Under Paired the trial_number argument is ignored, which is what makes the seed common across trials.

pub const fn test_seed( &self, study_seed: u64, trial_number: u64, replicate: u32, ) -> u64

The test seed of replicate replicate in trial trial_number.

Uses the shifted replicate index TEST_REPLICATE_OFFSET + replicate, so the test stream is disjoint from the tune stream (see the module documentation).