adds connectors to doc strings

Author: ValentinKaisermayer

src/Blocks/Blocks.jl

@@ -2,7 +2,7 @@
 The module `Blocks` contains common input-output components, referred to as blocks.
 """
 module Blocks
-using ModelingToolkit, Symbolics, IfElse, OrdinaryDiffEq
+using ModelingToolkit, Symbolics, OrdinaryDiffEq
 using IfElse: ifelse
 
 @parameters t

src/Blocks/continuous.jl

@@ -2,6 +2,10 @@
     Integrator(;name, k=1, x_start=0.0)
 
 Outputs `y = ∫k*u dt`, corresponding to the transfer function `1/s`.
+
+# Connectors:
+- `input`
+- `output`
 """
 function Integrator(;name, k=1, x_start=0.0)
     @named siso = SISO()
@@ -34,6 +38,10 @@ 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`
 """
 function Derivative(; name, k=1, T, x_start=0.0)
     T > 0 || throw(ArgumentError("Time constant `T` has to be strictly positive"))
@@ -63,6 +71,10 @@ sT + 1
 - `k`: Gain
 - `T`: [s] Time constants (T>0 required)
 - `x_start`: Initial value of state
+
+# Connectors:
+- `input`
+- `output`
 """
 function FirstOrder(; name, k=1, T, x_start=0.0)
     T > 0 || throw(ArgumentError("Time constant `T` has to be strictly positive"))
@@ -96,6 +108,10 @@ Critical damping corresponds to `d=1`, which yields the fastest step response wi
 - `d`: Damping
 - `x_start`: Initial value of state (output)
 - `xd_start`: Initial value of derivative of state (output)
+
+# Connectors:
+- `input`
+- `output`
 """
 function SecondOrder(; name, k=1, w, d, x_start=0.0, xd_start=0.0)
     @named siso = SISO()
@@ -119,6 +135,10 @@ Textbook version of a PI-controller without actuator saturation and anti-windup
 - `k`: Gain
 - `T`: [s] Integrator time constant (T>0 required)
 - `x_start`: Initial value for the integrator
+
+# Connectors:
+- `err_input`
+- `ctr_output`
 """
 function PI(;name, k=1, T, x_start=0.0)
     T > 0 || throw(ArgumentError("Time constant `T` has to be strictly positive"))
@@ -150,6 +170,10 @@ Text-book version of a PID-controller without actuator saturation and anti-windu
 - `Nd`: [s] Time constant for the derivative approximation (Nd>0 required; Nd=0 is ideal derivative).
 - `x_start`: Initial value for the integrator.
 - `xd_start`: Initial value for the derivative state.
+
+# Connectors:
+- `err_input`
+- `ctr_output`
 """
 function PID(;name, k=1, Ti=false, Td=false, Nd=10, xi_start=0, xd_start=0)
     with_I = !isequal(Ti, false)
@@ -215,6 +239,10 @@ Text-book version of a PI-controller with actuator saturation and anti-windup me
 - `T`: [s] Integrator time constant (T>0 required)
 - `Ta`: [s] Tracking time constant (Ta>0 required)
 - `x_start`: Initial value for the integrator
+
+# Connectors:
+- `err_input`
+- `ctr_output`
 """
 function LimPI(;name, k=1, T, u_max=1, u_min=-u_max, Ta, x_start=0.0)
     Ta > 0 || throw(ArgumentError("Time constant `Ta` has to be strictly positive"))
@@ -251,11 +279,6 @@ end
 
 Proportional-Integral-Derivative (PID) controller with output saturation, set-point weighting and integrator anti-windup.
 
-This block has inputs
-- `u_r` reference/set point
-- `u_y` measurement signal
-and output `y` corresponding to the control signal.
-
 The equation for the control signal is roughly
 ```
 k(ep + 1/Ti * ∫e + 1/Td * d/dt(ed))
