refactor: Blocks/continuous.jl

Author: ven-k

src/Blocks/continuous.jl

@@ -1,7 +1,8 @@
 """
-    Integrator(;name, k=1, x_start=0.0)
+    Integrator(;name, k = 1, x = 0.0)
 
 Outputs `y = ∫k*u dt`, corresponding to the transfer function `1/s`.
+Initial value of integrator state `x` can be set with `x`
 
 # Connectors:
 
@@ -11,22 +12,25 @@ Outputs `y = ∫k*u dt`, corresponding to the transfer function `1/s`.
 # Parameters:
 
   - `k`: Gain of integrator
-  - `x_start`: Initial value of integrator
 """
-@component function Integrator(; name, k = 1, x_start = 0.0)
-    @named siso = SISO()
-    @unpack u, y = siso
-    sts = @variables x(t)=x_start [description = "State of Integrator $name"]
-    pars = @parameters k=k [description = "Gain of Integrator $name"]
-    eqs = [D(x) ~ k * u
-        y ~ x]
-    extend(ODESystem(eqs, t, sts, pars; name = name), siso)
+@mtkmodel Integrator begin
+    @extend u, y = siso = SISO()
+    @variables begin
+        x(t) = 0.0, [description = "State of Integrator"]
+    end
+    @parameters begin
+        k = 1, [description = "Gain of Integrator"]
+    end
+    @equations begin
+        D(x) ~ k * u
+        y ~ x
+    end
 end
-
 """
-    Derivative(; name, k=1, T, x_start=0.0)
+    Derivative(; name, k = 1, T, x = 0.0)
 
 Outputs an approximate derivative of the input. The transfer function of this block is
+Initial value of the state `x` can be set with `x`
 
 ```
 k       k
@@ -44,31 +48,37 @@ A smaller `T` leads to a more ideal approximation of the derivative.
 
   - `k`: Gain
   - `T`: [s] Time constants (T>0 required; T=0 is ideal derivative block)
-  - `x_start`: Initial value of state
 
 # Connectors:
 
   - `input`
   - `output`
 """
-@component function Derivative(; name, k = 1, T, x_start = 0.0)
-    @symcheck T > 0 || throw(ArgumentError("Time constant `T` has to be strictly positive"))
-    @named siso = SISO()
-    @unpack u, y = siso
-    sts = @variables x(t)=x_start [description = "State of Derivative $name"]
-    pars = @parameters T=T [description = "Time constant of Derivative $name"] k=k [
-        description = "Gain of Derivative $name",
-    ]
-    eqs = [D(x) ~ (u - x) / T
-        y ~ (k / T) * (u - x)]
-    extend(ODESystem(eqs, t, sts, pars; name = name), siso)
+@mtkmodel Derivative begin
+    @extend u, y = siso = SISO()
+    @variables begin
+        x(t) = 0.0, [description = "State of Derivative"]
+    end
+    @parameters begin
+        T = T, [description = "Time constant of Derivative"]
+        k = 1, [description = "Gain of Derivative"]
+    end
+    begin
+        @symcheck T > 0 ||
+                  throw(ArgumentError("Time constant `T` has to be strictly positive"))
+    end
+    @equations begin
+        D(x) ~ (u - x) / T
+        y ~ (k / T) * (u - x)
+    end
 end
 
 """
-    FirstOrder(; name, k=1, T, x_start=0.0, lowpass=true)
+    FirstOrder(; name, k = 1.0, T, x = 0.0, lowpass = true)
 
 A first-order filter with a single real pole in `s = -T` and gain `k`. If `lowpass=true` (default), the transfer function
 is given by `Y(s)/U(s) = `
+Initial value of the state `x` can be set with `x`
 
 ```
    k
@@ -88,7 +98,6 @@ sT + 1 - k
 
   - `k`: Gain
   - `T`: [s] Time constants (T>0 required)
-  - `x_start`: Initial value of state
 
 # Connectors:
 
@@ -97,21 +106,28 @@ sT + 1 - k
 
 See also [`SecondOrder`](@ref)
 """
