specfem::sources::tensor_source

template<specfem::dimension::type DimensionTag>
class tensor_source : public specfem::sources::source<DimensionTag>

Class representing a tensor source.

The tensor source class is a base class for all tensor sources in the simulation. It provides the common interface and functionality for manipulating tensor sources. The main functionality being the return of a tensor that can be used to compute the GLL level source array, which is applied in the simulation.

Tensor sources represent stress or moment tensor sources, typically used for earthquake simulations. They provide a symmetric tensor representation of the source mechanism.

The main differences between 2D and 3D tensor sources are the dimensions and global and local coordinates for the point sources.

Examples of tensor sources:

Tensor Source Usage Pattern
// Example: Creating and using a tensor source (2D moment tensor)
auto stf = std::make_unique<specfem::source_time_functions::Ricker>(
    8.0, 0.01, 1.0, 0.0, 1.0, false
);

auto tensor_src =
specfem::sources::moment_tensor<specfem::dimension::type::dim2>( 12.5, 8.0,
// coordinates (x, z) 1.5,        // Mxx - normal stress in x direction 2.1,
// Mzz - normal stress in z direction 0.7,        // Mxz - shear stress
component std::move(stf), specfem::wavefield::simulation_field::forward
);

// Set the medium (tensor sources work with elastic media)
tensor_src.set_medium_tag(specfem::element::medium_tag::elastic_psv);

// Get the source tensor - dimensions depend on simulation:
// - 2D: 2x2 symmetric matrix [[Mxx, Mxz], [Mxz, Mzz]]
// - 3D: 3x3 symmetric matrix with 6 independent components
auto source_tensor = tensor_src.get_source_tensor();

// All tensor sources return tensor_source type
assert(tensor_src.get_source_type() ==
       specfem::sources::source_type::tensor_source);

// Access individual tensor components (for moment tensors)
type_real mxx = tensor_src.get_Mxx();
type_real mzz = tensor_src.get_Mzz();
type_real mxz = tensor_src.get_Mxz();

Note

This class inherits from specfem::sources::source

Template Parameters:

DimensionTag – Dimension of the tensor source (dim2 or dim3)

Public Functions

inline tensor_source()

Default tensor source constructor.

template<specfem::dimension::type U = DimensionTag, typename std::enable_if<U == specfem::dimension::type::dim2>::type* = nullptr>
inline tensor_source(type_real x, type_real z, std::unique_ptr<specfem::source_time_functions::stf> source_time_function)

Construct a new 2D tensor source object.

Parameters:

  • x – x-coordinate of source

  • z – z-coordinate of source

  • source_time_function – pointer to source time function

template<specfem::dimension::type U = DimensionTag, typename std::enable_if<U == specfem::dimension::type::dim3>::type* = nullptr>
inline tensor_source(type_real x, type_real y, type_real z, std::unique_ptr<specfem::source_time_functions::stf> source_time_function)

Construct a new 3D tensor source object.

Parameters:

  • x – x-coordinate of source

  • y – y-coordinate of source

  • z – z-coordinate of source

  • source_time_function – pointer to source time function

inline tensor_source(YAML::Node &Node, const int nsteps, const type_real dt)

Construct a new tensor source object from a YAML node and time steps.

Parameters:

  • Node – YAML node defining the tensor source

  • nsteps – Number of time steps in the simulation

  • dt – Time increment in the simulation

  • wavefield_type – Type of wavefield on which the source acts

virtual specfem::kokkos::HostView2d<type_real> get_source_tensor() const = 0

Get the source tensor.

Returns the source tensor \(\mathbf{M}\) representing the stress or moment tensor applied by this tensor source. The tensor is symmetric and its dimensionality depends on the simulation dimension and medium type.

2D Case:

\[\begin{split} \mathbf{M}_{2D} = \begin{pmatrix} M_{xx} & M_{xz} \\ M_{xz} & M_{zz} \end{pmatrix} \end{split}\]
Mathematical Definition

The source tensor represents the symmetric stress/moment tensor:

