Legate Core API Reference

Point

class legate.core.legion.Point(p=None, dim=None)

The Point class wraps an legion_point_{n}d_t in the Legion C API.

Attributes
dim

Methods

raw

set_point

Rect

class legate.core.legion.Rect(hi=None, lo=None, exclusive=True, dim=None)

The Rect class wrap a legion_rect_{n}d_t in the Legion C API. It represents an N-D rectangle of dense points.

Attributes
dim
hi
lo

Methods

raw

set_bounds

Domain

class legate.core.legion.Domain(domain)

The Domain class wraps a legion_domain_t in the Legion C API. A Domain is the value stored by an IndexSpace. It consists of an N-D rectangle describing an upper bound on the points contained in the IndexSpace as well as optional sparsity map describing the actual non-dense set of points. If there is no sparsity map then the domain is purely the set of dense points represented by the rectangle bounds.

Attributes
dim

Methods

get_volume

Transform

class legate.core.legion.Transform(M, N, eye=True)

A Transform wraps an legion_transform_{m}x{n}_t in the Legion C API. A transform is simply an MxN matrix that can be used to convert Point objects from one coordinate space to another.

Methods

apply(point)

Convert an N-D Point into an M-D point using this transform

compose(outer)

Construct a composed transform of this transform with another transform

raw

apply(point)

Convert an N-D Point into an M-D point using this transform

compose(outer)

Construct a composed transform of this transform with another transform

AffineTransform

class legate.core.legion.AffineTransform(M, N, eye=True)

An AffineTransform wraps a legion_affine_transform_{m}x{n}_t in the Legion C API. The AffineTransform class represents an affine transform as a MxN affine transform as an (M+1)x(N+1) matrix and can used to transform N-D Point objects into M-D Point objects. AffineTransform objects can also be naturally composed to construct new AffineTransforms.

Attributes
offset
trans

Methods

apply(point)

Convert an N-D Point into an M-D point using this transform

compose(outer)

Construct a composed transform of this transform with another transform

raw

apply(point)

Convert an N-D Point into an M-D point using this transform

compose(outer)

Construct a composed transform of this transform with another transform

IndexSpace

class legate.core.legion.IndexSpace(context, runtime, handle, parent=None, owned=True)

An IndexSpace object wraps a legion_index_space_t in the Legion C API. An IndexSpace provides a name for a collection of (sparse) points. An IndexSpace can serve as the names for the rows in a LogicalRegion or be used for dispatching collections of tasks or other operations using index space launches.

Parameters
contextlegion_context_

The Legion context from get_legion_context()

runtimelegion_runtime_t

Handle for the Legion runtime from get_legion_runtime()

handlelegion_index_space_t

Created handle for an index space from a Legion C API call

parentIndexPartition

Parent index partition for this index space if any

ownedbool

Whether this object owns the handle for this index space and can delete the index space handle when the object is collected

Attributes
domain

Return a Domain that represents the points in this index space

Methods

add_child(child)

Add a child partition to this IndexSpace.

destroy([unordered])

Force deletion of this IndexSpace regardless of ownership This must be a root index space

get_bounds()

Return a Rect that represents the upper bounds of the IndexSpace.

get_dim()

Return the dimension of the IndexSpace

get_root()

Find the root of IndexSpace tree.

get_volume()

Return the total number of points in the IndexSpace

add_child(child)

Add a child partition to this IndexSpace.

destroy(unordered=False)

Force deletion of this IndexSpace regardless of ownership This must be a root index space

Parameters
unorderedbool

Whether this request is coming directly from the task or through and unordered channel such as a garbage collection

property domain

Return a Domain that represents the points in this index space

get_bounds()

Return a Rect that represents the upper bounds of the IndexSpace.

get_dim()

Return the dimension of the IndexSpace

get_root()

Find the root of IndexSpace tree.

get_volume()

Return the total number of points in the IndexSpace

PartitionFunctor

class legate.core.legion.PartitionFunctor

PartitionFunctor objects provide a common interface to computing IndexPartition objects using Legion’s support for dependent partitioning. Each kind of dependent partitioning operator in Legion can be accessed through a custom PartitionFunctor.

Methods

partition(runtime, context, parent, …)

The generic interface for computing an IndexPartition

partition(runtime, context, parent, color_space, kind, part_id)

The generic interface for computing an IndexPartition

Parameters
runtimelegion_runtime_t

Handle for the Legion runtime from get_legion_runtime()

contextlegion_context_t

The Legion context from get_legion_context()

parentIndexSpace

The parent index space for which we’re computing this partition

color_spaceIndexSpace

The color space defining the names of subspaces to be created

kindlegion_partition_kind_t

Description of the disjointness and completeness property (if they are known) for the partition

part_idint

Desired name for the color of this partition in the parent index space’s color space (if any)

PartitionByRestriction

class legate.core.legion.PartitionByRestriction(transform, extent)

PartitionByRestriction constructs a tesselated IndexPartition where an IndexSpace is created for each Point in the color space by projecting the point through the transform to create the lower bound point and then adding the extent. Note that this can be used to create both disjoint and aliased partitions, depending on the properties of the transform and the extent.

Methods

partition(runtime, context, parent, …)

The generic interface for computing an IndexPartition

partition(runtime, context, parent, color_space, kind, part_id)

The generic interface for computing an IndexPartition

Parameters
runtimelegion_runtime_t

Handle for the Legion runtime from get_legion_runtime()

contextlegion_context_t

The Legion context from get_legion_context()

parentIndexSpace

The parent index space for which we’re computing this partition

color_spaceIndexSpace

The color space defining the names of subspaces to be created

kindlegion_partition_kind_t

Description of the disjointness and completeness property (if they are known) for the partition

part_idint

Desired name for the color of this partition in the parent index space’s color space (if any)

PartitionByImage

class legate.core.legion.PartitionByImage(region, part, field, mapper=0, tag=0)

PartitionByImage projects an existing IndexPartition through a field of Points that point from one LogicalRegion into an IndexSpace.

Methods

partition(runtime, context, parent, …)

The generic interface for computing an IndexPartition

partition(runtime, context, parent, color_space, kind, part_id)

The generic interface for computing an IndexPartition

Parameters
runtimelegion_runtime_t

Handle for the Legion runtime from get_legion_runtime()

