specfem::assembly::Info

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

Computes and stores mesh statistics and numerical stability parameters.

Analyzes the assembled mesh to extract spatial bounds, material property ranges, and element geometry statistics. Estimates the minimum resolvable period and suggests a time step based on the CFL condition.

The minimum period estimation follows Komatitsch et al. (2005): “average number of points per minimum wavelength in an element should be

around 5.”

Note

The minimum period is an empirical estimate, not a sharp cutoff. Synthetics become progressively less accurate for shorter periods.

Template Parameters:

DimensionTag – Spatial dimension (dim2 or dim3)

Public Functions

Info(const specfem::assembly::mesh<dimension_tag> &mesh, const specfem::assembly::properties<dimension_tag> &properties, const specfem::assembly::element_types<dimension_tag> &element_types)

Construct mesh info by analyzing mesh geometry and material properties.

Parameters:

  • mesh – Assembled mesh containing element geometry and GLL points

  • properties – Material properties at all mesh points

  • element_types – Element classification by medium and property type

std::string string() const

Generate formatted string representation of mesh statistics.

Returns:

Multi-line string with labeled mesh properties

Public Members

info::impl::BoundingBox<dimension_tag> domain_bounds

Spatial extent of the mesh domain

info::impl::Bounds element_size

Element corner-to-corner distances.

info::impl::Bounds gll_distance

Distances between adjacent GLL points.

info::impl::Bounds vp

P-wave velocity range.

info::impl::Bounds vs

S-wave velocity range.

info::impl::Bounds v

Combined wave velocity range.

info::impl::Bounds rho

Density range.

info::impl::Bounds vp_vs_ratio

Vp/Vs ratio range.

type_real suggested_time_step

Time step satisfying CFL condition.

type_real largest_minimum_period

Maximum of minimum resolvable periods across elements

Public Static Attributes

static constexpr auto dimension_tag = DimensionTag

Dimension tag.

Implementation Details

Bounds

struct Bounds

Min/max range for a scalar quantity.

Stores the minimum and maximum values observed for a property (e.g., velocity, density, distance). Provides utility methods for computing derived quantities.

Public Functions

inline Bounds()

Default constructor initializes to zero bounds.

inline Bounds(type_real min_in, type_real max_in)

Construct bounds from explicit min/max values.

Parameters:

  • min_in – Minimum value

  • max_in – Maximum value

inline type_real length() const

Compute the range (max - min).

inline type_real ratio() const

Compute the ratio (max / min).

Throws:

std::runtime_error – if min is zero

inline type_real center() const

Compute the midpoint of the range.

inline Bounds &operator=(const type_real value)

Set both min and max to the same value.

Parameters:

value – Value to assign to both bounds

Public Members

type_real min

Minimum value.

type_real max

Maximum value.

BoundingBox

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

Axis-aligned bounding box for mesh domain.

Stores min/max bounds for each spatial dimension (x, y, z). Provides dimension-specific accessors that handle 2D vs 3D cases.

Template Parameters:

DimensionTag – Spatial dimension (dim2 or dim3)

Public Functions

template<specfem::element::dimension_tag U = dimension_tag, typename std::enable_if<U == specfem::element::dimension_tag::dim2>::type* = nullptr>
inline BoundingBox(const type_real x_min, const type_real x_max, const type_real z_min, const type_real z_max)

Construct 2D bounding box from explicit min/max values.

Parameters:

  • x_min – Minimum x coordinate

  • x_max – Maximum x coordinate

  • z_min – Minimum z coordinate

  • z_max – Maximum z coordinate

template<specfem::element::dimension_tag U = dimension_tag, typename std::enable_if<U == specfem::element::dimension_tag::dim3>::type* = nullptr>
inline BoundingBox(const type_real x_min, const type_real x_max, const type_real y_min, const type_real y_max, const type_real z_min, const type_real z_max)

Construct 3D bounding box from explicit min/max values.

Parameters:

  • x_min – Minimum x coordinate

  • x_max – Maximum x coordinate

  • y_min – Minimum y coordinate

  • y_max – Maximum y coordinate

  • z_min – Minimum z coordinate

  • z_max – Maximum z coordinate

template<specfem::element::dimension_tag U = dimension_tag, typename std::enable_if<U == specfem::element::dimension_tag::dim2>::type* = nullptr>
inline BoundingBox(const std::vector<Bounds> &bounds)

Construct 2D bounding box from vector of Bounds.

Parameters:

bounds – Vector of 2 Bounds objects (x, z)

Throws:

std::invalid_argument – if bounds.size() != 2

template<specfem::element::dimension_tag U = dimension_tag, typename std::enable_if<U == specfem::element::dimension_tag::dim3>::type* = nullptr>
inline BoundingBox(const std::vector<Bounds> &bounds)

