API Reference

The module Blocks contains common input-output components, referred to as blocks.

Abs(; name)

Output the absolute value of the input.

Connectors:

See StaticNonLinearity

Acos(; name)

Output the arc cosine of the input.

Connectors:

See StaticNonLinearity

Add(; name, k1 = 1.0, k2 = 1.0)

Output the sum of the two scalar inputs.

Parameters:

• k1: Gain for first input
• k2: Gain for second input

Connectors:

• input1
• input2
• output

Add(; name, k1 = 1.0, k2 = 1.0, k3 = 1.0)

Output the sum of the three scalar inputs.

Parameters:

• k1: Gain for first input
• k2: Gain for second input
• k3: Gain for third input

Connectors:

• input1
• input2
• input3
• output

Asin(; name)

Output the arc sine of the input.

Connectors:

See StaticNonLinearity

Atan(; name)

Output the arc tangent of the input.

Connectors:

See StaticNonLinearity

Atan2(; name)

Output the arc tangent of the input.

Connectors:

• input1
• input2
• output

Ceil(; name)

Output the ceiling rounding of the input.

Connectors:

• input
• output

Constant(; name, k = 0.0)

Generate constant signal.

Parameters:

• k: Constant output value

Connectors:

• output

ContinuousClock(; name, offset = 0, start_time = 0)

Generate current time signal.

Parameters:

• offset: Offset of output signal
• start_time: [s] Output y = offset for t < start_time

Connectors:

• output

Cos(; name)

Output the cosine of the input.

Connectors:

See StaticNonLinearity

Cosh(; name)

Output the hyperbolic cosine of the input.

Connectors:

See StaticNonLinearity

Cosine(; name, frequency, amplitude = 1, phase = 0, offset = 0, start_time = 0,
smooth = false)

Generate cosine signal.

Parameters:

• frequency: [Hz] Frequency of cosine wave
• amplitude: Amplitude of cosine wave
• phase: [rad] Phase of cosine wave
• offset: Offset of output signal
• start_time: [s] Output y = offset for t < start_time
• smooth: If true, returns a smooth wave. Defaults to false It uses a default smoothing factor of δ=1e-5, but this can be changed by supplying smooth=δ.

Connectors:

• output

DeadZone(; name, u_max, u_min = -u_max)

The DeadZone block defines a region of zero output. If the input is within u_min ... u_max, the output is zero. Outside of this zone, the output is a linear function of the input with a slope of 1.

       y▲
        │     /
        │    /
  u_min │   /
─────|──┼──|───────► u
    /   │   u_max
   /    │
  /     │

Parameters:

• u_max: Upper limit of dead zone
• u_min: Lower limit of dead zone

Connectors:

• input
• output

Derivative(; name, k = 1, T, x = 0.0)

Outputs an approximate derivative of the input. The transfer function of this block is

k      k        ks
─ - ─────── = ──────
T   sT² + T   sT + 1

and a state-space realization is given by ss(-1/T, 1/T, -k/T, k/T) where T is the time constant of the filter. A smaller T leads to a more ideal approximation of the derivative.

Initial value of the state $x$ can be set with x.

Parameters:

• k: Gain
• T: [s] Time constant (T>0 required; T=0 is ideal derivative block)

Unknowns:

• x: Unknown of Derivative. Defaults to 0.0.

Connectors:

• input
• output

Division(; name)

Output first input divided by second input.

Connectors:

• input1
• input2
• output

Exp(; name)

Output the exponential (base e) of the input.

Connectors:

See StaticNonLinearity

ExpSine(; name, frequency, amplitude = 1, damping = 0.1, phase = 0, offset = 0, start_time = 0, smooth = false)

Exponentially damped sine signal.

Parameters:

• frequency: [Hz] Frequency of sine wave
• amplitude: Amplitude of sine wave
• damping: [1/s] Damping coefficient of sine wave
• phase: [rad] Phase of sine wave
• offset: Offset of output signal
• start_time: [s] Output y = offset for t < start_time
• smooth: If true, returns a smooth wave. Defaults to false It uses a default smoothing factor of δ=1e-5, but this can be changed by supplying smooth=δ.

Connectors:

• output

Feedback(; name)

Output difference between reference input (input1) and feedback input (input2).

Connectors:

• input1
• input2
• output

FirstOrder(; name, k = 1.0, T, x = 0.0, lowpass = true)

