Template Numerical Library: Overview of Segment Scan Functions

Template Numerical Library version\ main:0b2c40fb1

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

This page provides an overview of all scan (prefix-sum) functions available for segment operations, helping to understand the differences between variants and choose the right function for your needs.

# Function Categories

## Basic Scan Functions

These functions compute scan within specified segments:

Function | Segments Scanned | Scan Type
--- | --- | ---
Segments_inclusiveScanAllSegments | All segments | Inclusive
Segments_exclusiveScanAllSegments | All segments | Exclusive
Segments_inclusiveScanSegments_range (range) | Segments [begin, end) | Inclusive
Segments_exclusiveScanSegments_range (range) | Segments [begin, end) | Exclusive
Segments_inclusiveScanSegments_with_segment_indices (array) | Segments in array | Inclusive
Segments_exclusiveScanSegments_with_segment_indices (array) | Segments in array | Exclusive

When to use:

- Use *AllSegments when you need to scan all segments
- Use range overload when scanning a contiguous range of segments
- Use array overload when you have a specific, non-contiguous set of segment indices

## Conditional Scan Functions

These functions add segment-level conditions, including only segments that satisfy the condition in the scan:

Function | Segments Scanned | Scan Type
--- | --- | ---
Segments_inclusiveScanAllSegmentsIf | All segments | Inclusive with segment filter
Segments_exclusiveScanAllSegmentsIf | All segments | Exclusive with segment filter
Segments_inclusiveScanSegmentsIf_range | Segments [begin, end) | Inclusive with segment filter
Segments_exclusiveScanSegmentsIf_range | Segments [begin, end) | Exclusive with segment filter

When to use:

- Use these when you want to skip certain elements within segments
- Example: Compute prefix-sum only for positive values, or only for elements meeting specific criteria

## Low-Level Functions

Function | Purpose
--- | ---
Segments_inclusiveScanSegment | Computes inclusive scan for a single segment view
Segments_exclusiveScanSegment | Computes exclusive scan for a single segment view

When to use:

- Use these when you have a SegmentView object and need fine-grained control
- Useful when implementing custom segment algorithms

# Common Parameters

All scan functions share these common parameters:

- segments: The segments container to scan
- fetch: Lambda that retrieves element values (see Fetch Lambda)
- reduce: Function object that combines values (see Reduction Function Object)
- write: Lambda that stores the scan results (see Write Lambda)
- launchConfig: Configuration for parallel execution (optional)

Conditional variants additionally require:

- condition: Lambda that determines if an element should be included (see Condition Lambda)

# Usage Guidelines

In-place vs. out-of-place:

- All scan implementations support in-place operations
- Your write lambda can modify the same array that fetch reads from
- For out-of-place scans, write to a different array

Performance considerations:

- Scan operations are sequential within each segment
- Different segments are processed in parallel
- Use element conditions (*If variants) to skip unnecessary elements
- Choose appropriate reduction function objects for best performance

# Related Pages

- Lambda Functions for Segment Scan Operations - Detailed lambda function signatures
- Function objects for reduction operations - Available reduction operations