# dsphdl.CICInterpolator

Interpolate signal using CIC filter

## Description

The `dsphdl.CICInterpolator` System object™ interpolates an input signal by using a cascaded integrator-comb (CIC) interpolation filter. CIC interpolation filters are a class of linear phase finite impulse response (FIR) filters consisting of a comb part and an integrator part. The CIC interpolation filter structure consists of N sections of cascaded comb filters, a rate change factor of R, and N sections of cascaded integrators. For more information about CIC interpolation filters, see Algorithms.

The System object supports these combinations of input and output data.

• Scalar input and scalar output — Support for fixed and variable interpolation rates

• Scalar input and vector output — Support for fixed interpolation rates only

• Vector input and vector output — Support for fixed interpolation rates only

The System object provides an architecture suitable for HDL code generation and hardware deployment.

The System object supports real and complex fixed-point inputs.

To filter input data with a CIC interpolator filter, follow these steps:

1. Create the `dsphdl.CICInterpolator` object and set its properties.

2. Call the object with arguments, as if it were a function.

## Creation

### Syntax

``cicIntFilt = dsphdl.CICInterpolator``
``cicIntFilt = dsphdl.CICInterpolator(Name,Value)``

### Description

````cicIntFilt = dsphdl.CICInterpolator` creates a CIC interpolator filter System object, `cicIntFilt`, with default properties.```

example

````cicIntFilt = dsphdl.CICInterpolator(Name,Value)` creates the filter with properties set using one or more name-value arguments. Enclose each property name in single quotes.```

## Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the `release` function unlocks them.

If a property is tunable, you can change its value at any time.

Specify whether the System object operates with a fixed or variable interpolation rate.

• `'Property'` — Use a fixed interpolation rate specified by the `InterpolationFactor` property.

• `'Input port'` — Use a variable interpolation rate specified by the `R` input argument.

Note

The System object does not support variable interpolation for these two combinations of input and output:

• Scalar input and vector output

• Vector input and vector output

Specify the interpolation factor as an integer from 1 to 2048. The range of available values depends on the type of input and output data. This value gives the rate at which the System object interpolates the input.

Input DataOutput Data`InterpolationFactor` Valid Values
ScalarScalarInteger from 1 to 2048
ScalarVectorInteger from 1 to 64
VectorVectorInteger from 1 to 64

Note

For vector inputs, select the interpolation factor rate and input vector length such that their multiplication value does not exceed 64.

#### Dependencies

To enable this property, set the InterpolationSource property to `'Property'`.

Specify the upper bound of the range of valid values for the `R` input argument as an integer from 1 to 2048.

Note

The System object does not support variable interpolation for these two combinations of input and output:

• Scalar input and vector output

• Vector input and vector output

#### Dependencies

To enable this property, set the InterpolationSource property to `'Input port'`.

Specify the differential delay of the comb part of the filter as either `1` or `2` cycles.

Specify the number of sections in either the comb part or the integrator part of the System object.

Specify the minimum number of cycles between the valid input samples as `1`, factors of R, or multiples of R based on the type of input and output data, where R is the interpolation factor.

Input DataOutput DataMinimum Number of Cycles Between Valid Input Samples
ScalarScalargreater than or equal to R
ScalarVectorfactors less than R
VectorVector1

#### Dependencies

To enable this property, set the InterpolationSource property to `'Property'`.

Set this property to `true` to compensate for the output gain of the filter.

The latency of the System object changes depending on the type of interpolation you specify, the number of sections, and the value of this property. For more information on the latency of the System object, see Latency.

Choose the data type of the filtered output data.

• `'Full precision'` — The output data type has a word length equal to the input word length plus gain bits.

• `'Same word length as input'` — The output data type has a word length equal to the input word length.

• `'Minimum section word lengths'` — The output data type uses the word length you specify in the OutputWordLength property.

Word length of the output, specified as an integer from 2 to 104.

#### Dependencies

To enable this property, set the OutputDataType property to ```'Minimum section word lengths'```.

When you set this property to `true`, the System object expects a `reset` input argument.

## Usage

### Syntax

``[dataOut,validOut] = cicIntFilt(dataIn,validIn)``
``[dataOut,validOut] = cicIntFilt(dataIn,validIn,R)``
``[dataOut,validOut] = cicIntFilt(dataIn,validIn,reset)``
``[dataOut,validOut] = cicIntFilt(dataIn,validIn,R,reset)``

### Description

````[dataOut,validOut] = cicIntFilt(dataIn,validIn)` filters and interpolates the input data using a fixed interpolation factor only when `validIn` is `true`.```
````[dataOut,validOut] = cicIntFilt(dataIn,validIn,R)` filters the input data using the specified variable interpolation factor `R`. The `InterpolationSource` property must be set to `'Input port'`.```
````[dataOut,validOut] = cicIntFilt(dataIn,validIn,reset)` filters the input data when `reset` is `false` and clears filter internal states when `reset` is `true`. The System object expects the `reset` argument only when you set the ResetInputPort property to `true`.```
````[dataOut,validOut] = cicIntFilt(dataIn,validIn,R,reset)` filters the input data when `reset` is `false` and clears filter internal states when `reset` is `true`. The System object expects the `reset` argument only when you set the ResetInputPort property to `true`. The `InterpolationSource` property must be set to `'Input port'`.```

