Documentation
¶
Overview ¶
Package pid provides a generic PID controller implementation with filtered derivative.
This package implements a Proportional-Integral-Derivative controller suitable for various dynamic adjustment scenarios:
- Rate limiting (memory/load-based throttling)
- PoW difficulty adjustment (block time targeting)
- Temperature control
- Motor speed control
- Any system requiring feedback-based regulation
The controller features:
- Low-pass filtered derivative to suppress high-frequency noise
- Anti-windup on the integral term to prevent saturation
- Configurable output clamping
- Thread-safe operation
Control Theory Background ¶
The PID controller computes an output based on the error between the current process variable and a target setpoint:
output = Kp*error + Ki*∫error*dt + Kd*d(filtered_error)/dt
Where:
- Proportional (P): Immediate response proportional to current error
- Integral (I): Accumulated error to eliminate steady-state offset
- Derivative (D): Rate of change to anticipate future error (filtered)
Filtered Derivative ¶
Raw derivative amplifies high-frequency noise. This implementation applies an exponential moving average (low-pass filter) before computing the derivative:
filtered_error = α*current_error + (1-α)*previous_filtered_error derivative = (filtered_error - previous_filtered_error) / dt
Lower α values provide stronger filtering (recommended: 0.1-0.3).
Index ¶
- func DifficultyAdjustmentTuning() pidif.Tuning
- func MotorSpeedTuning() pidif.Tuning
- func RateLimitReadTuning() pidif.Tuning
- func RateLimitWriteTuning() pidif.Tuning
- func TemperatureControlTuning(targetTemp float64) pidif.Tuning
- type Controller
- func New(tuning pidif.Tuning) *Controller
- func NewDefault() *Controller
- func NewDifficultyAdjustmentController() *Controller
- func NewMotorSpeedController() *Controller
- func NewRateLimitReadController() *Controller
- func NewRateLimitWriteController() *Controller
- func NewTemperatureController(targetTemp float64) *Controller
- func NewWithGains(kp, ki, kd, setpoint float64) *Controller
- func (c *Controller) Gains() (kp, ki, kd float64)
- func (c *Controller) Reset()
- func (c *Controller) SetDerivativeFilter(alpha float64)
- func (c *Controller) SetGains(kp, ki, kd float64)
- func (c *Controller) SetIntegralLimits(min, max float64)
- func (c *Controller) SetOutputLimits(min, max float64)
- func (c *Controller) SetSetpoint(setpoint float64)
- func (c *Controller) SetTuning(tuning pidif.Tuning)
- func (c *Controller) Setpoint() float64
- func (c *Controller) State() (integral, prevError, prevFilteredError float64, initialized bool)
- func (c *Controller) Tuning() pidif.Tuning
- func (c *Controller) Update(pv pidif.ProcessVariable) pidif.Output
- func (c *Controller) UpdateValue(value float64) pidif.Output
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DifficultyAdjustmentTuning ¶
DifficultyAdjustmentTuning returns tuning for PoW difficulty adjustment. Designed for block time targeting where: - Process variable: actual_block_time / target_block_time (1.0 = on target) - Output: difficulty multiplier (1.0 = no change, >1 = harder, <1 = easier)
This uses: - Low Kp to avoid overreacting to individual blocks - Moderate Ki to converge on target over time - Small Kd with strong filtering to anticipate trends
func MotorSpeedTuning ¶
MotorSpeedTuning returns tuning for motor speed control. - Process variable: actual RPM / target RPM - Output: motor power level
func RateLimitReadTuning ¶
RateLimitReadTuning returns tuning optimized for read rate limiting. - Less aggressive than writes (reads are more latency-sensitive) - Lower gains to avoid over-throttling queries
func RateLimitWriteTuning ¶
RateLimitWriteTuning returns tuning optimized for write rate limiting. - Aggressive response to prevent memory exhaustion - Moderate integral for sustained load handling - Small derivative with strong filtering
func TemperatureControlTuning ¶
TemperatureControlTuning returns tuning for temperature regulation. Suitable for heating/cooling systems where: - Process variable: current temperature - Setpoint: target temperature - Output: heater/cooler power level (0-1)
Types ¶
type Controller ¶
type Controller struct {
// contains filtered or unexported fields
}
Controller implements a PID controller with filtered derivative. It is safe for concurrent use.
func New ¶
func New(tuning pidif.Tuning) *Controller
New creates a new PID controller with the given tuning parameters.
func NewDefault ¶
func NewDefault() *Controller
NewDefault creates a new PID controller with default tuning.
func NewDifficultyAdjustmentController ¶
func NewDifficultyAdjustmentController() *Controller
NewDifficultyAdjustmentController creates a controller for PoW difficulty.
func NewMotorSpeedController ¶
func NewMotorSpeedController() *Controller
NewMotorSpeedController creates a controller for motor speed control.
func NewRateLimitReadController ¶
func NewRateLimitReadController() *Controller
NewRateLimitReadController creates a controller for read rate limiting.
func NewRateLimitWriteController ¶
func NewRateLimitWriteController() *Controller
NewRateLimitWriteController creates a controller for write rate limiting.
func NewTemperatureController ¶
func NewTemperatureController(targetTemp float64) *Controller
NewTemperatureController creates a controller for temperature regulation.
func NewWithGains ¶
func NewWithGains(kp, ki, kd, setpoint float64) *Controller
NewWithGains creates a new PID controller with specified gains and defaults for other parameters.
func (*Controller) Gains ¶
func (c *Controller) Gains() (kp, ki, kd float64)
Gains returns the current PID gains.
func (*Controller) SetDerivativeFilter ¶
func (c *Controller) SetDerivativeFilter(alpha float64)
SetDerivativeFilter updates the derivative filter coefficient. Lower values provide stronger filtering (0.1-0.3 recommended).
func (*Controller) SetGains ¶
func (c *Controller) SetGains(kp, ki, kd float64)
SetGains updates the PID gains.
func (*Controller) SetIntegralLimits ¶
func (c *Controller) SetIntegralLimits(min, max float64)
SetIntegralLimits updates the anti-windup limits.
func (*Controller) SetOutputLimits ¶
func (c *Controller) SetOutputLimits(min, max float64)
SetOutputLimits updates the output clamping limits.
func (*Controller) SetSetpoint ¶
func (c *Controller) SetSetpoint(setpoint float64)
SetSetpoint updates the target value.
func (*Controller) SetTuning ¶
func (c *Controller) SetTuning(tuning pidif.Tuning)
SetTuning updates all tuning parameters at once.
func (*Controller) Setpoint ¶
func (c *Controller) Setpoint() float64
Setpoint returns the current setpoint.
func (*Controller) State ¶
func (c *Controller) State() (integral, prevError, prevFilteredError float64, initialized bool)
State returns the current internal state for monitoring/debugging.
func (*Controller) Tuning ¶
func (c *Controller) Tuning() pidif.Tuning
Tuning returns a copy of the current tuning parameters.
func (*Controller) Update ¶
func (c *Controller) Update(pv pidif.ProcessVariable) pidif.Output
Update computes the controller output based on the current process variable.
func (*Controller) UpdateValue ¶
func (c *Controller) UpdateValue(value float64) pidif.Output
UpdateValue is a convenience method that takes a raw float64 value.
Source Files
¶
- controller.go
- presets.go