dsp.ParallelFilter

Create parallel sum filter structure

Since R2023b

Description

The dsp.ParallelFilter object is a parallel sum filter structure where each branch is a filter System object™ or a scalar value. The object passes the input signal through each of its branches and sums the filtered output from each branch.

To see a list of filter objects that you can add as branches to the parallel filter stack, run this command in the MATLAB^® command prompt.

dsp.ParallelFilter.helpSupportedSystemObjects

To create a parallel sum filter structure:

1. Create the dsp.ParallelFilter object and set its properties.

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

To learn more about how System objects work, see What Are System Objects?

Alternatively, you can use the parallel function to create a dsp.ParallelFilter object. However, when you use the parallel function, you must specify at least one branch to be a filter object.

Using the generateFilteringCode function, you can generate a MATLAB function script from the parallel filter object, and call that function to filter a signal. The generated function supports C/C++ code generation if the filters in each branch support code generation.

Creation

Syntax

pf = dsp.ParallelFilter

pf = dsp.ParallelFilter(filt1,filt2,...,filtn)

pf = dsp.ParallelFilter(___, CloneBranches=flag)

Description

pf = dsp.ParallelFilter returns a parallel filter System object that has a single branch of dsp.FIRFilter System object with default properties.

pf = dsp.ParallelFilter(filt1,filt2,...,filtn) returns a System object with parallel branches of filters. The first branch is set to filt1, the second branch is set to filt2, and so on. Each branch can be a filter System object or a scalar gain value.

For example, create a parallel filter that includes a lowpass filter, a highpass filter, and a gain branch.

lpFilt = dsp.LowpassFilter(StopbandFrequency=15000, ...
                           PassbandFrequency=12000);
hpFilt = dsp.HighpassFilter(StopbandFrequency=5000, ...
                            PassbandFrequency=8000);
gain = 2;
pf = dsp.ParallelFilter(lpFilt,hpFilt,gain)

pf = 
  dsp.ParallelFilter with properties:

          Branch1: [1×1 dsp.LowpassFilter]
          Branch2: [1×1 dsp.HighpassFilter]
          Branch3: 2
    CloneBranches: true

pf = dsp.ParallelFilter(___, CloneBranches=flag) sets the CloneBranches property to true or false. Use this syntax in combination with any of the input arguments in previous syntaxes.

Properties

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.

For more information on changing property values, see System Design in MATLAB Using System Objects.

Branchi — Filter branch

dsp.FIRFilter System object with default properties (default) | filter System object | scalar gain value

Filter branch, specified as a filter System object or a scalar gain value. To see a list of System objects you can add as filter branches, run this command in the MATLAB command prompt:

dsp.ParallelFilter.helpSupportedSystemObjects

All branches of the parallel filter must have the same rate conversion factor.

To add or remove branches in the parallel filter, use the addBranch and removeBranch functions.

CloneBranches — Branch cloning flag

true (default) | false

Branch cloning flag, specified as:

• false –– The parallel filter branches assigned to the dsp.ParallelFilter object occupy the same memory as the branches you provide. You can add branches while creating the dsp.ParallelFilter object by direct assignment or by using the addBranch function.

• true –– The branches stored in the dsp.ParallelFilter object are clones of the branches you provide and do not occupy the same memory.

For an example that shows the difference between these two settings, see Compare Branch Cloning with Branch Referencing.

You can set this parameter only when you are constructing the dsp.ParallelFilter object.

Data Types: logical

Usage

Syntax

y = pf(x)

Description

y = pf(x) runs the input x through each branch of the parallel filter pf, sums the outputs from each branch, and returns the resultant output y. All branches of the parallel filter must support the size, data type, and complexity of the input signal.

This object supports variable-size signals if all the filter branches within the object support variable-size signals.

Input Arguments

x — Data input

vector | matrix

Data input, specified as a vector or a matrix. When the input is a matrix, each column of the matrix represents an independent data channel.