-@component function FirstOrder(; name, k = 1, T, x_start = 0.0, lowpass = true)
-    @symcheck T > 0 || throw(ArgumentError("Time constant `T` has to be strictly positive"))
-    @named siso = SISO()
-    @unpack u, y = siso
-    sts = @variables x(t)=x_start [description = "State of FirstOrder filter $name"]
-    pars = @parameters T=T [description = "Time constant of FirstOrder filter $name"] k=k [
-        description = "Gain of FirstOrder $name",
-    ]
-    eqs = [D(x) ~ (k * u - x) / T
-        lowpass ? y ~ x : y ~ k * u - x]
-    extend(ODESystem(eqs, t, sts, pars; name = name), siso)
+@mtkmodel FirstOrder begin
+    @extend u, y = siso = SISO()
+    @variables begin
+        x(t) = 0.0, [description = "State of FirstOrder filter"]
+    end
+    @parameters begin
+        lowpass = true
+        T = T, [description = "Time constant of FirstOrder filter"]
+        k = 1.0, [description = "Gain of FirstOrder"]
+    end
+    begin
+        @symcheck T > 0 ||
+                  throw(ArgumentError("Time constant `T` has to be strictly positive"))
+    end
+    @equations begin
+        D(x) ~ (k * u - x) / T
+        getdefault(lowpass) ? y ~ x : y ~ k * u - x
+    end
 end
 
 """
-    SecondOrder(; name, k=1, w, d, x_start=0.0, xd_start=0.0)
+    SecondOrder(; name, k = 1.0, w, d, x = 0.0, xd = 0.0)
 
 A second-order filter with gain `k`, a bandwidth of `w` rad/s and relative damping `d`. The transfer function
 is given by `Y(s)/U(s) = `
@@ -124,44 +140,47 @@ s² + 2d*w*s + w^2
 
 Critical damping corresponds to `d=1`, which yields the fastest step response without overshoot, `d < 1` results in an underdamped filter while `d > 1` results in an overdamped filter.
 `d = 1/√2` corresponds to a Butterworth filter of order 2 (maximally flat frequency response).
+Initial value of the state `x` can be set with `x`, and of derivative state `xd` with `xd`.
 
 # Parameters:
 
   - `k`: Gain
   - `w`: [`rad/s`] Angular frequency
   - `d`: Damping
-  - `x_start`: Initial value of state (output)
-  - `xd_start`: Initial value of derivative of state (output)
 
 # Connectors:
 
   - `input`
   - `output`
 """
-@component function SecondOrder(; name, k = 1, w, d, x_start = 0.0, xd_start = 0.0)
-    @named siso = SISO()
-    @unpack u, y = siso
-    @variables x(t)=x_start [description = "State of SecondOrder filter $name"]
-    @variables xd(t)=xd_start [description = "Derivative state of SecondOrder filter $name"]
-    @parameters k=k [description = "Gain of SecondOrder $name"]
-    @parameters w=w [description = "Bandwidth of SecondOrder $name"]
-    @parameters d=d [description = "Relative damping of SecondOrder $name"]
-    eqs = [D(x) ~ xd
+@mtkmodel SecondOrder begin
+    @extend u, y = siso = SISO()
+    @variables begin
+        x(t) = 0.0, [description = "State of SecondOrder filter"]
+        xd(t) = 0.0, [description = "Derivative state of SecondOrder filter"]
+    end
+    @parameters begin
+        k = 1.0, [description = "Gain of SecondOrder"]
+        w, [description = "Bandwidth of SecondOrder"]
+        d, [description = "Relative damping of SecondOrder"]
+    end
+    @equations begin
+        D(x) ~ xd
         D(xd) ~ w * (w * (k * u - x) - 2 * d * xd)
-        y ~ x]
-    extend(ODESystem(eqs, t; name = name), siso)
+        y ~ x
+    end
 end
 
 """
-    PI(;name, k=1, T, x_start=0.0)
+    PI(;name, gainPI.k = 1.0, T, int.x = 0.0)
 
 Textbook version of a PI-controller without actuator saturation and anti-windup measure.
+Initial value of integrator state `x` can be set with `int.x`
+Initial value of gain  can be set with `gainPI.k`
 
 # Parameters:
 
-  - `k`: Gain
   - `T`: [s] Integrator time constant (T>0 required)
-  - `x_start`: Initial value for the integrator
 
 # Connectors:
 
@@ -170,22 +189,28 @@ Textbook version of a PI-controller without actuator saturation and anti-windup
 
 See also [`LimPI`](@ref)
 """
-@component function PI(; name, k = 1, T, x_start = 0.0)
-    @symcheck T > 0 || throw(ArgumentError("Time constant `T` has to be strictly positive"))
-    @named err_input = RealInput() # control error
-    @named ctr_output = RealOutput() # control signal
-    @named gainPI = Gain(k)
-    @named addPI = Add()
-    @named int = Integrator(k = 1 / T, x_start = x_start)
-    sys = [err_input, ctr_output, gainPI, addPI, int]
-    eqs = [
-        connect(err_input, addPI.input1),
-        connect(addPI.output, gainPI.input),
-        connect(gainPI.output, ctr_output),
-        connect(err_input, int.input),
-        connect(int.output, addPI.input2),
-    ]
-    ODESystem(eqs, t, [], []; name = name, systems = sys)
+@mtkmodel PI begin
+    @parameters begin
+        T, [description = "Integrator time constant"]
+    end
+    begin
+        @symcheck T > 0 ||
+                  throw(ArgumentError("Time constant `T` has to be strictly positive"))
+    end
+    @components begin
+        err_input = RealInput() # control error
+        ctr_output = RealOutput() # control signal
+        gainPI = Gain(; k = 1.0)
+        addPI = Add()
+        int = Integrator(k = 1 / T, x = 0.0)
+    end
+    @equations begin
+        connect(err_input, addPI.input1)
+        connect(addPI.output, gainPI.input)
+        connect(gainPI.output, ctr_output)
+        connect(err_input, int.input)
+        connect(int.output, addPI.input2)
+    end
 end
 
 """
@@ -224,12 +249,12 @@ See also [`LimPID`](@ref)
     @named gainPID = Gain(k)
     @named addPID = Add3()
     if with_I
-        @named int = Integrator(k = 1 / Ti, x_start = xi_start)
+        @named int = Integrator(k = 1 / Ti, x = xi_start)
     else
         @named Izero = Constant(k = 0)
     end
     if with_D
-        @named der = Derivative(k = Td, T = 1 / Nd, x_start = xd_start)
+        @named der = Derivative(k = Td, T = 1 / Nd, x = xd_start)
     else
         @named Dzero = Constant(k = 0)
     end
@@ -265,16 +290,16 @@ See also [`LimPID`](@ref)
 end
 
 """
