Grids

Global and local grids are two data structures included into MPL to facilitate the implementation of domain decomposition mathods on regular rectangular multidimensional grids. See sections Distributed grid, Distributed grid collective operations, Heat equation Jacobi solver and Heat equation successive over-relaxation for examples.

Distributed grids

template<std::size_t dim, typename T, typename A = std::allocator<T>>
class distributed_grid

Local portion of a distributed data grid including local overlap data.

Param dim:

number of dimensions of the data grid, may be 1, 2, 3 or 4

Template Parameters:

  • T – data type that is hold at each grid point

  • A – memory allocator

Public Types

using vector_type = std::vector<T, A>

the underlying one-dimensional vector type

using value_type = typename vector_type::value_type

data type that is hold at each grid point

using allocator_type = typename vector_type::allocator_type

memory allocator

using size_type = std::ptrdiff_t

type used for indexing

Note

This is a signed integer type (unlike for STL containers).

using difference_type = typename vector_type::difference_type

signed integer type for iterator differences

using reference = typename vector_type::reference

reference to value_type

using const_reference = typename vector_type::const_reference

const reference to value_type

using pointer = typename vector_type::pointer

pointer to value_type

using const_pointer = typename vector_type::const_pointer

const pointer to value_type

Public Functions

inline explicit distributed_grid(const cartesian_communicator &communicator, const dimensions &dims)

Creates the local portion of a distributed data grid.

Note

The number of dimensions of the Cartesian communicator and the size of the dims parameter must be equal.

Parameters:

  • communicator – Cartesian communicator that wil be employed to update overlap data between adjacent processes.

  • dims – size and overlap data of the global grid

inline size_type gsize(size_type d) const

Determines the global size of the grid along a dimension.

Parameters:

d – dimension

Returns:

global size

inline size_type gbegin(size_type d) const

Determines the smallest index into the global distributed grid to the local portion of the grid.

Parameters:

d – dimension

Returns:

grid index

inline size_type gend(size_type d) const

Determines the smallest index into the global distributed grid that is beyond the local portion of the grid.

Parameters:

d – dimension

Returns:

grid index

inline size_type size(size_type d) const

Determines the size of the local portion of the distributed data grid along a dimension.

Parameters:

d – dimension

Returns:

local grid size

inline size_type begin(size_type d) const

Determines the lowest index to access the local portion of the distributed data grid along a dimension.

Parameters:

d – dimension

Returns:

grid index

inline size_type end(size_type d) const

Determines the last index (plus one) to access the local portion of the distributed data grid along a dimension.

Parameters:

d – dimension

Returns:

grid index

inline size_type obegin(size_type d) const

Determines the lowest index to access the local portion of the distributed grid including the overlap data along a dimension.

Parameters:

d – dimension

Returns:

grid index

inline size_type oend(size_type d) const

Determines the last index (plus one) to access the local portion of the distributed grid including the overlap data along a dimension.

Parameters:

d – dimension

Returns:

grid index

inline size_type gindex(size_type d, size_type i) const

Translates an index to access the local portion of the distributed data grid into an index into the global grid.

Parameters:

  • d – dimension

  • i – index with respect to local data

Returns:

grid index

template<std::size_t d = dim>
inline std::enable_if_t<d == 1, reference> operator()(size_type i_0)

Element access.

Parameters:

i_0 – 1st dimension index

Returns:

grid data element

template<std::size_t d = dim>
inline std::enable_if_t<d == 1, const_reference> operator()(size_type i_0) const

Element access.

Parameters:

i_0 – 1st dimension index

Returns:

grid data element

template<std::size_t d = dim>
inline std::enable_if_t<d == 2, reference> operator()(size_type i_0, size_type i_1)

Element access.

Parameters:

  • i_0 – 1st dimension index

  • i_1 – 2nd dimension index

Returns:

grid data element

template<std::size_t d = dim>
inline std::enable_if_t<d == 2, const_reference> operator()(size_type i_0, size_type i_1) const

Element access.

Parameters:

  • i_0 – 1st dimension index

  • i_1 – 2nd dimension index

Returns:

grid data element

template<std::size_t d = dim>
inline std::enable_if_t<d == 3, reference> operator()(size_type i_0, size_type i_1, size_type i_2)

Element access.

Parameters:

  • i_0 – 1st dimension index

  • i_1 – 2nd dimension index

  • i_2 – 3rd dimension index

Returns:

grid data element

template<std::size_t d = dim>
inline std::enable_if_t<d == 3, const_reference> operator()(size_type i_0, size_type i_1, size_type i_2) const

Element access.

Parameters:

  • i_0 – 1st dimension index

  • i_1 – 2nd dimension index

  • i_2 – 3rd dimension index

Returns:

grid data element

template<std::size_t d = dim>
inline std::enable_if_t<d == 4, reference> operator()(size_type i_0, size_type i_1, size_type i_2, size_type i_3)

Element access.

Parameters:

  • i_0 – 1st dimension index

  • i_1 – 2nd dimension index

  • i_2 – 3rd dimension index

  • i_3 – 4th dimension index

