EngeeDSP.BlockLMSFilter

Calculates the output, error, and weights using the adaptive least-mean-squares algorithm block.

Library	`EngeeDSP`
Block	LMS Filter

Description

System object EngeeDSP.BlockLMSFilter calculates the output data, error, and weights using a block implementing the Least Mean Squares Adaptive Algorithm (LMS).

To calculate the output, error, and weights, follow these steps:

Create an object EngeeDSP.BlockLMSFilter and set its properties.
Call the object with arguments as if it were a function.

To learn more about how to work with system objects, see Engee System Objects.

Syntax

Creation

blms = EngeeDSP.BlockLMSFilter() — returns the adaptive FIR filter system object blms, which filters the input signal and calculates the filter weights based on the least mean squares (LMS) algorithm block.
blms = EngeeDSP.BlockLMSFilter(length,blocksize) — returns the adaptive FIR filter system object blms, which has for the property Length value set length, and for the property BlockSize — value blocksize.
blms = EngeeDSP.BlockLMSFilter(Name=Value) — returns the adaptive FIR filter system object with the specified properties as a pair Name=Value, where Name — the name of the property, and Value — the appropriate value. You can specify multiple pairs «name-value» the order of the pairs does not matter. Unspecified properties retain their default values.

Example:
```
# создание адаптивного КИХ-фильтра с количеством отсчетов, полученных до адаптации весовых коэффициентов, 16
blms = EngeeDSP.BlockLMSFilter(BlockSize = 16)
```

Using

y,err,wts = blms(x,d) — filters the input signal x using d as the desired signal, and returns the filtered output signal y. Filter error — err, estimated filter weights — wts. The filter weights are updated once for each block of data processed by the object.
y,err = blms(x,d) — returns only the filtered output signal y and the filter error err if for the property WeightsOutputPort value set false.
___ = blms(x,d,mu) — uses mu as the step size, if for the property StepSizeSource value set "Input port". These input arguments can be used with any of the previous sets of output arguments.
___ = blms(x,d,a) — uses a as a signal controlling adaptation, if for the property AdaptInputPort value set true. When a not equal to zero, the filter continuously updates the filter weights. When a is equal to zero, the filter weights remain constant.
___ = blms(x,d,r) — uses r as a reset signal, if for the property WeightsResetInputPort value set true. Use the WeightsResetCondition 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 the input signal x using d as the desired signal, mu as a step size, a as a signal controlling adaptation, and r as a reset signal. The object returns a filtered output signal y, filter error err and adapted filter weights wts. Set the appropriate properties to provide all possible input data.

Arguments

Input arguments

# x — input data

+ scalar | column vector

Details

The signal that will be filtered by the LMS filter system object. The input signal x and the desired signal d they must have the same size and data type.

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

Типы данных	`Float32`, `Float64`
Support for complex numbers	Yes

# d is the desired signal

+ scalar | column vector

Details

The LMS filter adapts its weight coefficients wts to minimize errors err and the most accurate approximation of the input signal x to the desired signal d.

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

Типы данных	`Float32`, `Float64`
Support for complex numbers	Yes

# mu — step size

+ a non-negative scalar

Details

The coefficient of the adaptation step size, set as a non-negative scalar. The data type of the input step size must match the data type of the arguments. x and d.

The small step size ensures a small steady-state error between the output signal y and the desired signal d. If the step size is small, the convergence rate of the filter decreases. To increase the convergence rate, increase the step size. Note that if the step size is large, the filter may become unstable.

Dependencies

To use this argument, set the property to StepSizeSource value "Input port".

Типы данных

Float32, Float64

# a — adaptation management

+ scalar

Details

The adaptation control input, which determines how to update the filter weights. If the value of this parameter is not zero, the object constantly updates the filter weights. If the value of this parameter is zero, the filter weights remain at their current values.

Dependencies

This argument must be used if for the property AdaptInputPort value set true.

Типы данных

Float32, Float64, Int8, Int16, Int32, UInt8, UInt16, UInt32, Bool

