Engine & Interface | An Uncommon Lab

Nomenclature

When talking about filters, things can become verbose very quickly, so to keep it simple, let's establish some shorthand for the various ideas. We'll say things like observation function or even just $h$ and hope folks know what we're referring to, or we might just use the symbol $Q_{k-1}$ or Q_km1 so we don't constantly have to say, “discrete process noise covariance matrix associated with sample k-1”. We've tried to agree with common industry terms, so hopefully this all will seem pretty familiar.

Problem Definition

First, let's lay out the problem to be solved in generic terms. Let there be some vector of things we'd like to know, $x$, and let $x$ evolve from time, $t$, to $t + \Delta t$ as:

$$x(t+\Delta t) = f(t, x(t), q(t))$$

That is, $x$ is the state, and $f$ is the dynamics function. The state can consist of almost anything, from the pressure and temperature outside a house to the growth rate of fan corals. It might change quickly over time or not at all, and we might know how it changes very accurate or fairly poorly. Also, $q$ in the statement above represents process noise; it's a random variable. There's no need to make assumptions about its distribution at this point, but this variable allows us to acknowledge that our model of the dynamics isn't perfect.

Every so often, we'll get some data, such as how “high in the water” an inflated ball is floating in a pond, or how many pixels of an image of fan corals in shallow water appear “corally”. Neither does the ball tell us the pressure and temperature, nor does the number of corally pixels tell us growth rate, nor can we measure either without some noise, but they both provide some information. We'll call these bits of information measurements. Let the observation function be $h$ and the observation vector (the collection of all current observations) be $z$:

$$z(t) = h(t, x(t), r(t))$$

Similar to the process noise, $r$ is also a random variable, this one representing measurement noise.

By coupling the right observations with a notion of the dynamics, we can learn about the hidden states over time, and this process is called state estimation. When parts of the state do not change over time, those are called parameters. We will generally refer to state estimation as implying both state and parameter estimation.

Variable Shorthand

Next, let's set out a list of commonly used shorthand in this documentation. These will be actual variable names in the generated code and are used to describe various interfaces. It's important that we get these right, but there's no need to memorize them. They're pretty common and fairly intuitive. Plus, you can always come back and check this page when you need to.

The filters operate to update information from sample k-1 to sample k as measurements become available at sample k. A suffix of _k refers to sample k and _km1 refers to k-1. (Really, “sample k-1” refers to prior information and need not be from a different time at all. Likewise, “sample k” refers to posterior information.)

The most common variables are marked darkly.

