specfem::assembly::sources

template<specfem::dimension::type DimensionTag>
struct sources

Assembly-level source management for spectral element simulations.

This template class manages sources within assembled finite element meshes, providing efficient access to source data for both host and device computations. The sources are organized by medium type (elastic, acoustic, poroelastic) and support time-dependent source time functions.

Template Parameters:

DimensionTag – The spatial dimension (dim2 or dim3)

Dimension-Specific Implementations

template<>
struct sources<specfem::dimension::type::dim2>

2D template specialization for assembly-level source management

This class manages seismic sources within 2D assembled finite element meshes, providing efficient data access patterns and organization for spectral element wave propagation simulations. The class handles various source types including force sources, moment tensor sources, and external sources across different medium types.

Usage Examples:

// 1. Initialize source assembly from configuration
std::vector<std::shared_ptr<specfem::sources::source<specfem::dimension::type::dim2>>>
sources;
// ... populate sources from input files

auto source_assembly =
specfem::assembly::sources<specfem::dimension::type::dim2>( sources, mesh,
jacobian, element_types, 0.0, 0.01, 1000);

// 2. Filter sources by criteria
auto [host_elements, host_sources] = source_assembly.get_sources_on_host(
    specfem::element::medium_tag::elastic_psv,
    specfem::element::property_tag::isotropic,
    specfem::element::boundary_tag::none,
    specfem::wavefield::simulation_field::forward);

// 3. Time integration with source updates
for (int step = 0; step < nsteps; ++step) {
    source_assembly.update_timestep(step);

    // Device kernel example
    Kokkos::parallel_for("apply_sources",
        Kokkos::RangePolicy<Kokkos::DefaultExecutionSpace>(0, nsources),
        KOKKOS_LAMBDA(const int isource) {
            specfem::point::mapped_index<specfem::dimension::type::dim2> index;
            specfem::point::source<...> point_source;
            load_on_device(index, source_assembly, point_source);
            // ... use point_source for assembly
        });
}

Private Type Definitions

Kokkos view types used for efficient memory management and data access patterns in source computations.

Public Constants

static constexpr auto dimension_tag = specfem::dimension::type::dim2

Dimension tag indicating this is a 2D implementation.

Constructors and Destructors

Object lifecycle management for source assembly data structures.

sources() = default

Default constructor.

Creates an empty source assembly with no initialized data. Use the parameterized constructor to properly initialize with mesh and source data.

sources(std::vector<std::shared_ptr<specfem::sources::source<dimension_tag>>> &sources, const specfem::assembly::mesh<dimension_tag> &mesh, const specfem::assembly::jacobian_matrix<dimension_tag> &jacobian_matrix, const specfem::assembly::element_types<dimension_tag> &element_types, const type_real t0, const type_real dt, const int nsteps)

Construct source assembly from mesh and source configuration.

Initializes the complete source assembly data structure by processing source definitions against the finite element mesh. This constructor:

  • Maps sources to their containing spectral elements

  • Classifies elements by medium, property, and boundary types

  • Sets up efficient index mappings for source processing

  • Initializes time-dependent source computations

// Initialize source assembly
auto source_assembly =
specfem::assembly::sources<specfem::dimension::type::dim2>( source_vector,
mesh, jacobian, element_types, 0.0, 0.01, 1000);

// Use in simulation
source_assembly.update_timestep(current_step);

Parameters:

  • sources – Vector of source objects read from input configuration, each containing position, time function, and type information

  • mesh – Finite element mesh providing element connectivity and geometry

  • jacobian_matrix – Jacobian transformation matrices for all quadrature points, enabling coordinate transformations

  • element_types – Classification of elements by medium and property types, determining appropriate physics implementations

  • t0 – Initial simulation time (typically 0.0)

  • dt – Time step size for temporal discretization

  • nsteps – Total number of time steps in the simulation

Public Functions

std::tuple<Kokkos::View<int*, Kokkos::DefaultHostExecutionSpace>, Kokkos::View<int*, Kokkos::DefaultHostExecutionSpace>> get_sources_on_host(const specfem::element::medium_tag medium, const specfem::element::property_tag property, const specfem::element::boundary_tag boundary, const specfem::wavefield::simulation_field wavefield) const