contextlegion_context_t

The Legion context from get_legion_context()

parentIndexSpace

The parent index space for which we’re computing this partition

color_spaceIndexSpace

The color space defining the names of subspaces to be created

kindlegion_partition_kind_t

Description of the disjointness and completeness property (if they are known) for the partition

part_idint

Desired name for the color of this partition in the parent index space’s color space (if any)

PartitionByImageRange

class legate.core.legion.PartitionByImageRange(region, part, field, mapper=0, tag=0)

PartitionByImageRange projects an existing IndexPartition through a field of Rects that point from one LogicalRegion into a range of points in a destination IndexSpace.

Methods

partition(runtime, context, parent, …)

The generic interface for computing an IndexPartition

partition(runtime, context, parent, color_space, kind, part_id)

The generic interface for computing an IndexPartition

Parameters
runtimelegion_runtime_t

Handle for the Legion runtime from get_legion_runtime()

contextlegion_context_t

The Legion context from get_legion_context()

parentIndexSpace

The parent index space for which we’re computing this partition

color_spaceIndexSpace

The color space defining the names of subspaces to be created

kindlegion_partition_kind_t

Description of the disjointness and completeness property (if they are known) for the partition

part_idint

Desired name for the color of this partition in the parent index space’s color space (if any)

EqualPartition

class legate.core.legion.EqualPartition

EqualPartition will construct an IndexPartition that creates IndexSpace children with roughly equal numbers of points in each child.

Methods

partition(runtime, context, parent, …)

The generic interface for computing an IndexPartition

partition(runtime, context, parent, color_space, kind, part_id)

The generic interface for computing an IndexPartition

Parameters
runtimelegion_runtime_t

Handle for the Legion runtime from get_legion_runtime()

contextlegion_context_t

The Legion context from get_legion_context()

parentIndexSpace

The parent index space for which we’re computing this partition

color_spaceIndexSpace

The color space defining the names of subspaces to be created

kindlegion_partition_kind_t

Description of the disjointness and completeness property (if they are known) for the partition

part_idint

Desired name for the color of this partition in the parent index space’s color space (if any)

PartitionByWeights

class legate.core.legion.PartitionByWeights(weights)

PartitionByWeights will construct an IndexPartition with the number of points in each child IndexSpace being allocated proportionally to the the relative weights.

Methods

partition(runtime, context, parent, …)

The generic interface for computing an IndexPartition

partition(runtime, context, parent, color_space, kind, part_id)

The generic interface for computing an IndexPartition

Parameters
runtimelegion_runtime_t

Handle for the Legion runtime from get_legion_runtime()

contextlegion_context_t

The Legion context from get_legion_context()

parentIndexSpace

The parent index space for which we’re computing this partition

color_spaceIndexSpace

The color space defining the names of subspaces to be created

kindlegion_partition_kind_t

Description of the disjointness and completeness property (if they are known) for the partition

part_idint

Desired name for the color of this partition in the parent index space’s color space (if any)

IndexPartition

class legate.core.legion.IndexPartition(context, runtime, parent, color_space, functor=None, handle=None, kind=2, part_id=4294967295, owned=True, keep=False)

An IndexPartition wraps a legion_index_partition_t in the Legion C API. It describes a partitioning of an IndexSpace into a collection of child IndexSpace objects. IndexPartition objects can be both disjoint and aliased. They can also be both complete and incomplete partitions.

Parameters
contextlegion_context_t

The Legion context from get_legion_context()

runtimelegion_runtime_t

Handle for the Legion runtime from get_legion_runtime()

parentIndexSpace

The parent index space for this partition

color_spaceIndexSpace

The index space that describes this subregions in this partition

functorPartitionFunctor

Any object that implements the PartitionFunctor interface

handlelegion_index_partition_t

Created handle for an index partition from a Legion C API call

kindlegion_partition_kind_t

The disjointness and completeness properties for the partition

part_idint

The color for the partition in parent index space

ownedbool

Whether this object owns the handle for this index space and can delete the index space handle when the object is collected

keepbool

Whether to keep a reference to the functor object that was used to create this index partition

Methods

destroy([unordered, recursive])

Force deletion of this IndexPartition regardless of ownership

get_child(point)

Find the child IndexSpace assocated with the point in the color space.

get_root()

Return the root IndexSpace in this tree.

destroy(unordered=False, recursive=True)

Force deletion of this IndexPartition regardless of ownership

Parameters
unorderedbool

Whether this request is coming directly from the task or through and unordered channel such as a garbage collection

recursivebool

Whether to recursively destroy down the index space tree

get_child(point)

Find the child IndexSpace assocated with the point in the color space.

get_root()

Return the root IndexSpace in this tree.

FieldSpace

class legate.core.legion.FieldSpace(context, runtime, owned=True)

A FieldSpace wraps a legion_field_space_t in the Legion C API. It is used to represent the columns in a LogicalRegion. Users can allocate and destroy fields in a field space dynamically.

Parameters
contextlegion_context_t

The Legion context from get_legion_context()

runtimelegion_runtime_t

Handle for the Legion runtime from get_legion_runtime()

Attributes
has_space

Methods

allocate_field(size_or_type[, field_id])

Allocate a field in the field space by its size or by inferring its size from some type representation that is passed in

allocate_field_ctype(ctype[, field_id])

Allocate a field in the field space based on the ctypes type.

allocate_field_dtype(dtype[, field_id])

Allocate a field in the field space based on the NumPy dtype.

allocate_field_from_future(future[, field_id])

Allocate a field based on a size stored in a Future

destroy([unordered])

Force deletion of this FieldSpace regardless of ownership

destroy_field(field_id[, unordered])

Destroy a field in the field space and reclaim its resources.

get_type(field_id)

Return the type of the object used to create the field.

allocate_field(size_or_type, field_id=4294967295)

Allocate a field in the field space by its size or by inferring its size from some type representation that is passed in

allocate_field_ctype(ctype, field_id=4294967295)

Allocate a field in the field space based on the ctypes type.

allocate_field_dtype(dtype, field_id=4294967295)

Allocate a field in the field space based on the NumPy dtype.

allocate_field_from_future(future, field_id=4294967295)

Allocate a field based on a size stored in a Future

destroy(unordered=False)

Force deletion of this FieldSpace regardless of ownership

