Skip to main content

hopr_transport_session/balancer/
pid.rs

1use std::str::FromStr;
2
3use anyhow::anyhow;
4use pid::Pid;
5
6use crate::{
7    balancer::{BalancerControllerBounds, SurbBalancerController},
8    errors,
9    errors::SessionManagerError,
10};
11
12/// Carries finite Proportional, Integral and Derivative controller gains for a PID controller.
13#[derive(Clone, Copy, Debug, PartialEq)]
14pub struct PidControllerGains(f64, f64, f64);
15
16impl PidControllerGains {
17    /// Creates PID controller gains, returns an error if the gains are not finite.
18    pub fn new(p: f64, i: f64, d: f64) -> errors::Result<Self> {
19        if p.is_finite() && i.is_finite() && d.is_finite() {
20            Ok(Self(p, i, d))
21        } else {
22            Err(SessionManagerError::other(anyhow!("gains must be finite")).into())
23        }
24    }
25
26    /// Uses PID controller gains from the env variables or uses the defaults if not set.
27    pub fn from_env_or_default() -> Self {
28        let default = Self::default();
29        Self(
30            std::env::var("HOPR_BALANCER_PID_P_GAIN")
31                .ok()
32                .and_then(|v| f64::from_str(&v).ok())
33                .unwrap_or(default.0),
34            std::env::var("HOPR_BALANCER_PID_I_GAIN")
35                .ok()
36                .and_then(|v| f64::from_str(&v).ok())
37                .unwrap_or(default.1),
38            std::env::var("HOPR_BALANCER_PID_D_GAIN")
39                .ok()
40                .and_then(|v| f64::from_str(&v).ok())
41                .unwrap_or(default.2),
42        )
43    }
44
45    /// P gain.
46    #[inline]
47    pub fn p(&self) -> f64 {
48        self.0
49    }
50
51    /// I gain.
52    #[inline]
53    pub fn i(&self) -> f64 {
54        self.1
55    }
56
57    /// D gain.
58    #[inline]
59    pub fn d(&self) -> f64 {
60        self.2
61    }
62}
63
64// Safe to implement Eq, because the floats are finite
65impl Eq for PidControllerGains {}
66
67// Default coefficients for the PID controller
68// This might be tweaked in the future.
69const DEFAULT_P_GAIN: f64 = 0.6;
70const DEFAULT_I_GAIN: f64 = 0.7;
71const DEFAULT_D_GAIN: f64 = 0.2;
72
73impl Default for PidControllerGains {
74    fn default() -> Self {
75        Self(DEFAULT_P_GAIN, DEFAULT_I_GAIN, DEFAULT_D_GAIN)
76    }
77}
78
79impl TryFrom<(f64, f64, f64)> for PidControllerGains {
80    type Error = errors::TransportSessionError;
81
82    fn try_from(value: (f64, f64, f64)) -> Result<Self, Self::Error> {
83        Self::new(value.0, value.1, value.2)
84    }
85}
86
87/// Implementation of [`SurbBalancerController`] using a PID controller.
88#[derive(Clone, Copy, Debug)]
89pub struct PidBalancerController(Pid<f64>);
90
91impl PidBalancerController {
92    /// Creates new instance given the `setpoint`, `output_limit` and PID gains (P,I and D).
93    pub fn new(setpoint: u64, output_limit: u64, gains: PidControllerGains) -> Self {
94        let mut pid = Pid::new(setpoint as f64, output_limit as f64);
95        pid.p(gains.p(), output_limit as f64);
96        pid.i(gains.i(), output_limit as f64);
97        pid.d(gains.d(), output_limit as f64);
98        Self(pid)
99    }
100
101    /// Creates new instance with setpoint and output limit set to 0.
102    ///
103    /// Needs to be [reconfigured](SurbBalancerController::set_target_and_limit) in order to function
104    /// correctly.
105    pub fn from_gains(gains: PidControllerGains) -> Self {
106        Self::new(0, 0, gains)
107    }
108}
109
110impl Default for PidBalancerController {
111    /// The default instance does nothing unless [reconfigured](SurbBalancerController::set_target_and_limit).
112    fn default() -> Self {
113        Self::new(0, 0, PidControllerGains::default())
114    }
115}
116
117impl SurbBalancerController for PidBalancerController {
118    fn bounds(&self) -> BalancerControllerBounds {
119        BalancerControllerBounds::new(self.0.setpoint as u64, self.0.output_limit as u64)
120    }
121
122    fn set_target_and_limit(&mut self, bounds: BalancerControllerBounds) {
123        let mut pid = Pid::new(bounds.target() as f64, bounds.output_limit() as f64);
124        pid.p(self.0.kp, bounds.output_limit() as f64);
125        pid.i(self.0.ki, bounds.output_limit() as f64);
126        pid.d(self.0.kd, bounds.output_limit() as f64);
127        self.0 = pid;
128    }
129
130    fn next_control_output(&mut self, current_buffer_level: u64) -> u64 {
131        self.0.next_control_output(current_buffer_level as f64).output.max(0.0) as u64
132    }
133}
134
135#[cfg(test)]
136mod tests {
137    use super::*;
138
139    /// A starved buffer must command production. This is the controller's entire purpose, and a
140    /// cluster run showed it returning 0 for an error of -9803 -- maximally starved.
141    #[test]
142    fn pid_should_command_production_when_the_buffer_is_empty() {
143        let mut c = PidBalancerController::from_gains(PidControllerGains::default());
144        c.set_target_and_limit(BalancerControllerBounds::new(7_000, 5_000));
145
146        let out = c.next_control_output(0);
147        assert!(out > 0, "empty buffer against a 7000 target must produce, got {out}");
148    }
149
150    /// The output limit is what every PID term is clamped to. A zero limit silently turns the
151    /// controller into a no-op that reports a huge error and commands nothing -- which is
152    /// indistinguishable, from the outside, from a controller that thinks the buffer is full.
153    #[test]
154    fn pid_with_a_zero_output_limit_commands_nothing_however_starved() {
155        let mut c = PidBalancerController::from_gains(PidControllerGains::default());
156        c.set_target_and_limit(BalancerControllerBounds::new(7_000, 0));
157
158        assert_eq!(0, c.next_control_output(0), "a zero limit clamps every term to zero");
159    }
160
161    /// Reproduces the exact operating point observed on a cluster: target 9803, empty buffer,
162    /// default limit. Production logged `output=0` there, and 15 minutes per observation is too
163    /// slow a loop to debug in -- so pin it here at 80ms instead.
164    #[test]
165    fn pid_should_produce_at_the_operating_point_seen_in_production() {
166        let mut c = PidBalancerController::from_gains(PidControllerGains::default());
167        c.set_target_and_limit(BalancerControllerBounds::new(
168            9_803,
169            crate::SurbBalancerConfig::default().max_surbs_per_sec,
170        ));
171
172        let out = c.next_control_output(0);
173        assert!(out > 0, "target 9803 with an empty buffer produced {out}");
174    }
175
176    /// The very first output after configuration, which is the one that matters on a cold start or
177    /// straight after the estimate is discarded.
178    #[test]
179    fn pid_first_output_after_reconfiguration_should_not_be_zero() {
180        let mut c = PidBalancerController::default();
181        c.set_target_and_limit(BalancerControllerBounds::new(7_000, 5_000));
182
183        assert!(
184            c.next_control_output(0) > 0,
185            "first output after reconfiguration was zero"
186        );
187    }
188
189    /// The exact live bounds, read off a cluster run: target 9803, output limit 1960, empty buffer.
190    /// Production logs `output=0` here while the same controller with a 5000 limit produces.
191    #[test]
192    fn pid_should_produce_at_the_live_bounds() {
193        let mut c = PidBalancerController::from_gains(PidControllerGains::default());
194        c.set_target_and_limit(BalancerControllerBounds::new(9_803, 1_960));
195
196        let out = c.next_control_output(0);
197        assert!(out > 0, "target 9803 / limit 1960 with an empty buffer produced {out}");
198    }
199
200    /// A buffer that was healthy and then drained must be refilled. This is the return-path failure
201    /// exactly: the session runs at target, the return path breaks, the buffer empties -- and
202    /// production commands nothing despite an error of -9803.
203    #[test]
204    fn pid_should_recover_after_a_healthy_buffer_drains() {
205        let mut c = PidBalancerController::from_gains(PidControllerGains::default());
206        c.set_target_and_limit(BalancerControllerBounds::new(9_803, 1_960));
207
208        // Healthy: sitting at target, so the controller has nothing to do for a while.
209        for _ in 0..100 {
210            c.next_control_output(9_803);
211        }
212
213        // The return path breaks and the buffer drains.
214        let out = c.next_control_output(0);
215        assert!(out > 0, "an emptied buffer after a healthy period produced {out}");
216    }
217
218    // --- PidControllerGains tests ---
219
220    #[test]
221    fn gains_default_values_are_stable() {
222        let gains = PidControllerGains::default();
223        insta::assert_yaml_snapshot!((gains.p(), gains.i(), gains.d()));
224    }
225
226    #[test]
227    fn gains_finite_values_are_accepted() -> anyhow::Result<()> {
228        let gains = PidControllerGains::new(1.0, 2.0, 3.0)?;
229        insta::assert_yaml_snapshot!((gains.p(), gains.i(), gains.d()));
230        Ok(())
231    }
232
233    #[test]
234    fn gains_infinity_is_rejected() {
235        assert!(PidControllerGains::new(f64::INFINITY, 0.0, 0.0).is_err());
236        assert!(PidControllerGains::new(0.0, f64::NEG_INFINITY, 0.0).is_err());
237        assert!(PidControllerGains::new(0.0, 0.0, f64::NAN).is_err());
238    }
239
240    #[test]
241    fn gains_try_from_tuple() -> anyhow::Result<()> {
242        let gains = PidControllerGains::try_from((0.5, 0.3, 0.1))?;
243        insta::assert_yaml_snapshot!((gains.p(), gains.i(), gains.d()));
244        Ok(())
245    }
246
247    #[test]
248    fn gains_try_from_tuple_with_nan_fails() {
249        assert!(PidControllerGains::try_from((f64::NAN, 0.0, 0.0)).is_err());
250    }
251
252    #[test]
253    fn gains_eq_works() -> anyhow::Result<()> {
254        let a = PidControllerGains::new(1.0, 2.0, 3.0)?;
255        let b = PidControllerGains::new(1.0, 2.0, 3.0)?;
256        assert_eq!(a, b);
257        Ok(())
258    }
259
260    // --- PidBalancerController tests ---
261
262    #[test]
263    fn controller_default_has_zero_bounds() {
264        let ctrl = PidBalancerController::default();
265        assert_eq!(ctrl.bounds().unzip(), (0, 0));
266    }
267
268    #[test]
269    fn controller_new_stores_bounds() {
270        let gains = PidControllerGains::default();
271        let ctrl = PidBalancerController::new(100, 50, gains);
272        assert_eq!(ctrl.bounds().unzip(), (100, 50));
273    }
274
275    #[test]
276    fn controller_set_target_and_limit_updates_bounds() {
277        let mut ctrl = PidBalancerController::default();
278        ctrl.set_target_and_limit(BalancerControllerBounds::new(200, 100));
279        assert_eq!(ctrl.bounds().unzip(), (200, 100));
280    }
281
282    #[test]
283    fn controller_step_response_snapshot() {
284        // Apply a step input (setpoint=100, buffer=0) and observe outputs over N steps
285        let gains = PidControllerGains::default();
286        let mut ctrl = PidBalancerController::new(100, 200, gains);
287
288        let outputs: Vec<u64> = (0..10).map(|_| ctrl.next_control_output(0)).collect();
289        insta::assert_yaml_snapshot!(outputs);
290    }
291
292    #[test]
293    fn controller_at_setpoint_outputs_zero_or_near_zero() {
294        let gains = PidControllerGains::default();
295        let mut ctrl = PidBalancerController::new(100, 200, gains);
296
297        // When buffer level equals setpoint, output should converge toward 0
298        let output = ctrl.next_control_output(100);
299        // First call at setpoint: P=0, I=0, D=0 → output=0
300        assert_eq!(output, 0);
301    }
302
303    #[test]
304    fn controller_above_setpoint_clamps_to_zero() {
305        let gains = PidControllerGains::default();
306        let mut ctrl = PidBalancerController::new(100, 200, gains);
307
308        // Buffer well above setpoint — PID error is negative, output clamped to 0
309        let output = ctrl.next_control_output(200);
310        assert_eq!(output, 0);
311    }
312
313    #[test]
314    fn controller_convergence_from_empty_buffer() {
315        // Simulate filling a buffer from 0 toward setpoint=100
316        let gains = PidControllerGains::default();
317        let mut ctrl = PidBalancerController::new(100, 200, gains);
318
319        let mut buffer: f64 = 0.0;
320        let mut history = Vec::new();
321
322        for _ in 0..20 {
323            let output = ctrl.next_control_output(buffer as u64);
324            buffer += output as f64;
325            buffer = buffer.min(200.0); // clamp to limit
326            history.push(buffer as u64);
327        }
328
329        insta::assert_yaml_snapshot!(history);
330    }
331
332    #[test]
333    fn controller_from_gains_uses_defaults_for_bounds() {
334        let gains = PidControllerGains::default();
335        let ctrl = PidBalancerController::from_gains(gains);
336        assert_eq!(ctrl.bounds().unzip(), (0, 0));
337    }
338}