FIRLMS

Applies a FIR least mean squares (LMS) filter to a vector.

Syntax

Intel IPP style:

typedef struct {
    Ipp16u  numTaps;
    Ipp32f *pState;
    Ipp32f *pCoeffs;
    Ipp32f  mu;
} IppsqFIRLMSState_32f;

IppStatus ippsqFIRLMS_32f (const Ipp32f *pSrc , const Ipp32f *pRef , Ipp32f *pDst , Ipp32f *pErr , Ipp32u srcLen , IppsqFIRLMSState_32f *pSpec );

typedef struct {
    Ipp16u  numTaps;
    Ipp32f *pState;
    Ipp32f *pCoeffs;
    Ipp32f  mu;
    Ipp32u  postShift;
} IppsqFIRLMSState_16s;

IppStatus ippsqFIRLMSQ15_16s_Rms (const Ipp16s *pSrc , const Ipp16s *pRef , Ipp16s *pDst , Ipp16s *pErr , Ipp32u srcLen , IppsqFIRLMSState_16s *pSpec );

typedef struct {
    Ipp16u  numTaps;
    Ipp32s *pState;
    Ipp32s *pCoeffs;
    Ipp32s  mu;
    Ipp32u  postShift;
} IppsqFIRLMSState_32s;

IppStatus ippsqFIRLMSQ31_32s_Rm (const Ipp32s *pSrc , const Ipp32s *pRef , Ipp32s *pDst , Ipp32s *pErr , Ipp32u srcLen , IppsqFIRLMSState_32s *pSpec );

DSP style:

typedef struct {
    Ipp16u  numTaps;
    Ipp32f *pState;
    Ipp32f *pCoeffs;
    Ipp32f  mu;
} ippsq_lms_instance_f32;

void ippsq_lms_init_f32 (ippsq_lms_instance_f32 *S , uint16_t numTaps , float32_t *pCoeffs , float32_t *pState , float32_t mu , uint32_t blockSize ); void ippsq_lms_f32 (const ippsq_lms_instance_f32 *S , float32_t *pSrc , float32_t *pRef , float32_t *pDst , float32_t *pErr , uint32_t blockSize );

typedef struct {
    Ipp16u  numTaps;
    Ipp32f *pState;
    Ipp32f *pCoeffs;
    Ipp32f  mu;
    Ipp32u  postShift;
} ippsq_lms_instance_q15;

void ippsq_lms_init_q15 (ippsq_lms_instance_q15 *S , uint16_t numTaps , q15_t *pCoeffs , q15_t *pState , q15_t mu , uint32_t blockSize , uint32_t postShift );

void ippsq_lms_q15 (const ippsq_lms_instance_q15 *S , q15_t *pSrc , q15_t *pRef , q15_t *pDst , q15_t *pErr , uint32_t blockSize );

typedef struct {
    Ipp16u  numTaps;
    Ipp32s *pState;
    Ipp32s *pCoeffs;
    Ipp32s  mu;
    Ipp32u  postShift;
} ippsq_lms_instance_q31;

void ippsq_lms_init_q31 (ippsq_lms_instance_q31 *S , uint16_t numTaps , q31_t *pCoeffs , q31_t *pState , q31_t mu , uint32_t blockSize , uint32_t postShift );

void ippsq_lms_q31 (const ippsq_lms_instance_q31 *S , q31_t *pSrc , q31_t *pRef , q31_t *pDst , q31_t *pErr , uint32_t blockSize );

Include Files

ippsq.h

dsp.h

Parameters

pSrc

Pointer to the source vector.

pRef

Pointer to the reference signal.

pDst

Pointer to the filtering result.

pErr

Pointer to the error signal.

srcLen, blockSize

Number of elements in the source vector; can be zero.

pCoeffs

Pointer to the array containing the tap values. The number of elements in the array is numTaps.

numTaps

Number of elements in the array containing the tap values.

mu

Adaptation step.

postShift

Value by which the accumulated result might be shifted.

pState

Pointer to the array containing the delay line values.

Description

These functions apply a FIR least mean squares (LMS) filter to a vector. The following figure shows the structure of a FIR LMS filter:

Intel IPP style: The ippsqFIRLMS function filters the pSrc vector using an adaptive FIR LMS filter. Each of srcLen iterations performed by the function consists of two main procedures:

  1. The ippsqFIRLMS function filters the current element of the source vector pSrc and stores the result in pDst.

  2. The function updates the current taps using the reference signal pRef, computed result signal pDst, and the adaptation step mu.

Filtering is performed by the following formula:



where

  • x(n) is the input sample to be filtered

  • h(i) is the tap value

  • y(n) is the returned value

The function updates the filter coefficients that are stored in the filter state structure pSpec. Updated filter coefficients are defined as:



where

  • h n+1(i) is the new tap value.

  • h n(i) is the initial tap value.

  • mu is the adaptation step.

  • err(n) is the adaptation error. The err(n) value is computed as the difference between the reference and output signals ref(n) and y(n), respectively.

Before using the ippsqFIRLMS function, initialize all fields of the pSpec structure by setting proper values to numTaps, mu, postShift and assigning pointers to arrays to pCoeffs and pState.

Function flavors with the _Rm suffix round down the resulting value.

Function flavors with the _Rms suffix round down the resulting value and perform saturation if the resulting value exceeds the data range.

DSP style: Each function type (f32, q15, q31) has its own state structure. Before using the filtering function, initialize the structure using the corresponding initialization function. The initialization function copies arguments to the state structure and sets the elements of the pState array to zero. The number of elements of the pState array should be at least numTaps+blockSize-1.

Scaling, Truncation, Saturation

Intel IPP style:

Function Description
ippsqFIRLMSQ15_16s_Rms

The pSrc, pDst, pRef, pErr, pCoeffs, and pState values are represented in Q15 format. The function uses a 64-bit internal accumulator in Q34.30 format, so it preserves full precision of intermediate calculations and avoids internal overflow. In the end, the function shifts the accumulator right by 15-postShift bits and saturates it in the [IPP_MIN_16S, IPP_MAX_16S] range.

ippsqFIRLMSQ31_32s_Rm

The pSrc, pDst, pRef, pErr, pCoeffs, and pState values are represented in Q31 format. The function uses a 64-bit internal accumulator in Q2.62 format and provides only one guard bit. The function is not protected from internal overflow. In the end, the function shifts the accumulator right by 31-postShift bits and does not perform saturation.

DSP style:

Function Description
ippsq_lms_q15

The pSrc, pDst, pRef, pErr, pCoeffs, and pState values are represented in Q15 format. The function uses a 64-bit internal accumulator in Q34.30 format, so it preserves full precision of intermediate calculations and avoids internal overflow. In the end, the function shifts the accumulator right by 15-postShift bits and saturates it in the [IPP_MIN_16S, IPP_MAX_16S] range.

ippsq_lms_q31

The pSrc, pDst, pRef, pErr, pCoeffs, and pState values are represented in Q31 format. The function uses a 64-bit internal accumulator in Q2.62 format and provides only one guard bit. The function is not protected from internal overflow. In the end, the function shifts the accumulator right by 31-postShift bits and does not perform saturation.

Return Values

ippStsNoErr

Indicates no error.

ippStsSizeErr

Indicates an error when numTaps is equal to zero.

ippStsNullPtrErr

Indicates an error when any of the specified pointers is NULL.
For more complete information about compiler optimizations, see our Optimization Notice.