Template Numerical Library: Matrix Reduction Lambda Function Reference

Template Numerical Library version\ main:16b9213d5

Loading...
Searching...
No Matches
Matrix Reduction Lambda Function Reference

This page provides a comprehensive reference for all lambda function signatures used in matrix reduction operations.

# Fetch Lambda Functions

The fetch lambda is used to extract and transform values from matrix elements during reduction.

## For Non-Const Matrices

For non-const matrices sparse matrices (TNL::Matrices::SparseMatrix and TNL::Matrices::SparseMatrixView) the signature of the fetch lambda is:

auto fetch = [] __cuda_callable__ ( IndexType rowIdx, IndexType& columnIdx, RealType& value ) -> FetchValue { ... }
__cuda_callable__
#define __cuda_callable__
Definition Macros.h:49

Parameters:

- rowIdx - The index of the matrix row
- columnIdx - The index of the matrix column (can be modified)
- value - The value of the matrix element (can be modified)
- Returns: A value of type FetchValue to be used in the reduction

For other types matrices like dense (TNL::Matrices::DenseMatrix, TNL::Matrices::DenseMatrixView), tridiagonal matrices (TNL::Matrices::TridiagonalMatrix, TNL::Matrices::TridiagonalMatrixView) or multidiagonal (TNL::Matrices::MultidiagonalMatrix, TNL::Matrices::MultidiagonalMatrixView), the column index is defined implicitly and cannot be changed even for non-constant matrices. The signature then reads as:

auto fetch = [] __cuda_callable__ ( IndexType rowIdx, IndexType columnIdx, RealType& value ) -> FetchValue { ... }

Parameters:

- rowIdx - The index of the matrix row
- columnIdx - The index of the matrix column (passed by value)
- value - The value of the matrix element (can be modified)
- Returns: A value of type FetchValue to be used in the reduction

## For Const Matrices

auto fetch = [] __cuda_callable__ ( IndexType rowIdx, IndexType columnIdx, const RealType& value ) -> FetchValue { ... }

Parameters:

- rowIdx - The index of the matrix row
- columnIdx - The index of the matrix column (passed by value)
- value - The value of the matrix element (const reference)
- Returns: A value of type FetchValue to be used in the reduction

# Reduction Lambda Functions

The reduction lambda defines how values are combined during the reduction operation.

## Basic Reduction (Without Arguments)

auto reduction = [=] __cuda_callable__ ( const FetchValue& a, const FetchValue& b ) -> FetchValue { ... }

Parameters:

- a - First value to be reduced
- b - Second value to be reduced
- Returns: The result of reducing a and b

## Reduction With Argument (Position Tracking)

auto reduction = [] __cuda_callable__ ( Result& a, const Result& b, Index& aIdx, const Index& bIdx ) -> Result { ... }

Parameters:

- a - First value to be reduced (mutable reference)
- b - Second value to be reduced (const reference)
- aIdx - Index/position associated with value a (mutable reference for tracking)
- bIdx - Index/position associated with value b (const reference)

Note: This variant is used when you need to track which element produced the final result (e.g., finding the maximum value and its position).

# Store Lambda Functions

The store lambda is used to store the final reduction result for each row.

## Basic Store (Row Index Only)

auto store = [=] __cuda_callable__ ( IndexType rowIdx, const FetchValue& value ) { ... }

Parameters:

- rowIdx - The index of the row
- value - The result of the reduction for this row

## Store With Argument (Position Tracking)

auto store = [=] __cuda_callable__ ( IndexType rowIdx, IndexType localIdx, IndexType columnIdx, const Value& value, bool
emptySegment ) { ... }

Parameters:

- rowIdx - The index of the row
- localIdx - The local index of the element within the row (when tracking positions). Has no meaning when emptySegment is true.
- columnIdx - The column index of the element within the row (when tracking positions). Has no meaning when emptySegment is true.
- value - The result of the reduction for this row
- emptySegment - True if the row is empty (contains no elements), false otherwise. When true, localIdx and columnIdx are meaningless.

## Store With Row Index Array Or Condition

auto store = [=] __cuda_callable__ ( IndexType indexOfRowIdx, IndexType rowIdx, const FetchValue& value ) { ... }

Parameters:

- indexOfRowIdx - The position within the rowIndexes array or the rank in the set of rows for which the condition was true.
- rowIdx - The actual index of the row
- value - The result of the reduction for this row

## Store With Row Index Array and With Argument (Position Tracking)

auto store = [=] __cuda_callable__ ( IndexType indexOfRowIdx, IndexType rowIdx, IndexType localIdx, IndexType columnIdx,
const FetchValue& value, bool emptySegment ) { ...
}

Parameters:

- indexOfRowIdx - The position within the rowIndexes array or the rank in the set of rows for which the condition was true.
- rowIdx - The actual index of the row
- localIdx - The position of the element within the row. Has no meaning when emptySegment is true.
- columnIdx - The column index of the element within the row. Has no meaning when emptySegment is true.
- value - The result of the reduction for this row
- emptySegment - True if the row is empty (contains no elements), false otherwise. When true, localIdx and columnIdx are meaningless.

# Condition Lambda Functions

The condition lambda determines which rows should be processed (used in "If" variants).

## Condition Check

auto condition = [=] __cuda_callable__ ( IndexType rowIdx ) -> bool { ... }

Parameters:

- rowIdx - The index of the matrix row
- Returns: true if the row should be processed, false otherwise

# Reduction Function Objects

Instead of lambda functions, reduction operations can also be specified using function objects from Function objects for reduction operations or Function objects for reduction operations with argument.

When using function objects:

- They must provide a static template method getIdentity to automatically deduce the identity value
- For WithArgument variants, they must be instances of Function objects for reduction operations with argument
- Common examples: Min, Max, Sum, Product, MinWithArg, MaxWithArg

# Related Pages

- Overview of Matrix Reduction Functions - Overview of matrix reduction functions