Template Numerical Library: Overview of Matrix Reduction Functions

Template Numerical Library version\ main:c7077e4fd

Loading...
Searching...
No Matches
Overview of Matrix Reduction Functions

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

## 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 [begin,end) | Yes | Yes | const & non-const

# 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)

# 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