Overview of Segment Reduction Functions

Table of Contents

• Function Categories
  • Basic vs. WithArgument Variants
  • Scope and Conditional Variants (Which Segments to Process)
• Complete Function Matrix
  • Basic Reduction Functions
  • WithArgument Reduction Functions
• Common Parameters
• Usage Guidelines
• Behavior for Empty Segments
• Related Pages

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.

Behavior for Empty Segments

An empty segment is a segment of zero size, i.e. a segment that contains no elements to reduce over. Note that the segments know nothing about the meaning of their elements. A segment of nonzero size is not empty even if the fetch lambda returns the identity for all its elements (e.g., for the padding elements of sparse matrices).

The behavior depends on the reduction variant:

• Basic reduction (reduceAllSegments, reduceSegments, etc.): The storer 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 (reduceAllSegmentsWithArgument, reduceSegmentsWithArgument, etc.): The storer lambda is called with emptySegment set to true. In this case, the localIdx value passed to the storer lambda is meaningless and should not be used. The value parameter is set to the identity value.

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