3D Case:

\[\begin{split} \mathbf{M}_{3D} = \begin{pmatrix} M_{xx} & M_{xy} & M_{xz} \\ M_{xy} & M_{yy} & M_{yz} \\ M_{xz} & M_{yz} & M_{zz} \end{pmatrix} \end{split}\]

The returned tensor format depends on the medium:

  • Elastic PSV (2D): 2×2 matrix \([[M_{xx}, M_{xz}], [M_{xz}, M_{zz}]]\)

  • Elastic PSV-T (2D): 3×2 matrix with additional rotational component

  • Poroelastic (2D): 4×2 matrix (elastic tensor repeated for solid/fluid)

  • Elastic (3D): 3×3 full moment tensor

  • Electromagnetic: Modified tensor for Maxwell equations

where \(M_{ij}\) are the independent components of the symmetric tensor, representing seismic moment, stress, or equivalent source mechanisms.

Note

The actual tensor values and their physical meaning depend on the specific source type implementation. See individual source classes for detailed mathematical definitions of their tensor components.

Returns:

Kokkos::View<type_real **, Kokkos::LayoutLeft, Kokkos::HostSpace> Source tensor matrix with dimensions [ncomponents][ndim] where ncomponents depends on medium type and ndim is spatial dimension

inline virtual source_type get_source_type() const override

Get the source type.

Returns:

source_type type of source

inline type_real get_t0() const

Get the value of t0 from the specfem::stf::stf object.

Returns:

value of t0

inline void update_tshift(type_real tshift)

Update the value of tshift for specfem::stf::stf object.

Returns:

new value of tshift

inline virtual std::string print() const

User output.

void set_source_time_function(YAML::Node &Node, const int nsteps, const type_real dt)

Set the forcing function for the source.

This function initializes the source time function based on the configuration provided in the YAML node. It supports various types of source time functions such as Dirac, Gaussian, Ricker, dGaussian, Heaviside, and External. If the specified source time function is not recognized, an exception is thrown.

This method also is responsible for setting up the start time of the source time function depending on dimension (dim2, dim3) and forcing function type.

Parameters:

  • Node – YAML node containing source time function configuration

  • nsteps – number of time steps

  • dt – time step size

inline std::unique_ptr<specfem::source_time_functions::stf> &get_source_time_function()

Get the forcing function object.

Returns:

std::unique_ptr<specfem::source_time_functions::stf>&

inline void set_local_coordinates(const specfem::point::local_coordinates<dimension_tag> &local_coordinates)

Set the local xi coordinates of the source in the local coordinate system.

Parameters:

specfem::point::local_coordinates<dimension_tag> – local_coordinates

inline specfem::point::local_coordinates<dimension_tag> get_local_coordinates() const

Get the local coordinates of the source in the local coordinate system.

Returns:

specfem::point::local_coordinates<dimension_tag>

inline void set_global_coordinates(const specfem::point::global_coordinates<dimension_tag> &global_coordinates)

Set the global coordinates of the source in the global coordinate system.

Parameters:

specfem::point::global_coordinates<dimension_tag> – global_coordinates

inline specfem::point::global_coordinates<dimension_tag> get_global_coordinates() const

Get the global coordinates of the source in the global coordinate system.

Returns:

specfem::point::global_coordinates<dimension_tag>

void set_medium_tag(specfem::element::medium_tag medium_tag)

Set the medium tag for the source.

This needs to be set inside the since each medium requires a separate implementation for each medium and some source do not have implementations for certain media at all. E.g., if you want to assign a moment tensor to an element in the water column (acoustic), it does not make sense, or rather it is unphysical.

Parameters:

medium_tag – medium tag

virtual std::vector<specfem::element::medium_tag> get_supported_media() const = 0

Get the list of supported media for this source type.

Returns:

std::vector<specfem::element::medium_tag> list of supported media

inline specfem::element::medium_tag get_medium_tag() const

Get the medium tag for the source.

Returns:

specfem::medium::medium_tag medium tag