Parameters
unorderedbool

Whether this request is coming directly from the task or through and unordered channel such as a garbage collection

destroy_field(field_id, unordered=False)

Destroy a field in the field space and reclaim its resources. Set unordered to True if this is done inside a garbage collection.

get_type(field_id)

Return the type of the object used to create the field.

FieldID

class legate.core.legion.FieldID(field_space, fid, type)

A FieldID class wraps a legion_field_id_t in the Legion C API. It provides a canonical way to represent an allocated field in a field space and means by which to deallocate the field.

Parameters
field_spaceFieldSpace

The owner field space for this field

fidint

The ID for this field

typetype

The type of this field

Attributes
fid
type

Methods

destroy([unordered])

Deallocate this field from the field space

destroy(unordered=False)

Deallocate this field from the field space

Region

class legate.core.legion.Region(context, runtime, index_space, field_space, handle=None, parent=None, owned=True)

A Region wraps a legion_logical_region_t in the Legion C API. A logical region describes a dataframe-like representation of program data with the rows described by an IndexSpace and the columns described by a FieldSpace.

Parameters
contextlegion_context_t

The Legion context from get_legion_context()

runtimelegion_runtime_t

Handle for the Legion runtime from get_legion_runtime()

index_spaceIndexSpace

The index space for this logical region

field_spaceFieldSpace

The field space for this logical region

handlelegion_logical_region_t

Created handle for a logical region from a Legion C API call

parentPartition

Parent logical partition for this logical region if any

ownedbool

Whether this object owns the handle for this index space and can delete the index space handle when the object is collected

Methods

destroy([unordered])

Force deletion of this Region regardless of ownership

get_child(index_partition)

Find the Partition object that corresponds to the corresponding IndexPartition object for the IndexSpace of this Region.

get_root()

Return the root Region in this tree.

destroy(unordered=False)

Force deletion of this Region regardless of ownership

Parameters
unorderedbool

Whether this request is coming directly from the task or through and unordered channel such as a garbage collection

get_child(index_partition)

Find the Partition object that corresponds to the corresponding IndexPartition object for the IndexSpace of this Region.

get_root()

Return the root Region in this tree.

Partition

class legate.core.legion.Partition(context, runtime, index_partition, parent, handle=None)

A Partition wraps a legion_logical_partition_t in the Legion C API.

Parameters
contextlegion_context_t

The Legion context from get_legion_context()

runtimelegion_runtime_t

Handle for the Legion runtime from get_legion_runtime()

index_partitionIndexPartition

The index partition associated with this logical partition

parentRegion

Parent logical region for this logical partition if any

handlelegion_logical_partition_t

Created handle for logical partition from a Legion C API call

Attributes
color_space

Methods

destroy()

This method is deprecated and is a no-op Partition objects never need to explicitly destroy their handles

get_child(point)

Return the child Region associated with the point in the color space.

get_root()

Return the Region at the root of this region tree.

destroy()

This method is deprecated and is a no-op Partition objects never need to explicitly destroy their handles

get_child(point)

Return the child Region associated with the point in the color space.

get_root()

Return the Region at the root of this region tree.

Fill

class legate.core.legion.Fill(region, parent, field, future, mapper=0, tag=0)

A Fill object provides a mechanism for launching fill operations in the Legion C API. A fill operation initializes the data in a field of a logical region to a specific value. Importantly this is performed lazily so fills incur near-zero cost.

Parameters
regionRegion

The logical region to be filled

parentRegion

The parent logical region where priviles are derived from

fieldFieldID or int

The name of the field to be filled

futureFuture

Future describing the value to use for performing the fill

mapperint

ID of the mapper to use for mapping the fill

tagint

Tag to pass to the mapper to provide context for any mapper calls

Methods

set_point(point)

Set the point to describe this fill for sharding with control replication

set_sharding_space(space)

Set the sharding space for this individual fill launch

launch

set_point(point)

Set the point to describe this fill for sharding with control replication

Parameters
pointPoint or legion_domain_point_t

The point value to associate with this fill

set_sharding_space(space)

Set the sharding space for this individual fill launch

Parameters
spaceIndexSpace

The index space for use when performing sharding of this fill

IndexFill

class legate.core.legion.IndexFill(partition, proj, parent, field, future, mapper=0, tag=0, space=None)

An IndexFill object provides a mechanism for launching index space fill operations in the Legion C API. Index fill operations enable many subregions in a sub-tree to be filled concurrently and efficiently. An index fill operation initializes the data in the field of each of the logical regions targeted by the index fill operation. Importantly, this is performed lazily so index fills incur near-zero cost.

partitionPartition

The logical partition upper bound from which to project the point fills from the index fill

projint

Projection function ID to describe how to project from the upper bound partition

parentRegion

The parent logical region where privileges are derived from

fieldFieldID or int

The name of the field to be filled

future: Future

Future describing the value to use for performing the index fill

mapperint

ID of the mapper to use for mapping the index fill

tagint

Tag to pass to the mapper to provide context for any mapper calls

spaceIndexSpace or Domain (default:None)

launch space domain

Methods

set_sharding_space(space)

Set the sharding space to use for this index fill launch with control replication

launch

set_sharding_space(space)

Set the sharding space to use for this index fill launch with control replication

Parameters
spaceIndexSpace

The index space to use as the sharding space

Copy

class legate.core.legion.Copy(mapper=0, tag=0)

A Copy object provides a mechanism for launching explicit region-to-region copy operations. Note: you should NOT use these for trying to move data between memories! Copy launchers should only be used for logically moving data between fields.

Parameters
mapperint

ID of the mapper to use for mapping the copy operation

tagint

Tag to pass to the mapper to provide context for any mapper calls

Methods

add_dst_indirect_requirement(region, field)

Add a destination indirection region requirement to the copy operation

add_dst_requirement(region, fields[, …])

Add a destination region requirement to the copy operation

add_src_indirect_requirement(region, field)

Add a source indirection region requirement to the copy operation

add_src_requirement(region, fields[, …])

Add a source region requirement to the copy operation

set_point(point)

Set the point to describe this copy for sharding with control replication

set_possible_dst_indirect_out_of_range(flag)

For scatter indirection copies indicate whether any of the destination indirection pointers may point out of bounds in the destination logical regions.

set_possible_src_indirect_out_of_range(flag)