Data Types: single | double
Complex Number Support: Yes

Output Arguments

y — Filtered output data

vector | matrix

Filtered output data, returned as a vector or a matrix. The size, data type, and complexity of the output signal matches that of the input signal.

Data Types: double | single
Complex Number Support: Yes

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)

Specific to dsp.ParallelFilter

addBranch	Add new filter branch to parallel filter
generateFilteringCode	Generate MATLAB code to filter signals using parallel filter structure
getNumBranches	Get number of branches in parallel filter
releaseBranches	Call release on all branches in parallel filter
removeBranch	Remove branch from parallel filter
clone	Create duplicate System object

Filter Analysis Functions

parallel	Create parallel sum filter structure
filterAnalyzer	Analyze filters with Filter Analyzer app
info	Information about filter System object
freqz	Frequency response of discrete-time filter System object
freqzmr	Compute DTFT approximation of impulse response of multirate or single-rate filter
coeffs	Returns the filter System object coefficients in a structure
cost	Estimate cost of implementing filter System object
outputDelay	Determine output delay of single-rate or multirate filter

Common to All System Objects

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

Construct Parallel Filter

You can construct a parallel filter using the dsp.ParallelFilter object or the parallel function.

First, create the branches.

B1 = dsp.FIRFilter;
B2 = dsp.Delay(3);
B3 = 2;

Specify these branches while constructing the dsp.ParallelFilter object.

pf1 = dsp.ParallelFilter(B1,B2,B3)

pf1 = 
  dsp.ParallelFilter with properties:

          Branch1: [1x1 dsp.FIRFilter]
          Branch2: [1x1 dsp.Delay]
          Branch3: 2
    CloneBranches: true

You can also use the addBranch function to add branches to the default parallel filter.

pf2 = dsp.ParallelFilter(B1);
addBranch(pf2,B2,B3);
pf2

pf2 = 
  dsp.ParallelFilter with properties:

          Branch1: [1x1 dsp.FIRFilter]
          Branch2: [1x1 dsp.Delay]
    CloneBranches: true

Now, use the parallel filter function to construct a dsp.ParallelFilter object.

pf3 = parallel(B1,B2,B3)

pf3 = 
  dsp.ParallelFilter with properties:

          Branch1: [1x1 dsp.FIRFilter]
          Branch2: [1x1 dsp.Delay]
          Branch3: 2
    CloneBranches: true

Filter Signal Using Polyphase FIR Decimator

Implement a polyphase FIR decimator using the dsp.ParallelFilter object and visualize its frequency response.

Design Decimator

Design an FIR antialiasing lowpass filter with a decimation factor of 3 using the designMultirateFIR function.

M = 3;
coeffs = designMultirateFIR(1,M);

Implement the FIR decimator as a polyphase structure. For more information about polyphase structures, see the Algorithms section in dsp.FIRDecimator. Here, create the structure using a parallel filter with three branches (as indicated by the decimation factor). Each branch is a cascade of dsp.FIRDecimator, dsp.Delay, and dsp.FIRFilter objects.

branches = cell(1,M);
for phase=1:M
    downsample = dsp.FIRDecimator(M,1); % Trivial downsample
    phaseDelay = dsp.Delay(phase-1);
    phaseFIR = dsp.FIRFilter(coeffs(phase:3:end));
    branches{phase} = cascade(phaseDelay, downsample, phaseFIR);
end

PFdecim = dsp.ParallelFilter(branches{:})

PFdecim = 
  dsp.ParallelFilter with properties:

          Branch1: [1x1 dsp.FilterCascade]
          Branch2: [1x1 dsp.FilterCascade]
          Branch3: [1x1 dsp.FilterCascade]
    CloneBranches: true

Visualize the frequency response of the decimator.

filterAnalyzer(PFdecim)

Decimate by 3

The input is a cosine wave that has an angular frequency of $\frac{\pi }{4}$ radians per sample.

