# Documentation

### This is machine translation

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

# dsp.KalmanFilter System object

Estimate system measurements and states using Kalman filter

## Description

The `KalmanFilter` 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. Define and set up your Kalman filter. See Construction.

2. Call `step` to filter each channel of the input according to the properties of `dsp.KalmanFilter`. The behavior of `step` is specific to each object in the toolbox.

### Note

Starting in R2016b, instead of using the `step` method to perform the operation defined by the System object™, you can call the object with arguments, as if it were a function. For example, ```y = step(obj,x)``` and `y = obj(x)` perform equivalent operations.

## Construction

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

```kalman = dsp.KalmanFilter('PropertyName',PropertyValue, ...)``` returns an Kalman filter System object, `kalman`, with each property set to the specified value.

```kalman = dsp.KalmanFilter(STMatrix, MMatrix, PNCovariance, MNCovariance, CIMatrix, 'PropertyName', PropertyValue, ...)``` returns a Kalman filter System object, `kalman`. The `StateTransitionMatrix` property is set to `STMatrix`, and `MeasurementMatrix` property is set to `MMatrix`. In addition, the `ProcessNoiseCovariance` property set to `PNCovariance`, `MeasurementNoiseCovariance` property set to `MNCovariance`, `ControlInputMatrix` property set to `CIMatrix`. Other specified properties are set to the specified values.

## Properties

 `StateTransitionMatrix` Model of state transition 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. The default value is `1`. `ControlInputMatrix` Model of relation between control input and states Specify `B` in the state equation that relates the control input to the state. `B` is a matrix with a number of rows equal to the number of states. This property is activated only when the `ControlInputPort` property value is `true`. The default value is `1`. `MeasurementMatrix` Model of relation between states and measurement output Specify `H` in the measurement equation that relates the states to the measurements. `H` is a matrix with the number of columns equal to the number of measurements. The default value is `1`. `ProcessNoiseCovariance` Covariance of process noise Specify `Q` as a square matrix with each dimension equal to the number of states. This matrix, `Q`, is the covariance of the white Gaussian process noise, `w`, in the state equation. The default value is `0.1`. `MeasurementNoiseCovariance` Covariance of measurement noise Specify `R` as a square matrix with each dimension equal to the number of states. This matrix, `R`, is the covariance of the white Gaussian process noise, `v`, in the measurement equation. The default value is `0.1`. `InitialStateEstimate` Initial value for states Specify an initial estimate of the states of the model as a column vector with length equal to the number of states. The default value is `0`. `InitialErrorCovarianceEstimate` Initial value for state error covariance Specify an initial estimate for covariance of the state error, as a square matrix with each dimension equal to the number of states. The default value is `0.1`. `DisableCorrection` Disable port for filters Specify as a scalar logical value, disabling System object filters from performing the correction step after the prediction step in the Kalman filter algorithm. The default value is `false`. `ControlInputPort` Presence of a control input Specify if the control input is present, using a scalar logical value. The default value is `true`.

## Methods

 reset Reset internal states of Kalman filter step Filter input with Kalman filter object
Common to All System Objects
`clone`

Create System object with same property values

`getNumInputs`

Expected number of inputs to a System object

`getNumOutputs`

Expected number of outputs of a System object

`isLocked`

Check locked states of a System object (logical)

`release`

Allow System object property value changes

## Examples

expand all

Note: This example runs only in R2016b or later. If you are using an earlier release, replace each call to the function with the equivalent `step` syntax. For example, myObject(x) becomes step(myObject,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: This example runs only in R2016b or later. If you are using an earlier release, replace each call to the function with the equivalent `step` syntax. For example, myObject(x) becomes step(myObject,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: This example runs only in R2016b or later. If you are using an earlier release, replace each call to the function with the equivalent `step` syntax. For example, myObject(x) becomes step(myObject,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: This example runs only in R2016b or later. If you are using an earlier release, replace each call to the function with the equivalent `step` syntax. For example, myObject(x) becomes step(myObject,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.