hopr_transport_session/balancer/
pid.rs1use 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#[derive(Clone, Copy, Debug, PartialEq)]
14pub struct PidControllerGains(f64, f64, f64);
15
16impl PidControllerGains {
17 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 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 #[inline]
47 pub fn p(&self) -> f64 {
48 self.0
49 }
50
51 #[inline]
53 pub fn i(&self) -> f64 {
54 self.1
55 }
56
57 #[inline]
59 pub fn d(&self) -> f64 {
60 self.2
61 }
62}
63
64impl Eq for PidControllerGains {}
66
67const 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#[derive(Clone, Copy, Debug)]
89pub struct PidBalancerController(Pid<f64>);
90
91impl PidBalancerController {
92 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 pub fn from_gains(gains: PidControllerGains) -> Self {
106 Self::new(0, 0, gains)
107 }
108}
109
110impl Default for PidBalancerController {
111 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 #[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 #[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 #[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 #[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 #[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 #[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 for _ in 0..100 {
210 c.next_control_output(9_803);
211 }
212
213 let out = c.next_control_output(0);
215 assert!(out > 0, "an emptied buffer after a healthy period produced {out}");
216 }
217
218 #[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 #[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 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 let output = ctrl.next_control_output(100);
299 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 let output = ctrl.next_control_output(200);
310 assert_eq!(output, 0);
311 }
312
313 #[test]
314 fn controller_convergence_from_empty_buffer() {
315 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); 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}