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

ProxyConstraint align( std::variant<ProxyArrayArgument, ProxyInputArguments, ProxyOutputArguments, ProxyReductionArguments> left, std::variant<ProxyArrayArgument, ProxyInputArguments, ProxyOutputArguments, ProxyReductionArguments> right, )#

Construct an alignment constraint descriptor from a pair of proxy objects.

This routine may be used to describe an alignment constraint between prospective arguments to a task. For example:

legate::align(legate::proxy::inputs, legate::proxy::outputs[0])

Dictates that all inputs should be aligned with output 0. Similarly

legate::align(legate::proxy::inputs[0], legate::proxy::inputs[1])

Dictates that inputs 0 and 1 of the task should be aligned.

See also

align(Variable, Variable)

Parameters:

left – The left operand to the alignment constraint.
right – The right operand to the alignment constraint.

Returns:

The alignment descriptor.

ProxyConstraint align(ProxyInputArguments proxies)#

Construct an alignment constraint descriptor for all input arguments.

The returned constraint aligns all input arguments with each other.

Parameters:: proxies – The input arguments.
Returns:: The alignment descriptor.

ProxyConstraint align(ProxyOutputArguments proxies)#

Construct an alignment constraint descriptor for all output arguments.

The returned constraint aligns all output arguments with each other.

Parameters:: proxies – The output arguments.
Returns:: The alignment descriptor.

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

ProxyConstraint broadcast( std::variant<ProxyArrayArgument, ProxyInputArguments, ProxyOutputArguments, ProxyReductionArguments> value, std::optional<tuple<std::uint32_t>> axes = std::nullopt, )#

Construct a broadcast constraint descriptor.

This routine may be used to describe a broadcast constraint for prospective arguments to a task. For example:

legate::broadcast(legate::proxy::inputs[0])

Dictates that the first input argument should be broadcast to all leaf tasks, while

legate::broadcast(legate::proxy::outputs)

Dictates that all outputs should be broadcast to all leaf tasks.

See legate::broadcast() for more information on the precise semantics of broadcasting arguments.

Parameters:

value – The proxy value to apply the broadcast constraint to.
axes – Optional axes to specify when broadcasting.

Returns:

The broadcast descriptor.

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

ProxyConstraint image( std::variant<ProxyArrayArgument, ProxyInputArguments, ProxyOutputArguments, ProxyReductionArguments> var_function, std::variant<ProxyArrayArgument, ProxyInputArguments, ProxyOutputArguments, ProxyReductionArguments> var_range, std::optional<ImageComputationHint> hint = std::nullopt, )#

Construct an image constraint descriptor.

This routine may be used to describe an image constraint for prospective arguments to a task.

See legate::image() for more information on the precise semantics of image constraints.

Parameters:

var_function – The proxy symbol for the function store.
var_range – The proxy symbol for the range store.
hint – The optional hint given to the runtime describing how the image computation will be performed.

Returns:

The image descriptor.

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

ProxyConstraint scale( tuple<std::uint64_t> factors, std::variant<ProxyArrayArgument, ProxyInputArguments, ProxyOutputArguments, ProxyReductionArguments> var_smaller, std::variant<ProxyArrayArgument, ProxyInputArguments, ProxyOutputArguments, ProxyReductionArguments> var_bigger, )#

Construct a scaling constraint descriptor.

This routine may be used to describe a scaling constraint for prospective arguments to a task.

See legate::scale() for more information on the precise semantics of scaling constraints.

Parameters:

factors – The scaling factors.
var_smaller – The proxy argument for the smaller store (that which should be scaled).
var_bigger – The proxy argument for the bigger store.

Returns:

The scale descriptor.

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

ProxyConstraint bloat( std::variant<ProxyArrayArgument, ProxyInputArguments, ProxyOutputArguments, ProxyReductionArguments> var_source, std::variant<ProxyArrayArgument, ProxyInputArguments, ProxyOutputArguments, ProxyReductionArguments> var_bloat, tuple<std::uint64_t> low_offsets, tuple<std::uint64_t> high_offsets, )#

Construct a bloat constraint descriptor.

This routine may be used to describe a bloat constraint for prospective arguments to a task.

See legate::bloat() for more information on the precise semantics of bloat constraints.

Parameters:

var_source – The proxy source store.
var_bloat – The proxy target store.
low_offsets – Offsets to bloat towards the negative direction.
high_offsets – Offsets to bloat towards the positive direction.

Returns:

The bloat descriptor.

Variables

ProxyInputArguments inputs = {}#

A proxy object that models the input arguments to a task as whole.

See also

ProxyInputArguments

ProxyOutputArguments outputs = {}#

A proxy object that models the output arguments to a task as whole.

See also

ProxyOutputArguments

ProxyReductionArguments reductions = {}#

A proxy object that models the reduction arguments to a task as whole.

See also

ProxyReductionArguments

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

Class for partition symbols.

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

A base class for partitioning constraints.

class ProxyArrayArgument#

#include <legate/partitioning/proxy.h>

An object that models a specific array argument to a task.

Public Types

enum class Kind : std::uint8_t#

The kind of argument.

Values:

enumerator INPUT#

enumerator OUTPUT#

enumerator REDUCTION#

Public Members

Kind kind = {}#: The selected kind of the argument.

std::uint32_t index = {}#: The index into the argument list (as returned e.g. by TaskContext::inputs()) corresponding to the argument.

class ProxyInputArguments : public legate::proxy_detail::TaskArgsBase<ProxyInputArguments, ProxyArrayArgument::Kind::INPUT>#: #include <legate/partitioning/proxy.h>

A class that models the input arguments to a task.

class ProxyOutputArguments : public legate::proxy_detail::TaskArgsBase<ProxyOutputArguments, ProxyArrayArgument::Kind::OUTPUT>#: #include <legate/partitioning/proxy.h>

A class that models the output arguments to a task.

class ProxyReductionArguments : public legate::proxy_detail::TaskArgsBase<ProxyReductionArguments, ProxyArrayArgument::Kind::REDUCTION>#: #include <legate/partitioning/proxy.h>

A class that models the reduction arguments to a task.

class ProxyConstraint#

#include <legate/partitioning/proxy.h>

The base proxy constraint class.

Public Functions

explicit ProxyConstraint(SharedPtr<detail::ProxyConstraint> impl)#

Construct a proxy constraint.

Parameters:: impl – The pointer to the private implementation.

inline const SharedPtr<detail::ProxyConstraint> &impl() const#

Returns:: The pointer to the private implementation.

namespace proxy_detail#

template<typename T, ProxyArrayArgument::Kind KIND> class TaskArgsBase#: Subclassed by legate::ProxyInputArguments, legate::ProxyOutputArguments, legate::ProxyReductionArguments