A first-order filter with a single real pole at s = -1/T and gain k. If lowpass=true (default), the transfer function is given by $Y(s)/U(s) =$

   k
───────
sT + 1

and if lowpass=false, by

sT + 1 - k
──────────
  sT + 1

Initial value of the state x can be set with x

Parameters:

• k: Gain
• T: [s] Time constant (T>0 required)

Connectors:

• input
• output

See also SecondOrder

Floor(; name)

Output the floor rounding of the input.

Connectors:

• input
• output

Gain(; name, k)

Output the product of a gain value with the input signal.

Parameters:

• k: Scalar gain

Connectors:

• input
• output

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:

• input
• output

Parameters:

• k: Gain of integrator

Unknowns:

• x: State of Integrator. Defaults to 0.0.

Interpolation(interp_type, u, x, args...; name)

Represent function interpolation symbolically as a block component. By default interpolation types from DataInterpolations.jl are supported, but in general any callable type that builds the interpolation object via itp = interpolation_type(u, x, args...) and calls the interpolation with itp(t) should work. This does not need to represent an interpolation, it can be any type that satisfies the interface, such as lookup tables.

Arguments:

• interp_type: the type of the interpolation. For DataInterpolations,

these would be any of the available interpolations, such as LinearInterpolation, ConstantInterpolation or CubicSpline.

• u: the data used for interpolation. For DataInterpolations this will be an AbstractVector
• x: the values that each data points correspond to, usually the times corresponding to each value in u.
• args: any other arguments needed to build the interpolation

Keyword arguments:

• name: the name of the component

Parameters:

• interpolator: the symbolic representation of the interpolation object, callable as interpolator(t)

Connectors:

• input: a RealInput connector corresponding to the input variable
• output: a RealOutput connector corresponding to the interpolated value

LimPI(; name, k = 1.0, T, Ta, int__x = 0.0, u_max = 1.0, u_min = -u_max)

Text-book version of a PI-controller with actuator saturation and anti-windup measure.

The PI controller is implemented on standard form

