DATA_CONTAINER¶

Overview¶

The DATA_CONTAINER macro is a utility for generating standard data container structures for different medium types in SPECFEMPP. It creates a structured collection of DomainView2d elements with consistent interface methods for accessing and synchronizing data between host and device memory spaces.

Syntax¶

DATA_CONTAINER(param1, param2, ...)

Where param1, param2, etc. are the names of the DomainView2d elements to be included in the container.

Description¶

The DATA_CONTAINER macro generates:

A set of DomainView2d fields with the specified names
Corresponding host mirror variables for each field
Constructors that initialize these views with the proper dimensions
Methods to iterate over elements on both device and host
Synchronization methods to copy data between device and host views
Methods to iterate over all device and host views

Generated Methods¶

Method	Description
`copy_to_device()`	Synchronizes all data from host to device
`copy_to_host()`	Synchronizes all data from device to host
`for_each_on_device(index,` `functor)`	Applies a functor to each element specified by an index on the device
`for_each_on_host(index,` `functor)`	Applies a functor to each element specified by an index on the host
`for_each_device_view(` `functor)`	Applies a functor to each device view
`for_each_host_view(` `functor)`	Applies a functor to each host view

Examples¶

Basic Usage¶

struct MyContainer {
  DATA_CONTAINER(rho, kappa, mu)
};

This generates a container with three DomainView2d elements: rho, kappa, and mu.

In Context of SPECFEMPP¶

namespace specfem::medium_container::properties {
  template <>
  struct data_container<specfem::element::medium_tag::elastic,
                       specfem::element::property_tag::isotropic> {
    constexpr static auto dimension = specfem::element::dimension_tag::dim2;
    constexpr static auto medium_tag = specfem::element::medium_tag::elastic;
    constexpr static auto property_tag = specfem::element::property_tag::isotropic;

    DATA_CONTAINER(kappa, mu, rho)
  };
}

Generated Code Example¶

For DATA_CONTAINER(rho, kappa), the generated code includes:

// Field definitions
DomainView2d<type_real, 3, Kokkos::DefaultExecutionSpace::memory_space> rho;
DomainView2d<type_real, 3, Kokkos::DefaultExecutionSpace::memory_space> kappa;
typename decltype(rho)::HostMirror h_rho;
typename decltype(kappa)::HostMirror h_kappa;

// Constructor
data_container(const int nspec, const int ngllz, const int ngllx)
    : rho("rho", nspec, ngllz, ngllx),
      kappa("kappa", nspec, ngllz, ngllx),
      h_rho(specfem::kokkos::create_mirror_view(rho)),
      h_kappa(specfem::kokkos::create_mirror_view(kappa)) {}

// Synchronization methods
void copy_to_device() {
  specfem::kokkos::deep_copy(rho, h_rho);
  specfem::kokkos::deep_copy(kappa, h_kappa);
}

void copy_to_host() {
  specfem::kokkos::deep_copy(h_rho, rho);
  specfem::kokkos::deep_copy(h_kappa, kappa);
}

// And other accessor methods...

Use Cases¶

The DATA_CONTAINER macro is extensively used throughout SPECFEMPP for various medium types:

Acoustic media (rho_inverse, kappa)
Elastic isotropic media (kappa, mu, rho)
Elastic anisotropic media (c11, c13, c15, c33, c35, c55, c12, c23, c25, rho)
Elastic isotropic Cosserat media (rho, kappa, mu, nu, j, lambda_c, mu_c, nu_c)
Poroelastic media (phi, rho_s, rho_f, tortuosity, mu_G, H_Biot, C_Biot, M_Biot, etc.)

Technical Implementation¶

The macro leverages Boost Preprocessor library to generate repetitive code patterns, enabling compile-time code generation without the need for template metaprogramming. It handles the complex task of creating consistent interfaces for accessing data in a heterogeneous computing environment.