Add a feed-forward term (#3)

* Add a feed-forward term

The total control signal (PID + feed-forward) must be limited by the
integral anti-windup.

* Update src/DiscretePIDs.jl

Co-authored-by: Fredrik Bagge Carlson <[email protected]>

* Update README.md

Co-authored-by: Fredrik Bagge Carlson <[email protected]>

* Improve text format

Co-authored-by: Michele Zaffalon <[email protected]>
Co-authored-by: Fredrik Bagge Carlson <[email protected]>

Author: 3 people

README.md

@@ -5,12 +5,13 @@
 
 
 This package implements a discrete-time PID controller on the form
-$$U(s) = K \left( bR(s) - Y(s) + \dfrac{1}{sT_i} \left( R(s) - Y(s) \right) - \dfrac{sT_d}{1 + s T_d / N}Y(s) \right)$$
+$$U(s) = K \left( bR(s) - Y(s) + \dfrac{1}{sT_i} \left( R(s) - Y(s) \right) - \dfrac{sT_d}{1 + s T_d / N}Y(s) \right) + U_\textrm{ff}(s)$$
 
 where
 - $u(t) \leftrightarrow U(s)$ is the control signal
 - $y(t) \leftrightarrow Y(s)$ is the measurement signal
 - $r(t) \leftrightarrow R(s)$ is the reference / set point
+- $u_\textrm{ff}(t) \leftrightarrow u_\textrm{ff}(s)$ is the feed-forward contribution
 - $K$ is the proportional gain
 - $T_i$ is the integral time
 - $T_d$ is the derivative time
@@ -19,17 +20,17 @@ where
 
 The controller further has output saturation controlled by `umin, umax` and integrator anti-windup controlled by the tracking time $T_t$.
 
-Construct a controller using 
+Construct a controller using
 ```julia
 pid = DiscretePID(; K = 1, Ti = false, Td = false, Tt = √(Ti*Td), N = 10, b = 1, umin = -Inf, umax = Inf, Ts, I = 0, D = 0, yold = 0)
 ```
-and compute a control signal using 
+and compute a control signal using
 ```julia
-u = pid(r, y)
+u = pid(r, y, uff)
 ```
 or
 ```julia
-u = calculate_control!(pid, r, y)
+u = calculate_control!(pid, r, y, uff)
 ```
 
 The parameters $K, T_i, T_d$ may be updated using the functions, `set_K!, set_Ti!, set_Td!`.
@@ -40,7 +41,7 @@ The following example simulates the PID controller using ControlSystems.jl. We w
 ```julia
 using DiscretePIDs, ControlSystems, Plots
 Tf = 15 # Simulation time
-K  = 1 
+K  = 1
 Ti = 1
 Td = 1
 Ts = 0.01 # sample time
@@ -50,7 +51,7 @@ pid = DiscretePID(; K, Ts, Ti, Td)
 
 ctrl = function(x,t)
     y = (P.C*x)[] # measurement
-    d = 1         # disturbance 
+    d = 1         # disturbance
     r = 0         # reference
     u = pid(r, y)
     u + d # Plant input is control signal + disturbance
@@ -64,4 +65,5 @@ plot(res, plotu=true); ylabel!("u + d", sp=2)
 
 ## Details
 - The derivative term only acts on the (filtered) measurement and not the command signal. It is thus safe to pass step changes in the reference to the controller. The parameter $b$ can further be set to zero to avoid step changes in the control signal in response to step changes in the reference.
-- Bumpless transfer when updating `K` is realized by updating the state `I`. See the docs for `set_K!` for more details.
+- Bumpless transfer when updating `K` is realized by updating the state `I`. See the docs for `set_K!` for more details.
+- The total control signal $u(t)$ (PID + feed-forward) is limited by the integral anti-windup.

src/DiscretePIDs.jl

@@ -24,7 +24,7 @@ end
 """
     DiscretePID(; K = 1, Ti = false, Td = false, Tt = √(Ti*Td), N = 10, b = 1, umin = -Inf, umax = Inf, Ts, I = 0, D = 0, yold = 0)
 
-A discrete-time PID controller with set-point weighting and integrator anti-windup. 
+A discrete-time PID controller with set-point weighting and integrator anti-windup.
 The controller is implemented on the standard form
 ```math
 u = K \\left( e + \\dfrac{1}{Ti} \\int e dt + T_d \\dfrac{de}{dt} \\right)
@@ -74,13 +74,13 @@ function DiscretePID(;
     N ≥ 0 || throw(ArgumentError("N must be positive"))
     0 ≤ b ≤ 1 || throw(ArgumentError("b must be ∈ [0, 1]"))
     umax > umin || throw(ArgumentError("umax must be greater than umin"))
-    
+
     ar = Ts / Tt
     ad = Td / (Td + N * Ts)
     bd = K * N * ad
-    
+
     T = promote_type(typeof.((K, Ti, Td, Tt, N, b, umin, umax, Ts, bi, ar, bd, ad, I, D, yold))...)
-    
+
     DiscretePID(T.((K, Ti, Td, Tt, N, b, umin, umax, Ts, bi, ar, bd, ad, I, D, yold))...)
 end
 
@@ -128,15 +128,15 @@ end
 
 
 """
-    u = calculate_control!(pid::DiscretePID, r, y)
-    (pid)(r, y) # Alternative syntax
+    u = calculate_control!(pid::DiscretePID, r, y, uff=0)
+    (pid)(r, y, uff=0) # Alternative syntax
 
-Calculate the control output from the PID controller when `r` is the reference (set point) and `y` is the latest measurement.
+Calculate the control output from the PID controller when `r` is the reference (set point), `y` is the latest measurement and `uff` is the feed-forward contribution.
 """
-function calculate_control!(pid::DiscretePID, r, y)
+function calculate_control!(pid::DiscretePID, r, y, uff=0)
     P = pid.K * (pid.b * r - y)
     pid.D = pid.ad * pid.D - pid.bd * (y - pid.yold)
-    v = P + pid.I + pid.D
+    v = P + pid.I + pid.D + uff
     u = clamp(v, pid.umin, pid.umax)
     pid.I = pid.I + pid.bi * (r - y) + pid.ar * (u - v)
     pid.yold = y