hdl.iterfun

R2026b

Reduce frame-based data to frame-level characteristics

Since R2026b

Syntax

out = hdl.iterfun(kernelFcn,frame)

out = hdl.iterfun(kernelFcn,frame1,...,frameN)

[out1,...,outN] = hdl.iterfun(___)

___ = hdl.iterfun(___,"KernelArg",arg)

___ = hdl.iterfun(___,Name=Value)

Description

out = hdl.iterfun(kernelFcn,frame) applies the kernel function, kernelFcn, to each element of the frame-based input data, frame, and outputs the final iteration of the kernel function.

out = hdl.iterfun(kernelFcn,frame1,...,frameN) applies the kernel function to multiple frame-based inputs and outputs one argument.

[out1,...,outN] = hdl.iterfun(___) applies the kernel function to each element of the frame-based input data and outputs the same number of outputs as the kernel function.

___ = hdl.iterfun(___,"KernelArg",arg) passes the non-frame-based value arg to the kernel function on every iteration. The function does not iterate on the value of arg.

___ = hdl.iterfun(___,Name=Value) specifies one or more name-value arguments. Specify the name-value arguments after all the arguments in any of the previous syntaxes.

Examples

Compute Maximum Value of Frame-Based Input Data

Compute the maximum value across all elements of a frame-based input.

Create the frame-based input data.

frame = randi(100,1,10);

The maxKernel function computes the maximum value across all elements in the frame-based input data. The persistent variable, p, maintains state across iterations by storing the running maximum. This kernel does not implement reset behavior for the state.

function out = maxKernel(in)
persistent p
if isempty(p)
    p = in;
end
if in > p
    p = in;
end
out = p;
end

Use hdl.iterfun to apply maxKernel to each element by streaming the input data in frame.

maxVal = hdl.iterfun(@maxKernel,frame);

Reduce Multiple Frame-Based Inputs to Individual Sums

Compute the sum of all elements for multiple frame-based inputs and output each sum individually.

Create the frame-based input data.

frameA = [1 2 3];
frameB = [4 5 6];

The kernel function sumKernel sums the elements in each frame and returns each sum as an independent output.

function [outa,outb] = sumKernel(a,b)
persistent acca accb
if isempty(acca)
    acca = 0;
    accb = 0;
end
acca = acca + a;
accb = accb + b;
outa = acca;
outb = accb;
end

Use hdl.iterfun to apply sumKernel to each element by streaming the input data in frame.

[out1, out2] = hdl.iterfun(@sumKernel,frameA,frameB);

Reset State at Frame Start by Using Row and Column Inputs

Compute the maximum value of all elements in a frame-based input, then reset the maximum value before evaluating the next frame-based input.

Create the frame-based input data.

frame = randi(100,1,10);

Create a function named maxKernelReset that has the input arguments in, row, and col. The function uses the row and column indices, row and col, to reset the frame maximum after iterating through each frame-based input. Define the row and col input arguments after all other kernel function input arguments.

function out = maxKernelReset(in,row,col)
persistent p
if isempty(p)
    p = 0;
end
if row == 1 && col == 1
    p = 0;
end
if in > p
    p = in;
end
out = p;
end

Use hdl.iterfun to apply maxKernelReset to each element by streaming the input data in frame. To pass the row and column indices for each iteration to the kernel function, set RowColumnInputs to true.

out = hdl.iterfun(@maxKernelReset,frame,RowColumnInputs=true);

Input Arguments

kernelFcn — User-defined kernel function

function handle

User-defined kernel function, specified as a function handle.

The kernel function must:

• Be a named user function

• Not be an anonymous function

• Have a fixed number of inputs and outputs

• Not use the varargin or varargout functions

To maintain the iteration state, use persistent variables. To clear state between frames, the kernel must contain reset behavior.

hdl.iterfun calls the function specified by kernelFcn function once per element for each of the frame-based inputs in hdl.iterfun and computes an output. The function then outputs the output produced by the kernel function on the final iteration.

Example: @maxKernel

Data Types: function_handle

frame — Iterated frame-based inputs

2-D numeric array | 3-D numeric array

Iterated frame-based inputs, specified as a 2-D or 3-D numeric array.

The iterated frame-based inputs must have the same size. hdl.iterfun invokes the kernel function with corresponding elements from each frame-based input.

When you specify more than one frame-based input, hdl.iterfun iterates over the frames in conjunction.

Example: out = hdl.iterfun(@kernelFcn,frame1,frame2);

arg — Non-streamed kernel function input data

scalar | vector | 2-D matrix

Non-streamed kernel function input data, specified as a scalar, vector, or 2-D matrix. This value can be any input that is not streamed from frame to samples by frame-to-sample conversion. You can specify multiple kernel arguments by repeating the "KernelArg" argument. For example:

value1 = 3;
value2 = 6;

out = hdl.iterfun(@kernelFcn,frame1,"KernelArg",value1,"KernelArg",value2);

function y = kernelFcn(inFrame,value1,value2)
...
end

Example: out = hdl.iterfun(@kernelFcn,frame1,"KernelArg",3);

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: RowColumnInputs=true

InputProcessingOrder — Order in which function traverses over input frames in simulation

"RowMajor" (default) | "ColumnMajor"

Order in which the function traverses over the input frames in simulation, specified as "RowMajor" or "ColumnMajor".

If the kernel function uses persistent variables, the value of InputProcessingOrder must match the Input processing order HDL configuration parameter.

Example: out = hdl.iterfun(@kernelFcn,frame1,InputProcessingOrder="ColumnMajor");

RowColumnInputs — Row and column indices of current output sample

false (default) | true

Row and column indices of the current output sample, specified as a Boolean.

When this argument is true, the function passes the current row index, row, and the current column index, col, to the kernel function input argument list.

You must manually specify the row and col inputs in your kernel function and row and col must be uint32 data types.

Append the row and col inputs after all iterated and non-iterated inputs to the kernel function.

Example: out = hdl.iterfun(@kernelFcn,frame1,RowColumnInputs=true);

Output Arguments

out — Final kernel outputs

scalar | vector | matrix

Final kernel function outputs, returned as a scalar, vector, or matrix.

The number of out arguments must match the number of kernel function outputs. For example:

[kernelOut1, ..., kernelOutN] = kernelFcn(input);

[iterOut1, ..., iterOutN] = hdl.iterfun(@kernelFcn, frame);

Example: [out1, out2] = hdl.iterfun(@kernelFcn,frame1);

Tips

• To use hdl.iterfun, you must enable dataflow representation. To use hdl.iterfun in a MATLAB function, open the MATLAB HDL Workflow Advisor. In the HDL Code Generation task, in the Optimizations tab, enable the Aggressive Dataflow Conversion parameter. To use hdl.iterfun in a MATLAB Function block, set the Architecture HDL block property to Datapath.

Extended Capabilities

HDL Code Generation
Generate VHDL, Verilog and SystemVerilog code for FPGA and ASIC designs using HDL Coder™.

Version History

Introduced in R2026b