Retrieve source indices for specified criteria on host memory.

Filters sources based on medium type, material properties, boundary conditions, and wavefield application, returning host-accessible views for CPU-based processing.

// Get elastic sources for forward simulation
auto [elements, sources] = source_assembly.get_sources_on_host(
    specfem::element::medium_tag::elastic,
    specfem::element::property_tag::isotropic,
    specfem::element::boundary_tag::none,
    specfem::wavefield::simulation_field::forward);

Parameters:

  • medium – Physical medium type (elastic, acoustic, poroelastic) determining wave equation formulation

  • property – Material property classification (isotropic, anisotropic) affecting constitutive relationships

  • boundary – Boundary condition type (free surface, absorbing, etc.) influencing source application near boundaries

  • wavefield – Simulation type (forward, adjoint, backward) for proper source handling in different computational modes

Returns:

std::tuple containing:

  • Element indices view: Maps to spectral elements containing sources

  • Source indices view: Maps to sources within the filtered set

std::tuple<Kokkos::View<int*, Kokkos::DefaultExecutionSpace>, Kokkos::View<int*, Kokkos::DefaultExecutionSpace>> get_sources_on_device(const specfem::element::medium_tag medium, const specfem::element::property_tag property, const specfem::element::boundary_tag boundary, const specfem::wavefield::simulation_field wavefield) const

Retrieve source indices for specified criteria on device memory.

Device-accessible version of source filtering for GPU-based computations. Returns Kokkos views suitable for use in device kernels, enabling efficient parallel source processing during assembly operations.

// Get device views for acoustic sources in adjoint simulation
auto [dev_elements, dev_sources] = source_assembly.get_sources_on_device(
    specfem::element::medium_tag::acoustic,
    specfem::element::property_tag::isotropic,
    specfem::element::boundary_tag::none,
    specfem::wavefield::simulation_field::adjoint);

Parameters:

  • medium – Physical medium type determining appropriate wave equations

  • property – Material property type affecting physics implementation

  • boundary – Boundary condition classification for proper source handling

  • wavefield – Simulation mode for correct source application

Returns:

std::tuple containing device-accessible views:

  • Element indices: Spectral elements containing filtered sources

  • Source indices: Sources matching the specified criteria

inline void update_timestep(const int timestep)

Update the current simulation time step.

Sets the active time step index for time-dependent source function evaluation. This method must be called before each time step to ensure source time functions are evaluated at the correct temporal point. The time step is used by load_on_device and load_on_host methods for accessing time-dependent source amplitudes.

// Time integration loop
for (int step = 0; step < nsteps; ++step) {
    source_assembly.update_timestep(step);
    // ... perform assembly operations
}

Parameters:

timestep – Current time step index (0-based, typically from main time integration loop)

template<>
struct sources<specfem::dimension::type::dim3>

3D template specialization for assembly-level source management

This class manages seismic sources within 3D assembled finite element meshes, providing efficient data access patterns and organization for spectral element wave propagation simulations. The class handles various source types including force sources, moment tensor sources, and external sources across different medium types.

Usage Examples:

// 1. Initialize source assembly from configuration
std::vector<std::shared_ptr<specfem::sources::source<specfem::dimension::type::dim3>>> sources;
// ... populate sources from input files

auto source_assembly = specfem::assembly::sources<specfem::dimension::type::dim3>(
    sources, mesh, jacobian, element_types, 0.0, 0.01, 1000);

// 2. Filter sources by criteria
auto [host_elements, host_sources] = source_assembly.get_sources_on_host(
    specfem::element::medium_tag::elastic,
    specfem::element::property_tag::isotropic,
    specfem::element::boundary_tag::none,
    specfem::wavefield::simulation_field::forward);

// 3. Time integration with source updates
for (int step = 0; step < nsteps; ++step) {
    source_assembly.update_timestep(step);

    // Device kernel example
    Kokkos::parallel_for("apply_sources",
        Kokkos::RangePolicy<Kokkos::DefaultExecutionSpace>(0, nsources),
        KOKKOS_LAMBDA(const int isource) {
            specfem::point::mapped_index<specfem::dimension::type::dim3> index;
            specfem::point::source<...> point_source;
            load_on_device(index, source_assembly, point_source);
            // ... use point_source for assembly
        });
}