For gather indirection copies indicate whether any of the source indirection pointers may point out of bounds in the source logical regions.

set_sharding_space(space)

Set the sharding space for this individual copy launch

launch

add_dst_indirect_requirement(region, field, parent=None, tag=0, is_range=False, coherence=0)

Add a destination indirection region requirement to the copy operation

Parameters
regionRegion

The logical region to serve as a destination indirection of the copy

fieldint or FieldID

The ID of the field to serve as a destination indirection field of the copy

parentRegion

The parent logical region from which privileges are derived

tagint

A mapping tag to pass to the mapper for context of this requirement

is_rangebool

Indicate whether the indirection field is a single pointer or a range (e.g. Rect) of points

coherenceint

The coherence mode for which to access this region

add_dst_requirement(region, fields, parent=None, tag=0, redop=0, coherence=0)

Add a destination region requirement to the copy operation

Parameters
regionRegion

The logical region to serve as a destination of the copy

fieldsint or FieldID or List[int] or List[FieldID]

The ID(s) of the fields to serve as destinations of the copy

parentRegion

The parent logical region from which privileges are derived

tagint

A mapping tag to pass to the mapper for context of this requirement

redopint

Optional reduction operator ID to reduce to the destination fields

coherenceint

The coherence mode for which to access this region

add_src_indirect_requirement(region, field, parent=None, tag=0, is_range=False, coherence=0)

Add a source indirection region requirement to the copy operation

Parameters
regionRegion

The logical region to serve as a source indirection of the copy

fieldint or FieldID

The ID of the field to serve as a source indirection of the copy

parentRegion

The parent logical region from which privileges are derived

tagint

A mapping tag to pass to the mapper for context of this requirement

is_rangebool

Indicate whether the indirection field is a single pointer or a range (e.g. Rect) of points

coherenceint

The coherence mode for which to access this region

add_src_requirement(region, fields, parent=None, tag=0, coherence=0)

Add a source region requirement to the copy operation

Parameters
regionRegion

The logical region to serve as a source of the copy

fieldsint or FieldID or List[int] or List[FieldID]

The ID(s) of the fields to serve as sources of the copy

parentRegion

The parent logical region from which privileges are derived

tagint

A mapping tag to pass to the mapper for context of this requirement

coherenceint

The coherence mode for which to access this region

set_point(point)

Set the point to describe this copy for sharding with control replication

Parameters
pointPoint or legion_domain_point_t

The point value to associate with this copy

set_possible_dst_indirect_out_of_range(flag)

For scatter indirection copies indicate whether any of the destination indirection pointers may point out of bounds in the destination logical regions.

Parameters
flagbool

Indicate whether destination pointers may point outside the privileges

set_possible_src_indirect_out_of_range(flag)

For gather indirection copies indicate whether any of the source indirection pointers may point out of bounds in the source logical regions.

Parameters
flagbool

Indicate whether source pointers may point outside the privileges

set_sharding_space(space)

Set the sharding space for this individual copy launch

Parameters
spaceIndexSpace

The index space for use when performing sharding of this copy

IndexCopy

class legate.core.legion.IndexCopy(domain, mapper=0, tag=0)

An IndexCopy object provides a mechanism for launching explicit region-to-region copies between many different subregions simultaneously. Note: you should NOT use these for trying to move data between memories! Copy launchers should only be used for logically moving data between different fields.

Parameters
domainDomain

The domain of points for the index space launch

mapperint

ID of the mapper to use for mapping the copy operation

tagint

Tag to pass to the mapper to provide context for any mapper calls

Methods

add_dst_indirect_requirement(upper_bound, …)

Add a destination indirection region requirement to the index copy operation

add_dst_requirement(upper_bound, fields, …)

Add a destination region requirement to the index copy operation

add_src_indirect_requirement(upper_bound, …)

Add a source indirection region requirement to the index copy operation

add_src_requirement(upper_bound, fields, …)

Add a source region requirement to the index copy operation

set_possible_dst_indirect_out_of_range(flag)

For scatter indirection copies indicate whether any of the destination indirection pointers may point out of bounds in the destination logical regions.

set_possible_src_indirect_out_of_range(flag)

For gather indirection copies indicate whether any of the source indirection pointers may point out of bounds in the source logical regions.

set_sharding_space(space)

Set the sharding space to use for this index copy launch with control replication

launch

add_dst_indirect_requirement(upper_bound, field, projection, parent=None, tag=0, is_range=False, coherence=0)

Add a destination indirection region requirement to the index copy operation

Parameters
upper_bound: Region or Partition

The upper bound logical region or partition to serve as a destination of the index copy

fieldint or FieldID

The ID of the field to serve as a source indirection of the index copy

projectionint

The ID of a projection function to compute specific subregions for each point in the index space launch domain

parentRegion

The parent logical region from which privileges are derived

tagint

A mapping tag to pass to the mapper for context of this requirement

is_rangebool

Indicate whether the indirection field is a single pointer or a range (e.g. Rect) of points

coherenceint

The coherence mode for which to access this region

add_dst_requirement(upper_bound, fields, projection, parent=None, tag=0, redop=0, coherence=0)

Add a destination region requirement to the index copy operation

Parameters
upper_bound: Region or Partition

The upper bound logical region or partition to serve as a source of the copy

fieldsint or FieldID or List[int] or List[FieldID]

The ID(s) of the fields to serve as sources of the copy

projectionint

The ID of a projection function to compute specific subregions for each point in the index space launch domain

parentRegion

The parent logical region from which privileges are derived

tagint

A mapping tag to pass to the mapper for context of this requirement

redopint

Optional reduction operator ID to reduce the destination fields

coherenceint

The coherence mode for which to access this region

add_src_indirect_requirement(upper_bound, field, projection, parent=None, tag=0, is_range=False, coherence=0)

Add a source indirection region requirement to the index copy operation

Parameters
upper_bound: Region or Partition

The upper bound logical region or partition to serve as a source of the index copy

fieldint or FieldID

The ID of the field to serve as a source indirection of the index copy

projectionint

The ID of a projection function to compute specific subregions for each point in the index space launch domain

parentRegion

The parent logical region from which privileges are derived

tagint

A mapping tag to pass to the mapper for context of this requirement

is_rangebool

