Pattern Concept

Concept of a distribution pattern of n-dimensional containers to units in a team. More...

Collaboration diagram for Pattern Concept:

Modules
	Pattern Properties
	Property system for specification and deduction of pattern types.

Classes
class	dash::BlockPattern< NumDimensions, Arrangement, IndexType >
	Defines how a list of global indices is mapped to single units within a Team. More...
class	dash::BlockPattern< 1, Arrangement, IndexType >
	Defines how a list of global indices is mapped to single units within a Team. More...
class	dash::CSRPattern< 1, Arrangement, IndexType >
	Irregular Pattern for Compressed Sparse Row Storage. More...
class	dash::DynamicPattern< 1, Arrangement, IndexType >
	Irregular dynamic pattern. More...
class	dash::LoadBalancePattern< NumDimensions, CompBasedMeasure, MemBasedMeasure, Arrangement, IndexType >
	Irregular dynamic pattern. More...
class	dash::LoadBalancePattern< 1, CompBasedMeasure, MemBasedMeasure, Arrangement, IndexType >
	Irregular dynamic pattern. More...
class	dash::PatternIterator< PatternType, IndexType >
	{}Usage: More...
class	dash::SeqTilePattern< NumDimensions, Arrangement, IndexType >
	Defines how a list of global indices is mapped to single units within a Team. More...
class	dash::ShiftTilePattern< NumDimensions, Arrangement, IndexType >
	Defines how a list of global indices is mapped to single units within a Team. More...
class	dash::TilePattern< NumDimensions, Arrangement, IndexType >
	Defines how a list of global indices is mapped to single units within a Team. More...

Functions
template<typename PartitioningTags , typename MappingTags , typename LayoutTags , class SizeSpecType >
TeamSpec< SizeSpecType::ndim::value, typename SizeSpecType::index_type >	dash::make_team_spec (const SizeSpecType &sizespec, dash::Team &team=dash::Team::All(), typename SizeSpecType::size_type n_nodes=0, typename SizeSpecType::size_type n_numa_dom=0, typename SizeSpecType::size_type n_cores=0)
	{} More...
template<typename PartitioningTags , typename MappingTags , typename LayoutTags , class SizeSpecType , class TeamSpecType >
DistributionSpec< SizeSpecType::ndim::value >	dash::make_distribution_spec (const SizeSpecType &sizespec, const TeamSpecType &teamspec)
	Generic Abstract Factory for instances of dash::DistributionSpec. More...
template<typename PartitioningTags = dash::pattern_partitioning_default_properties, typename MappingTags = dash::pattern_mapping_default_properties, typename LayoutTags = dash::pattern_layout_default_properties, class SizeSpecType , class TeamSpecType >
std::enable_if< !MappingTags::diagonal &&PartitioningTags::rectangular &&PartitioningTags::balanced &&!PartitioningTags::unbalanced &&LayoutTags::blocked, TilePattern< SizeSpecType::ndim::value, dash::ROW_MAJOR, typename SizeSpecType::index_type >>::type	dash::make_pattern (const SizeSpecType &sizespec, const TeamSpecType &teamspec)
	Generic Abstract Factory for models of the Pattern concept. More...

Detailed Description

Concept of a distribution pattern of n-dimensional containers to units in a team.

Description

A pattern realizes a projection of a global index range to a local view:

Team Spec	Container
[ unit 0 : unit 1 ]	[ 0 1 2 3 4 5 ]
[ unit 1 : unit 0 ]	[ 6 7 8 9 10 11 ]

This pattern would assign local indices to teams like this:

Team	Local indices
unit 0	[ 0 1 2 9 10 11 ]
unit 1	[ 3 4 5 6 7 8 ]

Methods

Return Type	Method	Parameters	Description
index	local_at	index[d] lp	Linear local offset of the local point lp in local memory.
index	global_at	index[d] gp	Global offset of the global point gp in the pattern's iteration order.
team_unit_t	unit_at	index[d] gp	Unit id mapped to the element at global point p
global to local
{unit,index}	local	index gi	Unit and linear local offset at the global index gi
{unit,index[d]}	local	index[d] gp	Unit and local coordinates at the global point gp
{unit,index}	local_index	index[d] gp	Unit and local linear offset at the global point gp
point[d]	local_coords	index[d] gp	Local coordinates at the global point gp
local to global
index[d]	global	unit u, index[d] lp	Local coordinates lp of unit u to global coordinates
index	global_index	unit u, index[d] lp	Local coordinates lp of unit u to global index
index[d]	global	index[d] lp	Local coordinates lp of active unit to global coordinates
index	global	unit u, index li	Local offset li of unit u to global index
index	global	index li	Local offset li of active unit to global index
blocks
size[d]	blockspec		Number of blocks in all dimensions.
size[d]	local_blockspec		Number of local blocks in all dimensions.
index	block_at	index[d] gp	Global index of block at global coordinates gp
viewspec	block	index gbi	Offset and extent in global cartesian space of block at global block index gbi
viewspec	local_block	index lbi	Offset and extent in global cartesian space of block at local block index lbi
viewspec	local_block_local	index lbi	Offset and extent in local cartesian space of block at local block index lbi
locality test
bool	is_local	index gi, unit u	Whether the global index gi is mapped to unit u
bool	is_local	dim d, index o, unit u	(proposed) Whether any element in dimension d at global offset o is local to unit u
size
size	capacity		Maximum number of elements in the pattern in total
size	local_capacity		Maximum number of elements assigned to a single unit
size	size		Number of elements indexed in the pattern
size	local_size		Number of elements local to the calling unit
size[d]	extents		Number of elements in the pattern in all dimension
size	extent	dim d	Number of elements in the pattern in dimension d
size[d]	local_extents	unit u	Number of elements local to the given unit, by dimension
size	local_extent	dim d	Number of elements local to the calling unit in dimension d

