# 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.LMSFilter System object

## Description

The `LMSFilter` implements an adaptive FIR filter object that returns the filtered output, the error vector, and filter weights. The LMS filter uses one of five different LMS algorithms.

To implement the adaptive FIR filter object:

1. Define and set up your adaptive FIR filter object. See Construction.

2. Call `step` to implement the filter according to the properties of `dsp.LMSFilter`. 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

`lms = dsp.LMSFilter` returns an adaptive FIR filter object, `lms`, that computes the filtered output, filter error and the filter weights for a given input and desired signal using the Least Mean Squares (LMS) algorithm.

`lms = dsp.LMSFilter('PropertyName', PropertyValue,...)` returns an LMS filter object, `lms`, with each property set to the specified value.

`lms = dsp.LMSFilter(LEN,'PropertyName',PropertyValue,...)` returns an LMS filter object, `lms`, with the `Length` property set to `LEN`, and other specified properties set to the specified values.

## Properties

 `Method` Method to calculate filter weights Specify the method used to calculate filter weights as `LMS`, ```Normalized LMS```, `Sign-Error LMS`, `Sign-Data LMS`, or ```Sign-Sign LMS```. The default is `LMS`. `Length` Length of FIR filter weights vector Specify the length of the FIR filter weights vector as a positive integer. The default is `32`. `StepSizeSource` How to specify adaptation step size Choose how to specify the adaptation step size factor as `Property` or ```Input port```. The default is `Property`. `StepSize` Adaptation step size Specify the adaptation step size factor as a nonnegative real number. For convergence of the normalized LMS method, set the step size greater than `0` and less than `2`. This property only applies when the `StepSizeSource` property is `Property`. The default is `0.1`. This property is tunable. `LeakageFactor` Leakage factor used in LMS filter Specify the leakage factor as a real number between `0` and `1` inclusive. A leakage factor of `1` corresponds to no leakage in the adapting method. The default is `1`. This property is tunable. `InitialConditions` Initial conditions of filter weights Specify the initial values of the FIR filter weights as a scalar or vector of length equal to the `Length` property value. The default is `0`. `AdaptInputPort` Enable weight adaptation Specify when the LMS filter should adapt the filter weights. By default, the value of this property is `false`, and the object continuously updates the filter weights. When this property is set to `true`, an adaptation control input is provided to the `step` method. If the value of this input is nonzero, the object continuously updates the filter weights. If the input is zero, the filter weights remain at their current value. `WeightsResetInputPort` Enable weight reset Specify when the LMS filter should reset the filter weights. By default, the value of this property is `false`, and the object does not reset the weights. When this property is set to `true`, a reset control input is provided to the `step` method, and the `WeightsResetCondition` property applies. The object resets the filter weights based on the values of the `WeightsResetCondition` property and the `reset` input to the `step` method. `WeightsResetCondition` Reset trigger setting for filter weights Specify the event to reset the filter weights as `Rising edge`, `Falling edge`, `Either edge`, or `Non-zero`. The LMS filter resets the filter weights based on the values of this property and the `reset` input to the `step` method. This property only applies when the `WeightsResetInputPort` property is `true`. The default is `Non-zero`. `WeightsOutput` Enable returning filter weights Specify how to output the adapted filter weights as one of the following: `'Last'` (default) — The object returns a column vector of weights corresponding to the last sample of the data frame. The length of the weights vector is the value given by the `Length` property.`'All'` — The object returns a FrameLength-by-Length matrix of weights. The matrix corresponds to the full sample-by-sample history of weights values for all FrameLength samples of the input values. Each row in the matrix corresponds to a set of LMS filter weights calculated for the corresponding input sample.`'None'` — This setting disables the weights output.

## Methods

 maxstep Maximum step size for LMS adaptive filter convergence msepred Predicted mean-square error for LMS filter msesim Mean-squared error for LMS filter reset Reset filter states for LMS filter step Apply LMS adaptive filter to input
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).

```lms1 = dsp.LMSFilter(11,'StepSize',0.01); filt = dsp.FIRFilter; % System to be identified filt.Numerator = fir1(10,.25); x = randn(1000,1); % input signal d = filt(x) + 0.01*randn(1000,1); % desired signal [y,e,w] = lms1(x,d); subplot(2,1,1); plot(1:1000, [d,y,e]); title('System Identification of an FIR filter'); legend('Desired', 'Output', 'Error'); xlabel('time index'); ylabel('signal value'); subplot(2,1,2); stem([filt.Numerator.',w]); legend('Actual','Estimated'); xlabel('coefficient #'); ylabel('coefficient value');```

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).

Initialize the LMS filter with a length of 11 and step size of 0.05.

