API Reference

kf, x_sym, ps, iosys, mats, prob = KalmanFilter(model::System, inputs, outputs; disturbance_inputs, Ts, R1, R2, x0map=[], pmap=[], σ0 = 1e-4, init=false, static=true, split = true, simplify=true, discretize = true, parametric = false, kwargs...)

Construct a Kalman filter for a linear MTK ODESystem. No check is performed to verify that the system is truly linear, if it is nonlinear, it will be linearized.

Returns:

• kf: A Kalman filter. If parametric=true, the A,B,C,D,R1,R2 fields are all functions of (x,u,p,t), otherwise they are matrices that are evaluated at the x0map, pmap values.
• x_sym: The symbolic state variables of the system.
• ps: The symbolic parameters of the system.
• iosys: The simplified MTK System
• mats: A named tuple containing the symbolic system matrices (A,B,C,D,Bw,Dw), where Bw and Dw are the input matrices corresponding to the disturbance inputs.
• prob: A StateEstimationProblem object. This problem object does not play quite the same role as when using Unscented or Extended Kalman filters since the filter is created already by this constructor, but the problem object can still be useful for inspecting the simplified MTK system, to create EstimatedOutput objects and to make use of the symbolic indexing functionality.

Arguments:

• model: An MTK System model, this model must not have undergone structural simplification.
• inputs: The inputs to the dynamical system, a vector of symbolic variables.
• outputs: The outputs of the dynamical system, a vector of symbolic variables.
• disturbance_inputs: The disturbance inputs to the dynamical system, a vector of symbolic variables. These disturbance inputs indicate where dynamics noise $w$ enters the system. The probability distribution with covariance $R_1$ is defined over these variables.
• Ts: The discretization time step.
• R1: The covariance matrix of the dynamics noise (disturbance inputs) $w$.
• R2: The covariance matrix of the measurement noise $e$.
• x0map: A dictionary mapping symbolic variables to their initial values. If a variable is not provided, it is assumed to be initialized to zero. The value can be a scalar number, in which case the covariance of the initial state is set to σ0^2*I(nx), and the value can be a Distributions.Normal, in which case the provided distributions are used as the distribution of the initial state. When passing distributions, all state variables must be provided values.
• pmap: A dictionary mapping symbolic variables to their values.
• σ0: The standard deviation of the initial state. This is used when x0map is not provided.
• init: If true, the initial state is computed using an initialization problem. If false, the initial state is computed using the get_u0 function.
• static: If true, static arrays are used for the state and covariance matrix. This can improve performance for small systems.
• split: Passed to mtkcompile, see the documentation there.
• simplify: Passed to mtkcompile, see the documentation there.
• discretize: If true, the system is discretized using zero-order hold. If false, matrices/functions are generated for the continuous-time system, in which case the user must handle discretization themselves (filtering with a continuous-time system without discretization will yield nonsensical results).
• parametric_A: If true, the A field of the returned filter is a function of (x,u,p,t), otherwise it is a matrix that is evaluated at the x0map, pmap values.
• parametric_B: If true, the B field of the returned filter is a function of (x,u,p,t), otherwise it is a matrix that is evaluated at the x0map, pmap values.
• parametric_C: If true, the C field of the returned filter is a function of (x,u,p,t), otherwise it is a matrix that is evaluated at the x0map, pmap values.
• parametric_D: If true, the D field of the returned filter is a function of (x,u,p,t), otherwise it is a matrix that is evaluated at the x0map, pmap values.
• parametric_R1: If true, the R1 field of the returned filter is a function of (x,u,p,t), otherwise it is a matrix that is evaluated at the x0map, pmap values.
• parametric_R2: If true, the R2 field of the returned filter is a function of (x,u,p,t), otherwise it is a matrix that is evaluated at the x0map, pmap values.
• tuplify: If true, the parameter vector p is returned as a tuple instead of an array. This can improve performance for filters with a small number of parameters of heterogeneous types.
• kwargs: Additional keyword arguments passed to mtkcompile.

EstimatedOutput(kf, prob, sym)

Create an output function that can be called like

g(x::Vector,    u, p, t)     # Compute an output
g(xR::MvNormal, u, p, t)     # Compute an output distribution given input distribution xR
g(kf,           u, p, t)     # Compute an output distribution given the current state of an AbstractKalmanFilter

Arguments:

• kf: A Kalman type filter
• prob: A StateEstimationProblem object
• sym: A symbolic expression or vector of symbolic expressions that the function should output.

