# common¶

A collection of functions used throughout FilterPy, and/or functions that you will find useful when you build your filters.

Copyright 2015 Roger R Labbe Jr.

FilterPy library. http://github.com/rlabbe/filterpy

Supporting book at: https://github.com/rlabbe/Kalman-and-Bayesian-Filters-in-Python

filterpy.common.Q_discrete_white_noise(dim, dt=1.0, var=1.0)[source]

Returns the Q matrix for the Discrete Constant White Noise Model. dim may be either 2 or 3, dt is the time step, and sigma is the variance in the noise.

Q is computed as the G * G^T * variance, where G is the process noise per time step. In other words, G = [[.5dt^2][dt]]^T for the constant velocity model.

Parameters: dim : int (2 or 3) dimension for Q, where the final dimension is (dim x dim) dt : float, default=1.0 time step in whatever units your filter is using for time. i.e. the amount of time between innovations var : float, default=1.0 variance in the noise

References

Bar-Shalom. “Estimation with Applications To Tracking and Navigation”. John Wiley & Sons, 2001. Page 274.

filterpy.common.Q_continuous_white_noise(dim, dt=1.0, spectral_density=1.0)[source]

Returns the Q matrix for the Discretized Continuous White Noise Model. dim may be either 2 or 3, dt is the time step, and sigma is the variance in the noise.

Parameters: dim : int (2 or 3) dimension for Q, where the final dimension is (dim x dim) dt : float, default=1.0 time step in whatever units your filter is using for time. i.e. the amount of time between innovations spectral_density : float, default=1.0 spectral density for the continuous process

filterpy.common.van_loan_discretization(F, G, dt)[source]

Discretizes a linear differential equation which includes white noise according to the method of C. F. van Loan [1]. Given the continuous model

x’ = Fx + Gu

where u is the unity white noise, we compute and return the sigma and Q_k that discretizes that equation.

References

[1] C. F. van Loan. “Computing Integrals Involving the Matrix Exponential.”
IEEE Trans. Automomatic Control, AC-23 (3): 395-404 (June 1978)
[2] Robert Grover Brown. “Introduction to Random Signals and Applied
Kalman Filtering.” Forth edition. John Wiley & Sons. p. 126-7. (2012)

Examples

Given y’’ + y = 2u(t), we create the continuous state model of

x’ = [ 0 1] * x + [0]*u(t)
[-1 0] [2]

and a time step of 0.1:

>>> F = np.array([[0,1],[-1,0]], dtype=float)
>>> G = np.array([[0.],[2.]])
>>> phi, Q = van_loan_discretization(F, G, 0.1)

>>> phi
array([[ 0.99500417,  0.09983342],
[-0.09983342,  0.99500417]])

>>> Q
array([[ 0.00133067,  0.01993342],
[ 0.01993342,  0.39866933]])


(example taken from Brown[2])

filterpy.common.linear_ode_discretation(F, L=None, Q=None, dt=1)[source]

filterpy.common.kinematic_kf(dim, order, dt=1.0, order_by_dim=True)[source]

Returns a KalmanFilter using newtonian kinematics for an arbitrary number of dimensions and order. So, for example, a constant velocity filter in 3D space would be created with

kinematic_kf(3, 1)

which will set the state x to be interpreted as

[x, x’, y, y’, z, z’].T

If you set order_by_dim to False, then x is assumed to be

[x y z x’ y’ z’].T

As another example, a 2D constant jerk is created with

kinematic_kf(2, 3)

Assumes that the measurement z is position in each dimension. If this is not true you will have to alter the H matrix by hand.

P, Q, R are all set to the Identity matrix.

H is assigned assuming the measurement is position, one per dimension dim.

Parameters: dim : int number of dimensions order : int, >= 1 order of the filter. 2 would be a const acceleration model. dim_z : int, default 1 size of z vector per dimension dim. Normally should be 1 dt : float, default 1.0 Time step. Used to create the state transition matrix

filterpy.common.kinematic_state_transition(order, dt)[source]

create a state transition matrix of a given order for a given time step dt.

filterpy.common.runge_kutta4(y, x, dx, f)[source]

computes 4th order Runge-Kutta for dy/dx.

Parameters: y : scalar Initial/current value for y x : scalar Initial/current value for x dx : scalar difference in x (e.g. the time step) f : ufunc(y,x) Callable function (y, x) that you supply to compute dy/dx for the specified values.