-    LimPI(;name, k=1, T, u_max=1, u_min=-u_max, Ta)
+    LimPI(; name, T, Ta, k = 1.0, x_start = 0.0, u_max = 1.0, u_min = -u_max)
 
 Text-book version of a PI-controller with actuator saturation and anti-windup measure.
+Initial value of gain  can be set with `gainPI.k`
+Initial value of integrator state `x` can be set with `int.x`
 
 # Parameters:
 
-  - `k`: Gain
   - `T`: [s] Integrator time constant (T>0 required)
   - `Ta`: [s] Tracking time constant (Ta>0 required)
-  - `x_start`: Initial value for the integrator
 
 # Connectors:
 
@@ -291,7 +316,7 @@ Text-book version of a PI-controller with actuator saturation and anti-windup me
     @named gainPI = Gain(k)
     @named addPI = Add()
     @named addTrack = Add()
-    @named int = Integrator(k = 1 / T, x_start = x_start)
+    @named int = Integrator(k = 1 / T, x = x_start)
     @named limiter = Limiter(y_max = u_max, y_min = u_min)
     @named addSat = Add(k1 = 1, k2 = -1)
     @named gainTrack = Gain(1 / Ta)
@@ -376,7 +401,7 @@ where the transfer function for the derivative includes additional filtering, se
     @named measurement = RealInput()
     @named ctr_output = RealOutput() # control signal
     @named addP = Add(k1 = wp, k2 = -1)
-    @named gainPID = Gain(k)
+    @named gainPID = Gain(; k)
     @named addPID = Add3()
     @named limiter = Limiter(y_max = u_max, y_min = u_min)
     if with_I
@@ -387,12 +412,12 @@ where the transfer function for the derivative includes additional filtering, se
         else
             @named addI = Add(k1 = 1, k2 = -1)
         end
-        @named int = Integrator(k = 1 / Ti, x_start = xi_start)
+        @named int = Integrator(k = 1 / Ti, x = xi_start)
     else
         @named Izero = Constant(k = 0)
     end
     if with_D
-        @named der = Derivative(k = Td, T = 1 / Nd, x_start = xd_start)
+        @named der = Derivative(k = Td, T = 1 / Nd, x = xd_start)
         @named addD = Add(k1 = wd, k2 = -1)
     else
         @named Dzero = Constant(k = 0)

test/Blocks/continuous.jl

@@ -13,10 +13,10 @@ an integrator with a constant input is often used together with the system under
 
 @testset "Constant" begin
     @named c = Constant(; k = 1)
-    @named int = Integrator()
+    @named int = Integrator(x = 1)
     @named iosys = ODESystem(connect(c.output, int.input), t, systems = [int, c])
     sys = structural_simplify(iosys)
-    prob = ODEProblem(sys, Pair[int.x => 1.0], (0.0, 1.0))
+    prob = ODEProblem(sys, Pair[], (0.0, 1.0))
     sol = solve(prob, Rodas4())
     @test sol.retcode == Success
     @test all(sol[c.output.u] .≈ 1)
@@ -147,7 +147,7 @@ end
 @testset "PI" begin
     re_val = 2
     @named ref = Constant(; k = re_val)
-    @named pi_controller = PI(k = 1, T = 1)
+    @named pi_controller = PI(int.k = 1, T = 1)
     @named plant = Plant()
     @named fb = Feedback()
     @named model = ODESystem([
@@ -227,8 +227,12 @@ end
 @testset "LimPI" begin
     re_val = 1
     @named ref = Constant(; k = re_val)
-    @named pi_controller_lim = LimPI(k = 3, T = 0.5, u_max = 1.5, u_min = -1.5, Ta = 0.1)
-    @named pi_controller = PI(k = 3, T = 0.5)
+    @named pi_controller_lim = LimPI(k = 3,
+        T = 0.5,
+        u_max = 1.5,
+        u_min = -1.5,
+        Ta = 0.1)
+    @named pi_controller = PI(gainPI.k = 3, T = 0.5)
     @named sat = Limiter(y_max = 1.5, y_min = -1.5)
     @named plant = Plant()
     @named fb = Feedback()