Document partitionings

Author:    Jan-Willem Buurlage <janwillembuurlage@gmail.com>
Date:      Fri Nov 2 22:46:06 2018 +0100

README.md

@@ -1,6 +1,6 @@
 # Bulk [![Build Status](https://travis-ci.org/jwbuurlage/Bulk.svg?branch=develop)](https://travis-ci.org/jwbuurlage/Bulk)
 
-![](docs/pages/images/logo-square.png)
+![](https://raw.githubusercontent.com/jwbuurlage/Bulk/master/docs/pages/images/logo-square.png)
 
 The bulk-synchronous parallel (BSP) programming model gives a powerful method
 for implementing and describing parallel programs. Bulk is a novel interface for

docs/mkdocs.yml

@@ -21,7 +21,7 @@ extra_javascript:
 
 docs_dir: pages
 
-pages:
+nav:
 - Home: 'index.md'
 - Getting started: 'getting_started.md'
 - Tour: 'tour.md'
@@ -42,6 +42,7 @@ pages:
         - 'coarray': 'api/coarray.md'
         - 'queue': 'api/queue.md'
         - 'timer': 'api/timer.md'
+        - 'partitioning': 'api/partitioning.md'
     - Functions:
         - 'foldl': 'api/foldl.md'
         - 'gather_all': 'api/gather_all.md'

docs/pages/api/cartesian_partitioning/constructor.md

@@ -0,0 +1,12 @@
+# `bulk::cartesian_partitioning::cartesian_partitioning`
+
+```cpp
+cartesian_partitioning(index_type<D> global_size, index_type<G> grid_size);
+```
+
+Constructs a Cartesian partitioning.
+
+## Parameters
+
+* `global_size` - the shape of the data
+* `grid_size` - the shape of the processor grid

docs/pages/api/cartesian_partitioning/deconstructor.md

@@ -0,0 +1,7 @@
+# `bulk::cartesian_partitioning::~cartesian_partitioning`
+
+```cpp
+virtual ~cartesian_partitioning() = default;
+```
+
+Virtual deconstructor.

docs/pages/api/cartesian_partitioning/global.md

@@ -0,0 +1,22 @@
+# `bulk::cartesian_partitioning::global`
+
+```cpp
+using multi_partitioning<D, G>::global;
+virtual int global(int g, int u, int i); // overload
+```
+
+Convert a local index to a global one (overload).
+
+## Parameters
+
+- `g`: the axis for which to compute the index
+- `u`: the `g`th component of the local multi rank
+- `i`: the `g`th component of the local index
+
+## Return value
+
+- `int`: the `g`th component of the global index
+
+## See also
+
+- [`partitioning::global`](../partitioning/global.md)

docs/pages/api/cartesian_partitioning/local.md

@@ -0,0 +1,21 @@
+# `bulk::cartesian_partitioning::local`
+
+```cpp
+using multi_partitioning<D, G>::local;
+virtual int local(int g, int i); // overload
+```
+
+Convert a global index to a local one (overload).
+
+## Parameters
+
+- `g`: the axis for which to compute the index
+- `i`: the `g`th component of the global index
+
+## Return value
+
+- `int`: the `g`th component of the local index
+
+## See also
+
+- [`partitioning::local`](../partitioning/local.md)

docs/pages/api/cartesian_partitioning/local_size.md

@@ -0,0 +1,21 @@
+# `bulk::multi_partitioning::local_size`
+
+```cpp
+using multi_partitioning<D, G>::local_size;
+virtual int local_size(int g, int u); // overload
+```
+
+Returns the local data space shape for a given processor (overload).
+
+## Parameters
+
+- `g`: the axis for which to compute the index
+- `u`: the `g`th component of the local multi rank
+
+## Return value
+
+- `int`: The `g`th component of the shape of the local data space.
+
+## See also
+
+- [`partitioning::local_size`](../partitioning/local_size.md)

docs/pages/api/cartesian_partitioning/owner.md

@@ -0,0 +1,21 @@
+# `bulk::cartesian_partitioning::owner`
+
+```cpp
+using multi_partitioning<D, G>::owner;
+virtual int owner(int g, int i);
+```
+
+Returns the rank of the processor that owns the element at a given index.
+
+## Parameters
+
+- `g`: the axis for which to compute the index
+- `i`: the `g`th component of the local index
+
+## Return value
+
+- `int`: the `g`th component of the multi rank of the owner
+
+## See also
+
+- [`partitioning::owner`](../partitioning/owner.md)

docs/pages/api/index.md

@@ -1,21 +1,23 @@
 Bulk API reference
 ==================
 
-|                                                   |                                                                 |
-|---------------------------------------------------|-----------------------------------------------------------------|
-| **System**                                        |                                                                 |
-| [`bulk::environment`](environment.md)             | the central object that encapsulates the distributed system     |
-| [`bulk::world`](world.md)                         | an implementation of the low-level functions                    |
-| **Distributed objects and communication**         |                                                                 |
-| [`bulk::var`](var.md)                             | a distributed variable with an image for each processor         |
-| [`bulk::future`](future.md)                       | an object which encapsulates a value known in future supersteps |
-| [`bulk::coarray`](coarray.md)                     | a distributed array with a local array image for each processor |
-| **Message passing**                               |                                                                 |
-| [`bulk::queue`](queue.md)                 	    | a container containing messages                                 |
-| **Algorithms**                                    |                                                                 |
-| [`bulk::foldl`](foldl.md)                         | a left fold over a `var`                                        |
-| [`bulk::gather_all`](gather_all.md)               | gather results                                                  |
-| **Utility**                                       |                                                                 |
-| [`bulk::util::timer`](timer.md)                   | wall timer for benchmarking                                     |
-| [`bulk::util::flatten`](flatten.md)               | flatten multi-indices                                           |
-| [`bulk::util::unflatten`](unflatten.md)           | unflatten mutli-indices                                         |
+|                                                |                                                                 |
+|------------------------------------------------|-----------------------------------------------------------------|
+| **System**                                     |                                                                 |
+| [`bulk::environment`](environment.md)          | the central object that encapsulates the distributed system     |
+| [`bulk::world`](world.md)                      | an implementation of the low-level functions                    |
+| **Distributed objects and communication**      |                                                                 |
+| [`bulk::var`](var.md)                          | a distributed variable with an image for each processor         |
+| [`bulk::future`](future.md)                    | an object which encapsulates a value known in future supersteps |
+| [`bulk::coarray`](coarray.md)                  | a distributed array with a local array image for each processor |
+| **Message passing**                            |                                                                 |
+| [`bulk::queue`](queue.md)                 	 | a container containing messages                                 |
+| **Algorithms**                                 |                                                                 |
+| [`bulk::foldl`](foldl.md)                      | a left fold over a `var`                                        |
+| [`bulk::gather_all`](gather_all.md)            | gather results                                                  |
+| **Partitionings**                              |                                                                 |
+| [`bulk::partitioning`](partitioning.md)        | index computations for data distributions |
+| **Utility**                                    |                                                                 |
+| [`bulk::util::timer`](timer.md)                | wall timer for benchmarking                                     |
+| [`bulk::util::flatten`](flatten.md)            | flatten multi-indices                                           |
+| [`bulk::util::unflatten`](unflatten.md)        | unflatten mutli-indices                                         |

docs/pages/api/multi_partitioning/constructor.md

@@ -0,0 +1,12 @@
+# `bulk::multi_partitioning::multi_partitioning`
+
+```cpp
+multi_partitioning(index_type<D> global_size, index_type<G> grid_size);
+```
+
+Constructs a multi partitioning.
+
+## Parameters
+
+* `global_size` - the shape of the data
+* `grid_size` - the shape of the processor grid

docs/pages/api/multi_partitioning/deconstructor.md

@@ -0,0 +1,7 @@
+# `bulk::multi_partitioning::~multi_partitioning`
+
+```cpp
+virtual ~multi_partitioning() = default;
+```
+
+Virtual deconstructor.

docs/pages/api/multi_partitioning/global.md

@@ -0,0 +1,21 @@
+# `bulk::multi_partitioning::global`
+
+```cpp
+index_type<D> global(index_type<D> xs, int processor) override;
+virtual index_type<D> global(index_type<D> xs, index_type<G> processor); // overload
+```
+
+Convert a local index to a global one (overload).
+
+## Parameters
+
+- `processor`: the local multi rank
+- `xs`: the local index
+
+## Return value
+
+- `index_type<D>`: the global index
+
+## See also
+
+- [`partitioning::global`](../partitioning/global.md)

docs/pages/api/multi_partitioning/grid.md

@@ -0,0 +1,11 @@
+# `bulk::multi_partitioning::grid`
+
+```cpp
+index_type<G> grid();
+```
+
+Returns the processor grid space.
+
+## Return value
+
+- `index_type<G>`: The shape of the processor grid.

docs/pages/api/multi_partitioning/local_size.md

@@ -0,0 +1,20 @@
+# `bulk::multi_partitioning::local_size`
+
+```cpp
+index_type<D> local_size(int processor) override;
+virtual index_type<D> local_size(index_type<G> processor) // overload
+```
+
+Returns the local data space shape for a given processor (overload).
+
+## Parameters
+
+- `processor`: the multi rank for which to return the local shape.
+
+## Return value
+
+- `index_type<D>`: The shape of the local data space.
+
+## See also
+
+- [`partitioning::local_size`](../partitioning/local_size.md)

docs/pages/api/multi_partitioning/multi_owner.md

@@ -0,0 +1,20 @@
+# `bulk::partitioning::multi_owner`
+
+```cpp
+int owner(index_type<D> xs) override;
+virtual index_type<G> multi_owner(index_type<D> xs) // overload
+```
+
+Returns the multi rank of the processor that owns the element at a given index.
+
+## Parameters
+
+- `xs`: the index in the data space
+
+## Return value
+
+- `index_type<G>`: the multi rank of the processor that owns `xs`
+
+## See also
+
+- [`partitioning::owner`](../partitioning/owner.md)

docs/pages/api/multi_partitioning/multi_rank.md

@@ -0,0 +1,19 @@
+# `bulk::multi_partitioning::multi_rank`
+
+```cpp
+index_type<G> multi_rank(int t);
+```
+
+Convert a standard rank to a multi rank.
+
+## Parameters
+
+- `t`: the rank to convert
+
+## Return value
+
+- `index_type<G>`: the corresponding multi rank
+
+## See also
+
+- [`multi_partitioning::rank`](rank.md)

docs/pages/api/multi_partitioning/rank.md

@@ -0,0 +1,19 @@
+# `bulk::multi_partitioning::rank`
+
+```cpp
+int rank(index_type<G> ts);
+```
+
+Convert a multi rank to a standard one.
+
+## Parameters
+
+- `ts`: the multi rank to convert
+
+## Return value
+
+- `int`: the corresponding standard rank
+
+## See also
+
+- [`multi_partitioning::multi_rank`](multi_rank.md)