Private Type Definitions

Kokkos view types used for efficient memory management and data access patterns in 3D source computations.

Public Constants

static constexpr auto dimension_tag = specfem::dimension::type::dim3

Dimension tag indicating this is a 3D implementation.

Constructors and Destructors

Object lifecycle management for 3D source assembly data structures.

sources() = default

Default constructor.

Creates an empty source assembly with no initialized data. Use the parameterized constructor to properly initialize with mesh and source data.

sources(std::vector<std::shared_ptr<specfem::sources::source<dimension_tag>>> &sources, const specfem::assembly::mesh<dimension_tag> &mesh, const specfem::assembly::jacobian_matrix<dimension_tag> &jacobian_matrix, const specfem::assembly::element_types<dimension_tag> &element_types, const type_real t0, const type_real dt, const int nsteps)

Construct 3D source assembly from mesh and source configuration.

Initializes the complete 3D source assembly data structure by processing source definitions against the finite element mesh. This constructor:

  • Maps sources to their containing spectral elements in 3D space

  • Classifies elements by medium, property, and boundary types

  • Sets up efficient index mappings for 3D source processing

  • Initializes time-dependent source computations

// Initialize 3D source assembly
auto source_assembly =
specfem::assembly::sources<specfem::dimension::type::dim3>( source_vector,
mesh, jacobian, element_types, 0.0, 0.01, 1000);

// Use in simulation
source_assembly.update_timestep(current_step);

Parameters:

  • sources – Vector of 3D source objects read from input configuration, each containing position, time function, and type information

  • mesh – 3D finite element mesh providing element connectivity and geometry

  • jacobian_matrix – Jacobian transformation matrices for all quadrature points in 3D, enabling coordinate transformations

  • element_types – Classification of 3D elements by medium and property types, determining appropriate physics implementations

  • t0 – Initial simulation time (typically 0.0)

  • dt – Time step size for temporal discretization

  • nsteps – Total number of time steps in the simulation

Source Query Methods

Methods for retrieving filtered 3D source information based on physical and computational criteria.

std::tuple<Kokkos::View<int*, Kokkos::DefaultHostExecutionSpace>, Kokkos::View<int*, Kokkos::DefaultHostExecutionSpace>> get_sources_on_host(const specfem::element::medium_tag medium, const specfem::element::property_tag property, const specfem::element::boundary_tag boundary, const specfem::wavefield::simulation_field wavefield) const

Retrieve 3D source indices for specified criteria on host memory.

Filters sources based on medium type, material properties, boundary conditions, and wavefield application, returning host-accessible views for CPU-based processing in 3D domains.

// Get elastic sources for forward simulation in 3D
auto [elements, sources] = source_assembly.get_sources_on_host(
    specfem::element::medium_tag::elastic,
    specfem::element::property_tag::isotropic,
    specfem::element::boundary_tag::none,
    specfem::wavefield::simulation_field::forward);

Parameters:

  • medium – Physical medium type (elastic) determining wave equation formulation for 3D problems

  • property – Material property classification (isotropic) affecting constitutive relationships in 3D

  • boundary – Boundary condition type (none) influencing source application near 3D domain boundaries

  • wavefield – Simulation type (forward, adjoint, backward) for proper source handling in different computational modes

Returns:

std::tuple containing:

  • Element indices view: Maps to 3D spectral elements containing sources

  • Source indices view: Maps to sources within the filtered set

std::tuple<Kokkos::View<int*, Kokkos::DefaultExecutionSpace>, Kokkos::View<int*, Kokkos::DefaultExecutionSpace>> get_sources_on_device(const specfem::element::medium_tag medium, const specfem::element::property_tag property, const specfem::element::boundary_tag boundary, const specfem::wavefield::simulation_field wavefield) const

Retrieve 3D source indices for specified criteria on device memory.

