`specfem::assembly::jacobian_matrix`¶

template<specfem::element::dimension_tag DimensionTag> struct jacobian_matrix¶

Spectral element Jacobian matrix data container.

This class provides storage and data access functions for the Jacobian matrices associated with spectral elements in spectral element mesh. The dimension specific implementations provide data containers for storing individual terms of the Jacobian matrix as well as methods for loading and storing data on device and host.

Dimension-Specific Implementations¶

template<> struct jacobian_matrix<specfem::element::dimension_tag::dim2> : public specfem::data_access::Container<specfem::data_access::ContainerType::domain, specfem::data_access::DataClassType::jacobian_matrix, specfem::element::dimension_tag::dim2>¶

2D Jacobian matrix container for spectral element coordinate transformations

The Jacobian matrix enables mapping between physical coordinates (x,z) and reference coordinates (ξ,γ) for each quadrature point in spectral elements.

Mathematical Foundation: The Jacobian matrix represents the coordinate transformation:

\[\begin{split} J = \begin{pmatrix} \frac{\partial x}{\partial \xi} & \frac{\partial z}{\partial \xi} \\ \frac{\partial x}{\partial \gamma} & \frac{\partial z}{\partial \gamma} \end{pmatrix} \end{split}\]

Storage Components:

xix: \(\frac{\partial \xi}{\partial x}\) (inverse transformation derivatives)
xiz: \(\frac{\partial \xi}{\partial z}\)
gammax: \(\frac{\partial \gamma}{\partial x}\)
gammaz: \(\frac{\partial \gamma}{\partial z}\)
jacobian: Determinant \(|J|\) for integration weights

// Example usage
specfem::assembly::jacobian_matrix<specfem::element::dimension_tag::dim2> jacobian(...);

// Access in device kernel
specfem::point::index<specfem::element::dimension_tag::dim2> idx(ispec, iz, ix);
specfem::point::jacobian_matrix<specfem::element::dimension_tag::dim2> point_jac;
specfem::assembly::load_on_device(idx, jacobian, point_jac);

Type Definitions

using base_type = specfem::data_access::Container<specfem::data_access::ContainerType::domain, specfem::data_access::DataClassType::jacobian_matrix, specfem::element::dimension_tag::dim2>¶

Base container type providing data access infrastructure.

See also

specfem::data_access::Container

using view_type = typename base_type::scalar_type<type_real, Kokkos::DefaultExecutionSpace::memory_space>¶: Kokkos view type for storing Jacobian matrix components.

Constructors

Object lifecycle management for Jacobian matrix data structures.

jacobian_matrix() = default¶

Default constructor.

Creates an empty Jacobian matrix container. Use parameterized constructors to initialize with actual mesh data and compute transformation derivatives.

jacobian_matrix(const int nspec, const int ngllz, const int ngllx)¶

Construct Jacobian matrix with specified dimensions.

Allocates storage for Jacobian matrix components based on problem dimensions and quadrature point specifications. The actual derivative values must be computed and populated separately.

Parameters:

nspec – Number of spectral elements in the domain
ngllz – Number of GLL quadrature points in z-direction
ngllx – Number of GLL quadrature points in x-direction

jacobian_matrix(const specfem::assembly::mesh<specfem::element::dimension_tag::dim2> &mesh)¶

Construct Jacobian matrix from 2D mesh information.

Computes and initializes all Jacobian matrix components from mesh geometry. This constructor:

Computes coordinate transformation derivatives at all quadrature points
Calculates Jacobian determinants for integration weights
Sets up efficient device/host memory layouts
Validates mesh geometry and transformation quality

specfem::assembly::mesh<specfem::element::dimension_tag::dim2> mesh;
// ... initialize mesh
specfem::assembly::jacobian_matrix<specfem::element::dimension_tag::dim2>
jac(mesh);

Parameters:: mesh – 2D finite element mesh containing element connectivity, node coordinates, and geometric information

Public Types

using scalar_type = typename impl::ContainerValueType<ContainerType, dimension_tag>::template scalar_type<T, MemorySpace>¶

Container to be used when storing scalar data.

Template Parameters:

T – Base data type to be stored within the container
MemorySpace – Kokkos memory space for storage

using vector_type = typename impl::ContainerValueType<ContainerType, dimension_tag>::template vector_type<T, MemorySpace>¶

Container to be used when storing vector data.

Template Parameters:

T – Base data type to be stored within the container
MemorySpace – Kokkos memory space for storage

