FIRSparse

A filter is a circuit that passes certain frequencies or rejects all others. It is widely used in the communication system and signal processing system. From the functional point of view, a digital filter processes the digital code of input discrete signals to filter the signals that are out of the frequency band. Most of the coefficients in a sparse filter are equal to zero, and only filters with non-zero taps are recorded for signal processing.

The filtered vector dst(y) is obtained by performing a convolution operation on a sampling signal x in the filter coefficient array nzTaps(b) and the src(x) vector.

The formula is as follows:

The dlyLine vector supports null values: If dlyLine is null, the function uses an all-zero delay line.

The FIRSparse function calling process is as follows:

Call FIRSparseInit to perform initialization.
Call FIRSparse to perform filtering.
Call FIRSparseGetDlyLine or FIRSparseSetDlyLine to retrieve and set the delay line.
Call FIRSparseRelease to release the memory allocated by using FIRSparseInit.

The function interface declaration is as follows:

Initialization:
HmppResult HMPPS_FIRSparseInit_32f(const float *nzTaps, const int32_t *nzTapsPos, int32_t nzTapsLen, const float *dlyLine, HmppsFIRSparsePolicy_32f **policy);
Obtaining the delay line:
HmppResult HMPPS_FIRSparseGetDlyLine_32f(const HmppsFIRSparsePolicy_32f *policy, float *dlyLine);;
Setting the delay line:
HmppResult HMPPS_FIRSparseSetDlyLine_32f(HmppsFIRSparsePolicy_32f *policy, const float *dlyLine);
Main functions:
HmppResult HMPPS_FIRSparse_32f(const float *src, float *dst, int32_t len, HmppsFIRSparsePolicy_32f *policy);
Memory release:
HmppResult HMPPS_FIRSparseRelease_32f(HmppsFIRSparsePolicy_32f *policy);

Parameters

Parameter	Description	Value Range	Input/Output
nzTaps	Pointer to non-zero taps	The value cannot be NULL.	Input
nzTapPos	Pointer to the position (counted from 0) that contains non-zero taps	The value cannot be NULL. The values in the array must be in the range [0, INT_MAX] and in ascending order.	Input
nzTapsLen	Number of elements with non-zero taps in the array	(0, INT_MAX]	Input
dlyLine (in the Init and setDly functions)	Pointer to the array that contains the delay line values	The number of elements in the array is nzTapPos[nzTapsLen - 1]. When the value of dlyLine is null, 0 is used.	Input
dlyLine (in the getDly function)	Pointer to the delay line values	The value cannot be NULL.	Output
src	Pointer to the source vector	The value cannot be NULL.	Input
len	Number of elements in the source vector	(0, INT_MAX]	Input
dst	Pointer to the destination vector	The value cannot be NULL.	Output
policy (in the Init function)	Pointer to the memory that stores the pointer to FIRSparsePolicy	The value cannot be NULL.	Output
policy (in the setDly function)	Pointer to FIRSparsePolicy	The value cannot be NULL.	Output
policy (in the main, getDly, and release functions)	Pointer to the FIRSparsePolicy structure	The value cannot be NULL.	Input

Return Value

Success: HMPP_STS_NO_ERR
Failure: An error code is returned.

Error Codes

Error Code	Description
HMPP_STS_NO_ERR	No error occurs.
HMPP_STS_NULL_PTR_ERR	Any of the specified pointers is NULL.
HMPP_STS_SIZE_ERR	The value of nzTapsLen or len is less than or equal to 0.
HMPP_STS_SPARSE_ERR	Values in the array to which the nzTapPos pointer points are not sorted in ascending order, or there are negative or repeated values.
HMPP_STS_OVERFLOW	The function overflows.
HMPP_STS_MALLOC_FAILED	The Init function failed to allocate the memory required by the algorithm model.

Note

Before this interface is called for calculation, the Init interface must be called to initialize the FIRSparsePolicy standard structure.
The initialization of the FIRSparsePolicy structure needs to be applied for in the Init function. You cannot apply for or define this structure by yourself.
After the FIRSparsePolicy structure has been initialized, if a main function fails to be executed, the Release function must be used to release the structure.
src and dst cannot be the same array. Otherwise, the result may be incorrect.

Example

#define TPAS_LEN_S 5
#define DLYLINE_LEN_S 8
#define SRC_LEN_S 7
void FIRSparseExample(void)
{
    int32_t nzTapsLen = TPAS_LEN_S;
    float nzTaps[TPAS_LEN_S] = { 0.1, 0.2, 0.3, 0.4, 0.5 };
    int32_t nzTapsPos[TPAS_LEN_S] = { 1, 3, 4, 6, DLYLINE_LEN_S };
    float *dlyLine1 = NULL;
    float dlyLine2[DLYLINE_LEN_S] = { 0.01, 0.02, 0.03, 0.04, 0.05, 0.06, 0.07, 0.08 };
    float dlyDst[DLYLINE_LEN_S] = { 0.0f };
    int32_t len = SRC_LEN_S;
    float src[SRC_LEN_S] = { 0.2107, -40.6842, 17.1776, -15.6654, -2.407, -0.8981, 0.2883 };
    float dst[SRC_LEN_S] = { 0.0f };

    HmppsFIRSparsePolicy_32f *policy = NULL;
    HmppResult result;

    result = HMPPS_FIRSparseInit_32f(nzTaps, nzTapsPos, nzTapsLen, dlyLine1, &policy);
    printf("HMPPS_FIRSparseInit_32f result = %d\n", result);
    if (result != HMPP_STS_NO_ERR) {
        return;
    }
    result = HMPPS_FIRSparseSetDlyLine_32f(policy, dlyLine2);
    printf("HMPPS_FIRSparseSetDlyLine_32f result = %d\n", result);
    if (result != HMPP_STS_NO_ERR) {
        HMPPS_FIRSparseRelease_32f(policy);
        return;
    }
    result = HMPPS_FIRSparse_32f(src, dst, len, policy);
    printf("HMPPS_FIRSparse_32f result = %d\n", result);
    if (result != HMPP_STS_NO_ERR) {
        HMPPS_FIRSparseRelease_32f(policy);
        return;
    }
    result = HMPPS_FIRSparseGetDlyLine_32f(policy, dlyDst);
    printf("HMPPS_FIRSparseGetDlyLine_32f result = %d\n", result);
    HMPPS_FIRSparseRelease_32f(policy);
    policy = NULL;
    if (result != HMPP_STS_NO_ERR) {
        return;
    }

    int32_t i;
    printf("len = %d\ndst =", len);
    for(i = 0; i < len; ++i){
        printf(" %f", dst[i]);
    }
    printf("\ndlyDstLen = %d\ndlyDst =", DLYLINE_LEN_S);
    for(i = 0; i < DLYLINE_LEN_S; ++i){
        printf(" %f", dlyDst[i]);
    }
    printf("\n");
}

Output:

HMPPS_FIRSparseInit_32f result = 0
HMPPS_FIRSparseSetDlyLine_32f result = 0
HMPPS_FIRSparse_32f result = 0
HMPPS_FIRSparseGetDlyLine_32f result = 0
len = 7
dst = 0.083000 0.089070 -4.014420 1.799900 -9.612170 -8.991440 2.024671
dlyDstLen = 8
dlyDst = 0.288300 -0.898100 -2.407000 -15.665400 17.177601 -40.684200 0.210700 0.010000

Parent topic: Filtering Algorithms