Indicate whether the indirection field is a single pointer or a range (e.g. Rect) of points

coherenceint

The coherence mode for which to access this region

add_src_requirement(upper_bound, fields, projection, parent=None, tag=0, coherence=0)

Add a source region requirement to the index copy operation

Parameters
upper_bound: Region or Partition

The upper bound logical region or partition to serve as a source of the copy

fieldsint or FieldID or List[int] or List[FieldID]

The ID(s) of the fields to serve as sources of the copy

projectionint

The ID of a projection function to compute specific subregions for each point in the index space launch domain

parentRegion

The parent logical region from which privileges are derived

tagint

A mapping tag to pass to the mapper for context of this requirement

coherenceint

The coherence mode for which to access this region

set_possible_dst_indirect_out_of_range(flag)

For scatter indirection copies indicate whether any of the destination indirection pointers may point out of bounds in the destination logical regions.

Parameters
flagbool

Indicate whether destination pointers may point outside the privileges

set_possible_src_indirect_out_of_range(flag)

For gather indirection copies indicate whether any of the source indirection pointers may point out of bounds in the source logical regions.

Parameters
flagbool

Indicate whether source pointers may point outside the privileges

set_sharding_space(space)

Set the sharding space to use for this index copy launch with control replication

Parameters
spaceIndexSpace

The index space to use as the sharding space

Attach

class legate.core.legion.Attach(region, field, data, mapper=0, tag=0, read_only=False, row_major=True)

An Attach object provides a mechanism for attaching external data to a logical region, thereby allowing Legion to use external data in place for performing computations.

Parameters
regionRegion

The logical region to which external data will be attached

fieldint or FieldID

The field ID to which the data will be attached

datanumpy.ndarray or buffer

Input data in the form of a numpy array or an object that implements the Python buffer protocol

mapperint

ID of the mapper to use for mapping the copy operation

tagint

Tag to pass to the mapper to provide context for any mapper calls

read_onlybool

Whether this buffer should only be accessed read-only

row_majorbool

If data is a buffer, indicate whether dimensions should interpreted as row-major or column-major

Methods

set_mapped(mapped)

Set whether the resulting PhysicalRegion should be considered mapped in the enclosing task context.

set_restricted(restricted)

Set whether restricted coherence should be used on the logical region.

launch

set_mapped(mapped)

Set whether the resulting PhysicalRegion should be considered mapped in the enclosing task context.

set_restricted(restricted)

Set whether restricted coherence should be used on the logical region. If restricted coherence is enabled, changes to the data in the logical region will be eagerly reflected back to the external buffer.

Detach

class legate.core.legion.Detach(region, flush=True)

A Detach operation will unbind an external resource from a logical region. This will also allow any outstanding mutations to the logical region to be flushed back to the external memory allocation.

Parameters
regionPhysicalRegion

The physical region describing an external resource to be detached

flushbool

Whether to flush changes to the logical region to the external allocation

Methods

launch(runtime, context[, unordered])

Dispatch the detach operation to the runtime

launch(runtime, context, unordered=False)

Dispatch the detach operation to the runtime

Returns
Future containing no data that completes when detach operation is done
If ‘unordered’ is set to true then you must call legate_task_progress
before using the returned Future

Acquire

class legate.core.legion.Acquire(region, fields, mapper=0, tag=0)

An Acquire operation provides a mechanism for temporarily relaxing restricted coherence on a logical region, thereby enabling Legion to manage coherence with multiple copies of the data.

Parameters
regionRegion

The logical region on which to relax restricted coherence

fieldsint or FieldID or List[int] or List[FieldID]

The fields to perform the attach on

mapperint

ID of the mapper to use for mapping the copy operation

tagint

Tag to pass to the mapper to provide context for any mapper calls

Methods

launch

Release

class legate.core.legion.Release(region, fields, mapper=0, tag=0)

A Release operation will undo any acquire operations by putting restricted coherence requirements back onto a logical region.

Parameters
regionRegion

The logical region on which to relax restricted coherence

fieldsint or FieldID or List[int] or List[FieldID]

The fields to perform the attach on

mapperint

ID of the mapper to use for mapping the copy operation

tagint

Tag to pass to the mapper to provide context for any mapper calls

Methods

launch

Future

class legate.core.legion.Future(handle=None, type=None)

A Future object represents a pending computation from a task or other operation. Futures can carry “unstructured” data as a buffer of bytes or they can be empty and used only for synchronization.

Parameters
handlelegion_future_t

Wrap an optional handle in this Future. The Future object will take ownership of this handle

typeobject

Optional object to represent the type of this future

Attributes
type

Methods

destroy(unordered)

Eagerly destroy this Future before the garbage collector does It is illegal to use the Future after this call

get_buffer([size])

Return a buffer storing the data for this Future.

get_size()

Return the size of the buffer that the future stores.

get_string()

Return the result of the future interpreted as a string.

is_ready([subscribe])

Parameters

set_value(runtime, data, size[, type])

Parameters

wait()

Block waiting for the future to complete

destroy(unordered)

Eagerly destroy this Future before the garbage collector does It is illegal to use the Future after this call

Parameters
unorderedbool

Whether this Future is being destroyed outside of the scope of the execution of a Legion task or not

get_buffer(size=None)

Return a buffer storing the data for this Future. This will block until the future completes if it has not already.

Parameters
sizeint

Optional expected size of the future

Returns
——-
An object that implements the Python buffer protocol
that contains the data
get_size()

Return the size of the buffer that the future stores. This will block until the future completes if it has not already.

get_string()

Return the result of the future interpreted as a string. This will block until the future completes if it has not already.

is_ready(subscribe=False)
Parameters
subscribebool

Whether the data for this future is ultimately needed locally

Returns
bool indicating if the future has completed or not
set_value(runtime, data, size, type=None)
Parameters
runtimelegion_runtime_t*

Pointer to the Legion runtime object

databuffer

Set the value of the future from a buffer

sizeint

Size of the buffer in bytes

typeobject

An optional object to represent the type of the future

wait()

Block waiting for the future to complete

OutputRegion

class legate.core.legion.OutputRegion(context, runtime, field_space=None, fields=[], global_indexing=True, existing=None, flags=None, proj=None, parent=None, coherence=0, tag=0)