Function Documentation

make_distribution_spec()

template<typename PartitioningTags , typename MappingTags , typename LayoutTags , class SizeSpecType , class TeamSpecType >

DistributionSpec<SizeSpecType::ndim::value> dash::make_distribution_spec	(	const SizeSpecType &	sizespec,
		const TeamSpecType &	teamspec
	)

#include </tmp/tmporruphar/dash/include/dash/pattern/MakePattern.h>

Generic Abstract Factory for instances of dash::DistributionSpec.

Creates a DistributionSpec object from given pattern traits.

{}

Parameters

sizespec	Size spec of cartesian space to be distributed by the pattern.
teamspec	Team spec containing layout of units mapped by the pattern.

Definition at line 246 of file MakePattern.h.

References dash::ndim().

Referenced by dash::make_pattern().

{
  typedef typename SizeSpecType::size_type extent_t;

  DASH_LOG_TRACE("dash::make_distribution_spec()");
  // Deduce number of dimensions from size spec:
  const dim_t ndim = SizeSpecType::ndim::value;
  // Array of distribution specifiers in all dimensions,
  // e.g. { TILE(10), TILE(120) }:
  std::array<dash::Distribution, ndim> distributions = {{ }};
  extent_t min_block_extent = sizespec.size();
  if (PartitioningTags::minimal) {
    // Find minimal block size in minimal partitioning, initialize with
    // pattern size (maximum):
    for (auto d = 0; d < SizeSpecType::ndim::value; ++d) {
      auto extent_d    = sizespec.extent(d);
      auto nunits_d    = teamspec.extent(d);
      auto blocksize_d = extent_d / nunits_d;
      if (blocksize_d < min_block_extent) {
        min_block_extent = blocksize_d;
      }
    }
    DASH_LOG_TRACE("dash::make_distribution_spec",
                   "minimum block extent for square blocks:",
                   min_block_extent);
  }
  // Resolve balanced tile extents from size spec and team spec:
  for (auto d = 0; d < SizeSpecType::ndim::value; ++d) {
    auto extent_d  = sizespec.extent(d);
    auto nunits_d  = teamspec.extent(d);
    DASH_LOG_TRACE("dash::make_distribution_spec",
                   "d:",          d,
                   "extent[d]:",  extent_d,
                   "nunits[d]:",  nunits_d);
    auto nblocks_d = nunits_d;
    if (MappingTags::diagonal || MappingTags::neighbor) {
      // Diagonal and neighbor mapping properties require occurrence of every
      // unit in any hyperplane. Use total number of units in every dimension:
      nblocks_d = teamspec.size();
      DASH_LOG_TRACE("dash::make_distribution_spec",
                     "diagonal or neighbor mapping",
                     "d", d, "nblocks_d", nblocks_d);
    } else if (PartitioningTags::minimal) {
      // Trying to assign one block per unit:
      nblocks_d = nunits_d;
      if (!MappingTags::balanced) {
        // Unbalanced mapping, trying to use same block extent in all
        // dimensions:
        nblocks_d = extent_d / min_block_extent;
        DASH_LOG_TRACE("dash::make_distribution_spec",
                       "minimal partitioning, mapping not balanced",
                       "d", d, "nblocks_d", nblocks_d);
      }
    } else if (MappingTags::balanced) {
      // Balanced mapping, i.e. same number of blocks for every unit
      if (nblocks_d % teamspec.extent(d) > 0) {
        // Extent in this dimension is not a multiple of number of units,
        // balanced mapping property cannot be satisfied:
        DASH_THROW(dash::exception::InvalidArgument,
                   "dash::make_distribution_spec: cannot distribute " <<
                   nblocks_d << " blocks to " <<
                   nunits_d  << " units in dimension " << d);
      }
    }
    auto tilesize_d = extent_d / nblocks_d;
    DASH_LOG_TRACE("dash::make_distribution_spec",
                   "tile size in dimension", d, ":", tilesize_d);
    if (PartitioningTags::balanced) {
      // Balanced partitioning, i.e. same number of elements in every block
      if (extent_d % tilesize_d > 0) {
        // Extent in this dimension is not a multiple of tile size,
        // balanced partitioning property cannot be satisfied:
        DASH_THROW(dash::exception::InvalidArgument,
                   "dash::make_distribution_spec: cannot distribute " <<
                   extent_d   << " elements to " <<
                   nblocks_d  << " blocks in dimension " << d);
      }
    }
    if (LayoutTags::linear && LayoutTags::blocked) {
      distributions[d] = dash::TILE(tilesize_d);
    } else {
      distributions[d] = dash::BLOCKCYCLIC(tilesize_d);
    }
    DASH_LOG_TRACE_VAR("dash::make_distribution_spec", distributions[d]);
  }
  // Make distribution spec from template- and run time parameters:
  DASH_LOG_TRACE_VAR("dash::make_distribution_spec >", distributions);
  dash::DistributionSpec<ndim> distspec(distributions);
  DASH_LOG_TRACE_VAR("dash::make_distribution_spec >", distspec);
  return distspec;
}

