Add adaptive PID tuning with a thermal derate guard
source-pr / source (pull_request) Successful in 12s

Replace preset tuning with a bounded controller: a PID over chain frequency
that targets a DC power draw or a hashrate, inside the profile envelope. The
controller rate-limits its output, ignores errors inside a deadband, takes the
derivative on the measurement so a setpoint change does not kick it, and uses
conditional integration so a saturated actuator does not wind the integral up.

A thermal guard runs before the target logic: any sensor at or above the
ceiling derates the frequency regardless of what the operator asked for, so a
hashrate target can never cook a board.
This commit is contained in:
2026-10-22 10:26:30 -06:00
parent 724b3da478
commit 5aa6349e27
2 changed files with 384 additions and 0 deletions
+1
View File
@@ -23,6 +23,7 @@ pub mod stratum_submit;
pub mod stratum_v1;
pub mod stratum_wire;
pub mod stratum_work;
pub mod tuning;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum Vendor {
+383
View File
@@ -0,0 +1,383 @@
// SPDX-License-Identifier: MIT
//! Adaptive tuning.
//!
//! The miner targets a power draw, a hashrate, or an operating point chosen for the ambient
//! temperature. Rather than picking a preset, a bounded PID moves the chain frequency inside the
//! profile envelope each control period, and a thermal guard can always override it downward.
//!
//! The controller is deliberately conservative: bounded output, rate limit, deadband, derivative
//! on the measurement (no setpoint kick) and conditional integration (no windup while saturated).
use crate::detect::Envelope;
/// What the operator asked for.
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum TuningTarget {
/// Hold this DC power draw; efficiency follows from the power point.
PowerW(f32),
/// Maximise hashrate up to this value.
HashrateThs(f32),
}
/// Controller tuning.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct PidConfig {
pub kp: f32,
pub ki: f32,
pub kd: f32,
pub out_min: f32,
pub out_max: f32,
/// Maximum output change per second.
pub max_step_per_s: f32,
/// Errors inside this band are ignored.
pub deadband: f32,
}
impl Default for PidConfig {
fn default() -> Self {
Self {
kp: 0.5,
ki: 0.1,
kd: 0.0,
out_min: 0.0,
out_max: 1_000.0,
max_step_per_s: 50.0,
deadband: 1.0,
}
}
}
/// A bounded PID with anti-windup and rate limiting.
#[derive(Clone, Debug)]
pub struct Pid {
config: PidConfig,
integral: f32,
last_measurement: Option<f32>,
output: f32,
}
impl Pid {
pub fn new(config: PidConfig, initial_output: f32) -> Self {
Self {
config,
integral: 0.0,
last_measurement: None,
output: initial_output.clamp(config.out_min, config.out_max),
}
}
pub fn output(&self) -> f32 {
self.output
}
/// 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 {
return self.output;
}
let error = setpoint - measurement;
if error.abs() <= self.config.deadband {
self.last_measurement = Some(measurement);
return self.output;
}
let derivative = match self.last_measurement {
Some(previous) => -(measurement - previous) / dt_s,
None => 0.0,
};
let candidate = self.config.kp * error + self.integral + self.config.kd * derivative;
let saturated = candidate > self.config.out_max || candidate < self.config.out_min;
// Conditional integration: never accumulate while the actuator is pinned in the direction
// of the error, or the loop unwinds slowly after a saturation episode.
let pinning = (candidate > self.config.out_max && error > 0.0)
|| (candidate < self.config.out_min && error < 0.0);
if !saturated || !pinning {
self.integral += self.config.ki * error * dt_s;
}
let mut desired = self.config.kp * error + self.integral + self.config.kd * derivative;
desired = desired.clamp(self.config.out_min, self.config.out_max);
let max_step = self.config.max_step_per_s * dt_s;
let step = (desired - self.output).clamp(-max_step, max_step);
self.output = (self.output + step).clamp(self.config.out_min, self.config.out_max);
self.last_measurement = Some(measurement);
self.output
}
}
/// What the loop needs to know each period.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Observation {
pub power_w: Option<f32>,
pub hashrate_ths: Option<f32>,
/// Hottest sensor in millidegrees, when telemetry is available.
pub hottest_mc: Option<i32>,
}
/// Why the loop could not produce a command.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum TuningError {
/// The measurement the target needs is missing this period.
NoMeasurement,
}
/// The tuning loop: one PID over chain frequency, bounded by the profile envelope.
#[derive(Clone, Debug)]
pub struct TuningLoop {
pid: Pid,
envelope: Envelope,
target: TuningTarget,
ceiling_mc: i32,
}
impl TuningLoop {
/// Start from the conservative floor of the envelope.
pub fn new(target: TuningTarget, envelope: Envelope, pid: PidConfig, ceiling_mc: i32) -> Self {
let config = PidConfig {
out_min: f32::from(envelope.f_min_mhz),
out_max: f32::from(envelope.f_max_mhz),
..pid
};
let start = f32::from(envelope.f_min_mhz);
Self {
pid: Pid::new(config, start),
envelope,
target,
ceiling_mc,
}
}
pub fn frequency_mhz(&self) -> u16 {
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> {
// Thermal guard: a hot sensor always derates, whatever the target says.
if let Some(hottest) = observation.hottest_mc {
if hottest >= self.ceiling_mc {
let derated = (self.pid.output() - 25.0).max(f32::from(self.envelope.f_min_mhz));
self.pid = Pid::new(
PidConfig {
out_min: f32::from(self.envelope.f_min_mhz),
out_max: f32::from(self.envelope.f_max_mhz),
..self.pid.config
},
derated,
);
return Ok(self.frequency_mhz());
}
}
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())
}
}
#[cfg(test)]
mod tests {
use super::*;
fn envelope() -> Envelope {
Envelope {
v_min_mv: 1100,
v_max_mv: 1500,
f_min_mhz: 300,
f_max_mhz: 700,
}
}
#[test]
fn pid_drives_the_plant_to_the_setpoint() {
let mut pid = Pid::new(
PidConfig {
kp: 0.02,
ki: 0.01,
kd: 0.0,
out_min: 0.0,
out_max: 700.0,
max_step_per_s: 1_000.0,
deadband: 0.0,
},
0.0,
);
// Plant: power = 5 W per MHz.
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;
}
assert!((power - 3_000.0).abs() < 50.0, "power settled at {power}");
}
#[test]
fn output_is_rate_limited() {
let mut pid = Pid::new(
PidConfig {
kp: 1.0,
ki: 0.0,
kd: 0.0,
out_min: 0.0,
out_max: 1_000.0,
max_step_per_s: 10.0,
deadband: 0.0,
},
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}");
}
#[test]
fn deadband_holds_the_output() {
let mut pid = Pid::new(
PidConfig {
kp: 1.0,
ki: 0.1,
kd: 0.0,
out_min: 0.0,
out_max: 1_000.0,
max_step_per_s: 100.0,
deadband: 5.0,
},
100.0,
);
let before = pid.output();
let after = pid.update(102.0, 100.0, 1.0);
assert!((after - before).abs() < f32::EPSILON);
}
#[test]
fn saturation_does_not_wind_up_the_integral() {
let mut pid = Pid::new(
PidConfig {
kp: 1.0,
ki: 1.0,
kd: 0.0,
out_min: 0.0,
out_max: 100.0,
max_step_per_s: 1_000.0,
deadband: 0.0,
},
0.0,
);
for _ in 0..100 {
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);
}
assert!(
pid.output() < 99.0,
"output stuck at the rail: {}",
pid.output()
);
}
#[test]
fn tuning_loop_moves_frequency_inside_the_envelope() {
let mut loop_ = TuningLoop::new(
TuningTarget::PowerW(2_400.0),
envelope(),
PidConfig {
kp: 0.2,
ki: 0.05,
kd: 0.0,
out_min: 0.0,
out_max: 0.0,
max_step_per_s: 50.0,
deadband: 0.0,
},
95_000,
);
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");
assert!((300..=700).contains(&freq), "out of envelope: {freq}");
}
let power = 4.0 * f32::from(freq);
assert!((power - 2_400.0).abs() < 200.0, "power settled at {power}");
}
#[test]
fn thermal_guard_derates_regardless_of_target() {
let mut loop_ = TuningLoop::new(
TuningTarget::HashrateThs(200.0),
envelope(),
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 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");
assert!(
derated < hot,
"thermal guard did not derate: {derated} vs {hot}"
);
}
#[test]
fn missing_measurement_is_an_error() {
let mut loop_ = TuningLoop::new(
TuningTarget::PowerW(3_000.0),
envelope(),
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)
);
}
#[test]
fn zero_dt_holds_the_output() {
let mut pid = Pid::new(PidConfig::default(), 42.0);
assert!((pid.update(100.0, 0.0, 0.0) - 42.0).abs() < f32::EPSILON);
}
}