dsp.BlockLMSFilter

Compute output, error, and weights using block least mean squares (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.

To learn more about how System objects work, see What Are System Objects?

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.

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.

blms = dsp.BlockLMSFilter(Name=Value) sets the properties using one or more name-value arguments. For example, to specify the number of samples acquired before weight adaptation as 16, set BlockSize to 16.

Properties

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.

For more information on changing property values, see System Design in MATLAB Using System Objects.

Length — Length of FIR filter weights vector

32 (default) | positive integer

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

BlockSize — Number of samples acquired before weight adaptation

32 (default) | positive integer

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

StepSizeSource — Source of adaptation step size

"Property" (default) | "Input port"

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

StepSize — Adaptation step size

0.1 (default) | nonnegative scalar

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

LeakageFactor — Leakage factor used in leaky LMS algorithm

1 (default) | scalar

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

InitialWeights — Initial values of filter weights

0 (default) | scalar | vector

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

AdaptInputPort — Additional input to enable adaptation of filter weights

false (default) | true

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.

WeightsResetInputPort — Additional input to enable weights reset

false (default) | true

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.

WeightsResetCondition — Condition that triggers the resetting of filter weights

"Non-zero" (default) | "Rising edge" | "Falling edge" | "Either edge"

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.

WeightsOutputPort — Output filter weights

true (default) | false

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

[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

x — Data input

scalar | column vector

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

d — Desired signal

scalar | column vector

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

mu — Step size

nonnegative scalar

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

a — Adaptation control

scalar

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

r — Reset signal

scalar

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

y — Filtered output

scalar | column vector

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

err — Difference between output and desired signal

scalar | column vector

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

wts — Adaptive filter weights

scalar | column vector

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)

Specific to dsp.BlockLMSFilter

msesim	Estimated mean squared error for adaptive filters
maxstep	Maximum step size for LMS adaptive filter convergence

Common to All System Objects

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

Remove Noise Using Block LMS Adaptive Algorithm

 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");

System Identification of FIR Filter Using Block LMS Filter

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.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

See System Objects in MATLAB Code Generation (MATLAB Coder).

Version History

Introduced in R2012a