Apache Commons Math 3.6.1 · org.apache.commons.math3.filter.KalmanFilter

Implementation of a Kalman filter to estimate the state x_k of a discrete-time controlled process that is governed by the linear stochastic difference equation:

x_k = Ax_k-1 + Bu_k-1 + w_k-1

with a measurement x_k that is

z_k = Hx_k + v_k.

The random variables w_k and v_k represent the process and measurement noise and are assumed to be independent of each other and distributed with normal probability (white noise).

The Kalman filter cycle involves the following steps:

predict: project the current state estimate ahead in time
correct: adjust the projected estimate by an actual measurement

The Kalman filter is initialized with a ProcessModel and a MeasurementModel, which contain the corresponding transformation and noise covariance matrices. The parameter names used in the respective models correspond to the following names commonly used in the mathematical literature:

A - state transition matrix
B - control input matrix
H - measurement matrix
Q - process noise covariance matrix
R - measurement noise covariance matrix
P - error covariance matrix

Field Summary

Modifier and Type	Field and Description
private RealMatrix	controlMatrix The control matrix, equivalent to B.
private RealMatrix	errorCovariance The error covariance matrix, equivalent to P.
private RealMatrix	measurementMatrix The measurement matrix, equivalent to H.
private RealMatrix	measurementMatrixT The transposed measurement matrix.
private final MeasurementModel	measurementModel The measurement model used by this filter instance.
private final ProcessModel	processModel The process model used by this filter instance.
private RealVector	stateEstimation The internal state estimation vector, equivalent to x hat.
private RealMatrix	transitionMatrix The transition matrix, equivalent to A.
private RealMatrix	transitionMatrixT The transposed transition matrix.

Constructor Summary

Access	Constructor and Description
public	KalmanFilter(final ProcessModel the model defining the underlying process dynamics process, final MeasurementModel the model defining the given measurement characteristics measurement) Creates a new Kalman filter with the given process and measurement models.

Method Summary

Modifier and Type	Method and Description
public void	correct(final double[] the measurement vector z) Correct the current state estimate with an actual measurement.
public void	correct(final RealVector the measurement vector z) Correct the current state estimate with an actual measurement.
public double[][]	Returns: the error covariance matrix getErrorCovariance() Returns the current error covariance matrix.
public RealMatrix	Returns: the error covariance matrix getErrorCovarianceMatrix() Returns a copy of the current error covariance matrix.
public int	Returns: the measurement vector dimension getMeasurementDimension() Returns the dimension of the measurement vector.
public int	Returns: the state dimension getStateDimension() Returns the dimension of the state estimation vector.
public double[]	Returns: the state estimation vector getStateEstimation() Returns the current state estimation vector.
public RealVector	Returns: the state estimation vector getStateEstimationVector() Returns a copy of the current state estimation vector.
public void	predict() Predict the internal state estimation one time step ahead.
public void	predict(final double[] the control vector u) Predict the internal state estimation one time step ahead.
public void	predict(final RealVector the control vector u) Predict the internal state estimation one time step ahead.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

controlMatrix	back to summary
private RealMatrix controlMatrix The control matrix, equivalent to B.

errorCovariance	back to summary
private RealMatrix errorCovariance The error covariance matrix, equivalent to P.

measurementMatrix	back to summary
private RealMatrix measurementMatrix The measurement matrix, equivalent to H.

measurementMatrixT	back to summary
private RealMatrix measurementMatrixT The transposed measurement matrix.

measurementModel	back to summary
private final MeasurementModel measurementModel The measurement model used by this filter instance.

processModel	back to summary
private final ProcessModel processModel The process model used by this filter instance.

stateEstimation	back to summary
private RealVector stateEstimation The internal state estimation vector, equivalent to x hat.

transitionMatrix	back to summary
private RealMatrix transitionMatrix The transition matrix, equivalent to A.

transitionMatrixT	back to summary
private RealMatrix transitionMatrixT The transposed transition matrix.

Constructor Detail

KalmanFilter	back to summary
public KalmanFilter(final ProcessModel process, final MeasurementModel measurement) throws NullArgumentException, NonSquareMatrixException, DimensionMismatchException, MatrixDimensionMismatchException Creates a new Kalman filter with the given process and measurement models. Parameters process:ProcessModel the model defining the underlying process dynamics measurement:MeasurementModel the model defining the given measurement characteristics Exceptions NullArgumentException: if any of the given inputs is null (except for the control matrix) NonSquareMatrixException: if the transition matrix is non square DimensionMismatchException: if the column dimension of the transition matrix does not match the dimension of the initial state estimation vector MatrixDimensionMismatchException: if the matrix dimensions do not fit together

KalmanFilter

back to summary

public KalmanFilter(final ProcessModel process, final MeasurementModel measurement) throws NullArgumentException, NonSquareMatrixException, DimensionMismatchException, MatrixDimensionMismatchException

Creates a new Kalman filter with the given process and measurement models.