using tensor_type = typename impl::ContainerValueType<ContainerType, dimension_tag>::template tensor_type<T, MemorySpace>¶

Container to be used when storing tensor data.

Template Parameters:

T – Base data type to be stored within the container
MemorySpace – Kokkos memory space for storage

Public Functions

void sync_views()¶

Synchronize device and host memory views.

Ensures consistency between device and host copies of Jacobian matrix data by copying from device to host. This is typically called after device-based computations to make results available on the host.

std::tuple<bool, Kokkos::View<bool*, Kokkos::DefaultHostExecutionSpace>> check_small_jacobian() const¶

Validate Jacobian determinant values for numerical stability.

Checks all Jacobian determinant values to identify elements with potentially problematic transformations that could cause numerical instability during computation. Small or negative Jacobians indicate degenerate or inverted elements.

auto [has_small_jac, element_flags] = jacobian.check_small_jacobian();
if (has_small_jac) {
    // Handle problematic elements
    for (int i = 0; i < nspec; ++i) {
        if (element_flags(i)) {
            std::cout << "Element " << i << " has small Jacobian" <<
std::endl;
        }
    }
}

Note

Small Jacobians are typically defined as values below a threshold that could cause numerical instability in the finite element computation.

Returns:

std::tuple containing:

Boolean flag indicating if any small Jacobians were found
Boolean array flagging elements with small Jacobian values

Public Members

int nspec¶: Number of spectral elements in the computational domain.

int ngllz¶: Number of Gauss-Lobatto-Legendre quadrature points in z-direction.

int ngllx¶: Number of Gauss-Lobatto-Legendre quadrature points in x-direction.

Public Static Attributes

static constexpr auto container_type¶: Container layout type.

static constexpr auto data_class¶: Data classification type.

static constexpr auto dimension_tag¶: Spatial dimension.

template<> struct jacobian_matrix<specfem::element::dimension_tag::dim3> : public specfem::data_access::Container<specfem::data_access::ContainerType::domain, specfem::data_access::DataClassType::jacobian_matrix, specfem::element::dimension_tag::dim3>¶

3D Jacobian matrix container for spectral element coordinate transformations

The Jacobian matrix enables mapping between physical coordinates (x,y,z) and reference coordinates (ξ,η,γ) for each quadrature point in spectral elements.

Mathematical Foundation: The Jacobian matrix represents the coordinate transformation:

\[\begin{split} J = \begin{pmatrix} \frac{\partial x}{\partial \xi} & \frac{\partial y}{\partial \xi} & \frac{\partial z}{\partial \xi} \\ \frac{\partial x}{\partial \eta} & \frac{\partial y}{\partial \eta} & \frac{\partial z}{\partial \eta} \\ \frac{\partial x}{\partial \gamma} & \frac{\partial y}{\partial \gamma} & \frac{\partial z}{\partial \gamma} \end{pmatrix} \end{split}\]

Storage Components:

xix, xiy, xiz: \(\frac{\partial \xi}{\partial x}\), \(\frac{\partial \xi}{\partial y}\), \(\frac{\partial \xi}{\partial z}\) (inverse transformation derivatives)
etax, etay, etaz: \(\frac{\partial \eta}{\partial x}\), \(\frac{\partial \eta}{\partial y}\), \(\frac{\partial \eta}{\partial z}\)
gammax, gammay, gammaz: \(\frac{\partial \gamma}{\partial x}\), \(\frac{\partial \gamma}{\partial y}\), \(\frac{\partial \gamma}{\partial z}\)
jacobian: Determinant \(|J|\) for integration weights

// Example usage
specfem::assembly::jacobian_matrix<specfem::element::dimension_tag::dim3> jacobian(...);

// Access in device kernel
specfem::point::index<specfem::element::dimension_tag::dim3> idx(ispec, iz, iy, ix);
specfem::point::jacobian_matrix<specfem::element::dimension_tag::dim3> point_jac;
specfem::assembly::load_on_device(idx, jacobian, point_jac);

Type Definitions

using base_type = specfem::data_access::Container<specfem::data_access::ContainerType::domain, specfem::data_access::DataClassType::jacobian_matrix, specfem::element::dimension_tag::dim3>¶

Base container type providing data access infrastructure.

Data Access Functions¶

template<typename IndexType, typename ContainerType, typename PointType, typename std::enable_if_t<specfem::data_access::is_index_type<IndexType>::value && specfem::data_access::is_jacobian_matrix<ContainerType>::value && specfem::data_access::is_jacobian_matrix<PointType>::value, int> = 0> void load_on_device(const IndexType &index, const ContainerType &container, PointType &point)¶

