ryujin::Mirrored< T > Class Template Reference

#include <include/ryujin/base/gpu.h>

Inheritance diagram for ryujin::Mirrored< T >:

Collaboration diagram for ryujin::Mirrored< T >:

Public Types
using	value_type = std::remove_pointer_t< T >

Public Member Functions
template<typename InitializedMemorySpace = dealii::MemorySpace::Host> requires (!is_array)
	Mirrored (const std::string &label="mirrored object", const TransferPolicy transfer_policy=TransferPolicy::explicit_transfers, InitializedMemorySpace={})
template<typename InitializedMemorySpace = dealii::MemorySpace::Host> requires (is_array)
	Mirrored (const std::string &label="mirrored array", const std::size_t size=0, const TransferPolicy transfer_policy=TransferPolicy::explicit_transfers, InitializedMemorySpace={})
template<typename InitializedMemorySpace = dealii::MemorySpace::Host> requires (is_array)
void	reinit (const std::size_t size, const TransferPolicy transfer_policy=TransferPolicy::explicit_transfers, InitializedMemorySpace={})
std::size_t	size () const
template<typename MemorySpace = dealii::MemorySpace::Host>
value_type *	view ()
template<typename MemorySpace = dealii::MemorySpace::Host>
const value_type *	view () const
Public Member Functions inherited from ryujin::MirroredStorage< Mirrored< T > >
bool	is_resident () const
bool	is_pinned () const
void	copy_to_memory_space () const
void	move_to_memory_space ()
TransferPolicy	transfer_policy () const
void	set_transfer_policy (const TransferPolicy transfer_policy)

Static Public Attributes
static constexpr bool	is_array = std::is_pointer_v<T>

Internal fields, methods, and friends
class	MirroredStorage< Mirrored< T > >

Additional Inherited Members
Protected Member Functions inherited from ryujin::MirroredStorage< Mirrored< T > >
	MirroredStorage ()=default
void	prepare_read_access () const
void	prepare_write_access ()
void	reset_residency (const bool host_resident, const bool default_resident)

Detailed Description

template<typename T>
class ryujin::Mirrored< T >

A convenience wrapper around MirroredStorage that maintains a (trivially copyable) payload mirrored between the host and default (device) memory spaces.

This allows to encapsulate a "POD style" payload (such as the runtime parameters of a class) in a single structure that is moved into device memory once - instead of copying individual parameters field by field into a "view" object that is then captured by value in a computation loop.

The class operates in one of two modes that are selected by the template argument:

• Mirrored<T> maintains a single object of type T.
• Mirrored<T *> maintains a one dimensional array of objects of type T. The length is set in the constructor, or with reinit() and queried with size().

Intended usage of the scalar mode, here with the TransferPolicy::implicit_transfers_host_resident policy so that the payload is transferred on demand and the host storage - into which the runtime parameters are bound - is never deallocated:

class HyperbolicSystem {
public:
  struct Parameters { double gamma; double gamma_inverse; };
 
  HyperbolicSystem()
    : parameters_("hyperbolic system parameters",
                  TransferPolicy::implicit_transfers_host_resident)
  {
    auto *parameters = parameters_.view();
    parameters->gamma = 1.4;
    add_parameter("gamma", parameters->gamma, "...");
    // ... and call update_parameters() whenever "gamma" changes.
  }
 
  void update_parameters()
  {
    // A writable view drops the (now stale) mirror in the default
    // memory space:
    auto *parameters = parameters_.view();
    parameters->gamma_inverse = 1. / parameters->gamma;
  }
 
  template <typename MemorySpace>
  class View {
  public:
    View(const HyperbolicSystem &hyperbolic_system)
        // ... which is copied over again here:
        : parameters_(
              hyperbolic_system.parameters_.template view<MemorySpace>())
    {
    }
 
    DEAL_II_HOST_DEVICE double gamma() const { return parameters_->gamma; }
 
  private:
    const Parameters *parameters_;
  };
 
  template <typename MemorySpace>
  View<MemorySpace> view() const { return View<MemorySpace>(*this); }
 
private:
  Mirrored<Parameters> parameters_;
};

The array mode uses the same raw pointer interface, but the storage is sized explicitly with reinit():

class Stencil {
public:
  struct Entry { unsigned int index; double weight; };
 
  Stencil() : entries_("stencil entries") {}
 
  void prepare(const std::size_t n_entries)
  {
    entries_.reinit(n_entries, TransferPolicy::implicit_transfers);
 
    auto *entries = entries_.view();
    for (std::size_t i = 0; i < entries_.size(); ++i)
      entries[i] = {static_cast<unsigned int>(i), 1.};
  }
 
private:
  Mirrored<Entry *> entries_;
};

Note