Parameters

process:ProcessModel: the model defining the underlying process dynamics
measurement:MeasurementModel: the model defining the given measurement characteristics

Exceptions

NullArgumentException:: if any of the given inputs is null (except for the control matrix)
NonSquareMatrixException:: if the transition matrix is non square
DimensionMismatchException:: if the column dimension of the transition matrix does not match the dimension of the initial state estimation vector
MatrixDimensionMismatchException:: if the matrix dimensions do not fit together

Method Detail

correct back to summary

correct	back to summary
public void correct(final double[] z) throws NullArgumentException, DimensionMismatchException, SingularMatrixException Correct the current state estimate with an actual measurement. Parameters z:double[] the measurement vector Exceptions NullArgumentException: if the measurement vector is `null` DimensionMismatchException: if the dimension of the measurement vector does not fit SingularMatrixException: if the covariance matrix could not be inverted

public void correct(final double[] z) throws NullArgumentException, DimensionMismatchException, SingularMatrixException

Correct the current state estimate with an actual measurement.

Parameters

z:double[]: the measurement vector

Exceptions

NullArgumentException:: if the measurement vector is null
DimensionMismatchException:: if the dimension of the measurement vector does not fit
SingularMatrixException:: if the covariance matrix could not be inverted

correct back to summary

correct	back to summary
public void correct(final RealVector z) throws NullArgumentException, DimensionMismatchException, SingularMatrixException Correct the current state estimate with an actual measurement. Parameters z:RealVector the measurement vector Exceptions NullArgumentException: if the measurement vector is `null` DimensionMismatchException: if the dimension of the measurement vector does not fit SingularMatrixException: if the covariance matrix could not be inverted

public void correct(final RealVector z) throws NullArgumentException, DimensionMismatchException, SingularMatrixException

Correct the current state estimate with an actual measurement.

Parameters

z:RealVector: the measurement vector

Exceptions

NullArgumentException:: if the measurement vector is null
DimensionMismatchException:: if the dimension of the measurement vector does not fit
SingularMatrixException:: if the covariance matrix could not be inverted

getErrorCovariance	back to summary
public double[][] getErrorCovariance() Returns the current error covariance matrix. Returns:double[][] the error covariance matrix

getErrorCovariance

back to summary

public double[][] getErrorCovariance()

Returns the current error covariance matrix.

Returns:double[][]: the error covariance matrix

getErrorCovarianceMatrix	back to summary
public RealMatrix getErrorCovarianceMatrix() Returns a copy of the current error covariance matrix. Returns:RealMatrix the error covariance matrix

getErrorCovarianceMatrix

back to summary

public RealMatrix getErrorCovarianceMatrix()

Returns a copy of the current error covariance matrix.

Returns:RealMatrix: the error covariance matrix

getMeasurementDimension	back to summary
public int getMeasurementDimension() Returns the dimension of the measurement vector. Returns:int the measurement vector dimension

getMeasurementDimension

back to summary

public int getMeasurementDimension()

Returns the dimension of the measurement vector.

Returns:int: the measurement vector dimension

getStateDimension	back to summary
public int getStateDimension() Returns the dimension of the state estimation vector. Returns:int the state dimension

getStateDimension

back to summary

public int getStateDimension()

Returns the dimension of the state estimation vector.

Returns:int: the state dimension

getStateEstimation	back to summary
public double[] getStateEstimation() Returns the current state estimation vector. Returns:double[] the state estimation vector

getStateEstimation

back to summary

public double[] getStateEstimation()

Returns the current state estimation vector.

Returns:double[]: the state estimation vector

getStateEstimationVector	back to summary
public RealVector getStateEstimationVector() Returns a copy of the current state estimation vector. Returns:RealVector the state estimation vector

getStateEstimationVector

back to summary

public RealVector getStateEstimationVector()

Returns a copy of the current state estimation vector.

Returns:RealVector: the state estimation vector

predict	back to summary
public void predict() Predict the internal state estimation one time step ahead.

predict	back to summary
public void predict(final double[] u) throws DimensionMismatchException Predict the internal state estimation one time step ahead. Parameters u:double[] the control vector Exceptions DimensionMismatchException: if the dimension of the control vector does not fit

predict

back to summary

public void predict(final double[] u) throws DimensionMismatchException

Predict the internal state estimation one time step ahead.

Parameters

u:double[]: the control vector

Exceptions

DimensionMismatchException:: if the dimension of the control vector does not fit

predict	back to summary
public void predict(final RealVector u) throws DimensionMismatchException Predict the internal state estimation one time step ahead. Parameters u:RealVector the control vector Exceptions DimensionMismatchException: if the dimension of the control vector does not match

predict

back to summary

public void predict(final RealVector u) throws DimensionMismatchException

Predict the internal state estimation one time step ahead.

Parameters

u:RealVector: the control vector

Exceptions

DimensionMismatchException:: if the dimension of the control vector does not match

public Class KalmanFilter

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail