Struct SeedStream 

pub struct SeedStream { /* private fields */ }

A deterministic, fan-out seed generator for benchmark and training trials.

SeedStream derives independent 64-bit seeds for each (environment index, trial index) pair, and further splits each trial seed into separate env and agent seeds. Every derivation is a pure function of base and the index arguments, so the same SeedStream always produces the same sequence.

Design

Derivation uses splitmix64 — a bijective mixing function — XOR’d with index-dependent multipliers. The env and agent branches are separated by distinct domain constants so env_seed(t) != agent_seed(t) for all t.

Thread safety

SeedStream holds no mutable state and is Copy. All methods are const fn. It is safe to share across threads without synchronisation.

Implementations

impl SeedStream

pub const fn new(base: u64) -> Self

Creates a new SeedStream from the given base seed.

All seeds derived from this stream are fully determined by base. Two streams constructed with the same base produce identical output.

Examples

use rlevo_core::util::seed::SeedStream;

let stream = SeedStream::new(0xDEAD_BEEF);
assert_eq!(stream.base(), 0xDEAD_BEEF);

pub const fn base(&self) -> u64

Returns the base seed this stream was constructed with.

Useful for serialising or logging the root of a reproducible run.

Examples

use rlevo_core::util::seed::SeedStream;

let stream = SeedStream::new(42);
assert_eq!(stream.base(), 42);

pub const fn trial_seed(&self, env_idx: usize, trial_idx: usize) -> u64

Derives a deterministic seed for a specific (env index, trial index) pair.

The returned value is the root from which env_seed and agent_seed are derived for that trial. Different (env_idx, trial_idx) pairs always produce different seeds.

Examples

use rlevo_core::util::seed::SeedStream;

let stream = SeedStream::new(42);

// Repeated calls with identical arguments are stable.
assert_eq!(stream.trial_seed(0, 0), stream.trial_seed(0, 0));

// Different index pairs yield different seeds.
assert_ne!(stream.trial_seed(0, 0), stream.trial_seed(0, 1));
assert_ne!(stream.trial_seed(0, 0), stream.trial_seed(1, 0));

pub const fn env_seed(&self, trial_seed: u64) -> u64

Derives the environment seed for a given trial seed.

Pass the result of trial_seed as trial_seed. The returned value is guaranteed to differ from agent_seed for the same input, preventing env and agent RNGs from correlating.

Examples

use rlevo_core::util::seed::SeedStream;

let stream = SeedStream::new(42);
let t = stream.trial_seed(0, 0);
let env_seed = stream.env_seed(t);
let agent_seed = stream.agent_seed(t);
assert_ne!(env_seed, agent_seed);

pub const fn agent_seed(&self, trial_seed: u64) -> u64

Derives the agent seed for a given trial seed.

Pass the result of trial_seed as trial_seed. The returned value is guaranteed to differ from env_seed for the same input, preventing agent and env RNGs from correlating.

Examples

use rlevo_core::util::seed::SeedStream;

let stream = SeedStream::new(42);
let t = stream.trial_seed(0, 0);

// agent_seed and env_seed are derived with different domain constants,
// so they are always distinct for the same trial seed.
assert_ne!(stream.agent_seed(t), stream.env_seed(t));

// Repeated calls are stable.
assert_eq!(stream.agent_seed(t), stream.agent_seed(t));

Trait Implementations

impl Clone for SeedStream

fn clone(&self) -> SeedStream

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for SeedStream

impl Debug for SeedStream

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

Formats the value using the given formatter.