specfem::mesh::materials

template<specfem::element::dimension_tag Dimension>
struct materials

Struct to store materials.

Template Parameters:

DimensionTag – Dimension type

Dimension-Specific Specializations

template<>
struct materials<specfem::element::dimension_tag::dim2>

Material properties information.

Constructors

materials() = default

Default constructor.

inline materials(const int nspec)

Constructor used to allocate views.

Parameters:

nspec – Number of spectral elements

Public Functions

template<specfem::element::medium_tag MediumTag, specfem::element::property_tag PropertyTag, specfem::element::attenuation_tag AttenuationTag>
inline specfem::medium_container::material<dimension_tag, MediumTag, PropertyTag, AttenuationTag> get_material(const int index) const

Material material at spectral element index.

Parameters:

index – Spectral element index

Returns:

std::variant Material properties

template<specfem::element::medium_tag MediumTag, specfem::element::property_tag PropertyTag, specfem::element::attenuation_tag AttenuationTag>
inline specfem::point::properties<specfem::tags::Tags<dimension_tag, MediumTag, PropertyTag, false>> get_properties(const int index) const

Get point properties for the material at element index, dispatching on a runtime attenuation_tag value.

Template Parameters:

  • MediumTag – Medium type

  • PropertyTag – Property symmetry

Parameters:

  • index – Spectral element index

  • attenuation – Runtime attenuation tag

Returns:

Point properties (attenuation-independent)

template<specfem::element::medium_tag MediumTag, specfem::element::property_tag PropertyTag, specfem::element::attenuation_tag AttenuationTag>
inline specfem::mesh::materials<dimension_tag>::material<MediumTag, PropertyTag, AttenuationTag> &get_container()

Get the container object containing properties for a material type.

Template Parameters:

  • MediumTag – Medium tag for the material

  • PropertyTag – Property tag for the material

Returns:

material<MediumTag, PropertyTag>& material container

inline std::tuple<specfem::element::medium_tag, specfem::element::property_tag> get_material_type(const int index) const

Get the medium and property types for a given element index.

Returns a tuple containing the medium and property tags associated with the material specification for the specified element index.

// Get material type for element 42
auto [medium, property] = materials.get_material_type(42);

// Use in conditional logic
if (medium == specfem::element::medium_tag::elastic &&
    property == specfem::element::property_tag::isotropic) {
    // Handle elastic isotropic case
}

Parameters:

index – Element index to query

Returns:

Tuple of (medium_tag, property_tag) for the element’s material

Public Members

int n_materials = 0

Total number of different materials.

Kokkos::View<material_specification*, Kokkos::HostSpace> material_index_mapping

Mapping of spectral element to material properties

Public Static Attributes

static constexpr auto dimension_tag = specfem::element::dimension_tag::dim2

Dimension type.

template<>
struct material

Public Members

int n_materials = 0

Number of different materials.

std::vector<specfem::medium_container::material<dimension_tag, type, property, attenuation>> element_materials

Material properties.

template<>
struct material_specification

Public Functions

material_specification() = default

Default constructor.

inline material_specification(specfem::element::medium_tag type, specfem::element::property_tag property, specfem::element::attenuation_tag attenuation, int index, int database_index)

Constructor used to assign values.

Parameters:

  • type – Type of element

  • property – Property of element

  • index – Index of material property

Public Members

specfem::element::medium_tag type

Type of element.

specfem::element::property_tag property

Property of element.

specfem::element::attenuation_tag attenuation

Attenuation type.

int index

Index of material property.

int database_index

Index of material property in the database.

template<>
struct materials<specfem::element::dimension_tag::dim3>

3D specialization for MESHFEM3D material database management

This specialized implementation manages material properties for 3D spectral element simulations generated by MESHFEM3D. It provides:

  • Storage for materials read from MESHFEM3D database files

  • Type-safe material containers organized by medium and property types

  • Mapping between spectral elements and their material specifications

  • Template metaprogramming for compile-time material type dispatch

This ensures comprehensive material support while maintaining type safety and enabling compile-time optimizations in the spectral element framework.

// Create materials database for 1000 elements with 5 unique materials
spectral::mesh::meshfem3d::materials<specfem::element::dimension_tag::dim3>
    materials(1000, 5);

// Add an isotropic elastic material from MESHFEM3D database
specfem::medium_container::material<specfem::element::medium_tag::elastic,
                         specfem::element::property_tag::isotropic>
elastic_mat; materials.add_material(elastic_mat, database_index);

// Retrieve material for element during simulation
auto material = materials.get_material<specfem::element::medium_tag::elastic,
                                      specfem::element::property_tag::isotropic>(elem_id);

See also

specfem::medium_container::material

Core Data Members

int n_materials = 0

Total number of materials across all type containers.

int nspec

Total number of spectral elements in the mesh.

std::vector<material_specification> material_index_mapping

Mapping from element index to material specification.

For each spectral element in the mesh, stores the material specification that identifies which material container and index to use for retrieving the element’s material properties. This provides the link between mesh topology and material database entries.

Constructors

inline materials()

Default constructor creating empty materials database.

Creates an uninitialized materials collection with no elements or materials. Suitable for delayed initialization or when material data will be populated later through other means.

Material Access Interface

template<specfem::element::medium_tag MediumTag, specfem::element::property_tag PropertyTag, specfem::element::attenuation_tag AttenuationTag>
inline specfem::medium_container::material<dimension_tag, MediumTag, PropertyTag, AttenuationTag> get_material(const int index) const

Retrieve material object for a specific element with type safety.

Returns the material object associated with the given element index using compile-time template parameters for the specified medium and property types.