make_pattern()

template<typename PartitioningTags = dash::pattern_partitioning_default_properties, typename MappingTags = dash::pattern_mapping_default_properties, typename LayoutTags = dash::pattern_layout_default_properties, class SizeSpecType , class TeamSpecType >

std::enable_if< !MappingTags::diagonal && PartitioningTags::rectangular && PartitioningTags::balanced && !PartitioningTags::unbalanced && LayoutTags::blocked, TilePattern<SizeSpecType::ndim::value, dash::ROW_MAJOR, typename SizeSpecType::index_type>>::type dash::make_pattern	(	const SizeSpecType &	sizespec,
		const TeamSpecType &	teamspec
	)

#include </tmp/tmporruphar/dash/include/dash/pattern/MakePattern.h>

Generic Abstract Factory for models of the Pattern concept.

Creates an instance of a Pattern model that satisfies the contiguos linearization property from given pattern traits.

{}

Returns

An instance of dash::TilePattern if the following constraints are specified: (Partitioning: minimal) and (Layout: blocked)

Parameters

sizespec	Size spec of cartesian space to be distributed by the pattern.
teamspec	Team spec containing layout of units mapped by the pattern.

Examples:

ex.06.pattern-block-visualizer/main.cpp.

Definition at line 373 of file MakePattern.h.

References dash::make_distribution_spec(), and dash::ndim().

{
  // Deduce number of dimensions from size spec:
  const dim_t ndim = SizeSpecType::ndim::value;
  // Deduce index type from size spec:
  typedef typename SizeSpecType::index_type                 index_t;
  typedef dash::TilePattern<ndim, dash::ROW_MAJOR, index_t> pattern_t;
  DASH_LOG_TRACE("dash::make_pattern", PartitioningTags());
  DASH_LOG_TRACE("dash::make_pattern", MappingTags());
  DASH_LOG_TRACE("dash::make_pattern", LayoutTags());
  DASH_LOG_TRACE_VAR("dash::make_pattern", sizespec.extents());
  DASH_LOG_TRACE_VAR("dash::make_pattern", teamspec.extents());
  // Make distribution spec from template- and run time parameters:
  auto distspec =
    make_distribution_spec<
      PartitioningTags,
      MappingTags,
      LayoutTags,
      SizeSpecType,
      TeamSpecType
    >(sizespec,
      teamspec);
  // Make pattern from template- and run time parameters:
  pattern_t pattern(sizespec,
                    distspec,
                    teamspec);
  return pattern;
}

make_team_spec()

template<typename PartitioningTags , typename MappingTags , typename LayoutTags , class SizeSpecType >

TeamSpec<SizeSpecType::ndim::value, typename SizeSpecType::index_type> dash::make_team_spec	(	const SizeSpecType &	sizespec,
		dash::Team &	team = dash::Team::All(),
		typename SizeSpecType::size_type	n_nodes = 0,
		typename SizeSpecType::size_type	n_numa_dom = 0,
		typename SizeSpecType::size_type	n_cores = 0
	)

#include </tmp/tmporruphar/dash/include/dash/pattern/MakePattern.h>

{}

Parameters

sizespec

Size spec of cartesian space to be distributed by the pattern.

Definition at line 185 of file MakePattern.h.

References dash::Team::All(), and dash::make_team_spec().

{
  DASH_LOG_TRACE_VAR("dash::make_team_spec()", sizespec.extents());
  DASH_LOG_TRACE_VAR("dash::make_team_spec", team.size());

  dash::util::TeamLocality tloc(dash::Team::All());
  if (0 >= n_nodes) {
    n_nodes    = tloc.num_nodes();
    if (0 >= n_nodes) { n_nodes = 1; }
  }
  if (0 >= n_numa_dom) {
    n_numa_dom = tloc.domain().scope_domains(
                   dash::util::Locality::Scope::NUMA).size() / n_nodes;
    if (0 >= n_numa_dom) {
      n_numa_dom = tloc.domain().scope_domains(
                     dash::util::Locality::Scope::Package).size() / n_nodes;
    }
    if (0 >= n_numa_dom) { n_numa_dom = 1; }
  }
  if (0 >= n_cores) {
    n_cores    = tloc.num_cores();
    if (0 >= n_cores) { n_cores = 1; }
  }

  return make_team_spec<
           PartitioningTags,
           MappingTags,
           LayoutTags,
           SizeSpecType>(
             sizespec,
             team.size(),
             n_nodes,
             n_numa_dom,
             n_cores);
}