specfem::assembly::receivers

template<specfem::element::dimension_tag DimensionTag>
struct receivers

Assembly-level receiver management for spectral element simulations.

This template class manages seismic receivers within assembled finite element meshes, providing efficient access to receiver data for both host and device computations. The receivers support seismogram recording with various output types (displacement, velocity, acceleration) and handle coordinate transformations for proper seismogram orientation based on receiver geometry.

Template Parameters:

DimensionTag – The spatial dimension (dim2 or dim3)

Dimension-specific Specializations

template<>
struct receivers<specfem::element::dimension_tag::dim2> : public specfem::assembly::receivers_impl::StationIterator, public specfem::assembly::receivers_impl::SeismogramIterator<specfem::element::dimension_tag::dim2>, public specfem::assembly::receivers_impl::ReceiverIndexBase<specfem::assembly::element_types_impl::ElementSets<specfem::element::dimension_tag::dim2>>

2D assembly receiver specialization for seismic simulations

Specialized implementation of receivers for 2D spectral element simulations. This class manages seismic receivers located within 2D finite element meshes, handling Lagrange interpolation for accurate field sampling and coordinate transformations using receiver angles for proper seismogram orientation.

Key features for 2D:

  • Supports multiple medium types: elastic_psv, elastic_sh, acoustic, poroelastic

  • Uses angle-based coordinate rotation (sine/cosine) for 2D transformations

  • Records 2-component seismograms (typically horizontal and vertical)

  • Efficient Kokkos-based data structures for GPU computations

The class inherits from both StationIterator (for station metadata) and SeismogramIterator (for time-series data access), providing a unified interface for receiver management and seismogram recording.

Public Functions

receivers() = default

Construct a new receivers object.

receivers(const int nspec, const int ngllz, const int ngllx, const int max_sig_step, const type_real dt, const type_real t0, const int nsteps_between_samples, const std::vector<std::shared_ptr<specfem::receivers::receiver<dimension_tag>>> &receivers, const std::vector<specfem::enums::wavefield> &stypes, const specfem::assembly::mesh<dimension_tag> &mesh, const specfem::mesh::tags<dimension_tag> &tags, const specfem::assembly::element_types<dimension_tag> &element_types)

Construct a new receivers object.

Parameters:

  • nspec – Total Number of spectral elements in the domain

  • ngllz – Total Number of GLL points in the z-direction

  • ngllx – Total Number of GLL points in the x-direction

  • max_sig_step – Maximum number seismogram sample points

  • dt – Time increament

  • t0 – Initial time

  • nsteps_between_samples – Number of time steps between samples

  • receivers – Vector of receivers

  • stypes – Vector of seismogram types (displacement, velocity, acceleration, pressure, or rotation)

  • mesh – Mesh object

  • tags – Tags for every element in the mesh

  • properties – Properties object

inline std::vector<specfem::enums::wavefield> get_seismogram_types() const

Get the seismogram types.

Returns:

std::vector<specfem::enums::wavefield> Vector of seismogram types

inline const std::vector<StationInfo> &stations() const

Return a const ref to all stations.

template<typename Filter>
inline std::vector<StationInfo> stations(Filter filter) const

Return a vector of stations matching the predicate.

inline std::tuple<IndexViewType, IndexViewType> get_indices_on_device(const specfem::element::medium_tag medium, const specfem::element::property_tag property) const

Device-side (element, receiver) index views for a material.

Parameters:

  • medium – Medium tag.

  • property – Property tag.

Returns:

Tuple of (receiver_elements, receiver_indices), both as device-accessible views.

inline std::tuple<HostIndexViewType, HostIndexViewType> get_indices_on_host(const specfem::element::medium_tag medium, const specfem::element::property_tag property) const

Host-side (element, receiver) index views for a material.

Parameters:

  • medium – Medium tag.

  • property – Property tag.

Returns:

Tuple of (receiver_elements, receiver_indices), both as host-accessible views.

Public Static Attributes

static constexpr specfem::element::dimension_tag dimension_tag = specfem::element::dimension_tag::dim2

Dimension tag for this assembly

template<>
struct receivers<specfem::element::dimension_tag::dim3> : public specfem::assembly::receivers_impl::StationIterator, public specfem::assembly::receivers_impl::SeismogramIterator<specfem::element::dimension_tag::dim3>, public specfem::assembly::receivers_impl::ReceiverIndexBase<specfem::assembly::element_types_impl::ElementSets<specfem::element::dimension_tag::dim3>>

3D assembly receiver specialization for seismic simulations

