Template Numerical Library: Overview of Matrix Traversal Functions

Template Numerical Library version\ main:c7077e4fd

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

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

# What is Matrix Traversal?

Matrix traversal operations apply a user-defined function to matrix elements or rows. Unlike reductions (which compute results), traversals are used for side effects:

- Modifying matrix elements in-place
- Performing computations that depend on element positions
- Implementing custom matrix algorithms

# Function Categories

Matrix traversal functions are organized along three main dimensions:

## Const vs. Non-Const Matrix

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

Note: Each traversal function has both const and non-const overloads.

## Element-wise vs. Row-wise Traversal

Category | Operates On | Lambda Parameter | Use Case
--- | --- | --- | ---
Element-wise (forElements, forAllElements) | Individual elements | Element indices & values | Operate on each element separately
Row-wise (forRows, forAllRows) | Whole rows | RowView object | Operate on rows as units

## Scope and Conditional Variants

Similar to other matrix operations, traversal functions have different scope and conditional variants.

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

# Element-wise Traversal Functions

These functions iterate over individual elements within matrix rows:

## Basic Element Traversal

Function | Rows Processed | Description | Overloads
--- | --- | --- | ---
forAllElements | All rows | Process all elements in all rows | const & non-const
forElements (range) | Rows [begin, end) | Process elements in row range | const & non-const
forElements (array) | Rows in array | Process elements in specified rows | const & non-const
forAllElementsIf | All rows | Row-level condition | const & non-const
forElementsIf | Rows [begin, end) | Row-level condition | const & non-const

When to use:

- Matrix elements assembly and updates
- Element-level operations and transformations

# Row-wise Traversal Functions

These functions iterate over rows as whole units using RowView:

## Basic Row Traversal

Function | Rows Processed | Description | Overloads
--- | --- | --- | ---
forAllRows | All rows | Process all rows | const & non-const
forRows (range) | Rows [begin, end) | Process rows in range | const & non-const
forRows (array) | Rows in array | Process specified rows | const & non-const
forAllRowsIf | All rows | Row-level condition | const & non-const
forRowsIf | Rows [begin, end) | Row-level condition | const & non-const

When to use:

- Row-level operations (scaling, normalization)

# Common Parameters

All traversal functions share these common parameters:

- matrix: The matrix to traverse (const or non-const)
- function: Lambda function to apply (see Traversal Function (Non-Const Matrix), Traversal Function (Const Matrix), Row Traversal Function (Non-Const Matrix), or Row Traversal Function (Const Matrix))
- launchConfig: Configuration for parallel execution (optional)

Additional parameters:

- Scope variants: begin, end (range) or rowIndexes (array)
- If variants: condition lambda for filtering (see Condition Lambda)

# Usage Guidelines

Matrix type considerations:

- Sparse matrices (SparseMatrix, SparseMatrixView):
  - Element traversal: Can modify even column indices for non-const matrices
  - Row traversal: Use RowView for efficient sparse operations
- Dense matrices (DenseMatrix, DenseMatrixView):
  - Column indices are implicit
  - Element traversal processes all elements in each row
- Structured matrices (Tridiagonal, Multidiagonal) (NOT IMPLEMENTED YET):
  - Column indices follow fixed patterns
  - Element traversal only processes non-zero structure

Performance considerations:

- Element-wise traversal is is parallel within rows, i.e. one matrix row can be processed by multiple threads
- Row-wise traversal never maps multiple threads to the same row. Row-wise traversal is therefore preferred when row-level context is needed.

# Related Pages

- Matrix Traversal Lambda Functions Reference - Detailed lambda function signatures
- Overview of Matrix Reduction Functions - Matrix reduction operations