zeph_experiments/
random.rs

1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Uniform random sampling strategy for parameter variation.
5//!
6//! [`Random`] selects a parameter uniformly at random on each call, then samples
7//! its value uniformly from `[min, max]`, quantizing to the nearest step. It
8//! provides broad coverage without systematic ordering, which can be useful when
9//! the search space is large and a full [`GridStep`] sweep is too expensive.
10//!
11//! [`GridStep`]: crate::GridStep
12
13use std::collections::HashSet;
14use std::sync::Mutex;
15
16use ordered_float::OrderedFloat;
17use rand::RngExt as _;
18use rand::SeedableRng as _;
19use rand::rngs::SmallRng;
20
21use super::generator::VariationGenerator;
22use super::search_space::SearchSpace;
23use super::snapshot::ConfigSnapshot;
24use super::types::{Variation, VariationValue};
25
26/// Maximum number of retry attempts before giving up (space is considered exhausted).
27const MAX_RETRIES: usize = 1000;
28
29/// Uniform random sampling within parameter bounds.
30///
31/// At each call, a parameter is chosen uniformly at random, then a value is
32/// sampled uniformly from its `[min, max]` range and quantized to the nearest
33/// step (if configured). The sample is rejected if it was already visited.
34/// Returns `None` after 1000 consecutive rejections (the space is considered
35/// effectively exhausted for this seed).
36///
37/// The internal RNG is wrapped in a [`Mutex`] so that `Random` implements [`Sync`],
38/// which is required by [`VariationGenerator`] to allow [`ExperimentEngine`] to be
39/// used in an async context. The experiment loop is sequential, so the mutex is
40/// never contended.
41///
42/// # Examples
43///
44/// ```rust
45/// use std::collections::HashSet;
46/// use zeph_experiments::{ConfigSnapshot, Random, SearchSpace, VariationGenerator};
47///
48/// let mut generator = Random::new(SearchSpace::default(), 42);
49/// let baseline = ConfigSnapshot::default();
50/// let visited = HashSet::new();
51///
52/// // Two generators with the same seed produce the same first variation.
53/// let mut gen2 = Random::new(SearchSpace::default(), 42);
54/// let v1 = generator.next(&baseline, &visited);
55/// let v2 = gen2.next(&baseline, &visited);
56/// assert_eq!(v1, v2);
57/// ```
58///
59/// [`ExperimentEngine`]: crate::ExperimentEngine
60pub struct Random {
61    search_space: SearchSpace,
62    rng: Mutex<SmallRng>,
63}
64
65impl Random {
66    /// Create a new [`Random`] generator with a deterministic seed.
67    ///
68    /// Generators with the same `seed` and `search_space` will produce identical
69    /// variation sequences, making experiments reproducible.
70    ///
71    /// # Examples
72    ///
73    /// ```rust
74    /// use zeph_experiments::{Random, SearchSpace, VariationGenerator};
75    ///
76    /// let generator = Random::new(SearchSpace::default(), 1234);
77    /// assert_eq!(generator.name(), "random");
78    /// ```
79    #[must_use]
80    pub fn new(search_space: SearchSpace, seed: u64) -> Self {
81        Self {
82            search_space,
83            rng: Mutex::new(SmallRng::seed_from_u64(seed)),
84        }
85    }
86}
87
88impl VariationGenerator for Random {
89    fn next(
90        &mut self,
91        _baseline: &ConfigSnapshot,
92        visited: &HashSet<Variation>,
93    ) -> Option<Variation> {
94        if self.search_space.parameters.is_empty() {
95            return None;
96        }
97        let mut rng = self.rng.lock().expect("rng mutex poisoned");
98        for _ in 0..MAX_RETRIES {
99            let idx = rng.random_range(0..self.search_space.parameters.len());
100            let range = &self.search_space.parameters[idx];
101            let raw: f64 = rng.random_range(range.min()..=range.max());
102            let value = range.quantize(raw);
103            let variation = Variation {
104                parameter: range.kind(),
105                value: VariationValue::Float(OrderedFloat(value)),
106            };
107            if !visited.contains(&variation) {
108                return Some(variation);
109            }
110        }
111        None
112    }
113
114    fn name(&self) -> &'static str {
115        "random"
116    }
117}
118
119#[cfg(test)]
120mod tests {
121    #![allow(clippy::manual_range_contains)]
122
123    use std::collections::HashSet;
124
125    use super::super::search_space::ParameterRange;
126    use super::super::types::ParameterKind;
127    use super::*;
128
129    #[test]
130    fn random_produces_values_in_range() {
131        let space = SearchSpace {
132            parameters: vec![
133                ParameterRange::new(ParameterKind::Temperature, 0.0, 1.0, Some(0.1), 0.5).unwrap(),
134            ],
135        };
136        let mut generator = Random::new(space, 42);
137        let baseline = ConfigSnapshot::default();
138        let visited = HashSet::new();
139        for _ in 0..20 {
140            if let Some(v) = generator.next(&baseline, &visited) {
141                let val = v.value.as_f64();
142                assert!((0.0..=1.0).contains(&val), "out of range: {val}");
143            }
144        }
145    }
146
147    #[test]
148    fn random_skips_visited() {
149        // Use a very small range with a large step so only one grid point exists (0.5).
150        let space = SearchSpace {
151            parameters: vec![
152                ParameterRange::new(ParameterKind::Temperature, 0.5, 0.6, Some(1.0), 0.55).unwrap(),
153            ],
154        };
155        let mut generator = Random::new(space, 0);
156        let baseline = ConfigSnapshot::default();
157        let mut visited = HashSet::new();
158        visited.insert(Variation {
159            parameter: ParameterKind::Temperature,
160            value: VariationValue::Float(OrderedFloat(0.5)),
161        });
162        // Only one grid point (0.5 clamped from min), after visiting it must return None.
163        let result = generator.next(&baseline, &visited);
164        assert!(
165            result.is_none(),
166            "expected None when only option is already visited"
167        );
168    }
169
170    #[test]
171    fn random_empty_space_returns_none() {
172        let mut generator = Random::new(SearchSpace { parameters: vec![] }, 0);
173        let baseline = ConfigSnapshot::default();
174        let visited = HashSet::new();
175        assert!(generator.next(&baseline, &visited).is_none());
176    }
177
178    #[test]
179    fn random_is_deterministic_with_same_seed() {
180        let space = SearchSpace::default();
181        let baseline = ConfigSnapshot::default();
182        let visited = HashSet::new();
183        let mut gen1 = Random::new(space.clone(), 123);
184        let mut gen2 = Random::new(space, 123);
185        let v1 = gen1.next(&baseline, &visited);
186        let v2 = gen2.next(&baseline, &visited);
187        assert_eq!(v1, v2, "same seed must produce same first variation");
188    }
189
190    #[test]
191    fn random_quantizes_sampled_values() {
192        let space = SearchSpace {
193            parameters: vec![
194                ParameterRange::new(ParameterKind::TopP, 0.1, 1.0, Some(0.05), 0.9).unwrap(),
195            ],
196        };
197        let mut generator = Random::new(space, 7);
198        let baseline = ConfigSnapshot::default();
199        let visited = HashSet::new();
200        for _ in 0..30 {
201            if let Some(v) = generator.next(&baseline, &visited) {
202                let val = v.value.as_f64();
203                // Quantized values must be on the 0.05-step grid anchored at min=0.1:
204                // i.e. (val - 0.1) / 0.05 must be an integer.
205                let steps = (val - 0.1) / 0.05;
206                assert!(
207                    (steps - steps.round()).abs() < 1e-10,
208                    "value {val} is not on the 0.05-step grid anchored at 0.1"
209                );
210            }
211        }
212    }
213
214    #[test]
215    fn random_name() {
216        let generator = Random::new(SearchSpace::default(), 0);
217        assert_eq!(generator.name(), "random");
218    }
219
220    #[test]
221    fn random_is_sync() {
222        fn assert_sync<T: Sync>() {}
223        assert_sync::<Random>();
224    }
225}
zeph_experiments/random.rs

zeph_experiments/
random.rs
