API Reference

class py_pidx.controller.PID(Kp: float = 1.0, Ki: float = 0.0, Kd: float = 0.0, gain_scheduler: GainScheduler | None = None, setpoint: float = 0.0, sample_time: float = 0.01, output_limits: Tuple[float | None, float | None] = (None, None), output_deadband_limits: Tuple[float | None, float | None] = (None, None), error_deadband_limits: Tuple[float | None, float | None] = (None, None), feedforward: float = 0.0, derivative_filter: float = 0.0, auto_mode: bool = True, anti_windup: bool = True, max_output_rate: float | None = None, derivative_on_measurement: bool = False, integral_on_measurement: bool = False)[source]

Bases: object

PID controller implementing proportional-integral-derivative control with optional features including gain scheduling, deadbands, derivative filtering, anti-windup, slew rate limiting, feedforward control, and thread safety.

Parameters:

  • Kp (float, default=1.0) – Proportional gain coefficient.

  • Ki (float, default=0.0) – Integral gain coefficient.

  • Kd (float, default=0.0) – Derivative gain coefficient.

  • gain_scheduler (Optional[GainScheduler], default=None) – Optional object to dynamically update PID gains based on process variable.

  • setpoint (float, default=0.0) – Desired target value for the controlled variable.

  • sample_time (float, default=0.01) – Minimum time interval (seconds) between PID calculations.

  • output_limits (Tuple[Optional[float], Optional[float]], default=(None, None)) – Min and max allowable controller output.

  • output_deadband_limits (Tuple[Optional[float], Optional[float]], default=(None, None)) – Range around zero output where output is forced to zero to reduce noise effects.

  • error_deadband_limits (Tuple[Optional[float], Optional[float]], default=(None, None)) – Range around zero error where error is treated as zero to reduce sensitivity to noise.

  • feedforward (float, default=0.0) – Constant feedforward term added to controller output.

  • derivative_filter (float, default=0.0) – Low-pass smoothing factor (alpha) for derivative term (0.0–1.0).

  • auto_mode (bool, default=True) – Enable or disable PID output calculation.

  • anti_windup (bool, default=True) – Enable anti-windup to prevent integral runaway.

  • max_output_rate (Optional[float], default=None) – Max allowed rate of output change per second (slew rate limiting).

  • derivative_on_measurement (bool, default=False) – Compute derivative term from process variable instead of error.

  • integral_on_measurement (bool, default=False) – Compute integral term based on measurement changes instead of error.

Notes

  • Gain scheduling allows dynamic tuning of PID gains based on operating conditions.

  • Anti-windup helps prevent integral accumulation when actuators saturate.

  • Derivative filtering reduces noise amplification in the derivative term.

reset()[source]

Reset the internal PID controller state.

Clears integral accumulation, last error, last derivative, last process variable, and output history to initial states.

run(process_variable: float, delta_time: float | None = None, feedforward: float | None = None) → float[source]

Compute the PID output for the given process variable.

Parameters:

  • process_variable (float) – Current measured value of the process variable.

  • delta_time (float or None, optional) – Time elapsed since last update; if None, it will be internally computed.

  • feedforward (float or None, optional) – Optional feedforward term to override the internal feedforward value.

Returns:

Updated controller output value.

Return type:

float

set_auto_mode(enabled: bool, reset: bool = True)[source]

Enable or disable automatic PID computation mode.

When disabled, the PID output remains constant at the last computed value.

Parameters:

  • enabled (bool) – True to enable automatic PID computation, False to disable.

  • reset (bool, optional) – If True, reset internal state when mode is changed.

set_output_limits(min_output: float | None, max_output: float | None)[source]

Define the saturation limits for the controller output.

Controller output will be clamped within these bounds.

Parameters:

  • min_output (float or None) – Minimum output limit; None means no limit.

  • max_output (float or None) – Maximum output limit; None means no limit.