use crate::utils::training::run_progress;
#[derive(Clone, Copy, Debug, PartialEq, serde::Serialize, serde::Deserialize, Default)]
#[serde(rename_all = "lowercase")]
pub enum ChallengeDecay {
#[default]
Linear,
Exponential,
Custom { exponent: f32 },
}
impl ChallengeDecay {
pub(crate) fn exponent(self) -> f32 {
const MIN_EXPONENT: f32 = 0.0;
const MAX_EXPONENT: f32 = 100.0;
let k = match self {
ChallengeDecay::Linear => 1.0,
ChallengeDecay::Exponential => 2.0,
ChallengeDecay::Custom { exponent } => exponent,
};
k.max(MIN_EXPONENT).min(MAX_EXPONENT)
}
}
impl TryFrom<&str> for ChallengeDecay {
type Error = String;
fn try_from(s: &str) -> Result<Self, Self::Error> {
match s.trim() {
"linear" => Ok(ChallengeDecay::Linear),
"exponential" => Ok(ChallengeDecay::Exponential),
other => {
if let Some(k) = other.strip_prefix("custom:") {
let exponent: f32 = k.trim().parse().map_err(|_| {
format!("invalid challenge decay '{other}' (custom exponent must be a number, e.g. \"custom:1.5\")")
})?;
if !(exponent > 0.0) {
return Err(format!(
"invalid challenge decay '{other}' (exponent must be > 0)"
));
}
Ok(ChallengeDecay::Custom { exponent })
} else {
Err(format!(
"unknown challenge decay '{other}' (use \"linear\", \"exponential\" or \"custom:<exponent>\")"
))
}
}
}
}
}
impl std::fmt::Display for ChallengeDecay {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
ChallengeDecay::Linear => write!(f, "linear"),
ChallengeDecay::Exponential => write!(f, "exponential"),
ChallengeDecay::Custom { exponent } => write!(f, "custom:{exponent}"),
}
}
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ChallengePolicy {
#[default]
Random,
LeastAction,
}
impl TryFrom<&str> for ChallengePolicy {
type Error = String;
fn try_from(s: &str) -> Result<Self, Self::Error> {
match s.trim() {
"random" => Ok(ChallengePolicy::Random),
"least_action" | "least-action" => Ok(ChallengePolicy::LeastAction),
other => Err(format!(
"unknown challenge policy '{other}' (use \"random\" or \"least_action\")"
)),
}
}
}
impl std::fmt::Display for ChallengePolicy {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
ChallengePolicy::Random => write!(f, "random"),
ChallengePolicy::LeastAction => write!(f, "least_action"),
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ForcedAction {
Exact(usize),
Least,
}
impl ForcedAction {
pub fn resolve(self, values: &[f32]) -> usize {
match self {
ForcedAction::Exact(a) => a,
ForcedAction::Least => least_action(values),
}
}
}
pub fn least_action(values: &[f32]) -> usize {
let mut best = 0usize;
for (i, v) in values.iter().enumerate() {
let better = match (v.partial_cmp(&values[best]), v.is_nan()) {
(None, true) => !values[best].is_nan(),
(Some(std::cmp::Ordering::Less), _) => true,
_ => false,
};
if better {
best = i;
}
}
best
}
pub fn forced_action(
policy: ChallengePolicy,
net_seed: u64,
step: usize,
actions: usize,
) -> ForcedAction {
match policy {
ChallengePolicy::Random => {
let mut rng = fastrand::Rng::with_seed(
net_seed ^ (step as u64).wrapping_mul(0x9E37_79B9_7F4A_7C15),
);
ForcedAction::Exact(rng.usize(..actions))
}
ChallengePolicy::LeastAction => ForcedAction::Least,
}
}
pub fn effective_challenge_prob(
prob: f32,
step: usize,
max_steps: Option<usize>,
shape: ChallengeDecay,
) -> f32 {
match run_progress(step, max_steps) {
None => prob,
Some(progress) => prob * (1.0 - progress.powf(shape.exponent())),
}
}
pub fn challenge_fires(
run_seed: u64,
net_seed: u64,
step: usize,
prob: f32,
max_steps: Option<usize>,
shape: ChallengeDecay,
) -> bool {
let eff = effective_challenge_prob(prob, step, max_steps, shape);
if eff <= 0.0 {
return false;
}
let mut rng =
fastrand::Rng::with_seed(run_seed ^ net_seed.rotate_left(17) ^ ((step as u64) << 32));
rng.f32() < eff
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn decay_shapes_match_their_closed_form() {
let cases: &[(f32, ChallengeDecay, f32)] = &[
(0.0, ChallengeDecay::Linear, 1.0),
(0.5, ChallengeDecay::Linear, 0.5),
(1.0, ChallengeDecay::Linear, 0.0),
(0.5, ChallengeDecay::Exponential, 0.75),
(1.0, ChallengeDecay::Exponential, 0.0),
(0.5, ChallengeDecay::Custom { exponent: 3.0 }, 0.875),
];
for (progress, shape, want) in cases {
let got = 1.0 - progress.powf(shape.exponent());
assert!(
(got - want).abs() < 1e-6,
"progress {progress} shape {shape}: factor {got} ≠ {want}"
);
}
}
#[test]
fn effective_prob_decays_to_zero_and_is_flat_unbounded() {
assert_eq!(
effective_challenge_prob(1.0, 5, Some(10), ChallengeDecay::Linear),
0.5
);
assert_eq!(
effective_challenge_prob(1.0, 10, Some(10), ChallengeDecay::Linear),
0.0
);
assert_eq!(
effective_challenge_prob(1.0, 99, Some(10), ChallengeDecay::Linear),
0.0
);
assert_eq!(
effective_challenge_prob(0.3, 999, None, ChallengeDecay::Linear),
0.3
);
}
#[test]
fn degenerate_exponents_clamp() {
assert_eq!(ChallengeDecay::Custom { exponent: -1.0 }.exponent(), 0.0);
assert_eq!(
ChallengeDecay::Custom { exponent: f32::NAN }.exponent(),
0.0
);
assert_eq!(ChallengeDecay::Custom { exponent: 1e9 }.exponent(), 100.0);
}
#[test]
fn trigger_is_pure_and_respects_the_knob() {
assert!(!challenge_fires(
1,
7,
3,
0.0,
Some(10),
ChallengeDecay::Linear
));
assert!(!challenge_fires(
1,
7,
3,
-0.5,
Some(10),
ChallengeDecay::Linear
));
assert!(challenge_fires(
1,
7,
0,
1.0,
Some(10),
ChallengeDecay::Linear
));
let first = challenge_fires(42, 1234, 5, 0.5, Some(10), ChallengeDecay::Linear);
for step in 0..100 {
let _ = step;
assert_eq!(
challenge_fires(42, 1234, 5, 0.5, Some(10), ChallengeDecay::Linear),
first
);
}
}
#[test]
fn decay_string_round_trip_and_parse_errors() {
for (raw, want) in [
("linear", ChallengeDecay::Linear),
("exponential", ChallengeDecay::Exponential),
("custom:1.5", ChallengeDecay::Custom { exponent: 1.5 }),
] {
assert_eq!(ChallengeDecay::try_from(raw).unwrap(), want);
assert_eq!(want.to_string(), raw);
}
assert!(ChallengeDecay::try_from("sideways").is_err());
assert!(ChallengeDecay::try_from("custom:zero").is_err());
assert!(ChallengeDecay::try_from("custom:-1").is_err());
}
#[test]
fn trigger_is_per_net_not_per_step() {
use crate::utils::seed::derive_seed;
let fired = (0..64usize)
.filter(|i| {
challenge_fires(
42,
derive_seed(42, *i),
3,
0.5,
None,
ChallengeDecay::Linear,
)
})
.count();
assert!(
(16..=48).contains(&fired),
"trigger must track prob across nets, fired {fired}/64"
);
}
#[test]
fn least_action_resolves_per_turn_from_the_values() {
let forced = forced_action(ChallengePolicy::LeastAction, 42, 7, 2);
assert_eq!(forced, ForcedAction::Least);
assert_eq!(forced.resolve(&[5.0, 1.0]), 1);
assert_eq!(forced.resolve(&[1.0, 5.0]), 0);
assert_eq!(forced.resolve(&[0.5, -2.0, 0.9]), 1);
}
#[test]
fn least_action_picks_the_argmin_and_never_panics() {
assert_eq!(least_action(&[0.5, -1.0, 2.0]), 1);
assert_eq!(least_action(&[1.0, 1.0]), 0);
assert_eq!(least_action(&[-0.0, 0.0]), 0);
assert_eq!(least_action(&[3.0]), 0);
assert_eq!(least_action(&[]), 0);
assert_eq!(least_action(&[0.0, f32::NAN]), 1);
assert_eq!(least_action(&[f32::NAN, 0.0]), 0);
assert_eq!(least_action(&[f32::NAN, f32::NAN]), 0);
assert_eq!(least_action(&[f32::INFINITY, f32::NEG_INFINITY]), 1);
}
#[test]
fn policy_string_round_trip_and_parse_errors() {
for (raw, want) in [
("random", ChallengePolicy::Random),
("least_action", ChallengePolicy::LeastAction),
] {
assert_eq!(ChallengePolicy::try_from(raw).unwrap(), want);
assert_eq!(want.to_string(), raw);
}
assert_eq!(
ChallengePolicy::try_from("least-action").unwrap(),
ChallengePolicy::LeastAction
);
assert!(ChallengePolicy::try_from("argmin").is_err());
assert_eq!(ChallengePolicy::default(), ChallengePolicy::Random);
}
#[test]
fn random_policy_reproduces_the_historical_draw() {
fn legacy(net_seed: u64, step: usize) -> usize {
let mut rng = fastrand::Rng::with_seed(
net_seed ^ (step as u64).wrapping_mul(0x9E37_79B9_7F4A_7C15),
);
rng.usize(..2)
}
for net_seed in [1u64, 42, 999] {
for step in 0..8usize {
assert_eq!(
forced_action(ChallengePolicy::Random, net_seed, step, 2),
ForcedAction::Exact(legacy(net_seed, step))
);
}
}
assert_eq!(
forced_action(ChallengePolicy::Random, 42, 3, 2),
ForcedAction::Exact(1)
);
assert_eq!(
forced_action(ChallengePolicy::Random, 7, 0, 3),
ForcedAction::Exact(2)
);
}
#[test]
fn firing_rate_tracks_the_knob() {
const P: f32 = 0.25;
let fires = (0..4000u64)
.filter(|&i| challenge_fires(9, i as u64, i as usize, P, None, ChallengeDecay::Linear))
.count();
let rate = fires as f32 / 4000.0;
assert!((rate - P).abs() < 0.03, "rate {rate} far from knob {P}");
}
}