x = cos(pi/4*(0:95)');

Decimate the cosine signal by a factor of 3.

y = PFdecim(x);

Plot Data

Plot the original and the decimated signals. In order to plot the two signals on the same plot, you must account for the output delay of the FIR decimator and the scaling introduced by the filter. Use the outputDelay function to compute the delay value introduced by the decimator. Shift the output by this delay value.

Visualize the input and the resampled signals. After a short transition, the output converges to a cosine of frequency $\frac{3\pi }{4}$ as expected, which is three times the frequency of the input signal $\frac{\pi }{4}$. Due to the decimation factor of 3, the output samples coincide with every third input sample.

[delay,FsOut] = outputDelay(PFdecim,Fc=0)

delay = 
36

FsOut = 
0.3333

nx = (0:length(x)-1);
ty = (0:length(y)-1)/FsOut-delay;
stem(ty,y,'filled',MarkerSize=4); hold on;
stem(nx,x); hold off;
xlim([-10,22])
ylim([-2.5 2.5])
legend('Decimated by 3 (y)','Input signal (x)');

Compare Branch Cloning with Branch Referencing

When you set the CloneBranches property to false, the branches stored in the dsp.ParallelFilter object are references to the branches you provide and reside in the same memory location. Any changes you make to the branches you provide update the branches stored in the dsp.ParallelFilter object. For example, if you update a property in one of the branches you provide, the parallel filter with CloneBranches set to false updates the same property in its stored branches.

When you set the CloneBranches property to true, the branches stored in the dsp.ParallelFilter object are clones of the branches you provide and do not occupy the same memory. Any changes you make to the branches you provide have no impact on the branches stored in the dsp.ParallelFilter object.

Construct two parallel filters, one with CloneBranches set to true and the other with CloneBranches set to false. The two branches you provide B1 and B2 contain the dsp.FIRInterpolator and dsp.FIRDecimator, respectively.

B1 = dsp.FIRInterpolator(13);
B2 = dsp.FIRDecimator(17);
pf_clone = dsp.ParallelFilter(B1,B2)

pf_clone = 
  dsp.ParallelFilter with properties:

          Branch1: [1x1 dsp.FIRInterpolator]
          Branch2: [1x1 dsp.FIRDecimator]
    CloneBranches: true

pf_ref = dsp.ParallelFilter(B1,B2, CloneBranches = false)

pf_ref = 
  dsp.ParallelFilter with properties:

          Branch1: [1x1 dsp.FIRInterpolator]
          Branch2: [1x1 dsp.FIRDecimator]
    CloneBranches: false

Change the InterpolationFactor to 19 in B1.

B1.InterpolationFactor = 19

B1 = 
  dsp.FIRInterpolator with properties:

    InterpolationFactor: 19
        NumeratorSource: 'Property'
              Numerator: [0 -2.0633e-05 -4.7889e-05 -8.0608e-05 -1.1674e-04 -1.5337e-04 -1.8683e-04 -2.1293e-04 -2.2722e-04 -2.2540e-04 -2.0373e-04 -1.5948e-04 -9.1387e-05 0 1.1201e-04 2.3970e-04 3.7591e-04 5.1143e-04 6.3545e-04 ... ] (1x312 double)

  Use get to show all properties

Display the value of InterpolationFactor stored in Branch1 of both parallel filters. The change in interpolation factor of B1 does not affect the interpolation factor of Branch1 in the clone parallel filter, pf_clone. However, the same change updates the interpolation factor of Branch1 in the reference parallel filter, pf_ref.

pf_clone.Branch1.InterpolationFactor   % no sync (clone)

ans = 
13

pf_ref.Branch1.InterpolationFactor     % sync (reference)

ans = 
19

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• You cannot generate code directly from dsp.ParallelFilter. If the filters in each branch support code generation, you can generate C/C++ code from the function returned by generateFilteringCode.

• See System Objects in MATLAB Code Generation (MATLAB Coder).

Version History

Introduced in R2023b