Template Numerical Library: Overview of Graph Traversal Functions

Template Numerical Library version\ main:0b2c40fb1

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

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

# Function Categories

Graph traversal functions are organized along three main dimensions:

## Const vs. Non-Const Graph

Category | Graph Modifiable? | Use Case
--- | --- | ---
Non-const | Yes | Can modify graph edges and structure
Const | No | Read-only access to graph edges

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

## Edge-wise vs. Vertex-wise Traversal

Category | Operates On | Lambda Parameter | Use Case
--- | --- | --- | ---
Edge-wise (forEdges, forAllEdges) | Individual edges | Edge indices & weights | Operate on each edge separately
Vertex-wise (forVertices, forAllVertices) | Individual vertices | VertexView object | Operate on vertices as units

## Scope and Conditional Variants

Similar to other graph operations, traversal functions have different scope and conditional variants. All traversal functions follow this naming pattern: for[All]Vertices[If] or for[All]Edges[If]

Scope | Vertices Processed | Parameters
--- | --- | ---
All | All vertices | No range/array parameters
Range | Vertices in [begin, end) | begin and end indices
Array | Specific vertices | Array of vertex indices
If | Vertices filtered by a condition | Process vertices based on vertex-level properties

# Edge-wise Traversal Functions

These functions iterate in parallel over individual edges connected to given set of vertices:

## Basic Edge Traversal

Function | Vertices Processed | Description | Overloads
--- | --- | --- | ---
forAllEdges | All vertices | Process all edges connected to all vertices | const & non-const
forEdges (range) | Vertices in [begin, end) | Process edges connected to vertices in given range | const & non-const
forEdges (array) | Vertices in array | Process edges connected to specified vertices | const & non-const
forAllEdgesIf | All vertices | Vertex-level condition | const & non-const
forEdgesIf | Vertices in [begin, end) | Vertex-level condition | const & non-const

Note: Edge-wise traversal functions iterates over the given set of vertices and they traverse all edges connected to each vertex in parallel. Therefore some edges may be traversed twice if both source and target vertices are included in the set. Since the edges are traversed in parallel, one edge may be processed by multiple threads at the same time.

When to use:

- Edge-level operations (weight updates, edge filtering)
- Traversals that need to modify edge indices or weights

# Vertex-wise Traversal Functions

These functions iterate over vertices using VertexView:

## Basic Vertex Traversal

Function | Vertices Processed | Description | Overloads
--- | --- | --- | ---
forAllVertices | All vertices | Process all vertices | const & non-const
forVertices (range) | Vertices in [begin, end) | Process vertices in range | const & non-const
forVertices (array) | Vertices in array | Process specified vertices | const & non-const
forAllVerticesIf | All vertices | Vertex-level condition | const & non-const
forVerticesIf | Vertices in [begin, end) | Vertex-level condition | const & non-const

Note: Vertex-wise traversal functions process each vertex as a whole using VertexView. No vertex is processed by multiple threads at the same time.

When to use:

- Vertex-level operations

# Common Parameters

All traversal functions share these common parameters:

- graph The graph to traverse (const or non-const)
- function Lambda function to apply (see Traversal Function (Non-Const Graph), Traversal Function (Const Graph), Vertex Traversal Function (Non-Const Graph), or Vertex Traversal Function (Const Graph))
- launchConfig Configuration for parallel execution (optional)

Additional parameters:

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

# Usage Guidelines

Performance considerations:

Edge-wise traversal allows parallel processing of edges incident to the same vertex; multiple threads may therefore operate on edges associated with a single vertex.

Vertex-wise traversal assigns at most one thread to each vertex and never maps multiple threads to the same vertex. This traversal mode is therefore preferred when vertex-level context or per-vertex state updates are required.

# Related Pages

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