# r — reset signal

+ scalar

Details

A reset signal that resets the filter weights based on the values of the WeightsResetInputPort.

Dependencies

This argument must be used if for the property WeightsResetInputPort value set true.

Типы данных

Float32, Float64, Int8, Int16, Int32, UInt8, UInt16, UInt32, Bool

Output arguments

# y — filtered output signal

+ scalar | column vector

Details

The filtered output signal returned as a scalar or column vector. The object adapts its filter weights to the convergence of the input signal x to the desired signal d. The filter outputs a converging signal.

Типы данных	`Float32`, `Float64`
Support for complex numbers	Yes

# err — the difference between the output and the desired signal

+ scalar | column vector

Details

The difference between the output signal y and the desired signal d, returned as a scalar or column vector. Data type err corresponds to the data type y. The purpose of the adaptive filter is to minimize this error. The object adapts its weights to converge to optimal filter weights that provide an output signal as close as possible to the desired signal.

Типы данных

Float32, Float64

# wts — adaptive filter weights

+ scalar | column vector

Details

Adaptive filter weights returned as a scalar or column vector with the length specified by the property value Length.

Data type wts corresponds to the data type y.

Типы данных

Float32, Float64

Features

# Length — the length of the vector of weighting coefficients of the FIR filter
Real number

Details

The length of the vector of weighting coefficients of the FIR filter, set as a positive integer.

# StepSizeSource — the method of setting the size of the adaptation step
String

Details

The method of setting the coefficient of the size of the adaptation step, set as

"Property" — specify the step size using the StepSize.
"Input port" — specify the step size using the argument mu.

# InitialWeights — initial values of the filter weights
Scalar / vector of real and/or complex numbers

Details

The initial values of the filter weights, set as a scalar or vector with a length equal to the value of the property Length.

# WeightsResetInputPort — additional input for activating the reset of the weights
Logical

Details

An option that allows the FIR filter to reset the values of the filter weights. By default, this property is set to false, and the object does not lose weight. If this property is set to true, it is necessary to pass the reset control input signal to the object, then the [Property property will be applied:WeightsResetCondition]. The object resets the filter weights based on the values of the WeightsResetCondition and the reset input signal passed to the object algorithm.

# StepSize — The size of the adaptation step
Real number

Details

The coefficient of the adaptation step size, set as a non-negative scalar.

Dependencies

To use this property, set the StepSizeSource value "Property".

# LeakageFactor — the loss factor used in the leakage LMS algorithm
Real number

Details

The loss coefficient used in the leakage LMS algorithm, given as a scalar of 0 before 1 inclusive. If the value is less than 1, the system object implements the leaky LMS algorithm. The default value is 1, which means there is no leak in the adaptive algorithm.

# AdaptInputPort — additional input for activating the adjustment of the filter weights
Logical

Details

An option that allows you to specify when the object should adjust the filter weights. By default, this property is set to false, and the filter is constantly updating the filter weights. If this property is set to true, an adaptation control input signal is provided to the object. If the value of this input signal is not zero, the filter continuously updates the filter weights. If the input value is zero, the filter weights remain at their current values.

# WeightsResetCondition — the condition that triggers the reset of the filter weights

Details

Specify an event to reset the filter weights.: "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 input signal passed to the object’s algorithm.

Dependencies

To use this property, set the WeightsResetInputPort value "true".

# WeightsOutputPort — weighting factors at the filter output
Logical

Details

Set this property to true to output the adapted filter weights. Default value — true.

# BlockSize — the number of samples received before the weighting factors were adjusted
Real number

Details

The number of samples of the input signal, set as a positive integer. These samples must be obtained before the object updates the filter weights. The length of the input frame must be an integer multiple of the block size.

Methods

Common to all system objects

`step!`	Run the system object operation algorithm
`release!`	Allow changing the value of a system object property
`reset!`	Resetting the internal states of a system object

Algorithms

This object implements the algorithm, input and output data described in the block documentation. LMS Filter. The object properties correspond to the block parameters.