Returns:

grid data element

template<std::size_t d = dim>
inline std::enable_if_t<d == 4, const_reference> operator()(size_type i_0, size_type i_1, size_type i_2, size_type i_3) const

Element access.

Parameters:

  • i_0 – 1st dimension index

  • i_1 – 2nd dimension index

  • i_2 – 3rd dimension index

  • i_3 – 4th dimension index

Returns:

grid data element

inline pointer data()

Grands access to the flattened grid data.

Returns:

pointer to grid data

inline const_pointer data() const

Grands access to the flattened grid data.

Returns:

pointer to grid data

inline const subarray_layout<T> &left_mirror_layout(size_type d) const

Get the memory layout for receiving data when updating data in overlap regions along a given dimension.

The returned memory layout represents data in the left overlap region.

Parameters:

d – dimension

Returns:

memory layout

inline const subarray_layout<T> &right_mirror_layout(size_type d) const

Get the memory layout for receiving data when updating data in overlap regions along a given dimension.

The returned memory layout represents data in the right overlap region.

Parameters:

d – dimension

Returns:

memory layout

inline const subarray_layout<T> &left_border_layout(size_type d) const

Get the memory layout for sending data when updating data in overlap regions along a given dimension.

The returned memory layout represents data next to the left overlap region.

Parameters:

d – dimension

Returns:

memory layout

inline const subarray_layout<T> &right_border_layout(size_type d) const

Get the memory layout for sending data when updating data in overlap regions along a given dimension.

The returned memory layout represents data next to the right overlap region.

Parameters:

d – dimension

Returns:

memory layout

inline const subarray_layout<T> &interior_layout() const

Get the memory layout for sending or receiving data without overlap data.

The returned memory layout represents inner grid data without the overlap regions.

Returns:

memory layout

inline void swap(distributed_grid &other) noexcept

Swaps this distributed data grid with another.

Parameters:

other – other distributed data grid

class dimensions

Characterizes the dimensionality, total size and overlap of a distributed data grid.

Public Types

using value_type = size_overlap_pair
using reference = size_overlap_pair&
using const_reference = const size_overlap_pair&
using iterator = typename std::array<size_overlap_pair, dim>::iterator
using const_iterator = typename std::array<size_overlap_pair, dim>::const_iterator

Public Functions

inline dimensions(const size_overlap_pair &size_0)
inline dimensions(const size_overlap_pair &size_0, const size_overlap_pair &size_1)
inline dimensions(const size_overlap_pair &size_0, const size_overlap_pair &size_1, const size_overlap_pair &size_2)
inline dimensions(const size_overlap_pair &size_0, const size_overlap_pair &size_1, const size_overlap_pair &size_2, const size_overlap_pair &size_3)
inline size_type dimensionality() const

Determines the dimensionality.

Returns:

dimensionality (number of dimensions)

inline size_type size(size_type dimension) const

Determines the total size of a dimension.

Parameters:

dimension – the rank of the dimension

Returns:

the total size of the dimension

inline size_type overlap(size_type dimension) const

Determines the overlap size of a dimension.

Parameters:

dimension – the rank of the dimension

Returns:

the overlap of the dimension

inline const_reference operator[](size_type dimension) const

Determines then total size along a dimension and the overlap of a dimension.

Parameters:

dimension – the rank of the dimension

Returns:

the size and the overlap

inline reference operator[](size_type dimension)

Determines then total size along a dimension and the overlap of a dimension.

Parameters:

dimension – the rank of the dimension

Returns:

the size and the overlap

inline iterator begin()
inline const_iterator begin() const
inline const_iterator cbegin() const
inline iterator end()
inline const_iterator end() const
inline const_iterator cend() const

Friends

friend class distributed_grid
class size_overlap_pair

Pair of grid size and overlap size.

Public Functions

inline size_overlap_pair(size_type size, size_type overlap)

Creates a size-overlap pair.

Public Members

size_type size = {0}

indicates the total/global number data pints that the data grid holds along a dimension

size_type overlap = {0}

indicates the number of overlap data points the each local process holds as a copy of data hold by adjacent processes

Local grids

template<std::size_t dim, typename T, typename A = std::allocator<T>>
class local_grid

Data grid.

This data structure is suitable for gather and scatter operation in combination with distributed_grid.

Param dim:

number of dimensions of the data grid, may be 1, 2, 3 or 4

Template Parameters:

  • T – data type that is hold at each grid point

  • A – memory allocator

Public Types

using vector_type = std::vector<T, A>

the underlying one-dimensional vector type

using value_type = typename vector_type::value_type

data type that is hold at each grid point

using allocator_type = typename vector_type::allocator_type

memory allocator

using size_type = std::ptrdiff_t

type used for indexing

Note

This is a signed integer type (unlike for STL containers).

using difference_type = typename vector_type::difference_type

signed integer type for iterator differences

using reference = typename vector_type::reference

reference to value_type

using const_reference = typename vector_type::const_reference

const reference to value_type

using pointer = typename vector_type::pointer

pointer to value_type

using const_pointer = typename vector_type::const_pointer

