Add the ambient-temperature and max-fan tuning targets
source-pr / source (pull_request) Successful in 12s

Ambient mode holds the hottest sensor a configured margin above the measured
intake temperature, which is the efficiency-at-this-ambient operating point;
missing either sensor is an error rather than a guess. Max-fan mode pins the
fan at its cap, ramps frequency toward the envelope ceiling, and still defers
to the thermal guard.

step() now returns a Command carrying the frequency and, when the target owns
the fan, the duty to apply. The max-fan ramp is explicit rather than a
setpoint loop: a P controller fed its own output settles at half the ceiling,
which the ramp test caught.
This commit is contained in:
2026-10-22 10:28:53 -06:00
parent 5aa6349e27
commit 96f84dc283
+185 -62
View File
@@ -17,6 +17,10 @@ pub enum TuningTarget {
PowerW(f32),
/// Maximise hashrate up to this value.
HashrateThs(f32),
/// Hold the hottest sensor this far above the measured ambient: efficiency at that ambient.
AmbientC { margin_mc: i32 },
/// Pin the fan at this duty and maximise hashrate under it.
MaxFan { max_pwm: u8 },
}
/// Controller tuning.
@@ -70,6 +74,11 @@ impl Pid {
self.output
}
/// Force the output (used by ramp modes and the thermal guard).
pub fn set_output(&mut self, value: f32) {
self.output = value.clamp(self.config.out_min, self.config.out_max);
}
/// Advance one control period and return the new output.
pub fn update(&mut self, setpoint: f32, measurement: f32, dt_s: f32) -> f32 {
if !dt_s.is_finite() || dt_s <= 0.0 {
@@ -110,6 +119,16 @@ pub struct Observation {
pub hashrate_ths: Option<f32>,
/// Hottest sensor in millidegrees, when telemetry is available.
pub hottest_mc: Option<i32>,
/// Intake/enclosure temperature in millidegrees, for the ambient target.
pub ambient_mc: Option<i32>,
}
/// What the loop wants applied this period.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Command {
pub frequency_mhz: u16,
/// `Some` only when the target owns the fan (max-fan mode).
pub fan_pwm: Option<u8>,
}
/// Why the loop could not produce a command.
@@ -149,8 +168,23 @@ impl TuningLoop {
self.pid.output().round() as u16
}
/// One control period. Returns the frequency to apply, inside the envelope.
pub fn step(&mut self, observation: Observation, dt_s: f32) -> Result<u16, TuningError> {
/// Fan duty implied by the target, if the target owns the fan.
fn target_fan(&self) -> Option<u8> {
match self.target {
TuningTarget::MaxFan { max_pwm } => Some(max_pwm),
_ => None,
}
}
fn command(&self) -> Command {
Command {
frequency_mhz: self.frequency_mhz(),
fan_pwm: self.target_fan(),
}
}
/// One control period. Returns the command to apply, inside the envelope.
pub fn step(&mut self, observation: Observation, dt_s: f32) -> Result<Command, TuningError> {
// Thermal guard: a hot sensor always derates, whatever the target says.
if let Some(hottest) = observation.hottest_mc {
if hottest >= self.ceiling_mc {
@@ -163,16 +197,33 @@ impl TuningLoop {
},
derated,
);
return Ok(self.frequency_mhz());
return Ok(self.command());
}
}
let (setpoint, measurement) = match self.target {
TuningTarget::PowerW(setpoint) => (setpoint, observation.power_w),
TuningTarget::HashrateThs(setpoint) => (setpoint, observation.hashrate_ths),
};
let measurement = measurement.ok_or(TuningError::NoMeasurement)?;
self.pid.update(setpoint, measurement, dt_s);
Ok(self.frequency_mhz())
match self.target {
TuningTarget::PowerW(setpoint) => {
let measurement = observation.power_w.ok_or(TuningError::NoMeasurement)?;
self.pid.update(setpoint, measurement, dt_s);
}
TuningTarget::HashrateThs(setpoint) => {
let measurement = observation.hashrate_ths.ok_or(TuningError::NoMeasurement)?;
self.pid.update(setpoint, measurement, dt_s);
}
TuningTarget::AmbientC { margin_mc } => {
let ambient = observation.ambient_mc.ok_or(TuningError::NoMeasurement)?;
let hottest = observation.hottest_mc.ok_or(TuningError::NoMeasurement)?;
let setpoint = ambient as f32 + margin_mc as f32;
self.pid.update(setpoint, hottest as f32, dt_s);
}
TuningTarget::MaxFan { .. } => {
// No setpoint loop here: ramp toward the envelope ceiling and let the thermal
// guard be the only thing that stops it.
let step = self.pid.config.max_step_per_s * dt_s;
let next = (self.pid.output() + step).min(f32::from(self.envelope.f_max_mhz));
self.pid.set_output(next);
}
}
Ok(self.command())
}
}
@@ -189,6 +240,15 @@ mod tests {
}
}
fn observation(hottest: i32) -> Observation {
Observation {
power_w: None,
hashrate_ths: None,
hottest_mc: Some(hottest),
ambient_mc: None,
}
}
#[test]
fn pid_drives_the_plant_to_the_setpoint() {
let mut pid = Pid::new(
@@ -203,10 +263,9 @@ mod tests {
},
0.0,
);
// Plant: power = 5 W per MHz.
// Plant: 5 W per MHz, so 3 kW needs 600 MHz, inside the controller ceiling.
let mut power = 0.0_f32;
for _ in 0..400 {
// Setpoint 3 kW needs 600 MHz, inside the 700 MHz ceiling of the controller.
let freq = pid.update(3_000.0, power, 1.0);
power = 5.0 * freq;
}
@@ -227,10 +286,8 @@ mod tests {
},
0.0,
);
let first = pid.update(1_000.0, 0.0, 1.0);
assert!((first - 10.0).abs() < f32::EPSILON, "got {first}");
let second = pid.update(1_000.0, 0.0, 1.0);
assert!((second - 20.0).abs() < f32::EPSILON, "got {second}");
assert!((pid.update(1_000.0, 0.0, 1.0) - 10.0).abs() < f32::EPSILON);
assert!((pid.update(1_000.0, 0.0, 1.0) - 20.0).abs() < f32::EPSILON);
}
#[test]
@@ -248,8 +305,7 @@ mod tests {
100.0,
);
let before = pid.output();
let after = pid.update(102.0, 100.0, 1.0);
assert!((after - before).abs() < f32::EPSILON);
assert!((pid.update(102.0, 100.0, 1.0) - before).abs() < f32::EPSILON);
}
#[test]
@@ -270,7 +326,6 @@ mod tests {
pid.update(1_000.0, 0.0, 1.0);
}
assert!((pid.output() - 100.0).abs() < 0.01);
// Reverse the error: the output must leave the rail promptly.
for _ in 0..5 {
pid.update(0.0, 200.0, 1.0);
}
@@ -282,7 +337,7 @@ mod tests {
}
#[test]
fn tuning_loop_moves_frequency_inside_the_envelope() {
fn power_target_moves_frequency_inside_the_envelope() {
let mut loop_ = TuningLoop::new(
TuningTarget::PowerW(2_400.0),
envelope(),
@@ -300,16 +355,9 @@ mod tests {
let mut freq = loop_.frequency_mhz();
for _ in 0..100 {
let power = 4.0 * f32::from(freq);
freq = loop_
.step(
Observation {
power_w: Some(power),
hashrate_ths: None,
hottest_mc: Some(70_000),
},
1.0,
)
.expect("step");
let mut obs = observation(70_000);
obs.power_w = Some(power);
freq = loop_.step(obs, 1.0).expect("step").frequency_mhz;
assert!((300..=700).contains(&freq), "out of envelope: {freq}");
}
let power = 4.0 * f32::from(freq);
@@ -324,30 +372,15 @@ mod tests {
PidConfig::default(),
90_000,
);
// Push frequency up first.
for _ in 0..50 {
loop_
.step(
Observation {
power_w: None,
hashrate_ths: Some(10.0),
hottest_mc: Some(60_000),
},
1.0,
)
.expect("step");
let mut obs = observation(60_000);
obs.hashrate_ths = Some(10.0);
loop_.step(obs, 1.0).expect("step");
}
let hot = loop_.frequency_mhz();
let derated = loop_
.step(
Observation {
power_w: None,
hashrate_ths: Some(10.0),
hottest_mc: Some(91_000),
},
1.0,
)
.expect("step");
let mut obs = observation(91_000);
obs.hashrate_ths = Some(10.0);
let derated = loop_.step(obs, 1.0).expect("step").frequency_mhz;
assert!(
derated < hot,
"thermal guard did not derate: {derated} vs {hot}"
@@ -362,17 +395,9 @@ mod tests {
PidConfig::default(),
95_000,
);
assert_eq!(
loop_.step(
Observation {
power_w: None,
hashrate_ths: Some(1.0),
hottest_mc: None
},
1.0
),
Err(TuningError::NoMeasurement)
);
let mut obs = observation(50_000);
obs.hashrate_ths = Some(1.0);
assert_eq!(loop_.step(obs, 1.0), Err(TuningError::NoMeasurement));
}
#[test]
@@ -380,4 +405,102 @@ mod tests {
let mut pid = Pid::new(PidConfig::default(), 42.0);
assert!((pid.update(100.0, 0.0, 0.0) - 42.0).abs() < f32::EPSILON);
}
#[test]
fn ambient_target_holds_the_hottest_sensor_near_ambient_plus_margin() {
let mut loop_ = TuningLoop::new(
TuningTarget::AmbientC { margin_mc: 20_000 },
envelope(),
PidConfig {
kp: 0.5,
ki: 0.05,
kd: 0.0,
out_min: 0.0,
out_max: 0.0,
max_step_per_s: 50.0,
deadband: 0.0,
},
200_000,
);
// Plant: hottest = ambient + 50 mC per MHz.
let ambient = 40_000;
let mut freq = loop_.frequency_mhz();
for _ in 0..300 {
let hottest = ambient + 50 * i32::from(freq);
let obs = Observation {
power_w: None,
hashrate_ths: None,
hottest_mc: Some(hottest),
ambient_mc: Some(ambient),
};
freq = loop_.step(obs, 1.0).expect("step").frequency_mhz;
}
let hottest = ambient + 50 * i32::from(freq);
assert!(
(hottest - (ambient + 20_000)).abs() < 2_000,
"hottest settled at {hottest}"
);
}
#[test]
fn ambient_target_needs_an_ambient_sensor() {
let mut loop_ = TuningLoop::new(
TuningTarget::AmbientC { margin_mc: 20_000 },
envelope(),
PidConfig::default(),
95_000,
);
assert_eq!(
loop_.step(observation(50_000), 1.0),
Err(TuningError::NoMeasurement)
);
}
#[test]
fn max_fan_mode_pins_the_fan_and_ramps_frequency() {
let ramp = PidConfig {
kp: 1.0,
ki: 0.0,
kd: 0.0,
out_min: 0.0,
out_max: 0.0,
max_step_per_s: 50.0,
deadband: 0.0,
};
let mut loop_ = TuningLoop::new(
TuningTarget::MaxFan { max_pwm: 100 },
envelope(),
ramp,
120_000,
);
let start = loop_.frequency_mhz();
let mut last = start;
for _ in 0..20 {
let command = loop_.step(observation(70_000), 1.0).expect("step");
assert_eq!(command.fan_pwm, Some(100));
last = command.frequency_mhz;
}
assert!(last > start, "frequency did not ramp: {last} vs {start}");
assert!(
last == 700,
"ramp did not reach the envelope ceiling: {last}"
);
}
#[test]
fn max_fan_mode_still_respects_the_temperature_ceiling() {
let mut loop_ = TuningLoop::new(
TuningTarget::MaxFan { max_pwm: 100 },
envelope(),
PidConfig::default(),
80_000,
);
for _ in 0..50 {
loop_.step(observation(70_000), 1.0).expect("step");
}
let hot = loop_.frequency_mhz();
let command = loop_.step(observation(85_000), 1.0).expect("step");
assert!(command.frequency_mhz < hot);
assert_eq!(command.fan_pwm, Some(100));
}
}