Specialized implementation of receivers for 3D spectral element simulations. This class manages seismic receivers located within 3D finite element meshes, handling Lagrange interpolation for accurate field sampling and coordinate transformations using full 3x3 rotation matrices for proper seismogram orientation in three-dimensional space.

Key features for 3D:

  • Currently supports elastic medium type only

  • Uses full 3x3 rotation matrices for coordinate transformations

  • Records 3-component seismograms (X, Y, Z or North, East, Up)

  • Advanced rotation capabilities for arbitrary receiver orientations

  • Efficient Kokkos-based data structures for GPU computations

The class inherits from both StationIterator (for station metadata) and SeismogramIterator (for time-series data access), providing a unified interface for receiver management and seismogram recording.

Public Functions

receivers() = default

Construct a new receivers object.

inline std::vector<specfem::enums::wavefield> get_seismogram_types() const

Get the seismogram types.

Returns:

std::vector<specfem::enums::wavefield> Vector of seismogram types

inline void set_rotation_matrix(int irec, const std::array<std::array<type_real, 3>, 3> &rotation_matrix)

Set rotation matrix for a receiver.

Parameters:

  • irec – Receiver index

  • rotation_matrix – 3x3 rotation matrix (nrec, 3, 3) layout

inline const std::vector<StationInfo> &stations() const

Return a const ref to all stations.

template<typename Filter>
inline std::vector<StationInfo> stations(Filter filter) const

Return a vector of stations matching the predicate.

inline std::tuple<IndexViewType, IndexViewType> get_indices_on_device(const specfem::element::medium_tag medium, const specfem::element::property_tag property) const

Device-side (element, receiver) index views for a material.

Parameters:

  • medium – Medium tag.

  • property – Property tag.

Returns:

Tuple of (receiver_elements, receiver_indices), both as device-accessible views.

inline std::tuple<HostIndexViewType, HostIndexViewType> get_indices_on_host(const specfem::element::medium_tag medium, const specfem::element::property_tag property) const

Host-side (element, receiver) index views for a material.

Parameters:

  • medium – Medium tag.

  • property – Property tag.

Returns:

Tuple of (receiver_elements, receiver_indices), both as host-accessible views.

Public Static Attributes

static constexpr specfem::element::dimension_tag dimension_tag = specfem::element::dimension_tag::dim3

Dimension tag for this assembly

Data Access Functions

template<typename ChunkIndexType, typename ViewType>
void load_on_device(const ChunkIndexType &chunk_index, const receivers<specfem::element::dimension_tag::dim2> &receivers, ViewType &lagrange_interpolant)

Load the Lagrange interpolant for receivers associated with the iterator on the device.

Template Parameters:
Parameters:

  • chunk_index – Chunk index

  • receivers – Receivers object containing the receiver information

  • lagrange_interpolant – Lagrange interpolant associated with the receivers in the iterator

template<typename ChunkIndexType, typename SeismogramViewType>
void store_on_device(const ChunkIndexType &chunk_index, const SeismogramViewType &seismogram_components, const receivers<specfem::element::dimension_tag::dim2> &receivers)

Store the seismogram components for receivers associated with the iterator on the device.

Before you store the seismogram components, you need to set the seismogram time step and type. You can do this by calling the following functions: receivers.set_seismogram_step(isig_step); receivers.set_seismogram_type(iseis);

Template Parameters:

  • ChunkIndexType – Chunk index type

  • SeismogramViewType – View of the seismogram components

Parameters:

receivers – Receivers object containing the receiver information

template<typename ChunkIndexType, typename ViewType>
void load_on_device(const ChunkIndexType &chunk_index, const receivers<specfem::element::dimension_tag::dim3> &receivers, ViewType &lagrange_interpolant)

Load the Lagrange interpolant for receivers associated with the iterator on the device.

Template Parameters:
Parameters:

  • chunk_index – Chunk index

  • receivers – Receivers object containing the receiver information

  • lagrange_interpolant – Lagrange interpolant associated with the receivers in the iterator

template<typename ChunkIndexType, typename SeismogramViewType>
void store_on_device(const ChunkIndexType &chunk_index, const SeismogramViewType &seismogram_components, const receivers<specfem::element::dimension_tag::dim3> &receivers)

Store the seismogram components for receivers associated with the iterator on the device.

Before you store the seismogram components, you need to set the seismogram time step and type. You can do this by calling the following functions: receivers.set_seismogram_step(isig_step); receivers.set_seismogram_type(iseis);

Template Parameters:

  • ChunkIndexType – Chunk index type

  • SeismogramViewType – View of the seismogram components

Parameters:

receivers – Receivers object containing the receiver information