An OutputRegion creates a name for a logical region that will be produced as an output from executing a/an (index) task. The bounds of the index space for this region will not be immediately known, but users can still use the names of the logical region and index space throughout the program without needing to block to wait for the size to resolve.

Parameters
contextlegion_context_t

Context for the enclosing parent task

runtimelegion_runtime_t

Handle for the Legion runtime

field_spaceFieldSpace

The field space to use for the creation of a new logical region

fieldsint or FieldID or List[int] or List[FieldID]

The fields that will be created in the output region

global_indexingbool

Whether or not the runtime should use a global indexing approach to compute the new index space for the output logical region. If set to true, the output space will be a 1-D space with a prefix sum over all the subregions. If set to false then the output index space will be 2-D reflecting the output size for each of the different point tasks contributing.

existingRegion or Partition

An optional existing region or partition for which the output will be a new instance

flagsint

Flags to attach to the region requirement for the output region

projint

The ID of a projection function to use for projection

parentRegion

The parent logical region from which privileges are derived

coherenceint

The coherence mode for accessing the logical region

tagint

The tag to attach to the region requirement to provide context

Methods

add_field(field[, instance])

Add a field to this output region

destroy(unordered)

Eagerly destroy this OutputRegion before the garbage collector does It is illegal to use the OutputRegion after this call

get_partition([owned])

Parameters

get_region([owned])

Parameters

add_field(field, instance=True)

Add a field to this output region

Parameters
fieldint or FieldID

field to add to the output region

instancebool

whether this should be added to the instance vector of the region requirement for the output region

destroy(unordered)

Eagerly destroy this OutputRegion before the garbage collector does It is illegal to use the OutputRegion after this call

Parameters
unorderedbool

Whether this OutputRegion is being destroyed outside of the scope of the execution of a Legion task or not

get_partition(owned=True)
Parameters
ownedbool

Whether to take ownership of the created IndexPartition object

Returns
New logical partition created by the output region
get_region(owned=True)
Parameters
ownedbool

Whether to take ownership of the created IndexSpace and Region objects

Returns
New logical region created by the output region

PhysicalRegion

class legate.core.legion.PhysicalRegion(handle=None)

A PhysicalRegion object represents an actual mapping of a logical region to a physical allocation in memory and its associated layout. PhysicalRegion objects can be both mapped and unmapped. A mapped PhysicalRegion contains the most recent valid copy of the logical region’s data, whereas an unmapped PhysicalRegion can contains a stale copy of the data.

Parameters
handlelegion_physical_region_t

The handle for a physical region that this object will own

Methods

destroy(unordered)

Eagerly destroy this PhysicalRegion before the garbage collector does It is illegal to use the PhysicalRegion after this call

is_mapped()

Returns

launch(runtime, context)

unmap(runtime, context[, unordered])

Unmap this physical region from the current logical region If ‘unordered=True’ you must call legate_task_progress to guarantee that this unmapping is finished

wait_until_valid()

Block waiting until the data in this physical region to be ready to access

remap

destroy(unordered)

Eagerly destroy this PhysicalRegion before the garbage collector does It is illegal to use the PhysicalRegion after this call

Parameters
unorderedbool

Whether this PhysicalRegion is being destroyed outside of the scope of the execution of a Legion task or not

is_mapped()
Returns
bool indicating if this PhysicalRegion is currently mapped
unmap(runtime, context, unordered=False)

Unmap this physical region from the current logical region If ‘unordered=True’ you must call legate_task_progress to guarantee that this unmapping is finished

wait_until_valid()

Block waiting until the data in this physical region to be ready to access

InlineMapping

class legate.core.legion.InlineMapping(region, fields, read_only=False, mapper=0, tag=0, parent=None, coherence=0)

An InlineMapping object provides a mechanism for creating a mapped PhysicalRegion of a logical region for the local task to directly access the data in the logical region. Note that inline mappings do block deferred execution and therefore they should be used primarily as a productivity feature for loading and storing data infrequently. They should never be used in performance critical code.

Parameters
regionRegion

The logical region to map

fieldsint or FieldID or List[int] or List[FieldID]

The fields of the logical region to map

read_onlybool

Whether the inline mapping will only be reading the data

mapperint

ID of the mapper for managing the mapping of the inline mapping

tagint

Tag to pass to the mapper to provide calling context

parentRegion

Parent logical region from which privileges are derived

coherenceint

The coherence mode for the inline mapping

Methods

launch

Task

class legate.core.legion.Task(task_id, data=None, size=0, mapper=0, tag=0)

A Task object provides a mechanism for launching individual sub-tasks from the current parent task. For scalability we encourage the use of IndexTasks in the common case, but there are certainly many common uses of individual task launches as well.

task_idint

ID of the task to launch

dataobject that implements the Python buffer protocol

The data to pass to the task as a buffer by-value

sizeint

Number of bytes of data to pass as a by-value argument

mapperint

ID of the mapper for managing the mapping of the task

tagint

Tag to pass to the mapper to provide calling context

Methods

add_future(future)

Record a future as a precondition on running this task

add_no_access_requirement(region, fields[, …])

Add a no-access region requirement to the task

add_read_requirement(region, fields[, …])

Add a read-only region requirement to the task

add_read_write_requirement(region, fields[, …])

Add a read-write region requirement to the task

add_reduction_requirement(region, fields, redop)

Add a reduction region requirement to the task

add_write_requirement(region, fields[, …])

Add a write-discard region requirement to the task

set_local_function(local)

Set a flag indicating whether this task can be considered a local function task.

set_point(point)

Set the point to describe this task for sharding with control replication

set_sharding_space(space)

Set the sharding space for this individual task launch

launch

add_future(future)

Record a future as a precondition on running this task

Parameters
futureFuture

The future to record as a precondition

add_no_access_requirement(region, fields, parent=None, tag=0, flags=0, coherence=0)

Add a no-access region requirement to the task

Parameters
regionRegion

The logical region for the region requirement

fieldsint or FieldID or List[int] or List[FieldID]

List of field identifiers for the region requirement

parentRegion

The logical region from which privileges are derived

tagint

Tag to pass to the mapper to provide calling context

flagsint

Flags to attach to the region requirement

coherenceint

The coherence mode for the region requirement

add_read_requirement(region, fields, parent=None, tag=0, flags=0, coherence=0)

Add a read-only region requirement to the task