Load Jacobian matrix data from container to point structure on GPU device.

Load global coordinates for a GLL point from device memory.

This function transfers Jacobian transformation matrix components from a global container to a local point structure for GPU-based computations.

Data Components Loaded:

2D: xix, xiz, gammax, gammaz, jacobian (determinant)
3D: xix, xiy, xiz, etax, etay, etaz, gammax, gammay, gammaz, jacobian

// Example usage in GPU kernel
specfem::point::index<specfem::element::dimension_tag::dim2> idx(ispec, iz,
ix); specfem::point::jacobian_matrix<specfem::element::dimension_tag::dim2>
point_jac; specfem::assembly::load_on_device(idx, jacobian_container,
point_jac);

// Access loaded values
type_real xix_val = point_jac.xix;          // ∂ξ/∂x
type_real det_jac = point_jac.jacobian;     // |J|

This function transfers global coordinate data (x, z for 2D; x, y, z for 3D) from a mesh points container to a local point structure for GPU-based computations.

// Example usage in GPU kernel
specfem::point::index<specfem::element::dimension_tag::dim2> idx(ispec, iz,
ix);
specfem::point::global_coordinates<specfem::element::dimension_tag::dim2>
point_coord; specfem::assembly::load_on_device(idx, mesh.points,
point_coord);

// Access loaded values
type_real x_val = point_coord.x;
type_real z_val = point_coord.z;

Template Parameters:

IndexType – Point index type (specfem::point::index)
ContainerType – Jacobian matrix container type for the mesh
PointType – Local point Jacobian matrix type (specfem::point::jacobian_matrix)
IndexType – Point index type (specfem::point::index)
ContainerType – Points container type
PointType – Local point global_coordinates type (specfem::point::global_coordinates)

Parameters:

index – Quadrature point indices (ispec, iz, iy, ix)
container – Global Jacobian matrix container
point – Local point Jacobian matrix structure (output)
index – Quadrature point indices (ispec, iz, [iy,] ix)
container – Global points container
point – Local point global coordinates structure (output)

Pre:

IndexType must satisfy is_index_type constraint

Pre:

ContainerType and PointType must satisfy is_jacobian_matrix constraint

Pre:

Types must be compatible according to CheckCompatibility

Pre:

IndexType must satisfy is_index_type constraint

Pre:

ContainerType and PointType must satisfy is_global_coordinates constraint

template<typename IndexType, typename ContainerType, typename PointType, typename std::enable_if_t<specfem::data_access::is_index_type<IndexType>::value && specfem::data_access::is_jacobian_matrix<ContainerType>::value && specfem::data_access::is_jacobian_matrix<PointType>::value, int> = 0> void load_on_host(const IndexType &index, const ContainerType &container, PointType &point)¶

Load Jacobian matrix data from container to point structure on host functions.

Load global coordinates for a GLL point from host memory.

This function transfers Jacobian transformation matrix components from a global container to a local point structure for host-based computations.

Data Components Loaded:

2D: xix, xiz, gammax, gammaz, jacobian (determinant)
3D: xix, xiy, xiz, etax, etay, etaz, gammax, gammay, gammaz, jacobian

// Example usage in host code
specfem::point::index<specfem::element::dimension_tag::dim3> idx(ispec, iz,
iy, ix);
specfem::point::jacobian_matrix<specfem::element::dimension_tag::dim3>
point_jac; specfem::assembly::load_on_host(idx, jacobian_container,
point_jac);

// Process loaded transformation data
type_real volume_element = point_jac.jacobian;
type_real dxi_dx = point_jac.xix;

This function transfers global coordinate data (x, z for 2D; x, y, z for 3D) from a mesh points container to a local point structure for host-based computations.

// Example usage in host code
specfem::point::index<specfem::element::dimension_tag::dim3> idx(ispec, iz,
iy, ix);
specfem::point::global_coordinates<specfem::element::dimension_tag::dim3>
point_coord; specfem::assembly::load_on_host(idx, mesh.points, point_coord);

// Process loaded coordinate data
type_real x_val = point_coord.x;
type_real y_val = point_coord.y;
type_real z_val = point_coord.z;

Template Parameters:

IndexType – Point index type (specfem::point::index)
ContainerType – Jacobian matrix container type for the mesh
PointType – Local point Jacobian matrix type (specfem::point::jacobian_matrix)
IndexType – Point index type (specfem::point::index)
ContainerType – Points container type
PointType – Local point global_coordinates type (specfem::point::global_coordinates)