\[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
• T: [s] Integrator time constant (T>0 required)
• Ta: [s] Tracking time constant (Ta>0 required)

Connectors:

• err_input
• ctr_output

LimPID(; k, Ti=false, Td=false, wp=1, wd=1, Ni, Nd=12, u_max=Inf, u_min=-u_max, gains = false, name)

Proportional-Integral-Derivative (PID) controller with output saturation, set-point weighting and integrator anti-windup.

The equation for the control signal is roughly

k(ep + 1/Ti * ∫e + Td * d/dt(ed))
e = u_r - u_y
ep = wp*u_r - u_y
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: [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

Limiter(;name, y_max, y_min = y_max > 0 ? -y_max : -Inf)

Limit the range of a signal.

Parameters:

• y_max: Maximum of output signal
• y_min: Minimum of output signal

Connectors:

• input
• output

Log(; name)

Output the natural (base e) logarithm of the input.

Connectors:

See StaticNonLinearity

Log10(; name)

Output the base 10 logarithm of the input.

Connectors:

See StaticNonLinearity

MatrixGain(; K::AbstractArray, name)

Output the product of a gain matrix with the input signal vector.

Structural parameters:

• K: Matrix gain

Connectors:

• input
• output

Modulo(; name)

Output the remainder when the first input is divided by second input.

Connectors:

• dividend
• divisor
• remainder

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 k Initial value of integrator state x can be set with int.x

The PI controller is implemented on standard form:

\[U(s) = k (1 + \dfrac{1}{sT}) E(S)\]

Parameters:

• k: Proportional gain
• T: [s] Integrator time constant (T>0 required)

Connectors:

• err_input
• ctr_output

See also LimPI

PID(;name, k=1, Ti=false, Td=false, Nd=10, int__x=0, der__x=0)

Text-book version of a PID-controller without actuator saturation and anti-windup measure.

Parameters:

• k: Gain
• Ti: [s] Integrator time constant (Ti>0 required). If set to false, no integral action is used.
• Td: [s] Derivative time constant (Td>0 required). If set to false, no derivative action is used.
• Nd: [s] Maximum derivative gain (inverse of filter time constant, Nd>0 required; Nd=0 is ideal derivative).
• int__x: Initial value for the integrator.
• der__x: Initial value for the derivative state.

Connectors:

• err_input
• ctr_output

See also LimPID

ParametrizedInterpolation(interp_type, u, x, args...; name, t = ModelingToolkitBase.t_nounits)

Represent function interpolation symbolically as a block component, with the interpolation data represented parametrically. By default interpolation types from DataInterpolations.jl are supported, but in general any callable type that builds the interpolation object via itp = interpolation_type(u, x, args...) and calls the interpolation with itp(t) should work. This does not need to represent an interpolation, it can be any type that satisfies the interface, such as lookup tables.

Arguments:

• interp_type: the type of the interpolation. For DataInterpolations,

these would be any of the available interpolations, such as LinearInterpolation, ConstantInterpolation or CubicSpline.

• u: the data used for interpolation. For DataInterpolations this will be an AbstractVector
• x: the values that each data points correspond to, usually the times corresponding to each value in u.
• args: any other arguments beeded to build the interpolation

Keyword arguments:

• name: the name of the component

Parameters:

• data: the symbolic representation of the data passed at construction time via u.
• ts: the symbolic representation of times corresponding to the data passed at construction time via x.

Connectors:

• input: a RealInput connector corresponding to the independent variable
• output: a RealOutput connector corresponding to the interpolated value

Power(; name)

Output the exponential with base as the first input and exponent as second input i.e u1^u2

Connectors:

• base
• exponent
• output

Product(; name)

Output product of the two inputs.

Connectors:

• input1
• input2
• output

Ramp(; name, height = 1, duration = 1, offset = 0, start_time = 0, smooth = false)

Generate ramp signal.

Parameters:

• height: Height of ramp
• duration: [s] Duration of ramp (= 0.0 gives a Step)
• offset: Offset of output signal
• start_time: [s] Output y = offset for t < start_time
• smooth: If true, returns a smooth wave. Defaults to false It uses a default smoothing factor of δ=1e-5, but this can be changed by supplying smooth=δ.

Connectors:

• output

RealInput(; name, guess)

Connector with one input signal of type Real.

Parameters:

• guess=0: Guess value for u.

States:

• u: Value of the connector which is a scalar.

RealInputArray(; name, nin, guess)

Connector with an array of input signals of type Real.

Parameters:

• nin: Number of inputs.
• guess=zeros(nin): Guess value for u.

States:

• u: Value of the connector which is an array.

RealOutput(; name, guess)

Connector with one output signal of type Real.

Parameters:

• guess=0: Guess value for u.

States:

• u: Value of the connector which is a scalar.

RealOutputArray(; name, nout, guess)

Connector with an array of output signals of type Real.

Parameters:

• nout: Number of outputs.
• guess=zeros(nout): Guess value for u.

States:

• u: Value of the connector which is an array.

SISO(;name, u_start = 0.0, y_start = 0.0)

Single input single output (SISO) continuous system block.

Parameters:

• u_start: Initial value for the input
• y_start: Initial value for the output

SampledData(; name, buffer)

data input component.

Parameters:

• buffer: a Parameter type which holds the data and sample time

Connectors:

• output

SampledData(; name, buffer, sample_time, circular_buffer=true)

data input component.

Parameters:

• buffer::Vector{Real}: holds the data sampled at sample_time
• sample_time::Real
• circular_buffer::Bool = true: how to handle t > length(buffer)*sample_time. If true data is considered circular, otherwise last data point is held.

Connectors:

• output

SecondOrder(; name, k = 1.0, w = 1.0, d = 1.0, 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) =

      k*w^2
─────────────────
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

Connectors:

• input
• output

Sign(; name)

Output the sign of the input

Connectors:

See StaticNonLinearity

Sin(; name)

Output the sine of the input.

Connectors:

See StaticNonLinearity

Sine(; name, frequency, amplitude = 1, phase = 0, offset = 0, start_time = 0,
smooth = false)

Generate sine signal.

Parameters:

• frequency: [Hz] Frequency of sine wave
• amplitude: Amplitude of sine wave
• phase: [rad] Phase of sine wave
• offset: Offset of output signal
• start_time: [s] Output y = offset for t < start_time
• smooth: If true, returns a smooth wave. Defaults to false It uses a default smoothing factor of δ=1e-5, but this can be changed by supplying smooth=δ.

Connectors:

• output

Sinh(; name)

Output the hyperbolic sine of the input.

Connectors:

See StaticNonLinearity

SlewRateLimiter(; name, y_start, rising = 1.0, falling = -rising, Td = 0.001)

Limits the slew rate of a signal. Initial value of state Y can be set with int.y

Parameters:

• rising: Maximum rising slew rate
• falling: Maximum falling slew rate
• Td: [s] Derivative time constant
• y_start: Initial value of y state of SISO

Connectors:

• input
• output

Sqrt(; name)

Output the square root of the input (input >= 0 required).

Connectors:

See StaticNonLinearity

Square(; name, frequency = 1.0, amplitude = 1.0, offset = 0.0, start_time = 0.0,
smooth = false)

Generate smooth square signal.

Parameters:

• frequency: [Hz] Frequency of square wave
• amplitude: Amplitude of square wave
• offset: Offset of output signal
• start_time: [s] Output y = offset for t < start_time
• smooth: If true, returns a smooth wave. Defaults to false It uses a default smoothing factor of δ=1e-5, but this can be changed by supplying smooth=δ.

Connectors:

• output

StateSpace(A, B, C, D = 0; x = zeros(size(A,1)), u0 = zeros(size(B,2)), y0 = zeros(size(C,1)), name)

A linear, time-invariant state-space system on the form.

\[\begin{aligned} ẋ &= Ax + Bu \\ y &= Cx + Du \end{aligned}\]

Transfer functions can also be simulated by converting them to a StateSpace form.

y0 and u0 can be used to set an operating point, providing them changes the dynamics from an LTI system to the affine system

\[\begin{aligned} ẋ &= Ax + B(u - u0) \\ y &= Cx + D(u - u0) + y0 \end{aligned}\]

For a nonlinear system

\[\begin{aligned} ẋ &= f(x, u) \\ y &= h(x, u) \end{aligned}\]

linearized around the operating point x₀, u₀, we have y0, u0 = h(x₀, u₀), u₀.

Step(;name, height=1, offset=0, start_time=0, duration=Inf, smooth=true)

Generate step signal.

Parameters:

• height: Height of step
• offset: Offset of output signal
• start_time: [s] Output y = offset for t < start_time and thereafter offset+height.
• duration: [s] If duration < Inf is supplied, the output will revert to offset after duration seconds.
• smooth: If true, returns a smooth wave. Defaults to true It uses a default smoothing factor of δ=1e-5, but this can be changed by supplying smooth=δ.

Connectors:

• output

Sum(; input__nin::Int, name)

Output the sum of the elements of the input port vector. Input port dimension can be set with input__nin

Connectors:

• input
• output

Tan(; name)

Output the tangent of the input.

Connectors:

See StaticNonLinearity

Tanh(; name)

Output the hyperbolic tangent of the input.

Connectors:

See StaticNonLinearity

TimeVaryingFunction(f; name)

Outputs $f(t)$.

The input variable t can be changed by passing a different variable as the keyword argument t.

Connectors:

• output

TransferFunction(; b, a, name)

A single input, single output, linear time-invariant system provided as a transfer-function.

Y(s) = b(s) / a(s)  U(s)

where b and a are vectors of coefficients of the numerator and denominator polynomials, respectively, ordered such that the coefficient of the highest power of s is first.

The internal state realization is on controller canonical form, with state variable x, output variable y and input variable u. For numerical robustness, the realization used by the integrator is scaled by the last entry of the a parameter. The internally scaled state variable is available as x_scaled.

To set the initial state, it's recommended to set the initial condition for x, and let that of x_scaled be computed automatically.

Parameters:

• b: Numerator polynomial coefficients, e.g., 2s + 3 is specified as [2, 3]
• a: Denominator polynomial coefficients, e.g., s² + 2ωs + ω^2 is specified as [1, 2ω, ω^2]

Connectors:

• input
• output

See also StateSpace which handles MIMO systems, as well as ControlSystemsMTK.jl for an interface between ControlSystems.jl and ModelingToolkitBase.jl for advanced manipulation of transfer functions and linear statespace systems. For linearization, see ModelingToolkit.linearize and Linear Analysis.

Triangular(; name, amplitude = 1.0, frequency = 1.0, offset = 0.0,
start_time = 0.0, smooth = false)

Generate smooth triangular signal for frequencies less than or equal to 25 Hz

Parameters:

• frequency: [Hz] Frequency of square wave
• amplitude: Amplitude of square wave
• offset: Offset of output signal.
• start_time: [s] Output y = offset for t < start_time
• smooth: If true, returns a smooth wave. Defaults to false It uses a default smoothing factor of δ=1e-5, but this can be changed by supplying smooth=δ.

Connectors:

• output

UnaryMinus(; name)

Output the product of -1 and the input.

Connectors:

• input
• output