Warning

You are reading a version of the website built against the unstable main branch. This content is liable to change without notice and may be inappropriate for your use case. You can find the documentation for the current stable release here.

pyop3.index_tree package

Submodules

pyop3.index_tree.apply module

exception pyop3.index_tree.apply.MyBadError[source]

Bases: Exception

pyop3.index_tree.apply.collect_leaf_target_paths(axes)[source]
pyop3.index_tree.apply.collect_leaf_targets(axes)[source]
Returns:

An iterable of generators, one per leaf.

Return type:

tuple

Notes

This function is a generator because often the result does not need to be exhaustively searched.

pyop3.index_tree.apply.compose_targets(orig_axes, orig_targets, indexed_axes, indexed_target, fullmap, *, axis_path=immutabledict({}))[source]

Traverse indexed_axes, picking up bits from indexed_target_paths and keep trying to address orig_axes.paths with it. If there is a hit then we take that bit of the original target path into the new location.

We do not accumulate things as we go. The final result should be the map

{ (indexed_axis, component) -> ((target_path1 | target_path2, …), (targetexpr1 | targetexpr2)), … }

Things are complicated by the fact that not all of the targets from indexed_target_paths will resolve. Imagine axisB[p] where p is from axisA[::2].iter(). p targets 2 things and only one will match with axisB. We need to check for this outside the function.

—

pyop3.index_tree.apply.convert_region_to_affine_slice(region_slice, axis_component)[source]
pyop3.index_tree.apply.index_axes(index_tree, loop_context=None, orig_axes=None)[source]

Build an axis tree from an index tree.

Parameters:

axes – An axis tree that is being indexed. This argument is not always needed if, say, we are constructing the iteration set for the expression map(p).index(). If not provided then some indices (e.g. unbounded slices) will no longer work.

Returns:

  • AxisTree – The new axis tree.

  • plus target paths and target exprs

pyop3.index_tree.apply.make_indexed_axis_tree(index_tree, target_axes)[source]
pyop3.index_tree.apply.match_target_paths_to_axis_tree(index_tree, orig_axes)[source]

Traverse the index tree to determine which axes it targets.

pyop3.index_tree.apply.match_target_paths_to_axis_tree_rec(index_tree, orig_axes, *, index_path, candidate_target_paths_acc)[source]

pyop3.index_tree.parse module

exception pyop3.index_tree.parse.IncompletelyIndexedException[source]

Bases: Pyop3Exception

Exception raised when an axis tree is incompletely indexed by an index tree/forest.

pyop3.index_tree.parse.as_context_free_index_tree(index_tree, loop_context)[source]
pyop3.index_tree.parse.as_index_forest(forest, /, axes=None, *, strict=False)

Return a collection of index trees, split by loop context.

Parameters:
  • forest – The object representing an indexing operation.

  • axes – The axis tree to which the indexing is being applied.

  • strict – Flag indicating whether or not additional slices should be added implicitly. If \(False\) then extra slices are added to fill up any unindexed shape. If \(True\) then providing an insufficient set of indices will raise an exception.

Returns:

A mapping from loop contexts to a tuple of equivalent index trees. Loop contexts are represented by the mapping {loop index id: iterset path}.

Multiple index trees are needed because maps are able to yield multiple equivalent index trees.

Return type:

immutabledict.immutabledict

pyop3.index_tree.parse.as_index_forests(forest, /, axes=None, *, strict=False)[source]

Return a collection of index trees, split by loop context.

Parameters:
  • forest – The object representing an indexing operation.

  • axes – The axis tree to which the indexing is being applied.

  • strict – Flag indicating whether or not additional slices should be added implicitly. If \(False\) then extra slices are added to fill up any unindexed shape. If \(True\) then providing an insufficient set of indices will raise an exception.

Returns:

A mapping from loop contexts to a tuple of equivalent index trees. Loop contexts are represented by the mapping {loop index id: iterset path}.

Multiple index trees are needed because maps are able to yield multiple equivalent index trees.

Return type:

immutabledict.immutabledict

pyop3.index_tree.parse.collect_loop_contexts(obj, /)[source]
pyop3.index_tree.parse.collect_loop_contexts(index_tree, /)
pyop3.index_tree.parse.collect_loop_contexts(loop_index, /)
pyop3.index_tree.parse.collect_loop_contexts(called_map, /)
pyop3.index_tree.parse.collect_loop_contexts(index, /)
pyop3.index_tree.parse.collect_loop_contexts(index, /)
pyop3.index_tree.parse.collect_loop_contexts(index, /)
pyop3.index_tree.parse.collect_loop_contexts(index, /)
pyop3.index_tree.parse.collect_loop_contexts(index, /)
pyop3.index_tree.parse.collect_loop_contexts(index, /)
pyop3.index_tree.parse.collect_loop_contexts(index, /)
pyop3.index_tree.parse.collect_loop_contexts(index, /)
pyop3.index_tree.parse.collect_loop_contexts(index, /)
pyop3.index_tree.parse.collect_loop_contexts(seq, /)
pyop3.index_tree.parse.complete_index_tree(index_tree, axes)[source]
pyop3.index_tree.parse.relabel_indices(indices, relabeler)[source]
pyop3.index_tree.parse.relabel_indices(tuple_, relabeler)
pyop3.index_tree.parse.relabel_indices(label, relabeler)
pyop3.index_tree.parse.relabel_indices(label, relabeler)
pyop3.index_tree.parse.relabel_indices(list_, relabeler)
pyop3.index_tree.parse.relabel_indices(slice_, relabeler)

