Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English version of the page.

# dsp.KalmanFilter

Estimate system measurements and states using Kalman filter

## Description

The `dsp.KalmanFilter` System object™ is an estimator used to recursively obtain a solution for linear optimal filtering. This estimation is made without precise knowledge of the underlying dynamic system. The Kalman filter implements the following linear discrete-time process with state, x, at the kth time-step: $x\left(k\right)=Ax\left(k-1\right)+Bu\left(k-1\right)+w\left(k-1\right)$ (state equation). This measurement, z, is given as: $z\left(k\right)=Hx\left(k\right)+v\left(k\right)$ (measurement equation).

The Kalman filter algorithm computes the following two steps recursively:

• Prediction: Process parameters x (state) and P (state error covariance) are estimated using the previous state.

• Correction: The state and error covariance are corrected using the current measurement.

To filter each channel of the input:

1. Create the `dsp.KalmanFilter` object and set its properties.

2. Call the object with arguments, as if it were a function.

## Creation

### Syntax

``kalman = dsp.KalmanFilter``
``````kalman = dsp.KalmanFilter(STMatrix, MMatrix, PNCovariance, MNCovariance, CIMatrix)``````
``kalman = dsp.KalmanFilter(Name,Value)``

### Description

````kalman = dsp.KalmanFilter` returns the Kalman filter System object, `kalman`, with default values for the parameters.```

example

``````kalman = dsp.KalmanFilter(STMatrix, MMatrix, PNCovariance, MNCovariance, CIMatrix)``` returns a Kalman filter System object, `kalman`. The `StateTransitionMatrix` property is set to `STMatrix`, the `MeasurementMatrix` property is set to `MMatrix`, the `ProcessNoiseCovariance` property is set to `PNCovariance`, the `MeasurementNoiseCovariance` property is set to `MNCovariance`, and the `ControlInputMatrix` property is set to `CIMatrix`.```
````kalman = dsp.KalmanFilter(Name,Value)` returns an Kalman filter System object, `kalman`, with each property set to the specified value. Enclose each property name in single quotes. Unspecified properties have default values.```

## Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the `release` function unlocks them.

If a property is tunable, you can change its value at any time.

Specify A in the state equation that relates the state at the previous time step to the state at current time step. A is a square matrix with each dimension equal to the number of states.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Specify B in the state equation that relates the control input to the state. B is a column vector with a number of rows equal to the number of states.

#### Dependencies

This property is activated only when the `ControlInputPort` property value is `true`.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Specify H in the measurement equation that relates the states to the measurements. H is a row vector with a number of columns equal to the number of measurements.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Specify Q as a square matrix with each dimension equal to the number of states. Q is the covariance of the white Gaussian process noise, w, in the state equation.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Specify R as a square matrix with each dimension equal to the number of states. R is the covariance of the white Gaussian process noise, v, in the measurement equation.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Specify an initial estimate of the states of the model as a column vector with length equal to the number of states.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Specify an initial estimate for covariance of the state error, as a square matrix with each dimension equal to the number of states.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Specify as a scalar logical value, disabling System object filters from performing the correction step after the prediction step in the Kalman filter algorithm.

Specify if the control input is present, using a scalar logical value. The default value is `true`.

## Usage

For versions earlier than R2016b, use the `step` function to run the System object algorithm. The arguments to `step` are the object you created, followed by the arguments shown in this section.

For example, `y = step(obj,x)` and `y = obj(x)` perform equivalent operations.

### Syntax

``[zEst, xEst, MSE_Est, zPred, xPred, MSE_Pred] = kalman(z,u)``

### Description

example

````[zEst, xEst, MSE_Est, zPred, xPred, MSE_Pred] = kalman(z,u)` carries out the iterative Kalman filter algorithm over measurements `z` and control inputs `u`. The columns in `z` and `u` are treated as inputs to separate parallel filters, whose correction (or update) step can be disabled by the `DisableCorrection` property. The values returned are estimated measurements `zEst`, estimated states `xEst`, MSE of estimated states `MSE_Est`, predicted measurements `zPred`, predicted states `xPred`, and MSE of predicted states `MSE_Pred`.```