Construct 3D bounding box from vector of Bounds.

Parameters:

bounds – Vector of 3 Bounds objects (x, y, z)

Throws:

std::invalid_argument – if bounds.size() != 3

inline Bounds &x()

Access x-direction bounds.

inline const Bounds &x() const

Access x-direction bounds (const).

template<specfem::element::dimension_tag U = dimension_tag, typename std::enable_if<U == specfem::element::dimension_tag::dim3>::type* = nullptr>
inline Bounds &y()

Access y-direction bounds (3D only).

template<specfem::element::dimension_tag U = dimension_tag, typename std::enable_if<U == specfem::element::dimension_tag::dim3>::type* = nullptr>
inline const Bounds &y() const

Access y-direction bounds (3D only, const).

inline Bounds &z()

Access z-direction bounds (index 1 for 2D, index 2 for 3D).

inline const Bounds &z() const

Access z-direction bounds (const, index 1 for 2D, index 2 for 3D).

Public Members

specfem::datatype::RegisterArray<Bounds, Kokkos::extents<size_t, ndim>, Kokkos::layout_left> bounds_array

Array of bounds per dimension.

Public Static Attributes

static constexpr int ndim = specfem::element::dimension<dimension_tag>::dim

Number of dimensions.

Computation Functions

type_real specfem::assembly::info::impl::compute_average_gll_spacing(type_real element_size, int ngll_minus_one)

Compute average GLL point spacing from element size.

Parameters:

  • element_size – The maximum distance across an element (edge length).

  • ngll_minus_one – Number of GLL points minus one (polynomial order).

Returns:

Average distance between adjacent GLL points.

type_real specfem::assembly::info::impl::compute_minimum_period(type_real avg_gll_spacing, type_real min_velocity)

Compute the minimum resolvable period for an element.

The minimum period that can be accurately resolved depends on the spatial sampling (points per wavelength) and the wave velocity. Uses the empirical constant NPTS_PER_WAVELENGTH.

Parameters:

  • avg_gll_spacing – Average distance between GLL points.

  • min_velocity – Minimum wave velocity in the element.

Returns:

Minimum resolvable period (wavelength / velocity).

type_real specfem::assembly::info::impl::compute_suggested_timestep(type_real min_gll_distance, type_real max_velocity)

Compute suggested time step based on CFL condition.

The Courant-Friedrichs-Lewy (CFL) condition ensures numerical stability by limiting how far a wave can travel in one time step. Uses the empirical constant COURANT_NUMBER_SUGGESTED.

Parameters:

  • min_gll_distance – Minimum distance between adjacent GLL points.

  • max_velocity – Maximum wave velocity in the element.

Returns:

Suggested time step satisfying the CFL condition.

Distance Computation

template<specfem::element::dimension_tag DimensionTag, typename GllDistanceAcc, typename ElementGllDistanceAcc>
void specfem::assembly::info::impl::compute_gll_distances(const specfem::point::index<DimensionTag> &point_index, const specfem::assembly::mesh<DimensionTag> &mesh, const specfem::point::global_coordinates<DimensionTag> &current_point, GllDistanceAcc &gll_distance_acc, ElementGllDistanceAcc &element_gll_distance_acc)

Compute distances between adjacent GLL points in all directions.

Note

Y-direction is only computed for dim3 using if constexpr

Template Parameters:

DimensionTag – The dimension type (dim2 or dim3)

template<specfem::element::dimension_tag DimensionTag, typename DistanceAcc, typename ElementDistanceAcc>
void specfem::assembly::info::impl::compute_element_sizes(const specfem::point::index<DimensionTag> &point_index, const specfem::assembly::mesh<DimensionTag> &mesh, const specfem::point::global_coordinates<DimensionTag> &current_point, DistanceAcc &distance_acc, ElementDistanceAcc &element_distance_acc)

Compute element sizes (corner-to-corner distances) in all directions.

Note

Y-direction is only computed for dim3 using if constexpr

Template Parameters:

DimensionTag – The dimension type (dim2 or dim3)

Scatter-Based Reduction

template<typename T = type_real>
struct LocalMinMax

Lightweight struct for element-local min/max tracking inside lambdas.

template<typename T = type_real, size_t Extent = 0>
struct ScatterMinMax

Scatter-based min/max reducer for parallel reductions.

Encapsulates Kokkos views, scatter views, initialization, and finalization for computing global min/max values across parallel iterations.

Template Parameters:

  • T – Value type for min/max tracking

  • Extent – Compile-time extent (0 = dynamic, use runtime size)

struct Accessor

Accessor for use inside Kokkos lambdas.

struct Accessor

Accessor for use inside Kokkos lambdas.