Engee documentation

EngeeDSP.LMSFilter

Calculates the output, error, and coefficients using the Least Squares Method (LMS).

Library

EngeeDSP
Block

LMS Filter

Description

System object EngeeDSP.LMSFilter implements an adaptive filter with a finite impulse response (FIR filter), which ensures the convergence of the input signal to the desired signal using one of the following algorithms:

  • LMS;

  • Normalized LMS;

  • Sign-Data LMS;

  • Sign-Error LMS;

  • Sign-Sign LMS.

For more information about these algorithms, see Algorithms.

The filter adapts its weights until the error between the reference input signal and the desired signal is minimal.

To filter the signal using an adaptive FIR filter, follow these steps:

  1. Create an object EngeeDSP.LMSFilter and set its properties.

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

  • lms = EngeeDSP.LMSFilter() — returns the adaptive FIR filter system object lms, which calculates the filtered output signal, the filtering error, and the filter weights for a given input and required signals using the Least squares algorithm (LMS).

  • lms = EngeeDSP.LMSFilter(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.

Using

  • y,err,wts = lms(x,d) — filters the input signal x using d as the required signal, and returns the filtered output signal y, filtering error err and estimated filter weights wts. An object lms evaluates the weights needed to minimize the error between the output signal and the desired signal.

  • y,err = lms(x,d) — returns only the filtered output signal y and a filtering error err if for the property OutputFilterWeights value set false.

  • ___ = lms(x,d,mu) — uses mu as the step size, if for the property SpecifyStepSizeVia value set "Input port". These input arguments can be used with any of the previous sets of output arguments.

  • ___ = lms(x,d,a) — uses a as a signal controlling adaptation, if for the property AdaptPort value set true. When a If it is not equal to zero, the filter continuously updates the filter weights. When a is equal to zero, the filter weights remain constant.

  • ___ = lms(x,d,r) — uses r as a reset signal, if for the property ResetPort value set "Rising edge", "Falling edge", "Either edge" or "Non-zero sample". If a reset event occurs, the filter resets the filter weights to their initial values.

  • y,err,wts = lms(x,d,mu,a,r) — filters the input signal x using d as the required 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 signal

+ scalar | column vector

Details

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

Типы данных

Float32, Float64
Support for complex numbers

Yes

# d — required 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 required signal d.

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

The input signal d it can have a variable size. The number of elements in the column vector can be changed even after the object has entered a locked state. The system object is blocked when its algorithm is called.

Типы данных

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. To ensure the convergence of the method "Normalized LMS" the step size should be larger 0 And less 2. 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 required 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 SpecifyStepSizeVia value "Input port".

Типы данных

Float32, Float64

# a — adaptation management

+ scalar

Details

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

Dependencies

To use this argument, set the property to AdaptPort value 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 ResetPort.

Dependencies

To use this argument, set the property to ResetPort value "Rising edge", "Falling edge", "Either edge" or "Non-zero sample".

Типы данных

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 required signal d. The filter outputs a converging signal.

Типы данных

Float32, Float64
Support for complex numbers

Yes

# err — the difference between the output and required signals

+ scalar | column vector

Details

The difference between the output signal y and the required 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 weighting coefficients to converge to the optimal filter weighting coefficients, which 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, the length of which is determined by the value of the property FilterLength.

Типы данных

Float32, Float64

Features

# OutputFilterWeights — weighting factors at the filter output
Logical

Details

Set this property to true (default) to get the filter weights from the output argument wts.

To avoid using the output argument wts, set this property to false.

# ResetPort — additional input for activating the reset of weighting coefficients
String

Details

An event that initiates the reset of the filter weights, set using one of the following options:

  • "None" (default) — do not use the input argument. r.

  • "Rising edge" — starts the reset operation when the signal r it changes as follows:

    • increases from a negative value to a positive value or zero;

    • increases from zero to a positive value when the increase is not a continuation of the increase from a negative value to zero, as shown in the figure.:

      counter 1

  • "Falling edge" — starts the reset operation when the signal r it changes as follows:

    • decreases from a positive value to negative or zero;

    • decreases from zero to a negative value when the decrease is not a continuation of the decrease from a positive value to zero, as shown in the figure.:

      counter 2

  • "Either edge" — starts the reset operation when the input argument is r a launch event occurs "Rising edge" or "Falling edge".

  • "Non-zero sample" — starts the reset operation in each sampling cycle when the signal r is not equal to zero.

# Algorithm — algorithm for calculating filter weights
String

Details

A method for calculating the filter weights, specified using one of the following methods:

  • "LMS" (default) — solves the Wiener—Hopf equation and finds the filter coefficients for the adaptive filter.

  • "Normalized LMS" — a normalized version of the LMS algorithm.

  • "Sign-Data LMS" — the correction of the filter weights at each iteration depends on the sign of the input signal x.

  • "Sign-Error LMS" — the correction applied to the current filter weights at each subsequent iteration depends on the error sign. err.

  • "Sign-Sign LMS" — the correction applied to the current filter weights at each subsequent iteration depends on both the sign x, and from the sign err.

For more information about these algorithms, see Algorithms.

# StepSize — step size
Real number

Details

The coefficient of the adaptation step size, set as a non-negative scalar. To ensure the convergence of the method "Normalized LMS" the step size should be larger 0 And less 2.

The small step size ensures a low steady-state error between the output signal y and the required signal d. However, with a small step size, the convergence rate of the filter decreases. To increase the convergence rate, you should increase the step size. Keep in mind that if the step size is too large, the filter may become unstable.

Default value — 0.1.

Dependencies

To use this property, set the SpecifyStepSizeVia value "Dialog".

# LeakageFactor — loss ratio
Real number

Details

The loss coefficient for the implementation of the lossy LMS algorithm (leaky LMS), set as a scalar in the range [0, 1]. If the value is 1 (by default), there are no losses in the adaptation algorithm. If the value is less than 1 The filter implements a lossy LMS algorithm.

# AdaptPort — using the input argument to update the filter weights
Logical

Details

The option to use the input argument to update the filter weights, set by one of the following values:

  • false (default) — the object continuously updates the filter weights.;

  • true — when calling the algorithm, an adaptation control input signal is transmitted to the object. a. If the value of this signal is non-zero, the object continuously updates the filter weights. If the signal value is zero, the filter weights retain their current values.

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

Details

The method of setting the size of the adaptation step, set by one of the following values:

  • "Dialog" (default) — specify the step size using the StepSize;

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

# InitialValueOfFilterWeights — initial values of the filter weights
Scalar / array 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 FilterLength.

Default value — 0.

# FilterLength — filter length
Int64 integer

Details

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

Default value — 32.

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

The LMS filter algorithm is defined by the following equations:





The various adaptive LMS filter algorithms that can be set in the value of the Algorithm property are defined as follows:

  • "LMS" — solves the Wiener—Hopf equation and finds the filter coefficients for the adaptive filter:

  • "Normalized LMS" — a normalized version of the LMS algorithm:

    In the case "Normalized LMS" to overcome the potential numerical instability when updating the weights, a small positive constant is added to the denominator . For double-precision floating-point inputs equals the output of the function eps(Float64). For single precision data equals the output of the function eps(Float32).

  • "Sign-Error LMS" — the correction applied to the current filter weights at each subsequent iteration depends on the error sign. :

  • "Sign-Data LMS" — the correction of the filter weights at each iteration depends on the sign of the input signal :

    where it consists of real numbers.

  • "Sign-Sign LMS" — the correction applied to the current filter weights at each subsequent iteration depends on both the sign , and from the sign :

    where it consists of real numbers.

The following variables are used in the equations above:

  • — current time index;

  • — a vector of buffered input samples per step ;

  • is a complex conjugate vector of buffered input samples per step ;

  • — the vector of weight estimates of the filter in the step ;

  • — filtered output signal in the step ;

  • — estimation error in the step ;

  • — the required signal in the step ;

  • — the size of the adaptation step;

  • — the loss coefficient is such that ;

  • — a constant that corrects for any potential numerical instability that occurs during the update of the weights.

Literature

  1. Hayes, M.H. Statistical Digital Signal Processing and Modeling. New York: John Wiley & Sons, 1996.

Examples