dsp.BlockLMSFilter

Compute output, error, and weights using block LMS adaptive algorithm

Description

The `dsp.BlockLMSFilter` System object™ computes output, error, and weights using the block LMS adaptive algorithm.

To compute the output, error, and weights:

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

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

Creation

Syntax

``blms = dsp.BlockLMSFilter``
``blms = dsp.BlockLMSFilter(length,blocksize)``
``blms = dsp.BlockLMSFilter(Name,Value)``

Description

````blms = dsp.BlockLMSFilter` returns an adaptive FIR filter, `blms`, that filters the input signal and computes filter weights based on the block least mean squares (LMS) algorithm.```

example

````blms = dsp.BlockLMSFilter(length,blocksize)` returns an adaptive FIR filter, `blms`, with the `Length` property set to `length` and the `BlockSize` property set to `blocksize`.```

example

````blms = dsp.BlockLMSFilter(Name,Value)` returns an adaptive FIR filter, `blms`, with each specified 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 the length of the FIR filter weights vector as a positive integer scalar.

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

Specify the number of samples of the input signal to acquire before the object updates the filter weights. The input frame length must be an integer multiple of the block size.

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

Specify the source of the adaptation step size factor as `Property` or `Input port`.

Specify the adaptation step size factor as a scalar, nonnegative numeric value.

Tunable: Yes

Dependencies

This property applies only when you set the StepSizeSource property to `'Property'`.

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

Specify the leakage factor used in leaky LMS algorithm as a scalar numeric value between `0` and `1`, both inclusive. When the value is less than `1`, the System object implements a leaky LMS algorithm. The default is `1`, providing no leakage in the adapting algorithm.

Tunable: Yes

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

Specify the initial values of the filter weights as a scalar or a vector of length equal to the Length property value.

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

Specify when the object should adapt the filter weights. By default, the value of this property is `false`, and the filter continuously updates the filter weights. When this property is set to `true`, an adaptation control input is provided to the object. If the value of this input is nonzero, the filter continuously updates the filter weights. If the input is zero, the filter weights remain at their current value.

Specify whether the FIR filter can 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`, you must provide a reset control input to the object, 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 object algorithm.

Specify the event to reset the filter weights as one of ```Rising edge```, `Falling edge`, `Either edge`, or `Non-zero`. The object resets the filter weights based on the values of this property and the reset signal input to the object algorithm.

Dependencies

This property applies only when you set the `WeightsResetInputPort` property to `true`.

Set this property to `true` to output the adapted filter weights. The default is `true`.

Usage

Syntax

``[y,err,wts] = blms(x,d)``
``[y,err] = blms(x,d)``
``[___] = blms(x,d,mu)``
``[___] = blms(x,d,a)``
``[___] = blms(x,d,r)``
``[y,err,wts] = blms(x,d,mu,a,r)``

Description

example

````[y,err,wts] = blms(x,d)` filters the input `x`, using `d` as the desired signal, and returns the filtered output in `y`. The filter error is `err`, and the estimated filter weights is `wts`. The filter weights update once for every block of data that the object processes.```
````[y,err] = blms(x,d)` returns only the filtered output `y` and the filter error `err` when the `WeightsOutputPort` property is `false`.```
````[___] = blms(x,d,mu)` uses `mu` as the step size when you set the `StepSizeSource` property to `Input port`. These input arguments can be used with any of the previous sets of output arguments.```
````[___] = blms(x,d,a)` uses `a` as the adaptation control when you set the `AdaptInputPort` property to `true`. When `a` is nonzero, the filter continuously updates the filter weights. When `a` is zero, the filter weights remain constant.```
````[___] = blms(x,d,r)` uses `r` as a reset signal when you set the `WeightsResetInputPort` property to `true`. Use the `WeightsResetCondition` property to set the reset trigger condition. If a reset event occurs, the filter resets the filter weights to their initial values.```
````[y,err,wts] = blms(x,d,mu,a,r)` filters input `x`, using `d` as the desired signal, `mu` as the step size, `a` as the adaptation control, and `r` as the reset signal. The object returns the filtered output `y`, the filter error `err`, and the adapted filter weights `wts`. Set the properties appropriately to provide all possible inputs.```

