`specfem::execution::ChunkedIntersectionIterator`¶

template<typename ParallelConfig, typename ViewType> class ChunkedIntersectionIterator : public specfem::execution::TeamPolicy<ParallelConfig>¶

High-level chunked intersection iterator for efficient parallel processing of edge intersections.

This is the main iterator class for processing intersections between mesh edges in chunks. It manages two sets of edges (self and coupled) and processes their intersections in parallel using Kokkos teams. This approach is essential for coupled boundary conditions, interface operations, and multi-domain computations in spectral element methods.

Applications¶

The chunked intersection iterator is commonly used for:

Fluid-structure interaction boundaries
Acoustic-elastic interface coupling
Domain decomposition interface handling
Periodic boundary condition enforcement
Multi-physics coupling operations

Performance¶

The chunked approach provides benefits for intersection processing:

Improved memory locality for coupled edge data
Better load balancing across teams
Reduced synchronization overhead
Configurable chunk sizes for different architectures

Usage¶

#include "execution/chunked_intersection_iterator.hpp"
#include "execution/for_all.hpp"

// Define parallel configuration
using ParallelConfig =
specfem::parallel_configuration::default_chunk_edge_config<
    specfem::dimension::type::dim2, Kokkos::DefaultExecutionSpace>;

// Create edge views for intersection
constexpr int num_intersections = 5000;
constexpr int num_points = 5;

Kokkos::View<specfem::mesh_entity::edge<specfem::dimension::type::dim2>*>
self_edges("self_edges", num_intersections);
Kokkos::View<specfem::mesh_entity::edge<specfem::dimension::type::dim2>*>
coupled_edges("coupled_edges", num_intersections);

// Initialize intersection pairs
Kokkos::parallel_for("init_intersections", num_intersections,
KOKKOS_LAMBDA(int i) {
    // Self edges from domain A
    self_edges(i) =
specfem::mesh_entity::edge<specfem::dimension::type::dim2>(i,
specfem::mesh_entity::dim2::type::top);

    // Coupled edges from domain B (often with different orientation)
    coupled_edges(i) =
specfem::mesh_entity::edge<specfem::dimension::type::dim2>( num_intersections
- i - 1, specfem::mesh_entity::dim2::type::bottom);
});

// Create storage for coupled calculations
Kokkos::View<double*[num_points]> self_field("self_field",
num_intersections); Kokkos::View<double*[num_points]>
coupled_field("coupled_field", num_intersections);
Kokkos::View<double*[num_points]> interface_flux("interface_flux",
num_intersections);

// Create and use chunked intersection iterator
specfem::execution::ChunkedIntersectionIterator iterator(
    ParallelConfig(), self_edges, coupled_edges, num_points);

specfem::execution::for_all("compute_interface_coupling", iterator,
    KOKKOS_LAMBDA(const auto& index) {
        // Access interface point data
        auto interface_idx = index.get_index();
        auto self_point = interface_idx.self_index;
        auto coupled_point = interface_idx.coupled_index;
        int point = index.ipoint;

        // Compute interface coupling (e.g., acoustic-elastic)
        double self_value = self_field(self_point.ispec, point);
        double coupled_value = coupled_field(coupled_point.ispec, point);

        // Apply coupling operator (simplified example)
        double flux = 0.5 * (self_value + coupled_value);
        interface_flux(self_point.ispec, point) = flux;
    });

Kokkos::fence();

ChunkSize¶

The chunk size affects performance for intersection processing:

GPU: 128-512 intersections per chunk (memory bandwidth limited)
CPU: 32-128 intersections per chunk (cache hierarchy optimized)
Consider memory access patterns of coupled data structures

Template Parameters:

ParallelConfig – Configuration class defining execution parameters and chunk size
ViewType – Kokkos view type containing mesh edges

Public Types