@@ -265,14 +288,20 @@ ed = wd*u_r - u_y
 ```
 where the transfer function for the derivative includes additional filtering, see `? Derivative` for more details.
 
+# Parameters:
 - `k`: Proportional gain
-- `Ti`: Integrator time constant. Set to `false` to turn off integral action.
-- `Td`: Derivative time constant. Set to `false` to turn off derivative action.
-- `wp`: Set-point weighting in the proportional part.
-- `wd`: Set-point weighting in the derivative part.
-- `Nd`: Derivative limit, limits the derivative gain to Nd/Td. Reasonable values are ∈ [8, 20]. A higher value gives a better approximation of an ideal derivative at the expense of higher noise amplification.
-- `Ni`: `Ni*Ti` controls the time constant `Tₜ` of anti-windup tracking. A common (default) choice is `Tₜ = √(Ti*Td)` which is realized by `Ni = √(Td / Ti)`. Anti-windup can be effectively turned off by setting `Ni = Inf`.
+- `Ti`: [s] Integrator time constant. Set to `false` to turn off integral action.
+- `Td`: [s] Derivative time constant. Set to `false` to turn off derivative action.
+- `wp`: [0,1] Set-point weighting in the proportional part.
+- `wd`: [0,1] Set-point weighting in the derivative part.
+- `Nd`: [1/s] Derivative limit, limits the derivative gain to Nd/Td. Reasonable values are ∈ [8, 20]. A higher value gives a better approximation of an ideal derivative at the expense of higher noise amplification.
+- `Ni`: `Ni*Ti` controls the time constant `Ta` of anti-windup tracking. A common (default) choice is `Ta = √(Ti*Td)` which is realized by `Ni = √(Td / Ti)`. Anti-windup can be effectively turned off by setting `Ni = Inf`.
 ` `gains`: If `gains = true`, `Ti` and `Td` will be interpreted as gains with a fundamental PID transfer function on parallel form `ki=Ti, kd=Td, k + ki/s + kd*s`
+
+# Connectors:
+- `reference`
+- `measurement`
+- `ctr_output`
 """
 function LimPID(; name, k=1, Ti=false, Td=false, wp=1, wd=1,
     Ni= Ti == 0 ? Inf : √(max(Td / Ti, 1e-6)),

src/Blocks/math.jl

@@ -5,6 +5,10 @@ Output the product of a gain value with the input signal.
 
 # Parameters:
 - `k`: Scalar gain
+
+# Connectors:
+- `input`
+- `output`
 """
 function Gain(k=1; name)
     @named siso = SISO()
@@ -23,6 +27,10 @@ Output the product of a gain matrix with the input signal vector.
 
 # Parameters:
 - `K`: Matrix gain
+
+# Connectors:
+- `input`
+- `output`
 """
 function MatrixGain(K::AbstractArray; name)
     nout, nin = size(K)
@@ -41,6 +49,10 @@ Output the sum of the elements of the input port vector.
 
 # Parameters:
 - `n`: Input port dimension
+
+# Connectors:
+- `input`
+- `output`
 """
 function Sum(n::Int; name)
     @named input = RealInput(;nin=n)
@@ -55,6 +67,11 @@ end
     Feedback(;name)
 
 Output difference between reference input (input1) and feedback input (input2).
+
+# Connectors:
+- `input1`
+- `input2`
+- `output`
 """
 function Feedback(;name)
     @named input1 = RealInput()
@@ -74,6 +91,11 @@ Output the sum of the two scalar inputs.
 # Parameters:
 - `k1`: Gain for first input
 - `k2`: Gain for second input
+
+# Connectors:
+- `input1`
+- `input2`
+- `output`
 """
 function Add(;name, k1=1, k2=1)
     @named input1 = RealInput()
@@ -98,6 +120,12 @@ Output the sum of the three scalar inputs.
 - `k1`: Gain for first input
 - `k2`: Gain for second input
 - `k3`: Gain for third input
+
+# Connectors:
+- `input1`
+- `input2`
+- `input3`
+- `output`
 """
 function Add3(;name, k1=1, k2=1, k3=1)
     @named input1 = RealInput()
@@ -119,6 +147,11 @@ end
     Product(;name)
 
 Output product of the two inputs.
+
+# Connectors:
+- `input1`
+- `input2`
+- `output`
 """
 function Product(;name)
     @named input1 = RealInput()
@@ -134,6 +167,11 @@ end
     Division(;name)
 
 Output first input divided by second input.
