Overview of Matrix Reduction Functions

Table of Contents

• What is a Matrix Row Reduction?
• Function Categories
  • Const vs. Non-Const Matrix
  • Basic vs. WithArgument Variants
  • Scope and Conditional Variants (Which Rows to Process)
• Complete Function Matrix
  • Basic Reduction Functions
  • WithArgument Reduction Functions
• Common Parameters
• Behavior for Empty Rows
• Usage Guidelines
• Related Pages

This page provides an overview of all reduction functions available for matrix operations, helping to understand the differences between variants and choose the right function for your needs.

What is a Matrix Row Reduction?

A matrix row reduction performs a reduction operation (like sum, max, min) across the elements within each row of a matrix, producing one result per row. This is a fundamental operation for:

• Computing row sums, products, or norms
• Finding maximum/minimum values in each row
• Identifying specific elements (argmax, argmin)
• Row-level statistics and analysis

Function Categories

Matrix reduction functions are organized along three independent axes:

Const vs. Non-Const Matrix

Category	Matrix Modifiable?	Use Case
Non-const	Yes	Can modify matrix elements during reduction
Const	No	Read-only access to matrix elements

Note: Each reduction function has both const and non-const overloads. The possibility to modify the matrix during reduction allows to fuse reduction with traversing operations into a single pass. This can improve performance by reducing memory accesses.

Basic vs. WithArgument Variants

Category	Tracks Position?	Use Case
Basic	No	Only the reduced value is needed (e.g., row sum, row max)
WithArgument	Yes	Need value and column position (e.g., max value location)

Scope and Conditional Variants (Which Rows to Process)

Scope	Rows Processed	Parameters
All	All rows	No range/array parameters
Range	Rows [begin, end)	begin and end indices
Array	Specific rows	Array of row indices
If	Rows filtered by a condition	Process rows based on row-level properties

Complete Function Matrix

All reduction functions follow this naming pattern: reduce[Scope]Rows[WithArgument][If]

Each function has both const and non-const overloads (×2 multiplier).

Basic Reduction Functions

Function	Scope	Conditional	Tracks Position	Overloads
reduceAllRows	All	No	No	const & non-const
reduceRows (range)	Range [begin,end)	No	No	const & non-const
reduceRows (array)	Row array	No	No	const & non-const
reduceAllRowsIf	All	Yes	No	const & non-const
reduceRowsIf	Range [begin,end)	Yes	No	const & non-const
reduceRowsIf (array)	Row array	Yes	No	const & non-const

WithArgument Reduction Functions

Function	Scope	Conditional	Tracks Position	Overloads
reduceAllRowsWithArgument	All	No	Yes	const & non-const
reduceRowsWithArgument (range)	Range [begin,end)	No	Yes	const & non-const
reduceRowsWithArgument (array)	Row array	No	Yes	const & non-const
reduceAllRowsWithArgumentIf	All	Yes	Yes	const & non-const
reduceRowsWithArgumentIf (range)	Range [begin,end)	Yes	Yes	const & non-const
reduceRowsWithArgumentIf (array)	Row array	Yes	Yes	const & non-const

All variants with an array of row indexes accept either the whole array or an interval [begin, end) of its positions. The parameter indexOfRowIdx of the store lambda function is the position within the whole array for the unconditional variants and the rank of the row among the processed rows for the conditional variants.

Common Parameters

All reduction functions share these common parameters:

• matrix: The matrix to reduce (const or non-const)
• fetch: Lambda that retrieves element values (see For Non-Const Matrices or For Const Matrices)
• reduction: Lambda or function object that combines values (see Basic Reduction (Without Arguments) or Reduction With Argument (Position Tracking))
• store: Lambda that stores the reduction results (see Basic Store (Row Index Only) or variants)
• identity: The identity element for the reduction (e.g., 0 for addition, 1 for multiplication)
• launchConfig: Configuration for parallel execution (optional)

Additional parameters:

• Scope variants: begin, end (range) or rowIndexes (array)
• If variants: condition lambda for row filtering (see Condition Check)

Behavior for Empty Rows

An empty row is a row that contains no matrix elements to reduce over. This can happen, for example, with sparse matrices that have a row with zero non-zero elements (even if the row contains padding elements), with multidiagonal/tridiagonal matrices where all diagonals fall outside the valid column range for a given row, or with lambda matrices where all elements of a row are zero.

The behavior depends on the reduction variant:

• Basic reduction (reduceAllRows, reduceRows, etc.): The store lambda is called with the identity value. The user is responsible for choosing an identity that is a meaningful neutral element for the reduction (e.g., 0 for sum, 1 for product, \(-\infty\) for max).
• WithArgument reduction (reduceAllRowsWithArgument, reduceRowsWithArgument, etc.): The store lambda is called with emptyRow set to true. In this case, the localIdx and columnIdx values passed to the store lambda are meaningless and should not be used. The value parameter is set to the identity value.

Usage Guidelines

Matrix type considerations:

• Sparse matrices: Fetch lambda receives even mutable column index for non-const matrices
• Dense/structured matrices: Column index is implicit, passed by value
• Choose fetch lambda signature based on matrix type (see Fetch Lambda Functions)

Related Pages

• Matrix Reduction Lambda Function Reference - Detailed lambda function signatures
• Overview of Matrix Traversal Functions - Matrix traversal operations