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¶
- pyop3.index_tree.apply.collect_leaf_targets(axes)[source]¶
- Returns:
An iterable of generators, one per leaf.
- Return type:
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.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.parse module¶
- exception pyop3.index_tree.parse.IncompletelyIndexedException[source]¶
Bases:
Pyop3ExceptionException raised when an axis tree is incompletely indexed by an index tree/forest.
- 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:
- 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:
- 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.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.AffineSliceComponent(component, start=0, stop=None, step=1, label=DECIDE)[source]¶
Bases:
SliceComponentSlice component selecting indices of the form
a*i + b.- property component¶
- property is_full_slice¶
- label¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- start¶
- step¶
- stop¶
- 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:
AbstractCalledMapA map that has been called against some index.
It represents the object f(i), where f is a \(Map\) and i some other \(Index\).
- index¶
- 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,LabeledTreeA 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¶
- 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,UnitIndexLoopContextFreeLoopIndex(iterset: ‘AbstractNonUnitAxisTree’, label=None) -> ‘None’
- property comm¶
- property component_labels¶
- dtype = dtype('int32')¶
- 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.
- class pyop3.index_tree.tree.LoopContextSensitive[source]¶
Bases:
objectClass that looks different depending on the loop index branch.
- class pyop3.index_tree.tree.LoopIndex(iterset, label=None)[source]¶
Bases:
AbstractLoopIndexLoopIndex(iterset, label=None)
- iterset¶
- label¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- class pyop3.index_tree.tree.Map(connectivity)[source]¶
Bases:
AbstractMapA map between indices.
Maps are principly defined by their
connectivityattribute, 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 overaxes[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, theconnectivityargument 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.
- connectivity¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- class pyop3.index_tree.tree.RegionSliceComponent(component, region, *, label=None)[source]¶
Bases:
SliceComponentA 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:
UnitIndexScalarIndex(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:
AbstractMapAn arity 1 map that does not produce an additional axis in the tree.
- 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:
IndexA 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¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- 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:
SliceComponentA 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:
MapComponentA 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,AbstractCalledMapA 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:
AxisIndependentIndexAn index with unit shape.
- 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_, /)
