Merge pull request #230 from SciML/fb/PI_docs

improve docstring and interface to PI controller

Author: baggepinnen

src/Blocks/continuous.jl

@@ -172,14 +172,19 @@ Initial value of the state `x` can be set with `x`, and of derivative state `xd`
 end
 
 """
-    PI(;name, gainPI.k = 1.0, T, int.x = 0.0)
+    PI(;name, k = 1.0, T = 1.0, int.x = 0.0)
 
 Textbook version of a PI-controller without actuator saturation and anti-windup measure.
-The proportional gain can be set with `gainPI.k`
+The proportional gain can be set with `k`
 Initial value of integrator state `x` can be set with `int.x`
 
-# Parameters:
+The PI controller is implemented on standard form:
+```math
+U(s) = k (1 + \\dfrac{1}{sT}) E(S)
+```
 
+# Parameters:
+  - `k`: Proportional gain
   - `T`: [s] Integrator time constant (T>0 required)
 
 # Connectors:
@@ -191,7 +196,8 @@ See also [`LimPI`](@ref)
 """
 @mtkmodel PI begin
     @parameters begin
-        T, [description = "Integrator time constant"]
+        k = 1.0, [description = "Proportional gain"]
+        T = 1.0, [description = "Integrator time constant"]
     end
     begin
         @symcheck T > 0 ||
@@ -200,7 +206,7 @@ See also [`LimPI`](@ref)
     @components begin
         err_input = RealInput() # control error
         ctr_output = RealOutput() # control signal
-        gainPI = Gain(; k = 1.0)
+        gainPI = Gain(; k)
         addPI = Add()
         int = Integrator(k = 1 / T, x = 0.0)
     end
@@ -294,6 +300,12 @@ end
 
 Text-book version of a PI-controller with actuator saturation and anti-windup measure.
 
+The PI controller is implemented on standard form
+```math
+u(t) = sat(k (e(t) + ∫\\dfrac{1}{T}e(t) dt) )
+```
+The simplified expression above is given without the anti-windup protection.
+
 # Parameters:
 
   - `k`: Proportional gain

test/Blocks/continuous.jl

@@ -147,7 +147,7 @@ end
 @testset "PI" begin
     re_val = 2
     @named ref = Constant(; k = re_val)
-    @named pi_controller = PI(int.k = 1, T = 1)
+    @named pi_controller = PI(k = 1, T = 1)
     @named plant = Plant()
     @named fb = Feedback()
     @named model = ODESystem([