### Input Arguments

expand all

Specify input data as a scalar or a column vector with a length from 1 to 64. The input data must be a signed integer or signed fixed point with a word length less than or equal to 32.

Data Types: `int8` | `int16` | `int32` | `fi`
Complex Number Support: Yes

Control signal that indicates if the input data is valid. When `validIn` is `1` (`true`), the object captures the values from the `dataIn` argument. When `validIn` is `0` (`false`), the object ignores the values from the `dataIn` argument.

Data Types: `logical`

Use this argument to dynamically specify the variable interpolation rate during run time.

This value must have the data type `fi(0,12,0)` and must be an integer in the range from 1 to the `MaxInterpolationFactor` property value.

#### Dependencies

To enable this argument, set the InterpolationSource property to ```'Input port'```.

Data Types: `fi(0,12,0)`

Control signal that clears internal states. When `reset` is `1` (`true`), the object stops the current calculation and clears internal states. When the `reset` is `0` (`false`) and the input `valid` is `1` (`true`), the object captures data for processing.

For more reset considerations, see the Reset Signal section on the Hardware Control Signals page.

#### Dependencies

To enable this argument, set the ResetInputPort property to `true`.

Data Types: `logical`

### Output Arguments

expand all

CIC-interpolated output data, returned as a scalar or a column vector with a length from 1 to 64.

The OutputDataType property sets the data type of this argument.

Data Types: `int8` | `int16` | `int32` | `fi`
Complex Number Support: Yes

Control signal that indicates if the output data is valid. When `validOut` is `1` (`true`), the object returns valid data from the `dataOut` argument. When `validOut` is `0` (`false`), values from the `dataOut` argument are not valid.

Data Types: `logical`

Control signal that indicates that the object is ready for new input data sample on the next cycle. When `ready` is `1` (`true`), you can specify the `data` and `valid ` inputs for the next time step. When `ready` is `0` (`false`), the object ignores any input data in the next time step.

Data Types: `logical`

## Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named `obj`, use this syntax:

`release(obj)`

expand all

 `getLatency` Latency of CIC interpolation filter
 `step` Run System object algorithm `release` Release resources and allow changes to System object property values and input characteristics `reset` Reset internal states of System object

## Examples

collapse all

This example shows how to use a `dsphdl.CICInterpolator` System object™ to filter and upsample data. This object supports scalar and vector inputs. In this example, two functions are provided to work with scalar and vector input data separately. You can generate HDL code from these functions.

Generate Frames of Random Input Samples

Set up workspace variables for the object to use. The object supports fixed and variable interpolation rates for scalar inputs and only a fixed interpolation rate for vector inputs. The example runs the `HDLCICInterp_maxR8` function when you set the scalar variable to `true` and runs the `HDLCICInterp_vec` function when you set the scalar variable to `false`. For scalar inputs, choose a range of the input `varRValue` values and set the interpolation factor value `R` to the maximum expected interpolation factor. For vector inputs, the input data must be a column vector of size 1 to 64 and `R` must be an integer multiple of the input frame size.

```R = 8; % interpolation factor M = 1; % differential delay N = 3; % number of sections scalar = true; % true for scalar; false for vector if scalar varRValue = [2, 4, 5, 6, 7, 8]; vecSize = 1; else varRValue = R; %#ok fac = (factor(R)); vecSize = fac(randi(length(fac),1,1)); end numFrames = length(varRValue); dataSamples = cell(1,numFrames); varRtemp = cell(1,numFrames); framesize = zeros(1,numFrames); refOutput = []; WL = 0; % Word length FL = 0; % Fraction length ```

Generate Reference Output from `dsp.CICInterpolator` System Object

Generate frames of random input samples and apply the samples to the `dsp.CICInterpolator` System object. Later in this example, you use the output generated by the System object as reference data for comparison. The System object does not support a variable interpolation rate, so you must create and release the object for each change in interpolation factor value.

```totalsamples = 0; for i = 1:numFrames framesize(i) = varRValue(i)*randi([5 20],1,1); dataSamples{i} = fi(randn(vecSize,framesize(i)),1,16,8); ref_cic = dsp.CICInterpolator('DifferentialDelay',M, ... 'NumSections',N, ... 'InterpolationFactor',varRValue(i)); refOutput = [refOutput,ref_cic(dataSamples{i}(:)).']; %#ok release(ref_cic); end ```

Run Function Containing `dsphdl.CICInterpolator` System Object

Set the properties of the System object to match the input data parameters and run the function for your input type. These functions operate on a stream of data samples rather than a frame. You can generate HDL code from these functions.

The example uses the `HDLCICInterp_maxR8` function for a scalar input.