pyop3.index_tree.tree module

class pyop3.index_tree.tree.AbstractCalledMap[source]

Bases: AxisIndependentIndex

property connectivity
property is_context_free
property leaf_target_paths
class pyop3.index_tree.tree.AbstractLoopIndex[source]

Bases: Object

abstractmethod context_free()[source]
property id
class pyop3.index_tree.tree.AbstractMap[source]

Bases: Object

abstractmethod __call__(index, /, **kwargs)[source]
class pyop3.index_tree.tree.AffineSliceComponent(component, start=0, stop=None, step=1, label=DECIDE)[source]

Bases: SliceComponent

Slice component selecting indices of the form a*i + b.

property component
classmethod from_slice(component, slice_)[source]
property is_full_slice
label
record_new(**attrs)

Create and initialise a new record from an existing one.

start
step
stop
with_size(size=None)[source]
class pyop3.index_tree.tree.AxisIndependentIndex[source]

Bases: Index

abstract property axes
property component_labels
class pyop3.index_tree.tree.CalledMap(map, index, *, label=DECIDE)[source]

Bases: AbstractCalledMap

A map that has been called against some index.

It represents the object f(i), where f is a \(Map\) and i some other \(Index\).

property axes[source]
index
iter(*, eager=False)[source]
label
map
record_new(**attrs)

Create and initialise a new record from an existing one.

class pyop3.index_tree.tree.Index[source]

Bases: MultiComponentLabeledNode

class pyop3.index_tree.tree.IndexTree(node_map=None, *, comm=None)[source]

Bases: MutableLabeledTreeMixin, LabeledTree

A tree of indices.

Index trees describe the mapping between axis trees. They are necessary for complex indexing operations like packing multi-field dats (for which simple maps and slices are insufficient).

property comm
classmethod from_iterable(iterable, comm=None)[source]
classmethod from_nest(nest, *, comm=None)[source]
node_map
record_new(**attrs)

Create and initialise a new record from an existing one.

exception pyop3.index_tree.tree.InvalidIterationSetException[source]

Bases: Pyop3Exception

class pyop3.index_tree.tree.LoopContextFreeLoopIndex(iterset, label=None)[source]

Bases: AbstractLoopIndex, UnitIndex

LoopContextFreeLoopIndex(iterset: ‘AbstractNonUnitAxisTree’, label=None) -> ‘None’

collect_buffers(visitor)[source]
property comm
property component_labels
context_free()[source]
dtype = dtype('int32')
get_disk_cache_key(visitor)[source]
get_instruction_executor_cache_key(visitor)
is_context_free = True
iterset
label
property leaf_target_paths

Unlike with maps and slices, loop indices are single-component (so return a 1-tuple) but that component can target differently labelled axes (so the tuple entry is an n-tuple).

record_new(**attrs)

Create and initialise a new record from an existing one.

with_context(context, *args)[source]
class pyop3.index_tree.tree.LoopContextSensitive[source]

Bases: object

Class that looks different depending on the loop index branch.

filter_context(context)[source]
property loop_indices[source]
with_context(context, *, strict=False)[source]
class pyop3.index_tree.tree.LoopIndex(iterset, label=None)[source]

Bases: AbstractLoopIndex

LoopIndex(iterset, label=None)

context_free()[source]
get_instruction_executor_cache_key(visitor)[source]
is_context_free()[source]
iterset
label
record_new(**attrs)

Create and initialise a new record from an existing one.

class pyop3.index_tree.tree.Map(connectivity)[source]

Bases: AbstractMap

A map between indices.

Maps are principly defined by their connectivity attribute, which describes the individual mappings between input and output index types. This must be provided as an iterable of mappings because the map can both map from entirely different indices (e.g. multi-component loops that expand to different context-free indices, think looping over mesh.points) and semantically equivalent indices (e.g. a loop over axes[subset].index() has two possible sets of paths and index expressions and the map may map from one or both of these but the result should be the same, think looping over mesh.cells and mesh.points[cell_subset]). Accordingly, the connectivity argument should provide the different indices as different entries in the iterable, and the equivalent indices as different entries in each mapping.

In fact I think to understand the situation we need to consider the following:

