specfem::sources::vector_source

template<specfem::element::dimension_tag DimensionTag>
class vector_source : public specfem::sources::source<DimensionTag>

Class representing a vector source.

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

Vector sources apply forces in specific directions and the dimensionality of the force vector depends on the medium type and wave field configuration.

Examples of vector sources:

Vector Source Usage Pattern
// Example: Creating and using a vector source (2D force)
auto stf = std::make_unique<specfem::source_time_functions::Ricker>(
    15.0, 0.01, 1.0, 0.0, 1.0, false
);

auto vector_src =
specfem::sources::force<specfem::element::dimension_tag::dim2>( 3.5, 7.2, //
coordinates (x, z) 30.0,       // angle in degrees std::move(stf),
    specfem::simulation::field_type::forward
);

// Set the medium where the source is located
vector_src.set_medium_tag(specfem::element::medium_tag::elastic_psv);

// Get the force vector - size depends on medium:
// - acoustic: 1 component (pressure)
// - elastic_sh: 1 component (out-of-plane)
// - elastic_psv: 2 components (in-plane x,z)
// - elastic_psv_t: 3 components (x,z + rotation)
auto force_vector = vector_src.get_force_vector();

// All vector sources return vector_source type
assert(vector_src.get_source_type() ==
       specfem::sources::source_type::vector_source);

Note

This class inherits from specfem::sources::source

Template Parameters:

DimensionTag – The dimension specification (dim2 or dim3)

Public Functions

inline vector_source()

Default vector source constructor.

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

Construct a new 2D vector source object using the forcing function.

Parameters:

  • x – x-coordinate of source

  • z – z-coordinate of source

  • source_time_function – pointer to source time function

  • wavefield_type – type of wavefield

template<specfem::element::dimension_tag U = DimensionTag, typename std::enable_if<U == specfem::element::dimension_tag::dim3>::type* = nullptr>
inline vector_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 vector source object using the forcing function.

Parameters:

  • x – x-coordinate of source

  • y – y-coordinate of source

  • z – z-coordinate of source

  • source_time_function – pointer to source time function

  • wavefield_type – type of wavefield

inline vector_source(std::unique_ptr<specfem::coordinate_systems::coordinates<DimensionTag>> coordinates, std::unique_ptr<specfem::source_time_functions::stf> source_time_function)

Construct a new vector source from generic coordinates.

Parameters:

  • coordinates – Generic coordinate object

  • source_time_function – pointer to source time function

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

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

Parameters:

  • Node – YAML node defining the vector 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

inline virtual source_type get_source_type() const override

Get the source type object.

Returns:

source_type

virtual Kokkos::View<type_real*, Kokkos::LayoutRight, Kokkos::HostSpace> get_force_vector() const = 0

Get the force vector.

Returns the force vector \(\mathbf{f}\) applied by this vector source. The dimensionality and components depend on the medium type and simulation dimension.

where:

  • \(f_i\) are force components in direction \(i\)

  • \(m_i\) are rotational moment components about axis \(i\)

  • \(f_p\) is the pressure source amplitude

Mathematical Definition

The force vector represents the body force applied to the medium:

\[\begin{split} \mathbf{f} = \begin{cases} [f_p] & \text{acoustic: pressure source} \\ [f_y] & \text{elastic SH (2D): out-of-plane force} \\ [f_x, f_z] & \text{elastic PSV (2D): in-plane forces} \\ [f_x, f_z, m_y] & \text{elastic PSV+T (2D): forces + rotational moment} \\ [f_x, f_y, f_z] & \text{elastic (3D): three force components} \\ [f_x, f_y, f_z, m_x, m_y, m_z] & \text{elastic Cosserat (3D): forces + moments} \end{cases} \end{split}\]

Note

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

Returns:

Kokkos::View<type_real *, Kokkos::LayoutLeft, Kokkos::HostSpace> Force vector with size depending on medium type

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.

virtual std::string source_name() const = 0

Returns the human-readable source type name. Derived classes should override this to return their static name.

inline virtual std::string print_details() const

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.

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

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.