gpucoder.reduce - Optimized GPU implementation for reduction operations - MATLAB (original) (raw)
Optimized GPU implementation for reduction operations
Syntax
Description
[S](#mw%5Ff35c402e-c2bf-4a67-b2d0-d5cc07fd84a8) = gpucoder.reduce([A](#mw%5F36a96ce3-dddb-41e0-98a6-5c629b99092b),[FUN](#mw%5Fb00a263a-a3ab-40fc-ad2c-9745814da340)) aggregates the values in the input array A to a single value by using the function handle FUN. The output S is a scalar.
[S](#mw%5Ff35c402e-c2bf-4a67-b2d0-d5cc07fd84a8) = gpucoder.reduce([A](#mw%5F36a96ce3-dddb-41e0-98a6-5c629b99092b),{@FUN1,@FUN2,...}) aggregates the values in the input array to a single value using every function handle provided in the cell array. The size of output is 1-by-N, where_N_ is the number of function handles.
The code generator uses shuffle intrinsics to perform reduction operations on the GPU. The function aggregates multiple function handles inside a single kernel on the GPU.
[S](#mw%5Ff35c402e-c2bf-4a67-b2d0-d5cc07fd84a8) = gpucoder.reduce(___,[Name=Value](#namevaluepairarguments)) aggregates the values in the input array using the options specified by one or more name-value arguments.
Examples
This example generates CUDA® code that finds the minimum of an array and the sum of its elements greater than a specified threshold.
Write an entry-point function named multireduce that accepts the matrix input A, dimension dim, and a threshold value threshold. Use the gpucoder.reduce function to perform two types of reduction operations on the elements of A along the dimension dim.
function [s1, s2] = multireduce(A, dim, threshold) %codegen fh1 = @min; fh2 = @(a,b) a*(a > threshold) + b*(b > threshold); [s1, s2] = gpucoder.reduce(A, {fh1, fh2}, "dim", dim); end
Specify the input arguments as a 32-by-32 array for the input matrix, a constant value of 2 for the dimension, and a scalar value for the threshold. Run the codegen command to generate the CUDA MEX functionmultireduce_mex.
inputArgs = {rand(32, 32, "double"), coder.Constant(2), 0.5}; cfg = coder.gpuConfig('mex'); codegen -config cfg -args inputArgs multireduce -report
Call multireduce_mex with a constant input value of 2 for the second argument and an input value of 0.5 for the third argument.
[s1, s2] = multireduce_mex(rand(32), 2, 0.5);
Input Arguments
Input array, specified as a vector, matrix, or array. For code generation, the input array must be of numeric or logical data type.
User-defined function, specified as a named or anonymous function handle. The function handle is a binary function and must:
- Accept two inputs and return one output. The type of the inputs and output to the function must match the type of the input array
A. - Be commutative and associative.
If FUN is anonymous, it can refer to variables that exist in the scope where you define the function. You can use these variables in the reduction function in addition to the two input arguments to FUN.
Name-Value Arguments
Specify optional pairs of arguments asName1=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.
Before R2021a, use commas to separate each name and value, and enclose Name in quotes.
Example: gpucoder.reduce(A, {@min, @max}, dim=2);
Reduction dimension, specified as a positive integer scalar.
Example: gpucoder.reduce(A, {@min, @max}, dim=2);
Preprocessing function, specified as a named or anonymous function handle. By default, gpucoder.reduce does not preprocess the input array.
If the preprocess function handle is anonymous, you can refer to variables that exist in the scope where you define the function. You can create preprocessing functions that refer to these variables as well as the input array.
Example: gpucoder.reduce(A,@min, preprocess=@myScale);
Output Arguments
Result of the reduction operation, returned as a scalar, vector, or matrix. During reduction, the function initializes S to the value of one of the elements of the input array A. Then, S takes the actions in the table.
| Shape of A | Number of Function Handles | Input Argument dim | Output S |
|---|---|---|---|
| Vector | 1 | Unspecified | S is a scalar. |
| Vector | N | Unspecified | S is a 1-by-N vector. |
| Matrix | 1 | Specified | The function applies the reduction operation FUN toA along the dimension dim. For example, if size(A) = [8 16 32] and dim = 2, thensize(S) = [8 1 32]. |
| Matrix | N | Specified | The function applies each function handle to A along the dimension dim. For example, if size(A) = [8 16 32], dim = 2, and number of function handles isN, then [s1, s2, … sN] = gpucoder.reduce(___) and size(s1) = [8 1 32]. |
Limitations
gpucoder.reducedoes not support reducing complex arrays.- The user-defined function must accept two inputs and return one output. The data types of the inputs and output must match the data type of the preprocessed input array.
- The user-defined function must be commutative and associative. Otherwise, the behavior of the function is undefined.
- For code generation,
gpucoder.reduceaccepts a limited number of user-defined function handles based on the size of the output data type. For example, you can input up to 46 function handles that output thehalfdata type or up to 11 function handles that output thedoubledata type. If you input too many function handles, code generation generates an error. - For inputs that are of the integer data type, the generated code may contain intermediate computations that reach saturation. In this case, the results from the generated code may not match the simulation results from MATLAB®.
Version History
Introduced in R2019b
You can use input arrays that have the half data type. You can also use anonymous function handles for the reduction and preprocessing functions.
The code generated for gpucoder.reduce has improved performance when you specify the dimension name-value argument dim.
See Also
Apps
Functions
- codegen | coder.gpu.kernel | coder.gpu.kernelfun | coder.gpu.constantMemory | gpucoder.sort | stencilfun | selectdata