diff --git a/crates/mind-body/src/tempo.rs b/crates/mind-body/src/tempo.rs index c699346..5ae14ee 100644 --- a/crates/mind-body/src/tempo.rs +++ b/crates/mind-body/src/tempo.rs @@ -30,6 +30,10 @@ const RESETS_JITTER_MS: u64 = 60_000; /// vote: the sensor's own poll period, since the vote's effect cannot show in a /// reading sooner. const CARRY_FADE_H: f64 = 0.25; +/// The longest stretch of time one call may integrate: the longest beat, the +/// longest wait between two calls of a running heartbeat. A longer silence (a +/// restart, an outage) is not integrated as if the swarm had run through it. +const MAX_STEP_MS: i64 = FALLBACK_MAX_S as i64 * 1000; /// The turn rate, in beats per hour, that `DEFAULT_BEAT_S` stands for: the /// controller's bias. const BIAS_PER_H: f64 = 3600.0 / DEFAULT_BEAT_S as f64; @@ -64,7 +68,8 @@ pub const GAINS: Gains = Gains { /// never published as truth. `rate_per_h` is the last output as a turn rate /// (zero: none yet); while a vote decides the caller sets it to the voted beat's /// rate, and the controller turns the gap between that and its own answer into -/// `carry_per_h`, which fades after release. +/// `carry_per_h`, which fades after release, over the sensor's poll period +/// whatever the vote's length. #[derive(Clone, Debug, Default, PartialEq)] pub struct Fallback { pub integral: f64, @@ -79,12 +84,19 @@ pub struct Fallback { /// The beat when no vote is cast: a PID on the gap between the seven-day usage /// trajectory to `target_permille` and what was used, acting on the turn rate /// (behind the trajectory raises it). Derivative on the measurement, only -/// between distinct observations; conditional integration against the beat -/// limits. +/// between distinct observations; conditional integration: it does not +/// integrate error in the direction of a saturated actuator. `saturated` is the +/// caller's one report that a shorter beat cannot buy more spend: the last beat +/// was the floor, or launched nothing because every eligible Mind was busy +/// (ruling `tempo-controller-knows-the-ceiling`); the slow limit needs no report, +/// since the integral's own answer at it is the controller's. One call +/// integrates at most `MAX_STEP_MS` of time. /// While `voted` nothing integrates and the controller notes how far the voted /// beat (held inside the beat bounds) is from its own answer, so release starts -/// at the voted beat and the controller takes the wheel back within a poll -/// period or two. A new window clears the integral and the derivative memory; +/// at the voted beat, to within the one integration step of the first free call, +/// and the controller takes the wheel back within a poll period or two. The +/// carry fades on that period whatever the vote's length, so a vote of a minute +/// costs the extra turns of a poll period or two of fast beat. A new window clears the integral and the derivative memory; /// with no usable reading (none, an expired window, or one observed more than /// `STALE_AFTER_MS` ago, which a connector replaying its last answer keeps /// producing) the last beat holds (`DEFAULT_BEAT_S` before any). @@ -94,8 +106,17 @@ pub fn fallback_beat( now_ms: i64, target_permille: u32, voted: bool, + saturated: bool, ) -> u32 { - control(&GAINS, state, reading, now_ms, target_permille, voted) + control( + &GAINS, + state, + reading, + now_ms, + target_permille, + voted, + saturated, + ) } fn beat_of(rate_per_h: f64) -> u32 { @@ -125,9 +146,10 @@ fn control( now_ms: i64, target_permille: u32, voted: bool, + saturated: bool, ) -> u32 { let dt_h = if state.last_now_ms > 0 { - (now_ms - state.last_now_ms).max(0) as f64 / HOUR_MS + (now_ms - state.last_now_ms).clamp(0, MAX_STEP_MS) as f64 / HOUR_MS } else { 0.0 }; @@ -178,8 +200,9 @@ fn control( }; return held(state); } - let before = rate(state.integral) + state.carry_per_h; - let winding = (before >= high && error > 0.0) || (before <= low && error < 0.0); + // The slow limit is judged on the integral's own answer: the carry is a + // transient that fades and must not decide what the integral absorbs. + let winding = (saturated && error > 0.0) || (rate(state.integral) <= low && error < 0.0); if !winding && !rolled { state.integral += error * dt_h; } diff --git a/crates/mind-body/src/tempo/sim.rs b/crates/mind-body/src/tempo/sim.rs index 3578969..e3ac668 100644 --- a/crates/mind-body/src/tempo/sim.rs +++ b/crates/mind-body/src/tempo/sim.rs @@ -1,6 +1,9 @@ //! The plant the fallback controller is tuned against: one seven-day plan //! window at one-minute steps, each beat a Persona turn costing a lognormal //! number of permille, plus the operator's own usage on the same subscription. +//! The swarm has a throughput ceiling: a turn needs a Mind that is not in one, +//! each turn holds its Mind for a lognormal time, and when every Mind is busy +//! the beat launches nothing and the controller is told so. //! Test-only. The controller here is `super::control`, the same one the //! heartbeat will call through `fallback_beat`; the sweep passes it candidate //! gains, `GAINS` is committed. Rerun the sweep with @@ -19,6 +22,19 @@ const SELF_EVERY: u32 = 25; const SELF_FACTOR: f64 = 5.0; /// Half-width, in permille, of the band the error must leave to count as a side. const BAND: f64 = 15.0; +/// The roster the heartbeat routes (aqua, eureka, heimdall, kiko, libby, nibu, +/// void, weksa: the slugs it launched over 2026-10-30..11-01). +const MINDS: usize = 8; +/// How long a Persona turn holds its Mind, lognormal. Measured on Yggdrasil from +/// the `mind-persona@*` start and stop lines over 29 h (1284 turns): mean 15.4 s, +/// median 6.4 s, p90 27.7 s, p99 186 s; the fit below has median 7.5 s, p90 35 s. +const BUSY_MEAN_S: f64 = 15.4; +const BUSY_SIGMA: f64 = 1.2; +/// The shortest spacing between two on-beat launches is one heartbeat poll +/// (median 30 s over 4100 polls); the sim's step, 60 s, is the beat floor and is +/// longer, so the spacing never binds. +const POLL_S: i64 = 30; +const _: () = assert!(POLL_S * 1000 <= STEP_MS); struct Rng(u64); @@ -31,10 +47,10 @@ impl Rng { ((z ^ (z >> 31)) >> 11) as f64 / (1u64 << 53) as f64 } - fn lognormal(&mut self, mean: f64) -> f64 { + fn lognormal(&mut self, mean: f64, sigma: f64) -> f64 { let (a, b) = (self.next().max(1e-12), self.next()); let normal = (-2.0 * a.ln()).sqrt() * (std::f64::consts::TAU * b).cos(); - (mean.ln() - COST_SIGMA * COST_SIGMA / 2.0 + COST_SIGMA * normal).exp() + (mean.ln() - sigma * sigma / 2.0 + sigma * normal).exp() } } @@ -66,6 +82,11 @@ struct Scenario { /// The vote itself spends the week: no controller can end on target, it /// can only stop burning once the vote is gone. overspent: bool, + /// Minds the heartbeat can launch, and the factor on how long a turn holds one. + minds: usize, + busy_scale: f64, + /// The most band crossings the controller may show here. + max_crossings: u32, } const BASE: Scenario = Scenario { @@ -79,6 +100,9 @@ const BASE: Scenario = Scenario { gap: None, unreachable: false, overspent: false, + minds: MINDS, + busy_scale: 1.0, + max_crossings: 2, }; fn scenarios() -> Vec { @@ -112,6 +136,7 @@ fn scenarios() -> Vec { Scenario { name: "vote-60s-1h", vote: Some((48.0, 49.0, 60)), + max_crossings: 3, ..BASE }, Scenario { @@ -135,6 +160,20 @@ fn scenarios() -> Vec { vote: Some((48.0, 72.0, 86_400)), ..BASE }, + Scenario { + name: "cheap-then-x3", + mean_cost: 0.6, + cost_step: Some((84.0, 3.0)), + ..BASE + }, + Scenario { + name: "one-slow-mind", + mean_cost: 0.6, + cost_step: Some((84.0, 3.0)), + minds: 1, + busy_scale: 45.0, + ..BASE + }, Scenario { name: "rollover", windows: 2, @@ -176,10 +215,27 @@ struct Outcome { frac_at_max: f64, /// The beat on the last minute. last_beat: u32, + /// Minutes the beat was due and every Mind was busy. + stalls: u32, } fn run(scenario: &Scenario, sensor: Sensor, gains: &Gains, seed: u64) -> Outcome { + drive(scenario, sensor, gains, seed, true) +} + +/// `report_stalls` false withholds the busy half of the saturation report (the +/// floor half is always given): the controller as it was before it was told. +fn drive( + scenario: &Scenario, + sensor: Sensor, + gains: &Gains, + seed: u64, + report_stalls: bool, +) -> Outcome { let mut rng = Rng(seed); + let mut busy_rng = Rng(seed ^ 0xB05E_B05E_B05E_B05E); + let mut busy_until = vec![W0; scenario.minds]; + let mut stalled = false; let mut state = Fallback::default(); let mut used = scenario.start_used; let mut resets = W0 + WINDOW_MS; @@ -225,10 +281,21 @@ fn run(scenario: &Scenario, sensor: Sensor, gains: &Gains, seed: u64) -> Outcome let beat = match vote { Some(beat) => { state.rate_per_h = 3600.0 / f64::from(beat); - control(gains, &mut state, shown.as_ref(), now, TARGET, true); + control(gains, &mut state, shown.as_ref(), now, TARGET, true, false); beat } - None => control(gains, &mut state, shown.as_ref(), now, TARGET, false), + None => { + let saturated = prev_beat == FALLBACK_MIN_S || (report_stalls && stalled); + control( + gains, + &mut state, + shown.as_ref(), + now, + TARGET, + false, + saturated, + ) + } }; if vote.is_none() { if window + 1 == scenario.windows && in_window >= 144.0 { @@ -241,20 +308,30 @@ fn run(scenario: &Scenario, sensor: Sensor, gains: &Gains, seed: u64) -> Outcome prev_beat = beat; out.last_beat = beat; if now - last_turn >= i64::from(beat) * 1000 { - let step = scenario.cost_step.map_or( - 1.0, - |(at, factor)| if in_window >= at { factor } else { 1.0 }, - ); - turns += 1; - let self_run = if turns % SELF_EVERY == 0 { - SELF_FACTOR + if let Some(mind) = busy_until.iter().position(|&until| until <= now) { + stalled = false; + let step = + scenario.cost_step.map_or( + 1.0, + |(at, factor)| if in_window >= at { factor } else { 1.0 }, + ); + turns += 1; + let self_run = if turns % SELF_EVERY == 0 { + SELF_FACTOR + } else { + 1.0 + }; + used += rng.lognormal(scenario.mean_cost * step, COST_SIGMA) * self_run; + busy_until[mind] = now + + (busy_rng.lognormal(BUSY_MEAN_S * scenario.busy_scale, BUSY_SIGMA) * 1000.0) + as i64; + last_turn = now; + if sensor == Sensor::Stream && !gap { + reading = sense(used.min(1000.0), now, resets); + } } else { - 1.0 - }; - used += rng.lognormal(scenario.mean_cost * step) * self_run; - last_turn = now; - if sensor == Sensor::Stream && !gap { - reading = sense(used.min(1000.0), now, resets); + stalled = true; + out.stalls += 1; } } used = used.min(1000.0); @@ -329,7 +406,10 @@ fn sim_scenarios_meet_target() { o.worst_error_last_day <= LAST_DAY_ERROR_BOUND, "error {tag}" ); - assert!(o.band_crossings <= 3, "oscillation {tag}"); + assert!( + o.band_crossings <= scenario.max_crossings, + "oscillation {tag}" + ); } } } @@ -350,7 +430,7 @@ fn sweep() { let mut detail = String::new(); for s in &scen { let (mut f, mut e, mut j, mut x) = (0f64, 0f64, 0f64, 0u32); - let mut lastb = 0; + let (mut lastb, mut stalls) = (0, 0); for sensor in SENSORS { for seed in SEEDS { let o = run(s, sensor, &g, seed); @@ -369,13 +449,14 @@ fn sweep() { x = x.max(o.band_crossings); } lastb = o.last_beat; + stalls = stalls.max(o.stalls); } } final_err = final_err.max(f); err_day = err_day.max(e); jumps = jumps.max(j); detail.push_str(&format!( - " {:<14} final_err {f:6.1} worst_err_last_day {e:6.1} jumps/h {j:5.2} crossings {x} last_beat {lastb}\n", + " {:<14} final_err {f:6.1} worst_err_last_day {e:6.1} jumps/h {j:5.2} crossings {x} last_beat {lastb} stalled_min {stalls}\n", s.name )); } diff --git a/crates/mind-body/src/tempo/tests.rs b/crates/mind-body/src/tempo/tests.rs index c1dca99..5af29e1 100644 --- a/crates/mind-body/src/tempo/tests.rs +++ b/crates/mind-body/src/tempo/tests.rs @@ -237,6 +237,7 @@ fn behind_target_shortens_the_beat() { MID, 900, false, + false, ) }; // Halfway through the window the trajectory is 450: error +50, 0, -50 is a @@ -251,23 +252,47 @@ fn derivative_is_on_measurement() { let g = Gains { ki: 0.0, ..T }; let mut s = Fallback::default(); near( - control(&g, &mut s, Some(&read(410, MID)), MID, 900, false), + control(&g, &mut s, Some(&read(410, MID)), MID, 900, false, false), 750, ); // A new observation 10 permille higher a quarter hour on: the slope is 40 an hour. let next = read(420, MID + 15 * 60_000); near( - control(&g, &mut s, Some(&next), MID + 15 * 60_000, 900, false), + control( + &g, + &mut s, + Some(&next), + MID + 15 * 60_000, + 900, + false, + false, + ), 941, ); // The same reading again carries no derivative term. near( - control(&g, &mut s, Some(&next), MID + 16 * 60_000, 900, false), + control( + &g, + &mut s, + Some(&next), + MID + 16 * 60_000, + 900, + false, + false, + ), 778, ); // A step in the target with used unchanged moves the beat by kp x error alone. near( - control(&g, &mut s, Some(&next), MID + 18 * 60_000, 1000, false), + control( + &g, + &mut s, + Some(&next), + MID + 18 * 60_000, + 1000, + false, + false, + ), 639, ); } @@ -284,17 +309,17 @@ fn saturated_output_does_not_wind_up() { for i in 0..100 { let now = day5 + i * 60_000; assert_eq!( - control(&g, &mut s, Some(&read(0, now)), now, 900, false), + control(&g, &mut s, Some(&read(0, now)), now, 900, false, true), FALLBACK_MIN_S ); } assert_eq!( s.integral, 0.0, - "error is positive and the output is at its limit" + "error is positive and the caller reports the floor" ); for i in 100..110 { let now = day5 + i * 60_000; - control(&g, &mut s, Some(&read(600, now)), now, 900, false); + control(&g, &mut s, Some(&read(600, now)), now, 900, false, false); } assert!(s.integral > 0.0, "unsaturated again, it integrates"); @@ -308,7 +333,7 @@ fn saturated_output_does_not_wind_up() { ..Fallback::default() }; assert_eq!( - control(&g, &mut s, Some(&read(400, MID)), MID, 900, false), + control(&g, &mut s, Some(&read(400, MID)), MID, 900, false, false), FALLBACK_MAX_S ); assert!(s.integral > -1000.0); @@ -319,26 +344,50 @@ fn vote_freezes_and_release_is_bumpless() { let reading = read(300, MID); let mut s = Fallback::default(); for i in 0..5 { - control(&T, &mut s, Some(&reading), MID + i * 60_000, 900, false); + control( + &T, + &mut s, + Some(&reading), + MID + i * 60_000, + 900, + false, + false, + ); } s.rate_per_h = 3600.0 / 300.0; let (mut short, mut long) = (s.clone(), s.clone()); let (t_short, t_long) = (MID + 6 * 60_000, MID + 6 * 60_000 + HOUR); assert_eq!( - control(&T, &mut short, Some(&reading), t_short, 900, true), + control(&T, &mut short, Some(&reading), t_short, 900, true, false), 300 ); assert_eq!( - control(&T, &mut long, Some(&reading), t_long, 900, true), + control(&T, &mut long, Some(&reading), t_long, 900, true, false), 300 ); // However long the vote held, the first beat after it is the voted beat. near( - control(&T, &mut short, Some(&reading), t_short + 60_000, 900, false), + control( + &T, + &mut short, + Some(&reading), + t_short + 60_000, + 900, + false, + false, + ), 300, ); near( - control(&T, &mut long, Some(&reading), t_long + 60_000, 900, false), + control( + &T, + &mut long, + Some(&reading), + t_long + 60_000, + 900, + false, + false, + ), 300, ); } @@ -349,7 +398,7 @@ fn rollover_resets_memory() { let before = RESETS - 2 * HOUR; for i in 0..12 { let now = before + i * 10 * 60_000; - control(&T, &mut s, Some(&read(100, now)), now, 900, false); + control(&T, &mut s, Some(&read(100, now)), now, 900, false, false); } assert!(s.integral > 100.0); let new = Reading { @@ -359,7 +408,7 @@ fn rollover_resets_memory() { }; // Used fell from 100 to 5 across the reset: no derivative kick, no old integral. near( - control(&T, &mut s, Some(&new), RESETS + HOUR, 900, false), + control(&T, &mut s, Some(&new), RESETS + HOUR, 900, false, false), 898, ); assert!(s.integral < 2.0); @@ -370,18 +419,18 @@ fn rollover_resets_memory() { fn no_reading_holds() { let mut s = Fallback::default(); assert_eq!( - control(&T, &mut s, None, MID, 900, false), + control(&T, &mut s, None, MID, 900, false, false), DEFAULT_BEAT_S, "never set" ); let live = read(400, MID + 60_000); - control(&T, &mut s, Some(&read(400, MID)), MID, 900, false); - let held = control(&T, &mut s, Some(&live), MID + 60_000, 900, false); + control(&T, &mut s, Some(&read(400, MID)), MID, 900, false, false); + let held = control(&T, &mut s, Some(&live), MID + 60_000, 900, false, false); assert_ne!(held, DEFAULT_BEAT_S); let integral = s.integral; assert!(integral > 0.0, "a fresh reading integrates"); assert_eq!( - control(&T, &mut s, None, MID + 2 * 60_000, 900, false), + control(&T, &mut s, None, MID + 2 * 60_000, 900, false, false), held ); // Observed just before the window it names began: not its reading. @@ -397,7 +446,8 @@ fn no_reading_holds() { Some(&stale), RESETS - WINDOW_MS + 60_000, 900, - false + false, + false, ), held ); @@ -407,7 +457,15 @@ fn no_reading_holds() { ..live }; assert_eq!( - control(&T, &mut s, Some(&expired), MID + 6 * HOUR, 900, false), + control( + &T, + &mut s, + Some(&expired), + MID + 6 * HOUR, + 900, + false, + false + ), held ); assert_eq!(s.integral, integral, "nothing integrated while held"); @@ -419,6 +477,7 @@ fn no_reading_holds() { MID + 6 * HOUR + 60_000, 900, false, + false, ); assert!( s.integral - integral < 2.0, @@ -443,7 +502,8 @@ fn beat_is_bounded() { Some(&read(0, late)), late, 900, - false + false, + false, ), FALLBACK_MIN_S ); @@ -454,7 +514,8 @@ fn beat_is_bounded() { Some(&read(1000, MID)), MID, 900, - false + false, + false, ), FALLBACK_MAX_S ); @@ -468,6 +529,7 @@ fn beat_is_bounded() { MID, target, false, + false, ); assert!((FALLBACK_MIN_S..=FALLBACK_MAX_S).contains(&beat), "{beat}"); } @@ -479,16 +541,19 @@ fn beat_is_bounded() { fn fallback_beat_is_the_controller_with_the_committed_gains() { let live = read(400, MID); let (mut a, mut b) = (Fallback::default(), Fallback::default()); - let beat = fallback_beat(&mut a, Some(&live), MID, 900, false); - assert_eq!(beat, control(&GAINS, &mut b, Some(&live), MID, 900, false)); + let beat = fallback_beat(&mut a, Some(&live), MID, 900, false, false); + assert_eq!( + beat, + control(&GAINS, &mut b, Some(&live), MID, 900, false, false) + ); assert_ne!(beat, DEFAULT_BEAT_S, "behind the trajectory"); assert_eq!(a, b); // On the trajectory with no memory the answer is the bias, whatever the gains. let on = read(450, MID); - let beat = fallback_beat(&mut Fallback::default(), Some(&on), MID, 900, false); + let beat = fallback_beat(&mut Fallback::default(), Some(&on), MID, 900, false, false); assert_eq!(beat, DEFAULT_BEAT_S); assert_eq!( - fallback_beat(&mut Fallback::default(), None, MID, 900, false), + fallback_beat(&mut Fallback::default(), None, MID, 900, false, false), DEFAULT_BEAT_S ); } @@ -497,7 +562,7 @@ fn fallback_beat_is_the_controller_with_the_committed_gains() { fn a_window_that_ends_this_instant_is_expired() { let mut s = Fallback::default(); let live = read(400, MID); - let held = control(&T, &mut s, Some(&live), MID, 900, false); + let held = control(&T, &mut s, Some(&live), MID, 900, false, false); let ending = Reading { resets_at_ms: MID + 60_000, observed_at_ms: MID, @@ -505,7 +570,7 @@ fn a_window_that_ends_this_instant_is_expired() { }; // At its reset instant the window holds the last beat instead of steering. assert_eq!( - control(&T, &mut s, Some(&ending), MID + 60_000, 900, false), + control(&T, &mut s, Some(&ending), MID + 60_000, 900, false, false), held ); } @@ -515,7 +580,7 @@ fn warm(gains: &Gains) -> Fallback { let mut s = Fallback::default(); for i in 0..7 { let now = MID + i * 10 * 60_000; - control(gains, &mut s, Some(&read(300, now)), now, 900, false); + control(gains, &mut s, Some(&read(300, now)), now, 900, false, false); } assert!(s.integral > 0.0); s @@ -525,7 +590,7 @@ fn warm(gains: &Gains) -> Fallback { fn a_frozen_reading_does_not_wind_up() { let frozen = read(300, MID); let at = |s: &mut Fallback, hours: i64| { - control(&T, s, Some(&frozen), MID + hours * HOUR, 900, false) + control(&T, s, Some(&frozen), MID + hours * HOUR, 900, false, false) }; let mut s = Fallback::default(); at(&mut s, 0); @@ -543,7 +608,7 @@ fn a_frozen_reading_does_not_wind_up() { assert_eq!(s.integral, integral); // A reading that advances takes over again. let now = MID + 82 * HOUR; - control(&T, &mut s, Some(&read(300, now)), now, 900, false); + control(&T, &mut s, Some(&read(300, now)), now, 900, false, false); assert_ne!(s.rate_per_h, 3600.0 / f64::from(held)); } @@ -553,24 +618,24 @@ fn one_millisecond_of_resets_jitter_is_the_same_window() { for i in 0..60 { let now = MID + i * 60_000; let r = read(300, now); - control(&T, &mut steady, Some(&r), now, 900, false); + control(&T, &mut steady, Some(&r), now, 900, false, false); let jitter = Reading { resets_at_ms: RESETS + i % 2, ..r }; - control(&T, &mut jittery, Some(&jitter), now, 900, false); + control(&T, &mut jittery, Some(&jitter), now, 900, false, false); } assert!(steady.integral > 100.0); assert!((jittery.integral - steady.integral).abs() < 1e-3); // The jitter allowed is a minute, to the millisecond. for (jitter, same) in [(60_000, true), (60_001, false)] { let mut s = Fallback::default(); - control(&T, &mut s, Some(&read(300, MID)), MID, 900, false); + control(&T, &mut s, Some(&read(300, MID)), MID, 900, false, false); let later = Reading { resets_at_ms: RESETS + jitter, ..read(300, MID + HOUR) }; - control(&T, &mut s, Some(&later), MID + HOUR, 900, false); + control(&T, &mut s, Some(&later), MID + HOUR, 900, false, false); assert_eq!(s.integral > 0.0, same, "{jitter} ms"); } // A window a week on is not the same window. @@ -579,7 +644,7 @@ fn one_millisecond_of_resets_jitter_is_the_same_window() { resets_at_ms: RESETS + WINDOW_MS - 1_000, ..read(5, now) }; - control(&T, &mut jittery, Some(&next), now, 900, false); + control(&T, &mut jittery, Some(&next), now, 900, false, false); assert!(jittery.integral < 1.0); } @@ -590,17 +655,17 @@ fn a_vote_beyond_the_beat_bounds_leaves_the_integral_alone() { let integral = s.integral; s.rate_per_h = 3600.0 / voted_beat; let t = MID + 3 * HOUR; - control(&T, &mut s, Some(&read(300, t)), t, 900, true); + control(&T, &mut s, Some(&read(300, t)), t, 900, true, false); assert_eq!(s.integral, integral, "a vote integrates nothing"); // The controller can answer no more than its longest beat. let t = t + 60_000; - assert!(control(&T, &mut s, Some(&read(300, t)), t, 900, false) > 3500); + assert!(control(&T, &mut s, Some(&read(300, t)), t, 900, false, false) > 3500); // And takes the wheel back: well behind the trajectory, two hours on, the // beat is its own again. let mut beat = 0; for i in 1..=12 { let t = t + i * 10 * 60_000; - beat = control(&T, &mut s, Some(&read(300, t)), t, 900, false); + beat = control(&T, &mut s, Some(&read(300, t)), t, 900, false, false); } assert!(beat < 700, "{beat}"); } @@ -610,7 +675,15 @@ fn a_vote_beyond_the_beat_bounds_leaves_the_integral_alone() { fn a_short_vote_while_ahead_does_not_outlive_itself() { let mut s = Fallback::default(); let at = |s: &mut Fallback, ms: i64, voted: bool| { - control(&T, s, Some(&read(650, MID + ms)), MID + ms, 900, voted) + control( + &T, + s, + Some(&read(650, MID + ms)), + MID + ms, + 900, + voted, + false, + ) }; at(&mut s, 0, false); s.rate_per_h = 60.0; @@ -622,6 +695,10 @@ fn a_short_vote_while_ahead_does_not_outlive_itself() { at(&mut s, HOUR + i * 60_000, false); } assert_eq!(at(&mut s, HOUR + 122 * 60_000, false), FALLBACK_MAX_S); + assert_eq!( + s.integral, 0.0, + "the carry is not an output the integral absorbs" + ); } #[test] @@ -631,7 +708,7 @@ fn the_vote_carry_needs_no_integral_gain_and_a_set_rate() { let mut s = warm(&g); s.rate_per_h = 12.0; let t = MID + 3 * HOUR; - control(&g, &mut s, Some(&read(300, t)), t, 900, true); + control(&g, &mut s, Some(&read(300, t)), t, 900, true, false); near( control( &g, @@ -640,17 +717,34 @@ fn the_vote_carry_needs_no_integral_gain_and_a_set_rate() { t + 60_000, 900, false, + false, ), 300, ); // A vote cast before the caller set any rate is no carry at all. let (mut voted, mut plain) = (Fallback::default(), Fallback::default()); let r = read(300, MID); - control(&T, &mut voted, Some(&r), MID, 900, true); + control(&T, &mut voted, Some(&r), MID, 900, true, false); let after = read(300, MID + 60_000); assert_eq!( - control(&T, &mut voted, Some(&after), MID + 60_000, 900, false), - control(&T, &mut plain, Some(&after), MID + 60_000, 900, false) + control( + &T, + &mut voted, + Some(&after), + MID + 60_000, + 900, + false, + false + ), + control( + &T, + &mut plain, + Some(&after), + MID + 60_000, + 900, + false, + false + ) ); } @@ -659,7 +753,7 @@ fn a_clock_that_steps_back_integrates_and_fades_nothing_backwards() { let mut s = warm(&T); let integral = s.integral; let t = MID + 2 * HOUR; - control(&T, &mut s, Some(&read(300, t)), t, 900, false); + control(&T, &mut s, Some(&read(300, t)), t, 900, false, false); let after_forward = s.integral; assert!(after_forward > integral); control( @@ -669,10 +763,19 @@ fn a_clock_that_steps_back_integrates_and_fades_nothing_backwards() { t - HOUR, 900, false, + false, ); assert_eq!(s.integral, after_forward, "no negative step"); s.rate_per_h = 12.0; - control(&T, &mut s, Some(&read(300, t + 120_000)), t, 900, true); + control( + &T, + &mut s, + Some(&read(300, t + 120_000)), + t, + 900, + true, + false, + ); let carry = s.carry_per_h; control( &T, @@ -681,6 +784,7 @@ fn a_clock_that_steps_back_integrates_and_fades_nothing_backwards() { t - HOUR, 900, false, + false, ); assert!(s.carry_per_h.abs() <= carry.abs(), "the carry only fades"); } @@ -688,15 +792,107 @@ fn a_clock_that_steps_back_integrates_and_fades_nothing_backwards() { #[test] fn a_released_vote_that_saturates_the_output_does_not_wind_the_integral() { let mut s = Fallback::default(); - let at = |s: &mut Fallback, ms: i64, voted: bool| { - control(&T, s, Some(&read(300, MID + ms)), MID + ms, 900, voted) + let at = |s: &mut Fallback, ms: i64, voted: bool, saturated: bool| { + control( + &T, + s, + Some(&read(300, MID + ms)), + MID + ms, + 900, + voted, + saturated, + ) }; - at(&mut s, 0, false); + at(&mut s, 0, false, false); s.rate_per_h = 60.0; - at(&mut s, 60_000, true); + at(&mut s, 60_000, true, false); // Behind the trajectory, the voted rate is the fastest the controller can // answer and the error pushes further: the carry is part of the output the // integral must not wind against. - at(&mut s, 120_000, false); + at(&mut s, 120_000, false, true); assert_eq!(s.integral, 0.0); } + +/// Time spent without a call is not integrated as if the swarm had run through +/// it: one fresh reading after two days integrates one longest beat of error. +#[test] +fn a_gap_between_calls_integrates_at_most_one_longest_beat() { + let mut s = warm(&GAINS); + let before = s.integral; + let now = MID + 48 * HOUR; + let error = 900.0 * (now - (RESETS - WINDOW_MS)) as f64 / WINDOW_MS as f64 - 300.0; + let beat = control( + &GAINS, + &mut s, + Some(&read(300, now)), + now, + 900, + false, + false, + ); + let step = s.integral - before; + assert!( + (step - error * (MAX_STEP_MS as f64 / HOUR_MS)).abs() < 1e-6, + "{step} for error {error}" + ); + assert!( + beat > 100, + "an outage did not park the controller at its floor: {beat}" + ); + // A gap shorter than the cap is integrated whole. + let mut s = warm(&GAINS); + let before = s.integral; + let now = MID + 90 * 60_000; + let error = 900.0 * (now - (RESETS - WINDOW_MS)) as f64 / WINDOW_MS as f64 - 300.0; + control( + &GAINS, + &mut s, + Some(&read(300, now)), + now, + 900, + false, + false, + ); + assert!((s.integral - before - error * 0.5).abs() < 1e-6); +} + +/// The caller's saturation report stops integration toward more spend and +/// nothing else. +#[test] +fn a_saturated_report_stops_integration_toward_more_spend_only() { + let mut s = warm(&T); + let integral = s.integral; + let t = MID + 2 * HOUR; + control(&T, &mut s, Some(&read(300, t)), t, 900, false, true); + assert_eq!(s.integral, integral, "behind and saturated: nothing to buy"); + let t = t + 60_000; + control(&T, &mut s, Some(&read(300, t)), t, 900, false, false); + assert!(s.integral > integral, "not saturated, it integrates again"); + let integral = s.integral; + let t = t + 60_000; + control(&T, &mut s, Some(&read(700, t)), t, 900, false, true); + assert!( + s.integral < integral, + "ahead, saturation does not hold the integral up" + ); +} + +/// The vote's release is the voted beat less the one integration step the first +/// free call takes before it answers. +#[test] +fn release_of_the_slowest_vote_is_within_one_integration_step() { + let mut s = warm(&T); + s.rate_per_h = 1.0; + let t = MID + 3 * HOUR; + control(&T, &mut s, Some(&read(300, t)), t, 900, true, false); + let beat = control( + &T, + &mut s, + Some(&read(300, t + 60_000)), + t + 60_000, + 900, + false, + false, + ); + assert!((3400..FALLBACK_MAX_S).contains(&beat), "{beat}"); +} diff --git a/crates/mind-body/tests/public_surface.txt b/crates/mind-body/tests/public_surface.txt index c02fbcc..18e1cf6 100644 --- a/crates/mind-body/tests/public_surface.txt +++ b/crates/mind-body/tests/public_surface.txt @@ -267,7 +267,7 @@ mind_body::tempo: const FALLBACK_MAX_S : u32 mind_body::tempo: const FALLBACK_MIN_S : u32 mind_body::tempo: const GAINS : Gains mind_body::tempo: const LOG_BOUND_ORDERS : f64 -mind_body::tempo: fn fallback_beat (state : & mut Fallback , reading : Option < & Reading > , now_ms : i64 , target_permille : u32 , voted : bool ,) -> u32 +mind_body::tempo: fn fallback_beat (state : & mut Fallback , reading : Option < & Reading > , now_ms : i64 , target_permille : u32 , voted : bool , saturated : bool ,) -> u32 mind_body::tempo: fn pick (rows : & [Standing] , beat_s : u32) -> Option < usize > mind_body::tempo: fn score (standing : & Standing , beat_s : u32) -> f64 mind_body::tempo: fn tally (votes : & [Option < u32 >]) -> u32