Engee documentation

Functions: Plant Models

The SimModel types represents discrete state-space models that can be used to construct StateEstimators and PredictiveControllers, or as plant simulators by calling evaloutput and updatestate! methods on SimModel instances (to test estimator/controller designs). For time simulations, the states x are stored inside SimModel instances. Use setstate! method to manually modify them.

SimModel

Abstract supertype of LinModel and NonLinModel types.


(model::SimModel)(d=[]) -> y

Functor allowing callable SimModel object as an alias for evaloutput.

Examples

julia> model = NonLinModel((x,u,_)->-x + u, (x,_)->x .+ 20, 10.0, 1, 1, 1);

julia> y = model()
1-element Vector{Float64}:
 20.0

LinModel

LinModel(sys::StateSpace[, Ts]; i_u=1:size(sys,2), i_d=Int[])

Construct a linear model from state-space model sys with sampling time Ts in second.

Ts can be omitted when sys is discrete-time. Its state-space matrices are:

with the state and output vectors. The vector comprises the manipulated inputs and measured disturbances , in any order. i_u provides the indices of that are manipulated, and i_d, the measured disturbances. See Extended Help if sys is continuous-time, or discrete-time with Ts ≠ sys.Ts.

See also ss, tf.

Examples

julia> model = LinModel(ss(0.4, 0.2, 0.3, 0, 0.1))
Discrete-time linear model with a sample time Ts = 0.1 s and:
 1 manipulated inputs u
 1 states x
 1 outputs y
 0 measured disturbances d

Extended Help

State-space matrices are similar if sys is continuous (replace with and with on the LHS). In such a case, it’s discretized with c2d and :zoh for manipulated inputs, and :tustin, for measured disturbances. Lastly, if sys is discrete and the provided argument Ts ≠ sys.Ts, the system is resampled by using the aforementioned discretization methods.

Note that the constructor transforms the system to its minimal realization using minreal for controllability/observability. As a consequence, the final state-space representation may be different from the one provided in sys. It is also converted into a more practical form ( because of the zero-order hold):

Use the syntax LinModel{NT}(A, Bu, C, Bd, Dd, Ts) to force a specific state-space representation.

LinModel(sys::TransferFunction[, Ts]; i_u=1:size(sys,2), i_d=Int[])

Convert to minimal realization state-space when sys is a transfer function.

sys is equal to for continuous-time, and , for discrete-time.

Examples

julia> model = LinModel([tf(3, [30, 1]) tf(-2, [5, 1])], 0.5, i_d=[2])
Discrete-time linear model with a sample time Ts = 0.5 s and:
 1 manipulated inputs u
 2 states x
 1 outputs y
 1 measured disturbances d
LinModel(sys::DelayLtiSystem, Ts; i_u=1:size(sys,2), i_d=Int[])

Discretize with zero-order hold when sys is a continuous system with delays.

The delays must be multiples of the sample time Ts.

LinModel{NT}(A, Bu, C, Bd, Dd, Ts)

Construct the model from the discrete state-space matrices A, Bu, C, Bd, Dd directly.

This syntax do not modify the state-space representation provided in argument (minreal is not called). Care must be taken to ensure that the model is controllable and observable. The optional parameter NT explicitly specifies the number type of the matrices.

LinModel(model::NonLinModel; x=model.x, u=model.uop, d=model.dop)

Call linearize(model; x, u, d) and return the resulting linear model.

NonLinModel

NonLinModel{NT}(f::Function, h::Function, Ts, nu, nx, ny, nd=0)

Construct a nonlinear model from discrete-time state-space functions f and h.

The state update and output functions are defined as :

Ts is the sampling time in second. nu, nx, ny and nd are the respective number of manipulated inputs, states, outputs and measured disturbances. The optional parameter NT explicitly specifies the number type of vectors (default to Float64).

Replace the d argument with _ if nd = 0 (see Examples below).

Nonlinear continuous-time state-space functions are not supported for now. In such a case, manually call a differential equation solver in f (see Manual).

f and h must be pure Julia functions to use the model in NonLinMPC, ExtendedKalmanFilter, MovingHorizonEstimator and linearize.

See also LinModel.

Examples

julia> model = NonLinModel((x,u,_)->0.1x+u, (x,_)->2x, 10.0, 1, 1, 1)
Discrete-time nonlinear model with a sample time Ts = 10.0 s and:
 1 manipulated inputs u
 1 states x
 1 outputs y
 0 measured disturbances d

Set Operating Points

setop!(model::SimModel; uop=nothing, yop=nothing, dop=nothing) -> model

Set model inputs uop, outputs yop and measured disturbances dop operating points.

The state-space model with operating points (a.k.a. nominal values) is:

in which the uop, yop and dop vectors evaluate:

The structure is similar if model is a NonLinModel:

Examples

julia> model = setop!(LinModel(tf(3, [10, 1]), 2.0), uop=[50], yop=[20])
Discrete-time linear model with a sample time Ts = 2.0 s and:
 1 manipulated inputs u
 1 states x
 1 outputs y
 0 measured disturbances d

Linearize

linearize(model::NonLinModel; x=model.x, u=model.uop, d=model.dop) -> linmodel

Linearize model at the operating points x, u, d and return the LinModel.

The arguments x, u and d are the linearization points for the state , manipulated input and measured disturbance , respectively. The Jacobians of and functions are automatically computed with ForwardDiff.jl.

See Extended Help if you get an error like: MethodError: no method matching (::var"##")(::Vector{ForwardDiff.Dual}).

Examples

julia> model = NonLinModel((x,u,_)->x.^3 + u, (x,_)->x, 0.1, 1, 1, 1);

julia> linmodel = linearize(model, x=[10.0], u=[0.0]);

julia> linmodel.A
1×1 Matrix{Float64}:
 300.0

Extended Help

Automatic differentiation (AD) allows exact Jacobians. The NonLinModel f and h functions must be compatible with this feature though. See Automatic differentiation for common mistakes when writing these functions.