IIRSparse

Initializes an arbitrary-order sparse IIR filter and performs filtering.

The sparse filter processes only positions of non-zero taps. It is applicable to high-order situations with a small quantity of non-zero elements. The input vector x(n) is stored in src, and the output vector y(n) is stored in dst.

The formula is as follows:

$\text{[math]}$

During initialization, a non-zero tap vector whose length is nzTapsLen1 + nzTapsLen2, a non-zero tap position vector, and a delay line vector are input, and the tap vector is arranged as follows: $\text{[math]}$

The tap position vector is arranged as follows:

$\text{[math]}$

After the calculation is complete, the delay line stored in policy is updated.

The function calling process is as follows:

Call IIRSparseInit to perform initialization.
Call FIRSparse to perform filtering.
Call FIRSparseGetDlyLine or FirSparseSetDlyLine to retrieve and set the delay line.
Call IIRSparseRelease to release the memory requested by IIRSparseInit.

The function interface is declared as follows:

Initialization:
HmppResult HMPPS_IIRSparseInit_32f(HmppsIIRSparsePolicy_32f **policy, const float *nzTaps, const int32_t *nzTapPos, int32_t nzTapsLen1, int32_t nzTapsLen2, const float *dlyLine);

Filtering:
HmppResult HMPPS_IIRSparse_32f(const float *src, float *dst, int len, HmppsIIRSparsePolicy_32f *policy);

Memory release:
HmppResult HMPPS_IIRSparseRelease_32f(HmppsIIRSparsePolicy_32f *policy);

Return Value

Success: HMPP_STS_NO_ERR
Failure: An error code is returned.

Parameters

Parameter	Description	Value Range	Input/Output
nzTapsLen1	Length of tap vector A	(0, INT_MAX]	Input
nzTapsLen2	Length of tap vector B	(0, INT_MAX]	Input
nzTaps	Pointer to the tap vector	Not null. Elements in this vector cannot be 0.	Input
nzTapsPos	Pointer to the tap position vector	Not null and arranged in ascending order. Elements in this vector cannot be 0.	Input
src	Pointer to the source vector	Not null	Input
dst	Pointer to the destination vector	Not null	Output
dlyLine	Pointer to the delay line vector	The vector can be null. If it is null, the delay line is padded with 0s.	Input
len	Length of the source vector and destination vector	(0, INT_MAX]	Input
policy (in the Init function)	Pointer to the pointer to the IIRSparsePolicy structure	Not null	Output
policy (in the filter and release functions)	Pointer to the IIRSparsePolicy structure	Not null	Input

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 len is less than or equal to 0.
HMPP_STS_SPARSE_ERR	Divide-by-zero error. cannot be 0.
HMPP_STS_IIR_ORDER_ERR	The tap position array is not in ascending order, or pNZTapPos[nzTapsLen1] is 0.
HMPP_STS_MALLOC_FAILED	The Init function failed to allocate the memory required by the algorithm model.

Before this interface is called for calculation, the Init interface must be called to initialize the IIRSparsePolicy standard structure.
The initialization of the IIRSparsePolicy structure must be applied for in the Init function. You cannot apply for or define this structure by yourself.
After the IIRSparsePolicy structure has been initialized, if a main function fails to be executed, the Release function must be used to release the structure.
IIRSparsePolicy stores the current delay line, and the user cannot obtain or set it.

Example

#define TAPS_LEN1 3
#define TAPS_LEN2 2
#define SRC_LEN 5

void IIRSparseExample(void) {
    float nzTaps[TAPS_LEN1 + TAPS_LEN2] = {0.11381195, -0.22762391,  0.11381195, -0.8457246 , -0.30097242};
    int nzTapsPos[TAPS_LEN1 + TAPS_LEN2] = {0, 1, 2, 1, 2};
    float src[SRC_LEN] = {-609.13320264, -797.90780797, -654.27805165, -108.74137918, 24.2107372};
    float dly[TAPS_LEN1 + TAPS_LEN2] = {-578.53248547, 282.88755714, 861.85222751, 342.84958675, 769.01355443};
    float dst[SRC_LEN];
    HmppsIIRSparsePolicy_32f *policy = NULL;
    HmppResult result;

    result = HMPPS_IIRSparseInit_32f(&policy, nzTaps, nzTapsPos, TAPS_LEN1, TAPS_LEN2, dly);
    printf("HMPPS_IIRSparseInit_32f result = %d\n", result);
    if (result != HMPP_STS_NO_ERR) {
        return;
    }
    result = HMPPS_IIRSparse_32f(src, dst, SRC_LEN, policy);
    printf("HMPPS_IIR_32f result = %d\n", result);
    if (result != HMPP_STS_NO_ERR) {
        return;
    }
    int32_t i;
    printf("\ndstLen = %d\ndst =", SRC_LEN);
    for (i = 0; i < SRC_LEN; ++i) {
        printf(" %f", dst[i]);
    }
    printf("\n");
    HMPPS_IIRSparseRelease_32f(policy);
    policy = NULL;
}

Output:

HMPPS_IIRSparseInit_32f result = 0
HMPPS_IIR_32f result = 0

dstLen = 5
dst = -737.520752 346.343597 -33.106266 -30.499273 -11.198996

Parent topic: Filtering Algorithms