StateEstimationProblem(model, inputs, outputs; disturbance_inputs, discretization, Ts, df, dg, x0map=[], pmap=[], init=false)

A structure representing a state-estimation problem.

Arguments:

• model: An MTK ODESystem model, this model must not have undergone structural simplification.
• inputs: The inputs to the dynamical system, a vector of symbolic variables that must be of type @variables.
• outputs: The outputs of the dynamical system, a vector of symbolic variables that must be of type @variables.
• disturbance_inputs: The disturbance inputs to the dynamical system, a vector of symbolic variables that must be of type @variables. These disturbance inputs indicate where dynamics noise $w$ enters the system. The probability distribution $d_f$ is defined over these variables.
• discretization: A function discretization(f_cont, Ts, x_inds, alg_inds, nu) = f_disc that takes a continuous-time dynamics function f_cont(x,u,p,t) and returns a discrete-time dynamics function f_disc(x,u,p,t). x_inds is the indices of differential state variables, alg_inds is the indices of algebraic variables, and nu is the number of inputs.
• Ts: The discretization time step.
• df: The probability distribution of the dynamics noise $w$. When using Kalman-type estimators, this must be a MvNormal or SimpleMvNormal distribution.
• dg: The probability distribution of the measurement noise $e$. When using Kalman-type estimators, this must be a MvNormal or SimpleMvNormal distribution.
• x0map: A dictionary mapping symbolic variables to their initial values. If a variable is not provided, it is assumed to be initialized to zero. The value can be a scalar number, in which case the covariance of the initial state is set to σ0^2*I(nx), and the value can be a Distributions.Normal, in which case the provided distributions are used as the distribution of the initial state. When passing distributions, all state variables must be provided values.
• σ0: The standard deviation of the initial state. This is used when x0map is not provided or when the values in x0map are scalars.
• pmap: A dictionary mapping symbolic variables to their values. If a variable is not provided, it is assumed to be initialized to zero.
• init: If true, the initial state is computed using an initialization problem. If false, the initial state is computed using the get_u0 function.
• xscalemap: A dictionary mapping state variables to scaling factors. This is used to scale the state variables during integration to improve numerical stability. If a variable is not provided, it is assumed to have a scaling factor of 1.0. If provided, discretization is a function with signature discretization(f_cont, Ts, x_inds, alg_inds, nu, scale_x) where scale_x is a vector of scaling factors for the state variables.

Usage:

Pseudocode

prob      = StateEstimationProblem(...)
kf        = get_filter(prob, ExtendedKalmanFilter)      # or UnscentedKalmanFilter
filtersol = forward_trajectory(kf, u, y)
sol       = StateEstimationSolution(filtersol, prob)   # Package into higher-level solution object
plot(sol, idxs=[prob.state; prob.outputs; prob.inputs]) # Plot the solution

StateEstimationSolution(kfsol, prob)

A solution object that provides symbolic indexing to a KalmanFilteringSolution object.

Fields:

• sol: a KalmanFilteringSolution object.
• prob: a StateEstimationProblem object.

Example

sol = StateEstimationSolution(kfsol, prob)
sol[model.x]                 # Index with a variable
sol[model.y^2]               # Index with an expression
sol[model.y^2, dist=true]    # Obtain the posterior probability distribution of the provided expression
sol[model.y^2, Nsamples=100] # Draw 100 samples from the posterior distribution of the provided expression

get_filter(prob::StateEstimationProblem, ::Type{ExtendedKalmanFilter}; constant_R1=true, kwargs)
get_filter(prob::StateEstimationProblem, ::Type{UnscentedKalmanFilter}; kwargs)

Instantiate a filter from a state-estimation problem. kwargs are sent to the filter constructor.

If constant_R1=true, the dynamics noise covariance matrix R1 is assumed to be constant and is computed at the initial state. Otherwise, R1 is computed at each time step throug repeated linearization w.r.t. the disturbance inputs w.

propagate_distribution(f, kf, dist, args...; kwargs...)

Propagate a probability distribution dist through a nonlinear function f using the covariance-propagation method of filter kf.

Arguments:

• f: A nonlinear function f(x, args...; kwargs...) that takes a vector x and returns a vector.
• kf: A state estimator, such as an ExtendedKalmanFilter or UnscentedKalmanFilter.
• dist: A probability distribution, such as a MvNormal or SimpleMvNormal.
• args: Additional arguments to f.
• kwargs: Additional keyword arguments to f.