const pointer to value_type

Public Functions

inline local_grid(const cartesian_communicator &communicator, const dimensions &dims)

Creates a local data grid.

Note

The number of dimensions of the Cartesian communicator and the size of the dims parameter must be equal.

Parameters:

  • communicator – Cartesian communicator that will be employed to scatter or gather data.

  • dims – size of the global grid

inline size_type size(size_type d) const

Determines the size of the data grid along a dimension.

Parameters:

d – dimension

Returns:

local grid size

inline size_type begin(size_type d) const

Determines the lowest index to access the data grid along a dimension.

Parameters:

d – dimension

Returns:

grid index

inline size_type end(size_type d) const

Determines the last index (plus one) to access the data grid along a dimension.

Parameters:

d – dimension

Returns:

grid index

template<std::size_t d = dim>
inline std::enable_if_t<d == 1, reference> operator()(size_type i_0)

Element access.

Parameters:

i_0 – 1st dimension index

Returns:

grid data element

template<std::size_t d = dim>
inline std::enable_if_t<d == 1, const_reference> operator()(size_type i_0) const

Element access.

Parameters:

i_0 – 1st dimension index

Returns:

grid data element

template<std::size_t d = dim>
inline std::enable_if_t<d == 2, reference> operator()(size_type i_0, size_type i_1)

Element access.

Parameters:

  • i_0 – 1st dimension index

  • i_1 – 2nd dimension index

Returns:

grid data element

template<std::size_t d = dim>
inline std::enable_if_t<d == 2, const_reference> operator()(size_type i_0, size_type i_1) const

Element access.

Parameters:

  • i_0 – 1st dimension index

  • i_1 – 2nd dimension index

Returns:

grid data element

template<std::size_t d = dim>
inline std::enable_if_t<d == 3, reference> operator()(size_type i_0, size_type i_1, size_type i_2)

Element access.

Parameters:

  • i_0 – 1st dimension index

  • i_1 – 2nd dimension index

  • i_2 – 3rd dimension index

Returns:

grid data element

template<std::size_t d = dim>
inline std::enable_if_t<d == 3, const_reference> operator()(size_type i_0, size_type i_1, size_type i_2) const

Element access.

Parameters:

  • i_0 – 1st dimension index

  • i_1 – 2nd dimension index

  • i_2 – 3rd dimension index

Returns:

grid data element

template<std::size_t d = dim>
inline std::enable_if_t<d == 4, reference> operator()(size_type i_0, size_type i_1, size_type i_2, size_type i_3)

Element access.

Parameters:

  • i_0 – 1st dimension index

  • i_1 – 2nd dimension index

  • i_2 – 3rd dimension index

  • i_3 – 4th dimension index

Returns:

grid data element

template<std::size_t d = dim>
inline std::enable_if_t<d == 4, const_reference> operator()(size_type i_0, size_type i_1, size_type i_2, size_type i_3) const

Element access.

Parameters:

  • i_0 – 1st dimension index

  • i_1 – 2nd dimension index

  • i_2 – 3rd dimension index

  • i_3 – 4th dimension index

Returns:

grid data element

inline pointer data()

Grands access to the flattened grid data.

Returns:

pointer to grid data

inline const_pointer data() const

Grands access to the flattened grid data.

Returns:

pointer to grid data

inline const layouts<T> &sub_layouts() const

Get layouts for scatting and gathering of the grid data.

If there is a local_grid and a distributed_grid that have been created with the same Cartesian communicator argument and if both grids have the same total size then the i-th returned layout is suitable to send a sub-set of data from the local_grid to the distributed grid at the process with rank i in the Cartesian communicator.

Returns:

set of layouts

inline void swap(local_grid &other) noexcept
class dimensions

Characterizes the dimensionality and the total size of a local data grid.

Public Types

using value_type = size_type
using reference = size_type&
using const_reference = const size_type&
using iterator = typename std::array<size_type, dim>::iterator
using const_iterator = typename std::array<std::size_t, dim>::const_iterator

Public Functions

inline dimensions(const size_type &size_0)
inline dimensions(const size_type &size_0, const size_type &size_1)
inline dimensions(const size_type &size_0, const size_type &size_1, const size_type &size_2)
inline dimensions(const size_type &size_0, const size_type &size_1, const size_type &size_2, const size_type &size_3)
inline size_type dimensionality() const

Determines the dimensionality.

Returns:

dimensionality (number of dimensions)

inline size_type size(size_type dimension) const

Determines the total size of a dimension.

Parameters:

dimension – the rank of the dimension

Returns:

the total size of the dimension

inline const_reference operator[](size_type dimension) const

Determines then total size along a dimension of a dimension.

Parameters:

dimension – the rank of the dimension

Returns:

the size and the overlap

inline reference operator[](size_type dimension)

Determines then total size along a dimension.

Parameters:

dimension – the rank of the dimension

Returns:

the size and the overlap

inline iterator begin()
inline const_iterator begin() const
inline const_iterator cbegin() const
inline iterator end()
inline const_iterator end() const
inline const_iterator cend() const

Friends

friend class local_grid