Partitioning#

group partitioning

Enums

enum class ImageComputationHint : std::uint8_t#

Hints to the runtime for the image computation.

Values:

enumerator NO_HINT#: A precise image of the function is needed

enumerator MIN_MAX#: An approximate image of the function using bounding boxes is sufficient

enumerator FIRST_LAST#: Elements in the function store are sorted and thus bounding can be computed using only the first and the last elements

Functions

Constraint align(Variable lhs, Variable rhs)#

Creates an alignment constraint on two variables.

An alignment constraint between variables x and y indicates to the runtime that the PhysicalStores (leaf-task-local portions, typically equal-size tiles) of the LogicalStores corresponding to x and y must have the same global indices (i.e. the Stores must “align” with one another).

This is commonly used for e.g. element-wise operations. For example, consider an element-wise addition (z = x + y), where each array is 100 elements long. Each leaf task must receive the same local tile for all 3 arrays. For example, leaf task 0 receives indices 0 - 24, leaf task 1 receives 25 - 49, leaf task 2 receives 50 - 74, and leaf task 3 receives 75 - 99.

Parameters:

lhs – LHS variable
rhs – RHS variable

Returns:

Alignment constraint

Constraint broadcast(Variable variable)#

Creates a broadcast constraint on a variable.

A broadcast constraint informs the runtime that the variable should not be split among the leaf tasks, instead, each leaf task should get a full copy of the underlying store. In other words, the store should be “broadcast” in its entirety to all leaf tasks in a task launch.

In effect, this constraint prevents all dimensions of the store from being partitioned.

Parameters:: variable – Partition symbol to constrain
Returns:: Broadcast constraint

Constraint broadcast(Variable variable, tuple<std::uint32_t> axes)#

Creates a broadcast constraint on a variable.

A modified form of broadcast constraint which applies the broadcast to a subset of the axes of the LogicalStore corresponding to variable. The Store will be partitioned on all other axes.

Parameters:

variable – Partition symbol to constrain
axes – List of dimensions to broadcast

Throws:

std::invalid_argument – If the list of axes is empty

Returns:

Broadcast constraint

Constraint image( Variable var_function, Variable var_range, ImageComputationHint hint = ImageComputationHint::NO_HINT, )#

Creates an image constraint between partitions.

The elements of var_function are treated as pointers to elements in var_range. Each sub-store s of var_function is aligned with a sub-store t of var_range, such that every element in s will find the element of var_range it’s pointing to inside of t.

Currently, the precise image computation can be performed only by CPUs. As a result, the function store is copied to the system memory if the store was last updated by GPU tasks. The approximate image computation has no such issue and is fully GPU accelerated.

Note

An approximate image of a function potentially contains extra points not in the function’s image. For example, if a function sub-store contains two 2-D points (0, 0) and (1, 1), the corresponding sub-store of the range would only contain the elements at points (0, 0) and (1, 1) if it was constructed from a precise image computation, whereas an approximate image computation would yield a sub-store with elements at point (0, 0), (0, 1), (1, 0), and (1, 1) (two extra elements).

Parameters:

var_function – Partition symbol for the function store
var_range – Partition symbol of the store whose partition should be derived from the image
hint – Optional hint to the runtime describing how the image computation can be performed. If no hint is given (which is the default), the runtime falls back to the precise image computation. Otherwise, the runtime computes a potentially approximate image of the function.

Returns:

Image constraint

Constraint scale( tuple<std::uint64_t> factors, Variable var_smaller, Variable var_bigger, )#

Creates a scaling constraint between partitions.

A scaling constraint is similar to an alignment constraint, except that the sizes of the aligned tiles is first scaled by factors.

For example, this may be used in compacting a 5x56 array of bools to a 5x7 array of bytes, treated as a bitfield. In this case var_smaller would be the byte array, var_bigger would be the array of bools, and factors would be [1, 8] (a 2x3 tile on the byte array corresponds to a 2x24 tile on the bool array.

Formally: if two stores A and B are constrained by a scaling constraint

legate::scale(S, pA, pB)

where pA and pB are partition symbols for A and B, respectively, A and B will be partitioned such that each pair of sub-stores Ak and Bk satisfy the following property:

\(\mathtt{S} \cdot \mathit{dom}(\mathtt{Ak}) \cap \mathit{dom}(\mathtt{B}) \subseteq \) \(\mathit{dom}(\mathtt{Bk})\)

Parameters:

factors – Scaling factors
var_smaller – Partition symbol for the smaller store (i.e., the one whose extents are scaled)
var_bigger – Partition symbol for the bigger store

Returns:

Scaling constraint

Constraint bloat( Variable var_source, Variable var_bloat, tuple<std::uint64_t> low_offsets, tuple<std::uint64_t> high_offsets, )#

Creates a bloating constraint between partitions.

This is typically used in stencil computations, to instruct the runtime that the tiles on the “private + ghost” partition (var_bloat) must align with the tiles on the “private” partition (var_source), but also include a halo of additional elements off each end.

For example, if var_source and var_bloat correspond to 10-element vectors, var_source is split into 2 tiles, 0-4 and 5-9, low_offsets == 1 and high_offsets == 2, then var_bloat will be split into 2 tiles, 0-6 and 4-9.

Formally, if two stores A and B are constrained by a bloating constraint

legate::bloat(pA, pB, L, H)

where pA and pB are partition symbols for A and B, respectively, A and B will be partitioned such that each pair of sub-stores Ak and Bk satisfy the following property:

\( \forall p \in \mathit{dom}(\mathtt{Ak}). \forall \delta \in [-\mathtt{L}, \mathtt{H}]. \) \( p + \delta \in \mathit{dom}(\mathtt{Bk}) \lor p + \delta \not \in \mathit{dom}(\mathtt{B})\)

Parameters:

var_source – Partition symbol for the source store
var_bloat – Partition symbol for the target store
low_offsets – Offsets to bloat towards the negative direction
high_offsets – Offsets to bloat towards the positive direction

Returns:

Bloating constraint

class Variable#: #include <legate/partitioning/constraint.h>

Class for partition symbols.

class Constraint#: #include <legate/partitioning/constraint.h>

A base class for partitioning constraints.