Parameters:

index – Quadrature point indices (ispec, iz, iy, ix)
container – Global Jacobian matrix container
point – Local point Jacobian matrix structure (output)
index – Quadrature point indices (ispec, iz, [iy,] ix)
container – Global points container
point – Local point global coordinates structure (output)

Pre:

IndexType must satisfy is_index_type constraint

Pre:

ContainerType and PointType must satisfy is_jacobian_matrix constraint

Pre:

Types must be compatible according to CheckCompatibility

Pre:

IndexType must satisfy is_index_type constraint

Pre:

ContainerType and PointType must satisfy is_global_coordinates constraint

template<typename IndexType, typename ContainerType, typename PointType, typename std::enable_if_t<specfem::data_access::is_index_type<IndexType>::value && specfem::data_access::is_jacobian_matrix<ContainerType>::value && specfem::data_access::is_jacobian_matrix<PointType>::value, int> = 0> void store_on_device(const IndexType &index, ContainerType &container, const PointType &point)¶

Store Jacobian matrix data from point structure to container on GPU device.

This function writes Jacobian transformation matrix components from a local point structure back to the global container during GPU-based computations.

Storage Components: For 2D elements: xix, xiz, gammax, gammaz, jacobian For 3D elements: xix, xiy, xiz, etax, etay, etaz, gammax, gammay, gammaz, jacobian

// Example usage in GPU kernel after Jacobian computation
specfem::point::index<specfem::element::dimension_tag::dim2> idx(ispec, iz,
ix); specfem::point::jacobian_matrix<specfem::element::dimension_tag::dim2>
computed_jac;

// Compute Jacobian values (simplified)
computed_jac.xix = compute_xix(mesh_coords);
computed_jac.jacobian = compute_jacobian_determinant(mesh_coords);

// Store back to global container
specfem::assembly::store_on_device(idx, jacobian_container, computed_jac);

Template Parameters:

IndexType – Point index type (specfem::point::index)
ContainerType – Jacobian matrix container type for the mesh
PointType – Local point Jacobian matrix type

Parameters:

index – Quadrature point indices (ispec, iz, iy, ix)
container – Global Jacobian matrix container (modified)
point – Local point Jacobian matrix structure containing data to store

Pre:

IndexType must satisfy is_index_type constraint

Pre:

ContainerType and PointType must satisfy is_jacobian_matrix constraint

Pre:

Types must be compatible according to CheckCompatibility

template<typename IndexType, typename ContainerType, typename PointType, typename std::enable_if_t<specfem::data_access::is_index_type<IndexType>::value && specfem::data_access::is_jacobian_matrix<ContainerType>::value && specfem::data_access::is_jacobian_matrix<PointType>::value, int> = 0> void store_on_host(const IndexType &index, ContainerType &container, const PointType &point)¶

Store Jacobian matrix data from point structure to container on host functions.

This function writes Jacobian transformation matrix components from a local point structure back to the global container during host-based computations.

Storage Components: For 2D elements: xix, xiz, gammax, gammaz, jacobian For 3D elements: xix, xiy, xiz, etax, etay, etaz, gammax, gammay, gammaz, jacobian

// Example usage during mesh initialization
specfem::point::index<specfem::element::dimension_tag::dim3> idx(ispec, iz,
iy, ix);
specfem::point::jacobian_matrix<specfem::element::dimension_tag::dim3>
computed_jac;

// Compute Jacobian from mesh coordinates
compute_jacobian_from_coordinates(mesh_coords, computed_jac);

// Store to host container for later device synchronization
specfem::assembly::store_on_host(idx, jacobian_container, computed_jac);

// Later synchronize to device
jacobian_container.sync_to_device();

Template Parameters:

IndexType – Point index type (specfem::point::index)
ContainerType – Jacobian matrix container type for the mesh
PointType – Local point Jacobian matrix type

Parameters:

index – Quadrature point indices (ispec, iz, iy, ix)
container – Global Jacobian matrix container (modified)
point – Local point Jacobian matrix structure containing data to store

Pre:

IndexType must satisfy is_index_type constraint

Pre:

ContainerType and PointType must satisfy is_jacobian_matrix constraint

Pre:

Types must be compatible according to CheckCompatibility

specfem::assembly::jacobian_matrix¶

Dimension-Specific Implementations¶

Data Access Functions¶

`specfem::assembly::jacobian_matrix`¶