dash::halo::HaloMatrixWrapper< MatrixT, SigReady > Class Template Reference

As known from classic stencil algorithms, boundaries are the outermost elements within a block that are requested by neighoring units. More...

#include <HaloMatrixWrapper.h>

Public Types
using	Element_t = typename MatrixT::value_type
using	ViewSpec_t = ViewSpec< NumDimensions, pattern_index_t >
using	GlobBoundSpec_t = GlobalBoundarySpec< NumDimensions >
using	HaloBlock_t = HaloBlock< Element_t, Pattern_t, GlobMem_t >
using	HaloMemory_t = HaloMemory< HaloBlock_t >
using	HaloUpdateEnv_t = HaloUpdateEnv< HaloBlock_t, SigReady >
using	ElementCoords_t = std::array< pattern_index_t, NumDimensions >
using	region_index_t = internal::region_index_t
using	stencil_dist_t = internal::spoint_value_t

Public Member Functions
template<size_t NumStencilPointsFirst, typename... StencilSpecRestT>
	HaloMatrixWrapper (MatrixT &matrix, const GlobBoundSpec_t &glob_bnd_spec, const StencilSpec< StencilPoint< NumDimensions >, NumStencilPointsFirst > &stencil_spec_first, const StencilSpecRestT &... stencil_spec)
	Constructor that takes Matrix, a GlobalBoundarySpec and a user defined number of stencil specifications (StencilSpec) More...
template<typename StencilPointT = StencilPoint<NumDimensions>>
	HaloMatrixWrapper (MatrixT &matrix, const GlobBoundSpec_t &glob_bnd_spec, stencil_dist_t dist, std::enable_if_t< std::is_integral< stencil_dist_t >::value, std::nullptr_t >=nullptr)
	Constructor that takes Matrix and a stencil point distance to create a HaloMatrixWrapper with a full stencil with the given width. More...
template<typename StencilPointT = StencilPoint<NumDimensions>>
	HaloMatrixWrapper (MatrixT &matrix, stencil_dist_t dist, std::enable_if_t< std::is_integral< stencil_dist_t >::value, std::nullptr_t >=nullptr)
	Constructor that takes Matrix and a stencil point distance to create a HaloMatrixWrapper with a full stencil with the given width. More...
template<typename StencilPointT , std::size_t NumStencilPoints>
	HaloMatrixWrapper (MatrixT &matrix, const StencilSpec< StencilPointT, NumStencilPoints > stencil_spec)
	Constructor that takes Matrix and a user defined number of stencil specifications (StencilSpec). More...
template<typename... StencilSpecT, typename std::enable_if_t< sizeof...(StencilSpecT) > = 2, bool >
	HaloMatrixWrapper (MatrixT &matrix, const StencilSpecT &... stencil_spec)
	Constructor that takes Matrix and a user defined number of stencil specifications (StencilSpec). More...
const HaloBlock_t &	halo_block ()
	Returns the underlying HaloBlock. More...
void	update ()
	Initiates a blocking halo region update for all halo elements. More...
void	update_at (region_index_t index)
	Initiates a blocking halo region update for all halo elements within the the given region. More...
void	update_async ()
	Initiates an asychronous halo region update for all halo elements. More...
void	update_async_at (region_index_t index)
	Initiates an asychronous halo region update for all halo elements within the given region. More...
void	wait ()
	Waits until all halo updates are finished. More...
void	wait (region_index_t index)
	Waits until the halo updates for the given halo region is finished. More...
const ViewSpec_t &	view_local () const
	Returns the local ViewSpec. More...
HaloUpdateEnv_t &	halo_env ()
	Returns the halo environment management object HaloUpdateEnv. More...
const HaloUpdateEnv_t &	halo_env () const
	Returns the halo environment management object HaloUpdateEnv. More...
MatrixT &	matrix ()
	Returns the underlying NArray. More...
const MatrixT &	matrix () const
	Returns the underlying NArray. More...
template<typename FunctionT >
void	set_custom_halos (FunctionT f)
	Sets all global border halo elements. More...
Element_t *	halo_element_at_global (ElementCoords_t coords)
	Returns the halo value for a given global coordinate or nullptr if no halo element exists. More...
Element_t *	halo_element_at_local (ElementCoords_t coords)
	Returns the halo value for a given local coordinate or nullptr if no halo element exists. More...
template<typename StencilSpecT >
StencilOperator< HaloBlock_t, StencilSpecT >	stencil_operator (const StencilSpecT &stencil_spec)
	Crates StencilOperator for a given StencilSpec. More...
CoordinateAccess< HaloBlock_t >	coordinate_access ()

Detailed Description