Input Arguments

expand all

The signal to be filtered by the block LMS filter. The input, `x`, and the desired signal, `d`, must have the same size and data type.

The input length must be an integer multiple of the `BlockSize` property value.

Data Types: `single` | `double`
Complex Number Support: Yes

The LMS filter adapts its filter weights, `wts`, to minimize the error, `err`, and converge the input signal `x` to the desired signal `d` as closely as possible.

The input, `x`, and the desired signal, `d`, must have the same size and data type.

Data Types: `single` | `double`
Complex Number Support: Yes

Adaptation step size factor, specified as a scalar, nonnegative numeric value. The data type of the step size input must match the data type of `x` and `d`.

A small step size ensures a small steady state error between the output `y` and the desired signal `d`. If the step size is small, the convergence speed of the filter decreases. To improve the convergence speed, increase the step size. Note that if the step size is large, the filter can become unstable. To compute the maximum step size the filter can accept without becoming unstable, use the `maxstep` function.

Dependencies

This property applies only when you set the StepSizeSource property to ```'Input port'```.

Data Types: `single` | `double`

Adaptation control input that controls how the filter weights are updated. If the value of this input is nonzero, the object continuously updates the filter weights. If the value of this input is zero, the filter weights remain at their current value.

Dependencies

This input is required when the `AdaptInputPort` property is set to `true`.

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

Reset signal that resets the filter weights based on the values of the `WeightsResetInputPort` property.

Dependencies

This input is required when the `WeightsResetInputPort` property is set to `true`.

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

Output Arguments

expand all

Filtered output, returned as a scalar or a column vector. The object adapts its filter weights to converge the input signal `x` to match the desired signal `d`. The filter outputs the converged signal.

Data Types: `single` | `double`
Complex Number Support: Yes

Difference between the output signal `y` and the desired signal `d`, returned as a scalar or a column vector. The data type of `err` matches the data type of `y`. The objective of the adaptive filter is to minimize this error. The object adapts its weights to converge towards optimal filter weights that produce an output signal that matches closely with the desired signal.

Data Types: `single` | `double`

Adaptive filter weights, returned as a scalar or a column vector of length specified by the value in the `Length` property.

The data type of `wts` matches the data type of `y`.

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

 `msesim` Estimated mean squared error for adaptive filters `maxstep` Maximum step size for LMS adaptive filter convergence
 `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

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

``` blms = dsp.BlockLMSFilter(10,5); blms.StepSize = 0.01; blms.WeightsOutputPort = false; filt = dsp.FIRFilter; filt.Numerator = fir1(10,[.5, .75]); x = randn(1000,1); % Noise d = filt(x) + sin(0:.05:49.95)'; % Noise + Signal [y, err] = blms(x, d); subplot(2,1,1); plot(d); title('Noise + Signal'); subplot(2,1,2); plot(err); title('Signal');```

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

```fir = fir1(31,0.5); % FIR system to be identified firFilter = dsp.FIRFilter('Numerator',fir); iirFilter = dsp.IIRFilter('Numerator',sqrt(0.75),... 'Denominator',[1 -0.5]); x = iirFilter(sign(randn(2000,25))); % Observation noise signal n = 0.1*randn(size(x)); % Desired signal d = firFilter(x)+n; % Filter length l = 32; % Block LMS Step size mu = 0.008; % Decimation factor for analysis % and simulation results m = 32; fir = dsp.BlockLMSFilter(l,'StepSize',mu); [simmse,meanWsim,Wsim,traceKsim] = msesim(fir,x,d,m); plot(m*(1:length(simmse)),10*log10(simmse)); xlabel('Iteration'); ylabel('MSE (dB)'); % Plot the learning curve for % block LMS filter used in system identification title('Learning curve')```

Algorithms

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

Version History

Introduced in R2012a