The transfer policy defaults to TransferPolicy::explicit_transfers, where view() never triggers a memory transfer on its own and all transfers have to be requested manually. Keep in mind that copy_to_memory_space() is a no-op if the selected memory space is already resident: updating the payload under that policy requires a move_to_memory_space<Host>() before the write, and a copy_to_memory_space<Default>() afterwards.

The pointer returned by view() may only be dereferenced on the selected memory space. In the array mode the pointer references the first of size() contiguously stored objects; the length is not part of the returned pointer and has to be carried along by the caller.

In contrast to a copied Kokkos::View the pointer returned by view() does not pin the underlying storage: it dangles after a move_to_memory_space() away from the corresponding memory space - such as the implicit one performed by a writable view() under an implicit transfer policy. The TransferPolicy::implicit_transfers_host_resident policy used in the example above guarantees that the pointer into the host storage remains valid, but the device mirror is still dropped by every writable host view(): Recreate the View objects of the example above after every parameter update.

An object of this class allocates memory with Kokkos. It thus has to be created after Kokkos has been initialized, which is done by the dealii::Utilities::MPI::MPI_InitFinalize constructor.

Definition at line 459 of file gpu.h.

Member Typedef Documentation

value_type

template<typename T >

using ryujin::Mirrored< T >::value_type = std::remove_pointer_t<T>

The type of the stored object: T itself in the scalar mode, and the pointee type in the array mode.

Definition at line 473 of file gpu.h.

Constructor & Destructor Documentation

Mirrored() [1/2]

template<typename T >

template<typename InitializedMemorySpace = dealii::MemorySpace::Host>
requires (!is_array)

ryujin::Mirrored< T >::Mirrored	(	const std::string &	label = "mirrored object",
		const TransferPolicy	transfer_policy = TransferPolicy::explicit_transfers,
		InitializedMemorySpace	= {}
	)

Constructor for the scalar mode. Allocates the storage of a single object on the selected memory space. The label is used as the Kokkos allocation label, transfer_policy selects the transfer policy, see the documentation of TransferPolicy, and the (defaulted) last argument selects the memory space that is initialized.

Note

The selected memory space has to be consistent with the transfer policy: a policy that pins the other memory space is not admissible, see MirroredStorage.

Mirrored() [2/2]

template<typename T >

template<typename InitializedMemorySpace = dealii::MemorySpace::Host>
requires (is_array)

ryujin::Mirrored< T >::Mirrored	(	const std::string &	label = "mirrored array",
		const std::size_t	size = 0,
		const TransferPolicy	transfer_policy = TransferPolicy::explicit_transfers,
		InitializedMemorySpace	= {}
	)

Constructor for the array mode. Allocates the storage of a single object on the selected memory space. The label is used as the Kokkos allocation label, transfer_policy selects the transfer policy, see the documentation of TransferPolicy, and the (defaulted) last argument selects the memory space that is initialized.

Note

The selected memory space has to be consistent with the transfer policy: a policy that pins the other memory space is not admissible, see MirroredStorage.

Member Function Documentation

reinit()

template<typename T >

template<typename InitializedMemorySpace = dealii::MemorySpace::Host>
requires (is_array)

void ryujin::Mirrored< T >::reinit	(	const std::size_t	size,
		const TransferPolicy	transfer_policy = TransferPolicy::explicit_transfers,
		InitializedMemorySpace	= {}
	)

Reinitialize the object to maintain size objects. The storage is (re)allocated (and zero initialized) on the selected default memory space.

size()

template<typename T >

std::size_t ryujin::Mirrored< T >::size

(

)

const

Return the number of stored objects.

view() [1/2]

template<typename T >

template<typename MemorySpace = dealii::MemorySpace::Host>

value_type * ryujin::Mirrored< T >::view

(

)

Return a writable pointer to the stored object residing in the selected memory space. In the array mode the pointer references the first of size() contiguously stored objects.

view() [2/2]

template<typename T >

template<typename MemorySpace = dealii::MemorySpace::Host>

const value_type * ryujin::Mirrored< T >::view

(

)

const

Return a read only pointer to the stored object residing in the selected memory space. In the array mode the pointer references the first of size() contiguously stored objects.

Friends And Related Symbol Documentation

MirroredStorage< Mirrored< T > >

template<typename T >

friend class MirroredStorage< Mirrored< T > >

friend

Definition at line 604 of file gpu.h.

Member Data Documentation

is_array

template<typename T >

constexpr bool ryujin::Mirrored< T >::is_array = std::is_pointer_v<T>

staticconstexpr

True if the class maintains a one dimensional array of objects, i.e., if the template argument is of the form T *, and false if the class maintains a single object of type T.

Definition at line 467 of file gpu.h.

---

The documentation for this class was generated from the following file:

• include/ryujin/base/gpu.h