Parameters
regionRegion

The logical region for the region requirement

fieldsint or FieldID or List[int] or List[FieldID]

List of field identifiers for the region requirement

parentRegion

The logical region from which privileges are derived

tagint

Tag to pass to the mapper to provide calling context

flagsint

Flags to attach to the region requirement

coherenceint

The coherence mode for the region requirement

add_read_write_requirement(region, fields, parent=None, tag=0, flags=0, coherence=0)

Add a read-write region requirement to the task

Parameters
regionRegion

The logical region for the region requirement

fieldsint or FieldID or List[int] or List[FieldID]

List of field identifiers for the region requirement

parentRegion

The logical region from which privileges are derived

tagint

Tag to pass to the mapper to provide calling context

flagsint

Flags to attach to the region requirement

coherenceint

The coherence mode for the region requirement

add_reduction_requirement(region, fields, redop, parent=None, tag=0, flags=0, coherence=0)

Add a reduction region requirement to the task

Parameters
regionRegion

The logical region for the region requirement

fieldsint or FieldID or List[int] or List[FieldID]

List of field identifiers for the region requirement

redopint

ReductionOp ID that will be used in the sub-task

parentRegion

The logical region from which privileges are derived

tagint

Tag to pass to the mapper to provide calling context

flagsint

Flags to attach to the region requirement

coherenceint

The coherence mode for the region requirement

add_write_requirement(region, fields, parent=None, tag=0, flags=0, coherence=0)

Add a write-discard region requirement to the task

Parameters
regionRegion

The logical region for the region requirement

fieldsint or FieldID or List[int] or List[FieldID]

List of field identifiers for the region requirement

parentRegion

The logical region from which privileges are derived

tagint

Tag to pass to the mapper to provide calling context

flagsint

Flags to attach to the region requirement

coherenceint

The coherence mode for the region requirement

set_local_function(local)

Set a flag indicating whether this task can be considered a local function task. Specifically that means it only has future preconditions with no region arguments.

Parameters
localbool

Whether we can treat the task as a local function task

set_point(point)

Set the point to describe this task for sharding with control replication

Parameters
pointPoint or legion_domain_point_t

The point value to associate with this task

set_sharding_space(space)

Set the sharding space for this individual task launch

Parameters
spaceIndexSpace

The index space for use when performing sharding of this task

FutureMap

class legate.core.legion.FutureMap(handle=None)

A FutureMap object represents a collection of Future objects created by an index space operation such as an IndexTask launch. Applications can use a future map to synchronize with all the individual operations (not recommended), or to obtain individual futures from point operations in the index space launch.

Parameters
handlelegion_future_map_t

The handle for this FutureMap to wrap and take ownership of

Methods

destroy(unordered)

Eagerly destroy this FutureMap before the garbage collector does It is illegal to use the FutureMap after this call

from_list(context, runtime, futures)

Construct a FutureMap from a list of futures

get_future(point)

Extract a specific future from the future map

reduce(context, runtime, redop[, …])

Reduce all the futures in the future map down to a single future value using a reduction operator.

wait()

Wait for all the futures in the future map to complete

destroy(unordered)

Eagerly destroy this FutureMap before the garbage collector does It is illegal to use the FutureMap after this call

Parameters
unorderedbool

Whether this FutureMap is being destroyed outside of the scope of the execution of a Legion task or not

classmethod from_list(context, runtime, futures)

Construct a FutureMap from a list of futures

Parameters
contextlegion_context_

The context handle for the enclosing parent task

runtimelegion_runtime_t

The Legion runtime handle

futuresList[Future]

A list of futures to use to construct a future map

Returns
FutureMap that contains all the futures in 1-D space of points
get_future(point)

Extract a specific future from the future map

Parameters
pointPoint

The particular point in the index space launch to extract

Returns
Future describing the result from the particular point operation
reduce(context, runtime, redop, deterministic=False, mapper=0, tag=0)

Reduce all the futures in the future map down to a single future value using a reduction operator.

Parameters
contextlegion_context_t

The context handle for the enclosing parent task

runtimelegion_runtime_t

The Legion runtime handle

redopint

ID for the reduction operator to use for reducing futures

deterministicbool

Whether this reduction needs to be performed deterministically

mapperint

ID of the mapper for managing the mapping of the task

tagint

Tag to pass to the mapper to provide calling context

Returns
Future representing the reduced value of all the future in the map
wait()

Wait for all the futures in the future map to complete

IndexTask

class legate.core.legion.IndexTask(task_id, domain, argmap=None, data=None, size=0, mapper=0, tag=0)

An IndexTask object provides a mechnanism for launching a collection of tasks simultaneously as described by the points in an index space. The point tasks inside the index task launch can still name arbitrary subsets of data (although if they are interfering, the projection functions used must be capable of describing the dependences).

task_idint

ID of the task to launch

domainRect or IndexSpace

The domain description of the tasks to make (one task per point)

argmapArgumentMap

Optional argument map for passing data to point tasks

dataobject that implements the Python buffer protocol

Buffer of byte arguments to pass to all the point tasks

sizeint

The number of bytes in the data buffer to pass

mapperint

ID of the mapper for managing the mapping of the task

tagint

Tag to pass to the mapper to provide calling context

Methods

add_future(future)

Add a future precondition to all the points in the index space launch

add_no_access_requirement(upper_bound, …)

Add a region requirement without any access privileges

add_output(output)

Add an output region to the regoin requirements for this task

add_outputs(outputs)

Add a output regions to the regoin requirements for this task

add_point_future(argmap)

Add an additional argument map for passing arguments to each point task, each of these arguments will be appended to list of futures for each of the point tasks.

add_read_requirement(upper_bound, fields, …)

Add a region requirement read-only access privileges

add_read_write_requirement(upper_bound, …)

Add a region requirement with read-write privileges

add_reduction_requirement(upper_bound, …)

Add a region requirement with reduction privileges for a reduction op

add_write_requirement(upper_bound, fields, …)

Add a region requirement with write-discard privileges

set_point(point, data, size)

Set the point argument in the argument map for the index task

set_sharding_space(space)

Set the sharding space to use for this index launch with control replication

launch

add_future(future)

Add a future precondition to all the points in the index space launch

Parameters
futureFuture

A future that will be passed as a precondition to all point tasks