```function [dataOut,validOut] = HDLCICInterp_maxR8(dataIn,validIn,R) %HDLCICInterp_maxR8 % Performs CIC interpolation with an input interpolation factor up to 8. % sampleIn is a scalar fixed-point value. % validIn is a logical scalar value. persistent cic8; if isempty(cic8) cic8 = dsphdl.CICInterpolator('InterpolationSource','Input port', ... 'MaxInterpolationFactor',8, ... 'DifferentialDelay',1, ... 'NumSections',3); end [dataOut,validOut] = cic8(dataIn,validIn,R); end ```

The example uses the `HDLCICInterp_vec` function for a vector input.

```function [dataOut,validOut] = HDLCICInterp_vec(dataIn,validIn) %HDLCICInterp_vec % Performs CIC interpolation with an input vector. % sampleIn is a fixed-point vector. % validIn is a logical scalar value. persistent cicVec; if isempty(cicVec) cicVec = dsphdl.CICInterpolator('InterpolationSource','Property', ... 'InterpolationFactor',8, ... 'DifferentialDelay',1, ... 'NumSections',3); end [dataOut,validOut] = cicVec(dataIn,validIn); end ```

To flush the remaining data, run the object by inserting the required number of idle cycles after each frame using the `latency` variable. For more information, see the GainCorrection property.

Initialize the output to a size large enough to accommodate the output data. The final size is smaller than `totalsamples` due to interpolation.

```if scalar latency = 3 + N + 9; dataOut = zeros(1,totalsamples*R+numFrames*latency); else latency = 3 + (N*(vecSize*R))+ 3*N + 9; %#ok dataOut = zeros(vecSize*R,totalsamples+numFrames*latency); end validOut = zeros(1,size(dataOut,2)); idx=0; for ij = 1:numFrames if scalar dataIn = upsample(dataSamples{ij},R); validIn = upsample(true(1,length(dataSamples{ij})),R); % scalar input with variable interpolation for ii = 1:length(validIn) idx = idx+1; [dataOut(:,idx),validOut(idx)] = HDLCICInterp_maxR8( ... dataIn(ii), ... validIn(ii), ... fi(varRValue(ij),0,12,0)); end for ii = 1:latency idx = idx+1; [dataOut(:,idx),validOut(idx)] = HDLCICInterp_maxR8( ... fi(0,1,16,8), ... false, ... fi(varRValue(ij),0,12,0)); end else % vector input with fixed interpolation for ii = 1:size(dataSamples{ij},2) %#ok idx = idx+1; [dataOut(:,idx),validOut(idx)] = HDLCICInterp_vec( ... dataSamples{ij}(:,ii), ... true); end for ii = 1:latency idx = idx+1; [dataOut(:,idx),validOut(idx)] = HDLCICInterp_vec( ... fi(zeros(vecSize,1),1,16,8), ... false); end end end ```

Compare Function Output with Reference Data

Compare the function results against the output from the `dsp.CICInterpolator` object.

```cicOutput = dataOut(:,validOut==1); refOutput = refOutput(:); fprintf('\nCIC Interpolator\n'); difference = (abs(cicOutput(:)-refOutput(1:numel(cicOutput)))>0); fprintf(['\nTotal number of samples differed between Behavioral ' ... 'and HDL simulation: %d \n'],sum(difference)); ```
```CIC Interpolator Total number of samples differed between Behavioral and HDL simulation: 2773 ```

The latency of the `dsphdl.CICInterpolator` System object™ varies depending on how many integrator and comb sections your filter has, the input vector size, and whether you enable gain correction. Use the `getLatency` function to find the latency of a particular filter configuration. The latency is the number of cycles between the first valid input and the first valid output, assuming the input is continuously valid.

Create a `dsphdl.CICInterpolator` System object and request the latency. The default System object filter has two integrator and comb sections, and the gain correction is disabled.

`hdlcic = dsphdl.CICInterpolator`
```hdlcic = dsphdl.CICInterpolator with properties: InterpolationSource: 'Property' InterpolationFactor: 2 DifferentialDelay: 1 NumSections: 2 NumCycles: 1 GainCorrection: false Show all properties ```
`L_def = getLatency(hdlcic)`
```L_def = 13 ```

Modify the filter object so it has three integrator and comb sections. Check the resulting change in latency.

```hdlcic.NumSections = 3; L_3sec = getLatency(hdlcic)```
```L_3sec = 18 ```

Enable the gain correction on the filter object with vector input size 2. Check the resulting change in latency.

```hdlcic.GainCorrection = true; vecSize = 2; L_wgain = getLatency(hdlcic,vecSize)```
```L_wgain = 33 ```

expand all

## References

[1] Hogenauer, E. “An Economical Class of Digital Filters for Decimation and Interpolation.” IEEE Transactions on Acoustics, Speech, and Signal Processing 29, no. 2 (April 1981): 155–62. https://doi.org/10.1109/TASSP.1981.1163535.

## Version History

Introduced in R2022a