Device-accessible version of source filtering for GPU-based computations in 3D domains. Returns Kokkos views suitable for use in device kernels, enabling efficient parallel source processing during assembly operations.

// Get device views for elastic sources in adjoint 3D simulation
auto [dev_elements, dev_sources] = source_assembly.get_sources_on_device(
    specfem::element::medium_tag::elastic,
    specfem::element::property_tag::isotropic,
    specfem::element::boundary_tag::none,
    specfem::wavefield::simulation_field::adjoint);

Parameters:

  • medium – Physical medium type determining appropriate wave equations for 3D elastic problems

  • property – Material property type affecting physics implementation

  • boundary – Boundary condition classification for proper source handling

  • wavefield – Simulation mode for correct source application

Returns:

std::tuple containing device-accessible views:

  • Element indices: 3D spectral elements containing filtered sources

  • Source indices: Sources matching the specified criteria

Time Management

Methods for controlling temporal aspects of 3D source computations.

inline void update_timestep(const int timestep)

Update the current simulation time step.

Sets the active time step index for time-dependent source function evaluation in 3D simulations. This method must be called before each time step to ensure source time functions are evaluated at the correct temporal point. The time step is used by load_on_device and load_on_host methods for accessing time-dependent source amplitudes.

// Time integration loop for 3D simulation
for (int step = 0; step < nsteps; ++step) {
    source_assembly.update_timestep(step);
    // ... perform 3D assembly operations
}

Parameters:

timestep – Current time step index (0-based, typically from main time integration loop)

Data Access Functions

template<typename IndexType, typename PointSourceType>
void load_on_device(const IndexType index, const specfem::assembly::sources<specfem::dimension::type::dim2> &sources, PointSourceType &point_source)

Load source data for device-based computations.

Load source information into point source structures for use in device

// Usage in device kernel
specfem::point::mapped_index<specfem::dimension::type::dim2> idx;
specfem::point::source<...> src;
load_on_device(idx, source_assembly, src);

Note

In debug builds, the function performs validity checks on indices and medium/wavefield type consistency.

Template Parameters:

  • IndexType – 2D point index type (non-SIMD) for element-source mapping

  • PointSourceType – 2D point source type matching medium and wavefield tags

Parameters:

  • index – Spectral element index containing source location information

  • sources – Source assembly with current timestep configuration

  • point_source – [out] Output structure populated with source data

Pre:

Call sources.update_timestep(step) before using this function

template<typename IndexType, typename PointSourceType>
void load_on_host(const IndexType index, const specfem::assembly::sources<specfem::dimension::type::dim2> &sources, PointSourceType &point_source)

Load source data for host-based computations.

Load source information into point source structures for use in host

// Usage in host code
specfem::point::mapped_index<specfem::dimension::type::dim2> idx;
specfem::point::source<...> src;
load_on_host(idx, source_assembly, src);

Note

In debug builds, the function performs validity checks on indices and medium/wavefield type consistency.

Template Parameters:

  • IndexType – 2D point index type (non-SIMD) for element-source mapping

  • PointSourceType – 2D point source type matching medium and wavefield tags

Parameters:

  • index – Spectral element index containing source location information

  • sources – Source assembly with current timestep configuration

  • point_source – [out] Output structure populated with source data

Pre:

Call sources.update_timestep(step) before using this function

template<typename IndexType, typename PointSourceType>
void store_on_device(const IndexType index, const PointSourceType &point_source, const specfem::assembly::sources<specfem::dimension::type::dim2> &sources)

Store source data from device computations.

GPU-optimized version for writing computed source data back to the assembly structure. Used in device kernels where source parameters are updated.

// Usage in device kernel for source modification
specfem::point::source<...> modified_src;
// ... modify source parameters
store_on_device(idx, modified_src, source_assembly);

Note

In debug builds, the function performs validity checks on indices and medium/wavefield type consistency.

Template Parameters:

  • IndexType – 2D point index type (non-SIMD) for element-source mapping

  • PointSourceType – 2D point source type matching medium and wavefield tags

Parameters:

  • index – Spectral element index identifying storage location

  • point_source – [in] Source data to be stored in assembly

  • sources – Source assembly with current timestep configuration

Pre:

