3D `specfem::sources::moment_tensor` implementation¶

Moment-Tensor implementation

template<> class moment_tensor<specfem::element::dimension_tag::dim3> : public specfem::sources::tensor_source<specfem::element::dimension_tag::dim3>¶

Moment-tensor source.

This class implements a moment tensor source in 3D, which represents seismic sources like earthquakes through a symmetric 3x3 stress tensor. The six independent components (Mxx, Myy, Mzz, Mxy, Mxz, Myz) fully characterize the source mechanism.

Usage Example

// Create a Ricker wavelet source time function
auto stf = std::make_unique<specfem::source_time_functions::Ricker>(
    12.0,  // dominant frequency (Hz)
    0.01,  // time factor
    1.0,   // amplitude
    0.0,   // time shift
    1.0,   // normalization factor
    false  // do not reverse
);

// Create a 3D moment tensor source at (10.0, 15.0, 20.0)
auto mt_source =
specfem::sources::moment_tensor<specfem::element::dimension_tag::dim3>( 10.0,
// x-coordinate 15.0,  // y-coordinate 20.0,  // z-coordinate 1.2,   // Mxx -
normal stress in x direction 0.8,   // Myy - normal stress in y direction
    1.5,   // Mzz - normal stress in z direction
    0.3,   // Mxy - shear stress component
    0.1,   // Mxz - shear stress component
    0.2,   // Myz - shear stress component
    std::move(stf),
    specfem::simulation::field_type::forward
);

// Set the medium type (moment tensors work with elastic media)
mt_source.set_medium_tag(specfem::element::medium_tag::elastic);

// Get the source tensor (3x3 symmetric matrix for 3D)
auto source_tensor = mt_source.get_source_tensor();

Public Functions

inline moment_tensor()¶: Default source constructor.

inline type_real get_Mxx() const¶

Get the Mxx component of the moment tensor.

Returns:: type_real Mxx moment tensor component

inline type_real get_Myy() const¶

Get the Myy component of the moment tensor.

Returns:: type_real Myy moment tensor component

inline type_real get_Mzz() const¶

Get the Mzz component of the moment tensor.

Returns:: type_real Mzz moment tensor component

inline type_real get_Mxy() const¶

Get the Mxy component of the moment tensor.

Returns:: type_real Mxy moment tensor component

inline type_real get_Mxz() const¶

Get the Mxz component of the moment tensor.

Returns:: type_real Mxz moment tensor component

inline type_real get_Myz() const¶

Get the Myz component of the moment tensor.

Returns:: type_real Myz moment tensor component

inline moment_tensor(YAML::Node &Node, const int nsteps, const type_real dt, const specfem::simulation::field_type wavefield_type)¶

Construct a new moment tensor force object.

Parameters:: moment_tensor – a moment_tensor data holder read from source file written in .yml format

inline moment_tensor(type_real x, type_real y, type_real z, type_real Mxx, type_real Myy, type_real Mzz, type_real Mxy, type_real Mxz, type_real Myz, std::unique_ptr<specfem::source_time_functions::stf> source_time_function, const specfem::simulation::field_type wavefield_type)¶

Costruct new moment tensor source using forcing function.

Parameters:

x – x-coordinate of source
z – z-coordinate of source
Mxx – Mxx component of moment tensor
Mzz – Myy component of moment tensor
Mzz – Mzz component of moment tensor
Mxy – Mxy component of moment tensor
Mxz – Mxz component of moment tensor
Myz – Myz component of moment tensor
source_time_function – pointer to source time function
wavefield_type – type of wavefield

inline moment_tensor(std::unique_ptr<specfem::coordinate_systems::coordinates<specfem::element::dimension_tag::dim3>> coordinates, type_real Mxx, type_real Myy, type_real Mzz, type_real Mxy, type_real Mxz, type_real Myz, std::unique_ptr<specfem::source_time_functions::stf> source_time_function, const specfem::simulation::field_type wavefield_type)¶

Construct a new moment tensor source from generic coordinates.

Parameters:

coordinates – Generic coordinate object
Mxx – Mxx component of moment tensor
Myy – Myy component of moment tensor
Mzz – Mzz component of moment tensor
Mxy – Mxy component of moment tensor
Mxz – Mxz component of moment tensor
Myz – Myz component of moment tensor
source_time_function – pointer to source time function
wavefield_type – type of wavefield

inline virtual std::string source_name() const override¶: User output.

virtual std::string print_details() const override¶: Type-specific output (parameters unique to this source type). The default implementation returns an empty string for sources that have no additional parameters beyond location and source time function.

virtual Kokkos::View<type_real**, Kokkos::LayoutRight, Kokkos::HostSpace> get_source_tensor() const override¶

Get the source tensor.

Returns the full 3D seismic moment tensor for this source:

\[\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}\]

Where the six independent components represent:

\(M_{xx}, M_{yy}, M_{zz}\): Normal stress components (diagonal)
\(M_{xy}, M_{xz}, M_{yz}\): Shear stress components (off-diagonal)

The tensor format is a 3×3 symmetric matrix for elastic media, representing the complete seismic moment tensor used in earthquake source modeling.

Returns:: Kokkos::View<type_real **, Kokkos::LayoutRight, Kokkos::HostSpace> Source tensor with dimensions [ncomponents][3] where each row contains [Mxx, Mxy, Mxz], [Mxy, Myy, Myz], [Mxz, Myz, Mzz] etc, depending on the medium type

virtual std::vector<specfem::element::medium_tag> get_supported_media() const override¶

Get the list of supported media for this source type.

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

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 std::optional<specfem::datetime::type> get_starttime() const¶: Get the UTC start time of this source (nullopt if not set).

inline void set_starttime(std::optional<specfem::datetime::type> t)¶: Set the UTC start time of this source.

inline std::string print() const¶: User output — assembles source name, location, type-specific details, source time function, and (when MPI-enabled) the owning rank.

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

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

Get the medium tag for the source.

Returns:: specfem::medium::medium_tag medium tag

inline void set_read_coordinates(std::unique_ptr<specfem::coordinate_systems::coordinates<dimension_tag>> coordinates)¶

Set the generic coordinates for this source.

Parameters:: coordinates – Generic coordinate object (ownership transferred)

inline const specfem::coordinate_systems::coordinates<dimension_tag> *get_read_coordinates() const¶: Get the generic coordinates (const), or nullptr if not set.

inline specfem::coordinate_systems::coordinates<dimension_tag> *get_read_coordinates()¶

Get the generic coordinates (mutable), or nullptr if not set.

Used by resolve_coordinates to set the origin on cartesian coordinates.

3D specfem::sources::moment_tensor implementation¶

3D `specfem::sources::moment_tensor` implementation¶