add_no_access_requirement(upper_bound, fields, projection, parent=None, tag=0, flags=0, coherence=0)

Add a region requirement without any access privileges

Parameters
upper_boundRegion or Partition

The upper node in the region tree from which point task region requirements will be projected

fieldsint or FieldID or List[int] or List[FieldID]

The fields for the region requirement

projectionint

ID for the projection function to use for performing projections

parentRegion

The logical region from which privileges are derived

tagint

Tag to pass to the mapper to provide calling context

flagsint

Flags to attach to the region requirement

coherenceint

The coherence mode for the region requirement

add_output(output)

Add an output region to the regoin requirements for this task

Parameters
outputOutputRegion

The output region that will be determined by this index launch

add_outputs(outputs)

Add a output regions to the regoin requirements for this task

Parameters
outputsList[OutputRegion]

The output regions that will be determined by this index launch

add_point_future(argmap)

Add an additional argument map for passing arguments to each point task, each of these arguments will be appended to list of futures for each of the point tasks.

Parameters
argmapArgumentMap

Per-point arguments to be added to the list of future preconditions

add_read_requirement(upper_bound, fields, projection, parent=None, tag=0, flags=0, coherence=0)

Add a region requirement read-only access privileges

Parameters
upper_boundRegion or Partition

The upper node in the region tree from which point task region requirements will be projected

fieldsint or FieldID or List[int] or List[FieldID]

The fields for the region requirement

projectionint

ID for the projection function to use for performing projections

parentRegion

The logical region from which privileges are derived

tagint

Tag to pass to the mapper to provide calling context

flagsint

Flags to attach to the region requirement

coherenceint

The coherence mode for the region requirement

add_read_write_requirement(upper_bound, fields, projection, parent=None, tag=0, flags=0, coherence=0)

Add a region requirement with read-write privileges

Parameters
upper_boundRegion or Partition

The upper node in the region tree from which point task region requirements will be projected

fieldsint or FieldID or List[int] or List[FieldID]

The fields for the region requirement

projectionint

ID for the projection function to use for performing projections

parentRegion

The logical region from which privileges are derived

tagint

Tag to pass to the mapper to provide calling context

flagsint

Flags to attach to the region requirement

coherenceint

The coherence mode for the region requirement

add_reduction_requirement(upper_bound, fields, redop, projection, parent=None, tag=0, flags=0, coherence=0)

Add a region requirement with reduction privileges for a reduction op

Parameters
upper_boundRegion or Partition

The upper node in the region tree from which point task region requirements will be projected

fieldsint or FieldID or List[int] or List[FieldID]

The fields for the region requirement

redopint

ID for a reduction operator the tasks will use

projectionint

ID for the projection function to use for performing projections

parentRegion

The logical region from which privileges are derived

tagint

Tag to pass to the mapper to provide calling context

flagsint

Flags to attach to the region requirement

coherenceint

The coherence mode for the region requirement

add_write_requirement(upper_bound, fields, projection, parent=None, tag=0, flags=0, coherence=0)

Add a region requirement with write-discard privileges

Parameters
upper_boundRegion or Partition

The upper node in the region tree from which point task region requirements will be projected

fieldsint or FieldID or List[int] or List[FieldID]

The fields for the region requirement

projectionint

ID for the projection function to use for performing projections

parentRegion

The logical region from which privileges are derived

tagint

Tag to pass to the mapper to provide calling context

flagsint

Flags to attach to the region requirement

coherenceint

The coherence mode for the region requirement

set_point(point, data, size)

Set the point argument in the argument map for the index task

Parameters
pointPoint

The point to set in the argument map

dataobject that implements the Python buffer protocol

The data to be set for the point

sizeint

The size of the data in the buffer

set_sharding_space(space)

Set the sharding space to use for this index launch with control replication

Parameters
spaceIndexSpace

The index space to use as the sharding space

Fence

class legate.core.legion.Fence(mapping)

A Fence operation provides a mechanism for inserting either mapping or execution fences into the stream of tasks and other operations generated by a program. A mapping fence will prevent reordering of operations during the mapping process, but has no bearing on execution. An execution fence will ensure all tasks and operations that come perform the fence are ordered with respect to all the tasks and operations that come after it.

Parameters
mappingbool

Whether this is a mapping fence or not

Methods

launch

ArgumentMap

class legate.core.legion.ArgumentMap(handle=None, future_map=None)

An ArgumentMap is a object that allows for the passing of data directly to individual point tasks in IndexTask launches.

handlelegion_argument_map_t

The handle of which to take ownership

future_maplegion_future_map_t

A future map that is currently storing the data for this argument map

Methods

destroy(unordered)

Eagerly destroy this ArgumentMap before the garbage collector does It is illegal to use the ArgumentMap after this call

set_future(point, future[, replace])

Set the point argument in the argument map using a Future

set_point(point, data, size[, replace])

Set the point argument in the argument map

destroy(unordered)

Eagerly destroy this ArgumentMap before the garbage collector does It is illegal to use the ArgumentMap after this call

Parameters
unorderedbool

Whether this ArgumentMap is being destroyed outside of the scope of the execution of a Legion task or not

set_future(point, future, replace=True)

Set the point argument in the argument map using a Future

Parameters
pointPoint

The point to set in the argument map

futureFuture

The future

replacebool

Whether we should replace this argument if it already exists

set_point(point, data, size, replace=True)

Set the point argument in the argument map

Parameters
pointPoint

The point to set in the argument map

dataobject that implements the Python buffer protocol

The data to be set for the point

sizeint

The size of the data in the buffer

replacebool

Whether we should replace this argument if it already exists

BufferBuilder

class legate.core.legion.BufferBuilder(type_safe=False)

A BufferBuilder object is a helpful utility for constructing buffers of bytes to pass through to tasks in other languages.

Methods

add_arg

encode_dtype

get_size

get_string

pack_128bit_complex

pack_16bit_float

pack_16bit_int

pack_16bit_uint

pack_32bit_float

pack_32bit_int

pack_32bit_uint

pack_64bit_complex

pack_64bit_float

pack_64bit_int

pack_64bit_uint

pack_8bit_int

pack_8bit_uint

pack_accessor

pack_bool

pack_buffer

pack_char

pack_dimension

pack_dtype

pack_point

pack_string

pack_value