closure(mesh.cells.index()) is hard because mesh.cells is an indexed view of mesh.points, and so the loop index carries information on both about. We can feasibly have closure(point) AND closure(cell) being separately valid mappings and we don’t know which we want until we have a target set of axes to make a choice. We therefore want to propagate both for as long as possible. We could similarly imagine a scenario where closure(cell) yields POINTS, not cells, edges and vertices. That is similar in that we get different axis trees that we want to propagate to the end!

With this in mind, connectivity is therefore the map:

{
    input_index_label: [
        [*possible component outputs],
        [*possible component outputs]
    ]
}

for example, closure gives
{
    points: [
        [points],
    ]
    cells: [
        [cells, edges, vertices],
        [points],
    ]
    edges: [
        [edges, vertices],
        [points],
    ]
    ...
}

As a result, indexing things now gives different axis tree, not just different expressions! Indexing therefore must produce an axis forest.

__call__(index, /, **kwargs)[source]
connectivity
record_new(**attrs)

Create and initialise a new record from an existing one.

class pyop3.index_tree.tree.MapComponent[source]

Bases: Object

property target_path
class pyop3.index_tree.tree.RegionSliceComponent(component, region, *, label=None)[source]

Bases: SliceComponent

A slice component that takes all entries from a particular region.

This class differs from an affine slice in that it ‘consumes’ the region label, and so breaks any recursive cycle where one might have something like \(axes.owned.buffer_slice\) (which accesses \(axes.owned.buffer_slice\)…).

Note that ‘region’ can be a subset of the region label: e.g. “owned” matches {“owned”, “unconstrained”}

property component
property is_full_slice
label
record_new(**attrs)

Create and initialise a new record from an existing one.

region
class pyop3.index_tree.tree.ScalarIndex(axis, component, value, label=DECIDE)[source]

Bases: UnitIndex

ScalarIndex(axis, component, value, label=DECIDE) -> ‘None’

axis
component
property component_labels
label
property leaf_target_paths
record_new(**attrs)

Create and initialise a new record from an existing one.

value
class pyop3.index_tree.tree.ScalarMap(connectivity)[source]

Bases: AbstractMap

An arity 1 map that does not produce an additional axis in the tree.

__call__(index, /, **kwargs)[source]
connectivity

map connectivity. for each input path it can produce multiple equivalent targets (think points vs cells) but never more than one at a time. This differs from other map types where for instance the closure of a cell yields multiple result types.

record_new(**attrs)

Create and initialise a new record from an existing one.

class pyop3.index_tree.tree.Slice(axis, components, *, label=DECIDE)[source]

Bases: Index

A slice can be thought of as a map from a smaller space to the target space.

Like maps it can also target multiple outputs. This is useful for multi-component axes.

axis
property component_labels
components
property expanded
label
property leaf_target_paths[source]
record_new(**attrs)

Create and initialise a new record from an existing one.

restrict(paths)[source]
class pyop3.index_tree.tree.SliceComponent[source]

Bases: LabeledNodeComponent, ABC

abstract property component
abstract property is_full_slice
class pyop3.index_tree.tree.SubsetSliceComponent(component, array, *, label=None)[source]

Bases: SliceComponent

A slice component that maps indices using an array.

array
property component
property is_full_slice
label
record_new(**attrs)

Create and initialise a new record from an existing one.

class pyop3.index_tree.tree.TabulatedMapComponent(target_axis, target_component, array, *, label=DECIDE)[source]

Bases: MapComponent

A map component that maps indices using an array.

arity
array
property data
label
record_new(**attrs)

Create and initialise a new record from an existing one.

target_axis
target_component
class pyop3.index_tree.tree.UnitCalledMap(map, index, *, label=DECIDE)[source]

Bases: UnitIndex, AbstractCalledMap

A called map with a single output.

Compared to a typical \(CalledMap\), unit maps do not produce an axis in the resulting tree.

index
label
map
record_new(**attrs)

Create and initialise a new record from an existing one.

class pyop3.index_tree.tree.UnitIndex[source]

Bases: AxisIndependentIndex

An index with unit shape.

property axes[source]
pyop3.index_tree.tree.has_loop_indices(obj)[source]
pyop3.index_tree.tree.has_loop_indices(itree, /)
pyop3.index_tree.tree.has_loop_indices(idx, /)
pyop3.index_tree.tree.has_loop_indices(idx, /)
pyop3.index_tree.tree.has_loop_indices(tuple_, /)
pyop3.index_tree.tree.has_loop_indices(label, /)
pyop3.index_tree.tree.has_loop_indices(label, /)
pyop3.index_tree.tree.has_loop_indices(list_, /)
pyop3.index_tree.tree.has_loop_indices(scalar, /)
pyop3.index_tree.tree.has_loop_indices(scalar, /)
pyop3.index_tree.tree.has_loop_indices(slice_, /)
pyop3.index_tree.tree.has_loop_indices(slice_, /)

Module contents