### Input Arguments

expand all

Measurement input, specified as a vector or a matrix.

The ratio of the number of rows of the measurement input to the number of rows of the `MeasurementMatrix` property must be equal to the ratio of the number of rows of the control input to the number of columns of the `ControlInputMatrix` property.

The measurement signal can be a variable-size input. Once the object is locked, you can change the size of each input channel, but the number of channels cannot change.

Data Types: `single` | `double`

Control input, specified as a vector or a matrix.

The ratio of the number of rows of the control input to the number of columns of the `ControlInputMatrix` property must be equal to the ratio of the number of rows of the measurement input to the number of rows of the `MeasurementMatrix` property.

The control signal can be a variable-size input. Once the object is locked, you can change the size of each input channel, but the number of channels cannot change.

Data Types: `single` | `double`

### Output Arguments

expand all

Estimated measurements, returned as a vector or matrix.

Data Types: `single` | `double`

Estimated state, returned as a vector or matrix.

Data Types: `single` | `double`

Mean-squared error of estimated states, returned as a scalar or column vector. If the input is a row vector, the MSE of the estimated states is a scalar.

Data Types: `single` | `double`

Predicted measurements, returned as a vector or a matrix.

Data Types: `single` | `double`

Predicted states, returned as a vector or a matrix.

Data Types: `single` | `double`

Mean-squared error of predicted states, returned as a scalar or a column vector. If the input is a row vector, the MSE of the estimated states is a scalar.

Data Types: `single` | `double`

## Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named `obj`, use this syntax:

`release(obj)`

expand all

 `step` Run System object algorithm `release` Release resources and allow changes to System object property values and input characteristics `reset` Reset internal states of System object

## Examples

expand all

Note: If you are using R2016a or an earlier release, replace each call to the object with the equivalent step syntax. For example, obj(x) becomes step(obj,x).

Create the System objects for the changing scalar input, the Kalman filter, and the scope (for plotting).

```numSamples = 4000; R = 0.02; src = dsp.SignalSource; src.Signal = [ones(numSamples/4,1);-3*ones(numSamples/4,1);... 4*ones(numSamples/4,1); -0.5*ones(numSamples/4,1)]; tScope = dsp.TimeScope('NumInputPorts',3,'TimeSpan',numSamples, ... 'TimeUnits','Seconds','YLimits',[-5 5], ... 'ShowLegend',true); % Create the Time Scope kalman = dsp.KalmanFilter('ProcessNoiseCovariance', 0.0001,... 'MeasurementNoiseCovariance',R,... 'InitialStateEstimate',5,... 'InitialErrorCovarianceEstimate',1,... 'ControlInputPort',false); %Create Kalman filter ```

Add noise to the scalar, and pass the result to the Kalman filter. Stream the data, and plot the filtered signal.

```while(~isDone(src)) trueVal = src(); noisyVal = trueVal + sqrt(R)*randn; estVal = kalman(noisyVal); tScope(noisyVal,trueVal,estVal); end ```

Note: If you are using R2016a or an earlier release, replace each call to the object with the equivalent step syntax. For example, obj(x) becomes step(obj,x).

Create the signal, Kalman Filter, and Time Scope System objects.

```numSamples = 4000; R = 0.02; src = dsp.SignalSource; src.Signal = [ ones(numSamples/4,1);-3*ones(numSamples/4,1);... 4*ones(numSamples/4,1);-0.5*ones(numSamples/4,1)]; tScope = dsp.TimeScope('NumInputPorts',3,'TimeSpan',numSamples, ... 'TimeUnits','Seconds','YLimits',[-5 5],... 'Title',['True(channel 1),noisy(channel 2) and ',... 'estimated(channel 3) values'], ... 'ShowLegend', true); kalman = dsp.KalmanFilter('ProcessNoiseCovariance',0.0001,... 'MeasurementNoiseCovariance',R,... 'InitialStateEstimate',5,... 'InitialErrorCovarianceEstimate',1,... 'ControlInputPort',false); ctr = 0; ```