`C_k`	output	Lower Cholesky factor at sample k, used as a square-root form of the covariance in unscented Kalman filters. The covariance is related to the Cholesky factor as \|P_k = C_k * C_k.'\|.
`C_km1`	input	Lower Cholesky factor at sample k-1, used as a square-root form of the covariance in unscented Kalman filters. The covariance is related to the Cholesky factor as \|P_km1 = C_km1 * C_km1.'\|.
`c_k c_km1`	-	Consider parameters at sample k. These are used explicity in unscented Kalman filters and in any simulation built for a filter that uses consider covariance.
`constants`	input	Set of filter constants set with the initialization function.
`d_k`	output	Diagonal elements of D part of UDU decomposition of covariance at sample k. (When using consider covariance, this will include the state-consider covariance and will be `nx+nc` by 1.)
`d_km1`	input	Diagonal elements of D part of UDU decomposition of covariance at sample k-1. (When using consider covariance, this will include the state-consider covariance and will be `nx+nc` by 1.)
`F_km1`	-	State transition matrix (Jacobian of propagation function wrt the state) at sample k-1. May be a constant, an input, or the result of a function of information available at sample k-1.
`F_c_km1`	-	Jacobian of propagation function wrt the consider parameters) at sample k-1. May be a constant, an input, or the result of a function of information available at sample k-1.
`F_u_km1`	-	Jacobian of propagation function wrt the input vector at sample k-1. May be a constant, an input, or the result of a function of information available at sample k-1.
`f`	function	Propagation function, operating something like: `x_k = f(t_km1, t_k, x_km1, u_km1);` The interface will depend on the filter options and will be available in the Interfaces box.
`H_k`	-	Observation or sensitivity matrix (Jacobian of observation function wrt the state) at sample k. May be a constant, an input, or the result of a function of information available at sample k-1.
`H_c_k`	-	Jacobian of observation function wrt the consider parameters at sample k. May be a constant, an input, or the result of a function of information available at sample k-1.
`H_u_k`	-	Jacobian of observation function wrt the input vector at sample k. May be a constant, an input, or the result of a function of information available at sample k-1.
`h`	function	Observation function, operating something like: `z_k = h(t_k, x_k);` The interface will depend on the filter options and will be available in the Interfaces box.
`nc`	-	Dimension of consider parameters
`nq`	-	Dimension of process noise vector
`nr`	-	Dimension of measurement noise vector
`nu`	-	Dimension of input vector
`nX`	-	Number of particles
`nx`	-	Dimension of state
`nz`	-	Dimension of measurement vector
`P_cc`	input	Consider covariance
`P_k`	output	Estimate covariance sample k conditioned on information from k
`P_km1`	input	Estimate covariance sample k-1 conditioned on information from k-1
`P_xc_k`	output	Covariance of the estimate and consider parameters at sample k
`P_xc_km1`	input	Covariance of the estimate and consider parameters at sample k-1
`P_zz_k`	output	Covariance of the innovation vector at sample k
`Q_km1`	-	Process noise covariance at sample k-1. May be a constant, an input, or the result of a function of information available at sample k-1.
`q_km1`	-	Process noise draws at sample k-1 (used in unscented filters, particle filters, and simulations)
`R_k`	-	Measurement noise covariance at sample k. May be a constant, an input, or the result of a function of information available at sample k-1.
`r_k`	-	Measurement noise draws at sample k (used in unscented filters and simulations)
`t_k t_km1`	input	Time at sample k and k-1
`U_k`	output	U part of UDU decomposition of covariance at sample k. (When using consider covariance, this will include the state-consider covariance and will be `nx+nc` by `nx+nc`.)
`U_km1`	input	U part of UDU decomposition of covariance at sample k-1. (When using consider covariance, this will include the state-consider covariance and will be `nx+nc` by `nx+nc`.)
`u_km1`	input	Input vector at sample k-1. In general, the input vector for sample k is not considered to be known at the time of processing the kth sample. For this reason, the measurement can be a function of `u_km1` but not `u_k`. If `u_k` is available, it may be passed in as one of the “user variables”.
`updates`	input	A vector of booleans specifying which sensors have been updated; see the options for sequential updates and for sensor groups.
`X_k`	output	Set of particles at sample k (used in particle filters)
`x_k`	output	State estimate at sample k conditioned on information from k
`x_kkm1`	input	Predicted state estimate at sample k conditioned on information from k-1
`X_km1`	input	Set of particles at sample k-1 (used in particle filters)
`x_km1`	input	State estimate at sample k-1
`Y_k`	output	Information matrix at sample k; may have null space corresponding to a lack of information regarding the state. (When using consider covariance, this will be the information matrix for the augmented system that contains both the state estimate and consider parameters and will be (nx+nc)-by-(nx+nc).)
`y_k`	input/output	Innovation vector (measurement minus predicted measurement)
`Y_km1`	output	Information matrix at sample k-1; may have null space corresponding to a lack of information regarding the state. (When using consider covariance, this will be the information matrix for the augmented system that contains both the state estimate and consider parameters and will be (nx+nc)-by-(nx+nc).)
`z_hat_kkm1`	input	Predicted measurement vector at sample k conditioned on information from k-1
`z_k`	input	Measurement vector at sample k

Next Steps

Now that we can agree about how to talk about the filters, let's talk about how we can determine the right filter type to use or the right way to design and test them so that we can be sure we can trust them and deploy them quickly. We refer to this as the filter workflow.

Problem Definition
Variable Shorthand
Next Steps

Docs

Nomenclature

Problem Definition

Variable Shorthand

Next Steps

Table of Contents