template<typename MatrixT, SignalReady SigReady = SignalReady::OFF>
class dash::halo::HaloMatrixWrapper< MatrixT, SigReady >

As known from classic stencil algorithms, boundaries are the outermost elements within a block that are requested by neighoring units.

Halos represent additional outer regions of a block that contain ghost cells with values copied from adjacent units' boundary regions.

The HaloMatrixWrapper acts as a wrapper of the local blocks of the NArray and extends these by boundary and halo regions. The HaloMatrixWrapper also provides a function to create a StencilOperator.

Example for an outer block boundary iteration space (halo regions):

       .--halo region 0   .-- halo region 1
      /                  /
  .-------..-------------------------. -.
  |  0  1 ||  0  1  2  3  4  5  6  7 |  |
  |  2  3 ||  8  9 10 11 12 13 14 15 |  |-- halo width in dimension 0
  '-------''-------------------------' -'
  .-------..-------------------------..-------.
  |  0  1 ||                         ||  0  1 |
  :  ...  ::       local block       ::  ...  : --- halo region 5
  |  6  7 ||                         ||  6  7 |
  '-------''-------------------------''-------'
      :    .-------------------------.:       :
      |    |  0  1  2  3  4  5  6  7 |'---.---'
      |    |  8  9 10 11 12 13 14 15 |    :
      |    `-------------------------'    '- halo width in dimension 1
      '                  \
halo region 3             '- halo region 7

Examples:

ex.11.halo-stencil/main.cpp.

Definition at line 53 of file HaloMatrixWrapper.h.

Constructor & Destructor Documentation

HaloMatrixWrapper() [1/5]

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

template<size_t NumStencilPointsFirst, typename... StencilSpecRestT>

dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::HaloMatrixWrapper ( MatrixT &  matrix, const GlobBoundSpec_t &  glob_bnd_spec, const StencilSpec< StencilPoint< NumDimensions >, NumStencilPointsFirst > &  stencil_spec_first, const StencilSpecRestT &...  stencil_spec  )

inline

Constructor that takes Matrix, a GlobalBoundarySpec and a user defined number of stencil specifications (StencilSpec)

Definition at line 87 of file HaloMatrixWrapper.h.

  : _matrix(matrix), _glob_bnd_spec(glob_bnd_spec),
    _halo_spec(stencil_spec_first, stencil_spec...),
    _view_global(matrix.local.offsets(), matrix.local.extents()),
    _haloblock(matrix.begin().globmem(), matrix.pattern(), _view_global,
               _halo_spec, glob_bnd_spec),
    _view_local(_haloblock.view_local()),
    //_halomemory(_haloblock),
    _halo_env(_haloblock, matrix.lbegin(), matrix.team(), matrix.pattern().teamspec()) {
  }

HaloMatrixWrapper() [2/5]

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

template<typename StencilPointT = StencilPoint<NumDimensions>>

dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::HaloMatrixWrapper ( MatrixT &  matrix, const GlobBoundSpec_t &  glob_bnd_spec, stencil_dist_t  dist, std::enable_if_t< std::is_integral< stencil_dist_t >::value, std::nullptr_t >  = nullptr  )

inline

Constructor that takes Matrix and a stencil point distance to create a HaloMatrixWrapper with a full stencil with the given width.

The GlobalBoundarySpec is set to default.

Definition at line 107 of file HaloMatrixWrapper.h.

  : HaloMatrixWrapper(matrix, glob_bnd_spec, StencilSpecFactory<StencilPointT>::full_stencil_spec(dist)) {
  }

HaloMatrixWrapper() [3/5]

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

template<typename StencilPointT = StencilPoint<NumDimensions>>

dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::HaloMatrixWrapper ( MatrixT &  matrix, stencil_dist_t  dist, std::enable_if_t< std::is_integral< stencil_dist_t >::value, std::nullptr_t >  = nullptr  )

inline

Constructor that takes Matrix and a stencil point distance to create a HaloMatrixWrapper with a full stencil with the given width.

The GlobalBoundarySpec is set to default.

Definition at line 119 of file HaloMatrixWrapper.h.

  : HaloMatrixWrapper(matrix, GlobBoundSpec_t(), StencilSpecFactory<StencilPointT>::full_stencil_spec(dist)) {
  }

HaloMatrixWrapper() [4/5]

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

template<typename StencilPointT , std::size_t NumStencilPoints>

dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::HaloMatrixWrapper ( MatrixT &  matrix, const StencilSpec< StencilPointT, NumStencilPoints >  stencil_spec  )

inline

Constructor that takes Matrix and a user defined number of stencil specifications (StencilSpec).

The GlobalBoundarySpec is set to default.

Definition at line 129 of file HaloMatrixWrapper.h.

  : HaloMatrixWrapper(matrix, GlobBoundSpec_t(), stencil_spec) {}

HaloMatrixWrapper() [5/5]

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

template<typename... StencilSpecT, typename std::enable_if_t< sizeof...(StencilSpecT) > = 2, bool >

dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::HaloMatrixWrapper ( MatrixT &  matrix, const StencilSpecT &...  stencil_spec  )

inline

Constructor that takes Matrix and a user defined number of stencil specifications (StencilSpec).

The GlobalBoundarySpec is set to default.

Definition at line 138 of file HaloMatrixWrapper.h.

  : HaloMatrixWrapper(matrix, GlobBoundSpec_t(), stencil_spec...) {}

Member Function Documentation

halo_block()

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

const HaloBlock_t& dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::halo_block ( )

inline

Returns the underlying HaloBlock.

Definition at line 146 of file HaloMatrixWrapper.h.

{ return _haloblock; }

halo_element_at_global()

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

Element_t* dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::halo_element_at_global ( ElementCoords_t  coords )

inline

Returns the halo value for a given global coordinate or nullptr if no halo element exists.

This also means that only a unit connected to the given coordinate will return a halo value. All others will return nullptr.

Definition at line 285 of file HaloMatrixWrapper.h.

                                                            {
    const auto& offsets = _view_global.offsets();
    for(auto d = 0; d < NumDimensions; ++d) {
      coords[d] -= offsets[d];
    }

    return halo_element_at(coords);
  }

halo_element_at_local()

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

Element_t* dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::halo_element_at_local ( ElementCoords_t  coords )

inline

Returns the halo value for a given local coordinate or nullptr if no halo element exists.

Definition at line 298 of file HaloMatrixWrapper.h.

                                                           {
    return halo_element_at(coords);
  }

halo_env() [1/2]

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

HaloUpdateEnv_t& dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::halo_env ( )

inline

Returns the halo environment management object HaloUpdateEnv.

Definition at line 203 of file HaloMatrixWrapper.h.

{ return _halo_env; }

halo_env() [2/2]

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

const HaloUpdateEnv_t& dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::halo_env ( ) const

inline

Returns the halo environment management object HaloUpdateEnv.

Definition at line 208 of file HaloMatrixWrapper.h.

{ return _halo_env; }

matrix() [1/2]

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

MatrixT& dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::matrix ( )

inline

Returns the underlying NArray.

Examples:

ex.11.halo-stencil/main.cpp.

Definition at line 213 of file HaloMatrixWrapper.h.

{ return _matrix; }

matrix() [2/2]

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

const MatrixT& dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::matrix ( ) const

inline

Returns the underlying NArray.

Definition at line 218 of file HaloMatrixWrapper.h.

{ return _matrix; }

set_custom_halos()

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

template<typename FunctionT >

void dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::set_custom_halos ( FunctionT  f )

inline

Sets all global border halo elements.

set_custom_halos calls FuntionT with all global coordinates of type: std::array<dash::default_index_t,Number Dimensions>.

Every unit is called only with the related global coordinates. E.g.:

.............
: Border    | <- coordinates for example:
: Unit 0    |    (-1,-1),(0,-1), (-2,5)
:  .--------..--------.
:  |        ||        |
:  | Unit 0 || Unit 1 |
:  |        ||        |
'- :--------::--------:
   |        ||        |
   | Unit 2 || Unit 3 |
   |        ||        |
   '--------''--------'

Definition at line 243 of file HaloMatrixWrapper.h.

References dash::halo::HaloBlock< ElementT, PatternT, GlobMemT >::boundary_regions(), dash::distance(), dash::halo::HaloUpdateEnv< HaloBlockT, SigReady >::halo_memory(), dash::Matrix< ElementT, NumDimensions, IndexT, PatternT, LocalMemSpaceT >::pattern(), and dash::halo::HaloMemory< HaloBlockT >::range_at().

                                     {
    using signed_extent_t = typename std::make_signed<pattern_size_t>::type;
    for(const auto& region : _haloblock.boundary_regions()) {
      if(!region.is_custom_region()) {
        continue;
      }

      const auto& spec    = region.spec();
      std::array<signed_extent_t, NumDimensions> coords_offset{};
      const auto& reg_ext = region.view().extents();
      for(auto d = 0; d < NumDimensions; ++d) {
        if(spec[d] == 0) {
          coords_offset[d] -= reg_ext[d];
          continue;
        }
        if(spec[d] == 2)
          coords_offset[d] = reg_ext[d];
      }

      auto range_mem = _halo_env.halo_memory().range_at(region.index());
      auto it_mem = range_mem.first;
      auto it_reg_end  = region.end();
      DASH_ASSERT_MSG(
          std::distance(range_mem.first, range_mem.second) == region.size(),
          "Range distance of the HaloMemory is unequal region size");
      const auto& pattern = _matrix.pattern();
      for(auto it = region.begin(); it != it_reg_end; ++it, ++it_mem) {
        auto coords = pattern.coords(it.rpos(), region.view());
        for(auto d = 0; d < NumDimensions; ++d) {
          coords[d] += coords_offset[d];
        }

        *it_mem = f(coords);
      }
    }
  }

stencil_operator()

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

template<typename StencilSpecT >

StencilOperator<HaloBlock_t, StencilSpecT> dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::stencil_operator ( const StencilSpecT &  stencil_spec )

inline

Crates StencilOperator for a given StencilSpec.

Asserts whether the StencilSpec fits in the provided halo regions.

Examples:

ex.11.halo-stencil/main.cpp.

Definition at line 307 of file HaloMatrixWrapper.h.

References dash::halo::HaloSpec< NumDimensions >::extent(), dash::halo::HaloUpdateEnv< HaloBlockT, SigReady >::halo_memory(), dash::index(), dash::halo::HaloBlock< ElementT, PatternT, GlobMemT >::index_at(), dash::Matrix< ElementT, NumDimensions, IndexT, PatternT, LocalMemSpaceT >::lbegin(), dash::halo::HaloMemory< HaloBlockT >::range_at(), dash::halo::HaloSpec< NumDimensions >::spec(), and dash::halo::StencilSpec< StencilPointT, NumStencilPoints >::specs().

                                      {
    for(const auto& stencil : stencil_spec.specs()) {
      DASH_ASSERT_MSG(
        stencil.max()
          <= _halo_spec.extent(RegionSpec<NumDimensions>::index(stencil)),
        "Stencil point extent higher than halo region extent.");
    }

    return StencilOperator<HaloBlock_t, StencilSpecT>(
      &_haloblock, _matrix.lbegin(), &_halo_env.halo_memory(), stencil_spec);
  }

update()

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

void dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::update ( )

inline

Initiates a blocking halo region update for all halo elements.

Definition at line 151 of file HaloMatrixWrapper.h.

References dash::halo::HaloUpdateEnv< HaloBlockT, SigReady >::update().

                {
    _halo_env.update();
  }

update_async()

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

void dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::update_async ( )

inline

Initiates an asychronous halo region update for all halo elements.

Examples:

ex.11.halo-stencil/main.cpp.

Definition at line 166 of file HaloMatrixWrapper.h.

References dash::halo::HaloUpdateEnv< HaloBlockT, SigReady >::update_async().

                      {
    _halo_env.update_async();
  }

update_async_at()

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

void dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::update_async_at ( region_index_t  index )

inline

Initiates an asychronous halo region update for all halo elements within the given region.

Definition at line 174 of file HaloMatrixWrapper.h.

References dash::halo::HaloUpdateEnv< HaloBlockT, SigReady >::update_async_at().

                                             {
    _halo_env.update_async_at(index);
  }

update_at()

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

void dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::update_at ( region_index_t  index )

inline

Initiates a blocking halo region update for all halo elements within the the given region.

Definition at line 159 of file HaloMatrixWrapper.h.

References dash::halo::HaloUpdateEnv< HaloBlockT, SigReady >::update_at().

                                       {
    _halo_env.update_at(index);
  }

view_local()

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

const ViewSpec_t& dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::view_local ( ) const

inline

Returns the local ViewSpec.

Definition at line 198 of file HaloMatrixWrapper.h.

{ return _view_local; }

wait() [1/2]

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

void dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::wait ( )

inline

Waits until all halo updates are finished.

Only useful for asynchronous halo updates.

Examples:

ex.11.halo-stencil/main.cpp.

Definition at line 182 of file HaloMatrixWrapper.h.

References dash::halo::HaloUpdateEnv< HaloBlockT, SigReady >::wait().

              {
    _halo_env.wait();
  }

wait() [2/2]

template<typename MatrixT , SignalReady SigReady = SignalReady::OFF>

void dash::halo::HaloMatrixWrapper< MatrixT, SigReady >::wait ( region_index_t  index )

inline

Waits until the halo updates for the given halo region is finished.

Only useful for asynchronous halo updates.

Definition at line 190 of file HaloMatrixWrapper.h.

References dash::halo::HaloUpdateEnv< HaloBlockT, SigReady >::wait().

                                  {
    _halo_env.wait(index);
  }

---

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

• /tmp/tmporruphar/dash/include/dash/halo/HaloMatrixWrapper.h