// Retrieve elastic isotropic material for element 42
auto elastic_material = materials.get_material<
    specfem::element::medium_tag::elastic,
    specfem::element::property_tag::isotropic>(42);

// Access material properties
auto density = elastic_material.get_density();
auto vp = elastic_material.get_p_velocity();
auto vs = elastic_material.get_s_velocity();

// Use in wave equation computations
compute_elastic_forces(elastic_material, element_coords);

Template Parameters:

  • MediumTag – Medium type (acoustic, elastic)

  • PropertyTag – Property type (isotropic, anisotropic)

Parameters:

index – Element index to retrieve material for

Returns:

Material object with specified medium and property types

template<specfem::element::medium_tag MediumTag, specfem::element::property_tag PropertyTag, specfem::element::attenuation_tag AttenuationTag>
inline specfem::mesh::materials<dimension_tag>::material<MediumTag, PropertyTag, AttenuationTag> &get_container()

Get reference to material container for specific medium and property types.

Returns a reference to the internal container storing materials of the specified type combination for direct access by material management functions.

// Get container for elastic isotropic materials
auto& elastic_container = materials.get_container<
    specfem::element::medium_tag::elastic,
    specfem::element::property_tag::isotropic>();

// Access container properties
int num_elastic_materials = elastic_container.n_materials;
auto& material_vector = elastic_container.element_materials;

// Direct manipulation (use with caution)
elastic_container.element_materials.reserve(expected_count);

Template Parameters:

  • MediumTag – Medium type (acoustic, elastic)

  • PropertyTag – Property type (isotropic, anisotropic)

Returns:

Reference to the material container for specified types

template<specfem::element::medium_tag MediumTag, specfem::element::property_tag PropertyTag, specfem::element::attenuation_tag AttenuationTag>
inline int add_material(const specfem::medium_container::material<dimension_tag, MediumTag, PropertyTag, AttenuationTag> &new_material)

Add a new material to the database.

Adds a material to the appropriate container based on its type, updates counts, and creates mapping to the original MESHFEM3D database index.

// Add elastic isotropic material from MESHFEM3D database
specfem::medium_container::material<specfem::element::medium_tag::elastic,
                         specfem::element::property_tag::isotropic> mat;
const auto index = materials.add_material(mat);

Template Parameters:

  • MediumTag – Medium type (acoustic, elastic)

  • PropertyTag – Property type (isotropic, anisotropic)

Parameters:

  • new_material – Material object to add

  • database_index – Original MESHFEM3D database index

Returns:

Local index of the added material within its container

inline std::tuple<specfem::element::medium_tag, specfem::element::property_tag, specfem::element::attenuation_tag> get_material_type(const int index) const

Get the medium and property types for a given element index.

Returns a tuple containing the medium and property tags associated with the material specification for the specified element index.

// Get material type for element 42
auto [medium, property] = materials.get_material_type(42);

// Use in conditional logic
if (medium == specfem::element::medium_tag::elastic &&
    property == specfem::element::property_tag::isotropic) {
    // Handle elastic isotropic case
}

Parameters:

index – Element index to query

Returns:

Tuple of (medium_tag, property_tag) for the element’s material

Public Static Attributes

static constexpr auto dimension_tag = specfem::element::dimension_tag::dim3

Dimension tag for compile-time type identification.

Fixed to dim3 for this specialization, used for template metaprogramming and ensuring compatibility with the SPECFEM++ dimension system.

template<>
struct material

Template container for materials of specific type and property.

Stores material objects of a specific medium/property combination with count tracking for efficient memory management. Each container holds materials of exactly one type (e.g., all elastic isotropic materials).

This design enables:

  • Type-safe material storage and retrieval

  • Efficient memory layout for materials of the same type

  • Compile-time optimization based on material properties

  • Integration with SPECFEM++ template metaprogramming system

Template Parameters:

  • type – Medium type (acoustic, elastic)

  • property – Property type (isotropic, anisotropic)

Public Functions

inline material()

Default constructor creating empty container.

material(const int n_materials, const std::vector<specfem::medium_container::material<dimension_tag, type, property, attenuation>> &l_material)

Construct container from existing material vector.

Parameters:

  • n_materials – Number of materials to store

  • l_material – Vector of materials to initialize container with

Public Members

int n_materials = 0

Number of materials stored in this container.

std::vector<specfem::medium_container::material<dimension_tag, type, property, attenuation>> element_materials

Storage for material objects of this type/property combination.

template<>
struct material_specification

Material specification linking elements to material database entries.

Associates spectral elements with their corresponding material types and database indices from MESHFEM3D material files. This structure provides the mapping between mesh topology and material properties.

Used internally to maintain the association between:

  • Element indices in the mesh

  • Material types (medium + property combinations)

  • Original database indices from MESHFEM3D input files

  • Local indices within type-specific material containers

Public Functions

material_specification() = default

Default constructor initializing with default values.

inline material_specification(specfem::element::medium_tag type, specfem::element::property_tag property, specfem::element::attenuation_tag attenuation, int index, int database_index)

Construct material specification from components.

Parameters:

  • type – Physical medium type for wave equation selection

  • property – Material property type for constitutive relations

  • index – Local material index within container

  • database_index – Original MESHFEM3D database index

Public Members

specfem::element::medium_tag type

Physical medium type (acoustic, elastic, etc.)

specfem::element::property_tag property

Material property type (isotropic, anisotropic)

specfem::element::attenuation_tag attenuation

Attenuation type (none, constant_isotropic, etc.)

int index

Local index within the type-specific material container.

int database_index

Original database index from MESHFEM3D material files.

Implementation Details