Skip to main content

tufazip_codec/
rng.rs

1use candle_core::{DType, Device, Shape, Tensor};
2use rand::{Rng, SeedableRng};
3use rand_chacha::ChaCha8Rng;
4use rand_distr::{Distribution, Normal};
5use serde::{Deserialize, Serialize};
6
7use crate::error::CodecError;
8
9/// Exact serializable state of [`DeterministicRng`].
10#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
11pub struct RngState {
12    /// 256-bit ChaCha8 seed.
13    pub seed: [u8; 32],
14    /// Stream identifier.
15    pub stream: u64,
16    /// Lower 64 bits of the 128-bit ChaCha word position.
17    pub word_pos_lo: u64,
18    /// Upper 64 bits of the 128-bit ChaCha word position.
19    pub word_pos_hi: u64,
20}
21
22/// Deterministic, checkpointable PRNG for weight initialization and replay dropout.
23#[derive(Debug, Clone)]
24pub struct DeterministicRng {
25    inner: ChaCha8Rng,
26}
27
28impl DeterministicRng {
29    /// Constructs a PRNG deterministically from a 64-bit seed.
30    #[must_use]
31    pub fn from_seed_u64(seed: u64) -> Self {
32        Self {
33            inner: ChaCha8Rng::seed_from_u64(seed),
34        }
35    }
36
37    /// Captures the exact internal PRNG state for resumable checkpoints.
38    #[must_use]
39    pub fn state(&self) -> RngState {
40        let word_pos = self.inner.get_word_pos();
41        RngState {
42            seed: self.inner.get_seed(),
43            stream: self.inner.get_stream(),
44            word_pos_lo: word_pos as u64,
45            word_pos_hi: (word_pos >> 64) as u64,
46        }
47    }
48
49    /// Restores a previously captured [`RngState`].
50    pub fn restore_state(&mut self, state: &RngState) {
51        let mut inner = ChaCha8Rng::from_seed(state.seed);
52        inner.set_stream(state.stream);
53        let word_pos = (u128::from(state.word_pos_hi) << 64) | u128::from(state.word_pos_lo);
54        inner.set_word_pos(word_pos);
55        self.inner = inner;
56    }
57
58    /// Samples `len` i.i.d. normal values `N(mean, std^2)`.
59    ///
60    /// # Errors
61    ///
62    /// Returns [`CodecError::InvalidConfig`] if `std` is negative or non-finite.
63    pub fn sample_normal_vec(
64        &mut self,
65        len: usize,
66        mean: f32,
67        std: f32,
68    ) -> Result<Vec<f32>, CodecError> {
69        let dist = Normal::new(mean, std).map_err(|e| {
70            CodecError::InvalidConfig(format!("invalid normal distribution parameters: {e}"))
71        })?;
72        let mut out = Vec::with_capacity(len);
73        for _ in 0..len {
74            out.push(dist.sample(&mut self.inner));
75        }
76        Ok(out)
77    }
78
79    /// Generates an inverted-dropout scaling mask of `shape` on `device` in `dtype`.
80    ///
81    /// # Errors
82    ///
83    /// Returns [`CodecError`] on invalid `drop_p` or tensor transfer failure.
84    pub fn dropout_mask(
85        &mut self,
86        shape: &Shape,
87        drop_p: f32,
88        dtype: DType,
89        device: &Device,
90    ) -> Result<Tensor, CodecError> {
91        if !(0.0..1.0).contains(&drop_p) {
92            return Err(CodecError::InvalidConfig(format!(
93                "dropout probability must be in [0.0, 1.0), got {drop_p}"
94            )));
95        }
96        let n = shape.elem_count();
97        let keep_prob = 1.0f32 - drop_p;
98        let scale = 1.0f32 / keep_prob;
99        let mut mask = Vec::with_capacity(n);
100        for _ in 0..n {
101            let draw: f32 = self.inner.random();
102            mask.push(if draw >= drop_p { scale } else { 0.0 });
103        }
104        let tensor = Tensor::from_vec(mask, shape.clone(), device)?;
105        if dtype == DType::F32 {
106            Ok(tensor)
107        } else {
108            Ok(tensor.to_dtype(dtype)?)
109        }
110    }
111}