Template Numerical Library: Overview of Segment Reduction Functions

Template Numerical Library version\ main:0b2c40fb1

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

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

# Function Categories

The segment reduction functions are organized along three independent axes:

## Basic vs. WithArgument Variants

Category | Tracks Position? | Use Case
--- | --- | ---
Basic | No | Only the reduced value is needed (e.g., sum, product)
WithArgument | Yes | Need both the value and its position (e.g., max value and where it occurs)

## Scope and Conditional Variants (Which Segments to Process)

Scope | Segments Processed | Parameters
--- | --- | ---
All | All segments | No range/array parameters
Range | Segments [begin, end) | begin and end indices
Array | Specific segments | Array of segment indices
If | Segment condition | Process segments based on segment-level properties

# Complete Function Matrix

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

## Basic Reduction Functions

Function | Scope | Conditional | Tracks Position
--- | --- | --- | ---
Segments_reduceAllSegments | All | No | No
Segments_reduceSegments_range (range) | Range [begin,end) | No | No
Segments_reduceSegments_with_segment_indices (array) | Segment array | No | No
Segments_reduceAllSegmentsIf | All | Yes | No
Segments_reduceSegmentsIf | Range [begin,end) | Yes | No

## WithArgument Reduction Functions

Function | Scope | Conditional | Tracks Position
--- | --- | --- | ---
Segments_reduceAllSegmentsWithArgument | All | No | Yes
Segments_reduceSegmentsWithArgument_range (range) | Range [begin,end) | No | Yes
Segments_reduceSegmentsWithArgument_with_segment_indices (array) | Segment array | No | Yes
Segments_reduceAllSegmentsWithArgumentIf | All | Yes | Yes
Segments_reduceSegmentsWithArgumentIf | Range [begin,end) | Yes | Yes

# Common Parameters

All reduction functions share these common parameters:

- segments: The segments container to reduce
- fetch: Lambda that retrieves element values (see Full Form (With All Parameters) or Brief Form (Global Index Only))
- reduction: Lambda or function object that combines values (see Basic Reduction (Without Arguments) or Reduction With Argument (Position Tracking))
- storer: Lambda that stores the reduction results (see Basic Storer (Segment 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 for specific variants:

- Scope variants: begin, end (range) or segmentIndexes (array)
- If variants: condition lambda for segment filtering (see Condition Check)

# Usage Guidelines

Performance considerations:

- Use the brief form of fetch lambda when possible for better performance.
- Use *If variants to skip unnecessary segments.
- Consider using function objects instead of lambda reductions for common operations.
- Range and array overloads avoid processing unnecessary segments.
- The fetch lambda can even modify data on-the-fly if needed and thus it allows merging multiple operations into one kernel and improving performance.

# Related Pages

- Segment Reduction Lambda Function Reference - Detailed lambda function signatures
- Function objects for reduction operations - Pre-defined reduction function objects
- Function objects for reduction operations with argument - Reduction objects with position tracking