`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 interface intersections.

This is the main iterator class for processing intersections between mesh interfaces in chunks. It manages two sets of interfaces (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 interface 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::element::dimension_tag::dim2, Kokkos::DefaultExecutionSpace>;

// Create intersection views
constexpr int num_intersections = 5000;

Kokkos::View<specfem::mesh_entity::edge<specfem::element::dimension_tag::dim2>*>
self_intersections("self_intersections", num_intersections);
Kokkos::View<specfem::mesh_entity::edge<specfem::element::dimension_tag::dim2>*>
coupled_intersections("coupled_intersections", num_intersections);

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

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

// Create and use chunked intersection iterator
specfem::execution::ChunkedIntersectionIterator iterator(
    ParallelConfig(), self_intersections, coupled_intersections);

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 intersections

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_intersections, const ViewType coupled_intersections)¶

Constructor with explicit intersection views.

Parameters:

self_intersections – View of self mesh intersections (first side of intersection)
coupled_intersections – View of coupled mesh intersections (second side of intersection)

inline ChunkedIntersectionIterator(const ParallelConfig, const ViewType self_intersections, const ViewType coupled_intersections)¶

Constructor with parallel configuration.

Parameters:

config – Parallel configuration (unused but required for interface compatibility)
self_intersections – View of self mesh intersections (first side of intersection)
coupled_intersections – View of coupled mesh intersections (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 interface 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 interface 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::element::dimension_tag::dim2, Kokkos::DefaultExecutionSpace>;

// Create intersection views
constexpr int num_intersections = 5000;

Kokkos::View<specfem::mesh_entity::edge<specfem::element::dimension_tag::dim2>*>
self_intersections("self_intersections", num_intersections);
Kokkos::View<specfem::mesh_entity::edge<specfem::element::dimension_tag::dim2>*>
coupled_intersections("coupled_intersections", num_intersections);

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

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

// Create and use chunked intersection iterator
specfem::execution::ChunkedIntersectionIterator iterator(
    ParallelConfig(), self_intersections, coupled_intersections);

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 intersections

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_intersections, const ViewType coupled_intersections)

Constructor with explicit intersection views.

Parameters:

self_intersections – View of self mesh intersections (first side of intersection)
coupled_intersections – View of coupled mesh intersections (second side of intersection)

inline ChunkedIntersectionIterator(const ParallelConfig, const ViewType self_intersections, const ViewType coupled_intersections)

Constructor with parallel configuration.

Parameters:

config – Parallel configuration (unused but required for interface compatibility)
self_intersections – View of self mesh intersections (first side of intersection)
coupled_intersections – View of coupled mesh intersections (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`¶