Add noise to the signal. Stream the data, and plot the filtered signal.

```while(~isDone(src)) trueVal = src(); noisyVal = trueVal + sqrt(R)*randn; estVal = kalman(noisyVal); tScope(trueVal,noisyVal,estVal); % Disabling the correction step of second filter for the middle % one-third of the simulation if ctr == floor(numSamples/3) kalman.DisableCorrection = true; end if ctr == floor(2*numSamples/3) kalman.DisableCorrection = false; end ctr = ctr + 1; end ```

Note: If you are using R2016a or an earlier release, replace each call to the object with the equivalent step syntax. For example, obj(x) becomes step(obj,x).

Create the signal where the columns are the two scalar values to be tracked. Also create the Kalman Filter, and the Time Scopes.

```numSamples = 4000; R = 0.02; src = dsp.SignalSource; sig1 = [ ones(numSamples/4,1); -3*ones(numSamples/4,1);... 4*ones(numSamples/4,1); -0.5*ones(numSamples/4,1)]; sig2 = [-2*ones(numSamples/4,1); 4*ones(numSamples/4,1);... -3*ones(numSamples/4,1); 1.5*ones(numSamples/4,1)]; src.Signal = [sig1, sig2]; tScope1 = dsp.TimeScope('NumInputPorts', 3, 'TimeSpan', numSamples, ... 'TimeUnits', 'Seconds', 'YLimits',[-5 5], ... 'Title', ['True(channel 1), noisy(channel 2) and ',... 'estimated(channel 3) values'], ... 'ShowLegend', true); tScope2 = clone(tScope1); kalman = dsp.KalmanFilter('ProcessNoiseCovariance', 0.0001,... 'MeasurementNoiseCovariance', R,... 'InitialStateEstimate', -3,... 'InitialErrorCovarianceEstimate', 1,... 'ControlInputPort',false); ```

Add noise to the signal. Stream the data, and plot the filtered signal.

```while(~isDone(src)) trueVal = src(); noisyVal = trueVal + sqrt(R)*randn(1,2); estVal = kalman(noisyVal); % Plot results of first channel on Time Scope tScope1(trueVal(:,1),noisyVal(:,1),estVal(:,1)); % Plot results of second channel on Time Scope tScope2(trueVal(:,2),noisyVal(:,2),estVal(:,2)); end ```

Note: If you are using R2016a or an earlier release, replace each call to the object with the equivalent step syntax. For example, obj(x) becomes step(obj,x).

Use a unit step as the control input to track a ramp signal. Create the ramp signal to be tracked, the control input, the Time Scope, and the Kalman Filter.

```numSamples = 200; R = 100; src = dsp.SignalSource; src.Signal = (1:numSamples)'; control = dsp.SignalSource; control.Signal = ones(numSamples,1); tScope = dsp.TimeScope('NumInputPorts', 3, 'TimeSpan', numSamples, ... 'TimeUnits', 'Seconds', 'YLimits',[-5 205], ... 'Title', ['Noisy(channel 1), True(channel 2) and ',... 'estimated(channel 3) values'], ... 'ShowLegend', true); kalman = dsp.KalmanFilter('ProcessNoiseCovariance', 0.0001,... 'MeasurementNoiseCovariance', R,... 'InitialStateEstimate', 1,... 'InitialErrorCovarianceEstimate', 1); ```

Add noise to the signal. Filter the signal using kalman filter. View the output using time scope.

```while(~isDone(src)) trueVal = src(); ctrl = control(); noisyVal = trueVal + sqrt(R)*randn; estVal = kalman(noisyVal,ctrl); tScope(noisyVal,trueVal,estVal); end ```

## Algorithms

This object implements the algorithm, inputs, and outputs described on the Kalman Filter block reference page. The object properties correspond to the block parameters.

## References

[1] Greg Welch and Gary Bishop, An Introduction to the Kalman Filter, Technical Report TR95 041. University of North Carolina at Chapel Hill: Chapel Hill, NC., 1995.