using base_policy_type = typename base_type::base_policy_type¶: Base policy type. Evaluates to Kokkos::TeamPolicy`

using policy_index_type = typename base_type::policy_index_type¶: Policy index type. Evaluates to Kokkos::TeamPolicy::member_type

using execution_space = typename base_type::execution_space¶: Execution space type.

using base_index_type = InterfacePointIndex<ParallelConfig::dimension, int, typename base_type::execution_space>¶: Index type to be used when calling specfem::execution::for_all with this iterator.

Public Functions

inline ChunkedIntersectionIterator(const ViewType self_edges, const ViewType coupled_edges)¶

Constructor with explicit edge views and point count.

Parameters:

self_edges – View of self mesh edges (first side of intersection)
coupled_edges – View of coupled mesh edges (second side of intersection)

inline ChunkedIntersectionIterator(const ParallelConfig, const ViewType self_edges, const ViewType coupled_edges)¶

Constructor with parallel configuration.

Parameters:

config – Parallel configuration (unused but required for interface compatibility)
self_edges – View of self mesh edges (first side of intersection)
coupled_edges – View of coupled mesh edges (second side of intersection)

inline const index_type operator()(const policy_index_type &team) const¶

Team operator for intersection chunk processing.

Creates a chunk-specific intersection index for the given team. Each team processes a contiguous chunk of intersection pairs, improving memory locality for coupled computations.

Parameters:: team – Kokkos team member
Returns:: index_type Chunk intersection index for this team

template<typename ...Args> inline ChunkedIntersectionIterator &set_scratch_size(Args&&... args)¶

Set scratch memory size for teams.

Forwards scratch memory configuration to the underlying team policy. Useful for teams that need temporary storage for intersection computations.

Template Parameters:: Args – Variadic template for scratch size arguments
Parameters:: args – Arguments to forward to team policy
Returns:: ChunkedIntersectionIterator& Reference to this iterator for chaining

Public Static Attributes

static constexpr PolicyType policy_type = PolicyType::KokkosPolicy ¶: Indicates this is a Kokkos policy.

static constexpr bool is_top_level_policy = true¶: Indicates this is a top-level policy.

`specfem::execution::ChunkedIntersectionIndex`¶

Warning

doxygenclass: Cannot find class “specfem::execution::ChunkedIntersectionIndex” in doxygen xml output for project “specfem++” from directory: _build/doxygen/xml

`specfem::execution::ChunkedIntersectionIterator`¶

template<typename ParallelConfig, typename ViewType> class ChunkedIntersectionIterator : public specfem::execution::TeamPolicy<ParallelConfig>

High-level chunked intersection iterator for efficient parallel processing of edge intersections.

Applications¶

The chunked intersection iterator is commonly used for:

Fluid-structure interaction boundaries
Acoustic-elastic interface coupling
Domain decomposition interface handling
Periodic boundary condition enforcement
Multi-physics coupling operations

Performance¶

The chunked approach provides benefits for intersection processing:

Improved memory locality for coupled edge data
Better load balancing across teams
Reduced synchronization overhead
Configurable chunk sizes for different architectures

Usage¶

#include "execution/chunked_intersection_iterator.hpp"
#include "execution/for_all.hpp"

// Define parallel configuration
using ParallelConfig =
specfem::parallel_configuration::default_chunk_edge_config<
    specfem::dimension::type::dim2, Kokkos::DefaultExecutionSpace>;

// Create edge views for intersection
constexpr int num_intersections = 5000;
constexpr int num_points = 5;

Kokkos::View<specfem::mesh_entity::edge<specfem::dimension::type::dim2>*>
self_edges("self_edges", num_intersections);
Kokkos::View<specfem::mesh_entity::edge<specfem::dimension::type::dim2>*>
coupled_edges("coupled_edges", num_intersections);

// Initialize intersection pairs
Kokkos::parallel_for("init_intersections", num_intersections,
KOKKOS_LAMBDA(int i) {
    // Self edges from domain A
    self_edges(i) =
specfem::mesh_entity::edge<specfem::dimension::type::dim2>(i,
specfem::mesh_entity::dim2::type::top);

    // Coupled edges from domain B (often with different orientation)
    coupled_edges(i) =
specfem::mesh_entity::edge<specfem::dimension::type::dim2>( num_intersections
- i - 1, specfem::mesh_entity::dim2::type::bottom);
});

// Create storage for coupled calculations
Kokkos::View<double*[num_points]> self_field("self_field",
num_intersections); Kokkos::View<double*[num_points]>
coupled_field("coupled_field", num_intersections);
Kokkos::View<double*[num_points]> interface_flux("interface_flux",
num_intersections);

// Create and use chunked intersection iterator
specfem::execution::ChunkedIntersectionIterator iterator(
    ParallelConfig(), self_edges, coupled_edges, num_points);

specfem::execution::for_all("compute_interface_coupling", iterator,
    KOKKOS_LAMBDA(const auto& index) {
        // Access interface point data
        auto interface_idx = index.get_index();
        auto self_point = interface_idx.self_index;
        auto coupled_point = interface_idx.coupled_index;
        int point = index.ipoint;

        // Compute interface coupling (e.g., acoustic-elastic)
        double self_value = self_field(self_point.ispec, point);
        double coupled_value = coupled_field(coupled_point.ispec, point);

        // Apply coupling operator (simplified example)
        double flux = 0.5 * (self_value + coupled_value);
        interface_flux(self_point.ispec, point) = flux;
    });

Kokkos::fence();

ChunkSize¶

The chunk size affects performance for intersection processing:

GPU: 128-512 intersections per chunk (memory bandwidth limited)
CPU: 32-128 intersections per chunk (cache hierarchy optimized)
Consider memory access patterns of coupled data structures

Template Parameters:

ParallelConfig – Configuration class defining execution parameters and chunk size
ViewType – Kokkos view type containing mesh edges

Public Types

using base_policy_type = typename base_type::base_policy_type: Base policy type. Evaluates to Kokkos::TeamPolicy`