```FrameSize = 100; NIter = 10; lmsfilt2 = dsp.LMSFilter('Length',11,'Method','Normalized LMS', ... 'StepSize',0.05); firfilt2 = dsp.FIRFilter('Numerator', fir1(10,[.5, .75])); sinewave = dsp.SineWave('Frequency',0.01, ... 'SampleRate',1,'SamplesPerFrame',FrameSize); TS = dsp.TimeScope('TimeSpan',FrameSize*NIter,'TimeUnits','Seconds',... 'YLimits',[-3 3],'BufferLength',2*FrameSize*NIter, ... 'ShowLegend',true,'ChannelNames', ... {'Noisy signal', 'Filtered signal'}); ```

Pass the noisy input signal into the LMS filter and view the filtered output in the time scope.

```for k = 1:NIter x = randn(FrameSize,1); % Input signal d = firfilt2(x) + sinewave(); % Noise + Signal [y,e,w] = lmsfilt2(x,d); TS([d,e]); % Noisy = channel 1; Filtered = channel 2 end ```

Note: This example runs only in R2017a or later. If you are using a release earlier than R2017a, the object does not output a full sample-by-sample history of filter weights. If you are using a release earlier than R2016b, replace each call to the function with the equivalent `step` syntax. For example, myObject(x) becomes step(myObject,x).

Initialize the `dsp.LMSFilter` System object™ and set the `WeightsOutput` property to `'All'`. This setting enables the LMS filter to output a matrix of weights with dimensions `[FrameLength Length]`, corresponding to the full sample-by-sample history of weights for all `FrameLength` samples of input values.

```FrameSize = 15000; lmsfilt3 = dsp.LMSFilter('Length',63,'Method','LMS', ... 'StepSize',0.001,'LeakageFactor',0.99999, ... 'WeightsOutput','All'); % full Weights history w_actual = fir1(64,[0.5 0.75]); firfilt3 = dsp.FIRFilter('Numerator',w_actual); sinewave = dsp.SineWave('Frequency',0.01, ... 'SampleRate',1,'SamplesPerFrame',FrameSize); TS = dsp.TimeScope('TimeSpan',FrameSize,'TimeUnits','Seconds', ... 'YLimits',[-0.25 0.75],'BufferLength',2*FrameSize, ... 'ShowLegend',true,'ChannelNames', ... {'Coeff 33 Estimate','Coeff 34 Estimate','Coeff 35 Estimate', ... 'Coeff 33 Actual','Coeff 34 Actual','Coeff 35 Actual'}); ```

Run one frame and output the full adaptive weights history, `w`.

```x = randn(FrameSize,1); % Input signal d = firfilt3(x) + sinewave(); % Noise + Signal [~,~,w] = lmsfilt3(x,d); ```

Each row in `w` is a set of weights estimated for the respective input sample. Each column in `w` gives the complete history of a specific weight. Plot the actual weight and the entire history of the 33rd, 34th, and the 35th weight. In the plot, you can see that the estimated weight output eventually converges with the actual weight as the adaptive filter receives input samples and continues to adapt.

```idxBeg = 33; idxEnd = 35; TS([w(:,idxBeg:idxEnd), repmat(w_actual(idxBeg:idxEnd),FrameSize,1)]); ```

## Algorithms

This filter’s algorithm is defined by the following equations.

`$\begin{array}{c}y\left(n\right)={w}^{T}\left(n-1\right)u\left(n\right)\\ e\left(n\right)=d\left(n\right)-y\left(n\right)\\ w\left(n\right)=\alpha w\left(n-1\right)+f\left(u\left(n\right),e\left(n\right),\mu \right)\end{array}$`

The various LMS adaptive filter algorithms available in this System object are defined as:

• LMS:

`$f\left(u\left(n\right),e\left(n\right),\mu \right)=\mu e\left(n\right){u}^{*}\left(n\right)$`

• Normalized LMS:

`$f\left(u\left(n\right),e\left(n\right),\mu \right)=\mu e\left(n\right)\frac{{u}^{\ast }\left(n\right)}{\epsilon +{u}^{H}\left(n\right)u\left(n\right)}$`

• Sign-Error LMS:

`$f\left(u\left(n\right),e\left(n\right),\mu \right)=\mu sign\left(e\left(n\right)\right)u*\left(n\right)$`

• Sign-Data LMS:

`$f\left(u\left(n\right),e\left(n\right),\mu \right)=\mu e\left(n\right)sign\left(u\left(n\right)\right)$`
where u(n) is real.

• Sign-Sign LMS:

`$f\left(u\left(n\right),e\left(n\right),\mu \right)=\mu sign\left(e\left(n\right)\right)sign\left(u\left(n\right)\right)$`
where u(n) is real.

The variables are as follows:

VariableDescription

n

The current time index

u(n)

The vector of buffered input samples at step n

u*(n)

The complex conjugate of the vector of buffered input samples at step n

w(n)

The vector of filter weight estimates at step n

y(n)

The filtered output at step n

e(n)

The estimation error at step n

d(n)

The desired response at step n

µ

αThe leakage factor (0 < α ≤ 1)