+
+# Connectors:
+- `input1`
+- `input2`
+- `output`
 """
 function Division(;name)
     @named input1 = RealInput()
@@ -152,6 +190,10 @@ end
 Applies the given function to the input. 
 
 If the given function is not composed of simple core methods (e.g. sin, abs, ...), it has to be registered via `@register_symbolic func(u)`
+
+# Connectors:
+- `input`
+- `output`
 """
 function StaticNonLinearity(func; name)
     @named siso = SISO()
@@ -164,69 +206,101 @@ end
     Abs(;name)
 
 Output the absolute value of the input.
+
+# Connectors:
+See [`StaticNonLinearity`](@ref)
 """
 Abs(;name) = StaticNonLinearity(abs; name)
 
 """
     Sign(;name)
 
 Output the sign of the input
+
+# Connectors:
+See [`StaticNonLinearity`](@ref)
 """
 Sign(;name) = StaticNonLinearity(sign; name)
 
 """
     Sqrt(;name)
 
 Output the square root of the input (input >= 0 required).
+
+# Connectors:
+See [`StaticNonLinearity`](@ref)
 """
 Sqrt(;name) = StaticNonLinearity(sqrt; name)
 
 """
     Sin(;name)
 
 Output the sine of the input.
+
+# Connectors:
+See [`StaticNonLinearity`](@ref)
 """
 Sin(;name) = StaticNonLinearity(sin; name)
 
 """
     Cos(;name)
 
 Output the cosine of the input.
+
+# Connectors:
+See [`StaticNonLinearity`](@ref)
 """
 Cos(;name) = StaticNonLinearity(cos; name)
 
 """
     Tan(;name)
 
 Output the tangent of the input.
+
+# Connectors:
+See [`StaticNonLinearity`](@ref)
 """
 Tan(;name) = StaticNonLinearity(tan; name)
 
 """
     Asin(;name)
 
 Output the arc sine of the input.
+
+# Connectors:
+See [`StaticNonLinearity`](@ref)
 """
 Asin(;name) = StaticNonLinearity(asin; name)
 
 """
     Acos(;name)
 
 Output the arc cosine of the input.
+
+# Connectors:
+See [`StaticNonLinearity`](@ref)
 """
 Acos(;name) = StaticNonLinearity(acos; name)
 
 """
     Atan(;name)
 
 Output the arc tangent of the input.
+
+# Connectors:
+See [`StaticNonLinearity`](@ref)
 """
 Atan(;name) = StaticNonLinearity(atan; name)
 
 """
     Atan2(;name)
 
 Output the arc tangent of the input.
+
+# Connectors:
+- `input1`
+- `input2`
+- `output`
 """
 function Atan2(;name)
     @named input1 = RealInput()
@@ -242,40 +316,58 @@ end
     Sinh(;name)
 
 Output the hyperbolic sine of the input.
+
+# Connectors:
+See [`StaticNonLinearity`](@ref)
 """
 Sinh(;name) = StaticNonLinearity(sinh; name)
 
 """
     Cosh(;name)
 
 Output the hyperbolic cosine of the input.
+
+# Connectors:
+See [`StaticNonLinearity`](@ref)
 """
 Cosh(;name) = StaticNonLinearity(cosh; name)
 
 """
     Tanh(;name)
 
 Output the hyperbolic tangent of the input.
+
+# Connectors:
+See [`StaticNonLinearity`](@ref)
 """
 Tanh(;name) = StaticNonLinearity(tanh; name)
 
 """
     Exp(;name)
 
 Output the exponential (base e) of the input.
+
+# Connectors:
+See [`StaticNonLinearity`](@ref)
 """
 Exp(;name) = StaticNonLinearity(exp; name)
 
 """
     Log(;name)
 
 Output the natural (base e) logarithm of the input.
+
+# Connectors:
+See [`StaticNonLinearity`](@ref)
 """
 Log(;name) = StaticNonLinearity(log; name)
 
 """
     Log10(;name)
 
 Output the base 10 logarithm of the input.
+
+# Connectors:
+See [`StaticNonLinearity`](@ref)
 """
 Log10(;name) = StaticNonLinearity(log10; name)