Call sources.update_timestep(step) before using this function

template<typename IndexType, typename PointSourceType>
void store_on_host(const IndexType index, const PointSourceType &point_source, const specfem::assembly::sources<specfem::dimension::type::dim2> &sources)

Store source data from host computations.

Host-optimized version for writing computed source data back to the assembly structure. Used in CPU code where source parameters are updated.

// Usage in host code for source modification
specfem::point::source<...> modified_src;
// ... modify source parameters
store_on_host(idx, modified_src, source_assembly);

Note

In debug builds, the function performs validity checks on indices and medium/wavefield type consistency.

Template Parameters:

  • IndexType – 2D point index type (non-SIMD) for element-source mapping

  • PointSourceType – 2D point source type matching medium and wavefield tags

Parameters:

  • index – Spectral element index identifying storage location

  • point_source – [in] Source data to be stored in assembly

  • sources – Source assembly with current timestep configuration

Pre:

Call sources.update_timestep(step) before using this function

template<typename IndexType, typename PointSourceType>
void load_on_device(const IndexType index, const specfem::assembly::sources<specfem::dimension::type::dim3> &sources, PointSourceType &point_source)

Load 3D source data for device-based computations.

Efficiently retrieves 3D source information optimized for GPU kernels, including time-dependent source functions, spatial coordinates, and medium-specific properties. This function provides type-safe access with compile-time validation for 3D elastic problems.

// Usage in 3D device kernel
specfem::point::mapped_index<specfem::dimension::type::dim3> idx;
specfem::point::source<...> src;
load_on_device(idx, source_assembly, src);

Warning

Function will abort on invalid indices or mismatched medium/wavefield types

Template Parameters:

  • IndexType – 3D point index type (non-SIMD) for element-source mapping

  • PointSourceType – 3D point source type matching medium and wavefield tags

Parameters:

  • index – 3D spectral element index containing source location information

  • sources – 3D source assembly with current timestep configuration

  • point_source – [out] Output structure populated with 3D source data

Pre:

Call sources.update_timestep(step) before using this function

template<typename IndexType, typename PointSourceType>
void load_on_host(const IndexType index, const specfem::assembly::sources<specfem::dimension::type::dim3> &sources, PointSourceType &point_source)

Load 3D source data for host-based computations.

CPU-optimized version of 3D source data retrieval for host-side processing, setup operations, and analysis. Provides identical interface to device version with host memory access patterns for 3D elastic problems.

// Usage in 3D host code
specfem::point::mapped_index<specfem::dimension::type::dim3> idx;
specfem::point::source<...> src;
load_on_host(idx, source_assembly, src);

Warning

Function will abort on invalid indices or mismatched medium/wavefield types

Template Parameters:

  • IndexType – 3D point index type (non-SIMD) for element-source mapping

  • PointSourceType – 3D point source type matching medium and wavefield tags

Parameters:

  • index – 3D spectral element index containing source location information

  • sources – 3D source assembly with current timestep configuration

  • point_source – [out] Output structure populated with 3D source data

Pre:

Call sources.update_timestep(step) before using this function

template<typename IndexType, typename PointSourceType>
void store_on_device(const IndexType index, const PointSourceType &point_source, const specfem::assembly::sources<specfem::dimension::type::dim3> &sources)

Store 3D source data from device computations.

Efficiently writes computed 3D source data back to the assembly structure during GPU-based operations. Used for adjoint computations, source inversion, and iterative algorithms where 3D source terms are modified.

// Usage in 3D device kernel for adjoint computation
specfem::point::source<...> computed_src;
// ... compute adjoint source in 3D
store_on_device(idx, computed_src, source_assembly);

Warning

Function will abort on invalid indices or mismatched medium/wavefield types

Template Parameters:

  • IndexType – 3D point index type (non-SIMD) for element-source mapping

  • PointSourceType – 3D point source type matching medium and wavefield tags

Parameters:

  • index – 3D spectral element index identifying storage location

  • point_source – [in] 3D source data to be stored in assembly

  • sources – 3D source assembly with current timestep configuration

Pre:

Call sources.update_timestep(step) before using this function

Implementation Details