using policy_index_type = typename base_type::policy_index_type: Policy index type. Evaluates to Kokkos::TeamPolicy::member_type

using execution_space = typename base_type::execution_space: Execution space type.

using base_index_type = InterfacePointIndex<ParallelConfig::dimension, int, typename base_type::execution_space>: Index type to be used when calling specfem::execution::for_all with this iterator.

Public Functions

inline ChunkedIntersectionIterator(const ViewType self_edges, const ViewType coupled_edges)

Constructor with explicit edge views and point count.

Parameters:

self_edges – View of self mesh edges (first side of intersection)
coupled_edges – View of coupled mesh edges (second side of intersection)

inline ChunkedIntersectionIterator(const ParallelConfig, const ViewType self_edges, const ViewType coupled_edges)

Constructor with parallel configuration.

Parameters:

config – Parallel configuration (unused but required for interface compatibility)
self_edges – View of self mesh edges (first side of intersection)
coupled_edges – View of coupled mesh edges (second side of intersection)

inline const index_type operator()(const policy_index_type &team) const

Team operator for intersection chunk processing.

Creates a chunk-specific intersection index for the given team. Each team processes a contiguous chunk of intersection pairs, improving memory locality for coupled computations.

Parameters:: team – Kokkos team member
Returns:: index_type Chunk intersection index for this team

template<typename ...Args> inline ChunkedIntersectionIterator &set_scratch_size(Args&&... args)

Set scratch memory size for teams.

Forwards scratch memory configuration to the underlying team policy. Useful for teams that need temporary storage for intersection computations.

Template Parameters:: Args – Variadic template for scratch size arguments
Parameters:: args – Arguments to forward to team policy
Returns:: ChunkedIntersectionIterator& Reference to this iterator for chaining

Public Static Attributes

static constexpr PolicyType policy_type = PolicyType::KokkosPolicy: Indicates this is a Kokkos policy.

static constexpr bool is_top_level_policy = true: Indicates this is a top-level policy.

`specfem::execution::IntersectionPointIndex`¶

Warning

doxygenclass: Cannot find class “specfem::execution::IntersectionPointIndex” in doxygen xml output for project “specfem++” from directory: _build/doxygen/xml

specfem::execution::ChunkedIntersectionIterator¶

Applications¶

Performance¶

Usage¶

ChunkSize¶

specfem::execution::ChunkedIntersectionIndex¶

specfem::execution::ChunkedIntersectionIterator¶

Applications¶

Performance¶

Usage¶

ChunkSize¶

specfem::execution::IntersectionPointIndex¶

`specfem::execution::ChunkedIntersectionIterator`¶

`specfem::execution::ChunkedIntersectionIndex`¶

`specfem::execution::ChunkedIntersectionIterator`¶

`specfem::execution::IntersectionPointIndex`¶