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.axis_tree package¶
Subpackages¶
Submodules¶
pyop3.axis_tree.context_sensitive module¶
- class pyop3.axis_tree.context_sensitive.LoopContextSensitiveAxisTreeLike(trees)[source]¶
Bases:
LoopContextAwareAxisTreeLike,LoopContextSensitiveLoopContextSensitiveAxisTreeLike(trees: collections.abc.Mapping)
- property context_map¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- trees¶
pyop3.axis_tree.parse module¶
- pyop3.axis_tree.parse.as_axis(arg)[source]¶
- pyop3.axis_tree.parse.as_axis(axis)
- pyop3.axis_tree.parse.as_axis(component)
- pyop3.axis_tree.parse.as_axis_component(arg)[source]¶
- pyop3.axis_tree.parse.as_axis_component(component)
- pyop3.axis_tree.parse.as_axis_component(arg)
- pyop3.axis_tree.parse.as_axis_forest(arg)[source]¶
- pyop3.axis_tree.parse.as_axis_forest(arg)
- pyop3.axis_tree.parse.as_axis_forest(arg)
- pyop3.axis_tree.parse.as_axis_forest(arg)
- pyop3.axis_tree.parse.as_axis_forest(arg)
- pyop3.axis_tree.parse.as_axis_forest(arg)
- pyop3.axis_tree.parse.as_axis_forest(arg)
- pyop3.axis_tree.parse.as_axis_tree(arg)[source]¶
- pyop3.axis_tree.parse.as_axis_tree(axes_per_context)
- pyop3.axis_tree.parse.as_axis_tree(axes)
- pyop3.axis_tree.parse.as_axis_tree(axes)
- pyop3.axis_tree.parse.as_axis_tree(axes)
- pyop3.axis_tree.parse.as_axis_tree(axes)
- pyop3.axis_tree.parse.as_axis_tree(axes)
- pyop3.axis_tree.parse.as_axis_tree(axis)
- pyop3.axis_tree.parse.as_axis_tree_type(arg)[source]¶
- pyop3.axis_tree.parse.as_axis_tree_type(axis_tree, /)
- pyop3.axis_tree.parse.as_axis_tree_type(axis_tree, /)
- pyop3.axis_tree.parse.as_axis_tree_type(axis_tree, /)
- pyop3.axis_tree.parse.as_axis_tree_type(axis_tree, /)
- pyop3.axis_tree.parse.as_axis_tree_type(axis_tree, /)
- pyop3.axis_tree.parse.collect_unindexed_axis_trees(tree, /)[source]¶
- pyop3.axis_tree.parse.collect_unindexed_axis_trees(axis_tree, /)
- pyop3.axis_tree.parse.collect_unindexed_axis_trees(axis_tree, /)
- pyop3.axis_tree.parse.collect_unindexed_axis_trees(indexed_axis_tree, /)
- pyop3.axis_tree.parse.collect_unindexed_axis_trees(indexed_axis_tree, /)
- pyop3.axis_tree.parse.collect_unindexed_axis_trees(axis_forest, /)
- pyop3.axis_tree.parse.collect_unindexed_axis_trees(cs_axes, /)
pyop3.axis_tree.tree module¶
- class pyop3.axis_tree.tree.AbstractAxisTree[source]¶
Bases:
LoopContextFreeAxisTreeLikeBase class for non-forest axis tree types.
- property trees¶
- class pyop3.axis_tree.tree.AbstractIndexedAxisTree[source]¶
Bases:
LoopContextFreeAxisTreeLikeBase class for axis trees that are indexed.
- class pyop3.axis_tree.tree.AbstractNonUnitAxisTree[source]¶
Bases:
LabeledTree,AbstractAxisTreeBase class for non-unit axis trees.
- property axes¶
- abstract property global_numbering¶
- property global_size[source]¶
This function is logically collective over MPI ranks, it is an error to call it on fewer than all the ranks in MPI communicator. PYOP3_SPMD_STRICT=1 is in your environment and function calls will be guarded by a barrier where possible.
- index(**kwargs)¶
- property is_nested¶
- abstract property layouts¶
- property leaf_axis¶
- property leaf_component¶
- property leaf_subst_layouts¶
- abstract property regionless¶
- abstract property targets¶
- class pyop3.axis_tree.tree.AbstractUnindexedAxisTree[source]¶
Bases:
LoopContextFreeAxisTreeLikeBase class for axis trees that are not indexed.
- property unindexed¶
- class pyop3.axis_tree.tree.AbstractUnitAxisTree[source]¶
Bases:
AbstractAxisTreeBase class for ‘unit’ (1-sized) axis trees.
- block_shape = ()¶
- buffer_size = 1¶
- is_empty = False¶
- is_linear = True¶
- is_nested = False¶
- node_map = immutabledict({immutabledict({}): None})¶
- property owned¶
- region_sets = ()¶
- size = 1¶
- property unconstrained¶
- class pyop3.axis_tree.tree.Axis(components, label=DECIDE)[source]¶
Bases:
LoopContextFreeAxisTreeLike,MultiComponentLabeledNodeAxis(components, label=DECIDE)
- axes(**kwargs)¶
- property block_shape¶
- property component¶
- property component_labels¶
- components¶
- property count¶
Return the total number of entries in the axis across all axis parts. Will fail if axis parts do not have integer counts.
- get_instruction_executor_cache_key(visitor)¶
- property is_linear¶
- property is_nested¶
- label¶
- property local_size¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- property size¶
- property trees¶
- property unindexed¶
- class pyop3.axis_tree.tree.AxisComponent(regions, label=DECIDE, *, sf=None, size=None)[source]¶
Bases:
LabeledNodeComponent- Parameters:
regions (Any) – regions
label (NodeComponentLabelT) – label
sf (AbstractStarForest | None) – sf
size – This is useful if we know a-priori that the region sizes sum to something. For example the number of unconstrained+constrained dofs will always add to 3.
- property count¶
- property flat_region_labels¶
- get_instruction_executor_cache_key(visitor)¶
- property has_non_trivial_regions¶
- label¶
- property rank_equal¶
Return whether or not this axis component has constant size between ranks.
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- property region_labels¶
- regions¶
- sf¶
- class pyop3.axis_tree.tree.AxisComponentRegion(size, label=None)[source]¶
Bases:
ObjectAxisComponentRegion(size, label=None) -> ‘None’
- get_instruction_executor_cache_key(visitor)¶
- label = None¶
- property local_size¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- size¶
- class pyop3.axis_tree.tree.AxisForest(*args, **kwargs)[source]¶
Bases:
LoopContextFreeAxisTreeLikeA collection of equivalent axis trees.
Axis forests are useful to describe circumstances where there are multiple viable axis trees for describing a layout. For instance, one can view the data layout for a function space as a set of DoFs per mesh strata, or as a flat set of nodes. These layouts cannot be transformed between each other and so must coexist.
- property block_shape¶
- property global_size¶
- property is_linear¶
- property is_nested¶
- property local_max_size¶
- property local_size¶
- property nest_labels¶
- property owned¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- property root¶
- property sf¶
- property size¶
- property trees¶
- property unconstrained¶
- class pyop3.axis_tree.tree.AxisTarget(axis, component, expr)[source]¶
Bases:
ObjectTODO.
(this is hard to explain)
- axis¶
- component¶
- expr¶
- get_instruction_executor_cache_key(visitor)¶
- property path¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- property replace_map¶
- class pyop3.axis_tree.tree.AxisTree(node_map=None, *, comm=None, _validate=True)[source]¶
Bases:
MutableLabeledTreeMixin,AbstractUnindexedAxisTree,AbstractNonUnitAxisTreeData layout descriptor.
- Parameters:
node_map (collections.abc.Mapping[pyop3.types.PathT, Axis] | types.NoneType) – Mapping representing the tree of axes. Each key is a path of
Axis,AxisComponentlabel pairs (also a mapping), and each value is theAxisat this point in the tree. Ifnode_mapisNonethen the tree is considered empty (zero-sized).comm (mpi4py.MPI.Comm | types.NoneType) – MPI communicator for the object.
- property comm¶
- get_instruction_executor_cache_key(visitor)¶
- property layout_axes¶
- property layouts2¶
- linearize(path, *, partial=False)[source]¶
Return the axis tree dropping all components not specified in the path.
- partial :
If \(True\) then only linearise using a partial path.
- node_map¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- class pyop3.axis_tree.tree.IndexedAxisTree(node_map, unindexed, *, targets, _validate=True)[source]¶
Bases:
AbstractNonUnitAxisTree,AbstractIndexedAxisTreeAn axis tree that has been indexed.
Indexed axis trees preserve the original axis tree and the expressions that are needed to address the original tree using indices in the current tree.
- blocked(block_shape)[source]¶
Note: this function assumes that the block shape still exists in the tree.
- property comm¶
- property global_numbering¶
- property layouts¶
- linearize(path, *, partial=False)[source]¶
Return the axis tree dropping all components not specified in the path.
- node_map¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- property unindexed¶
- property unique_markers¶
- class pyop3.axis_tree.tree.LoopContextAwareAxisTreeLike[source]¶
Bases:
ObjectBase class for things that look like axis trees or forests.
- abstract property __getitem__¶
- class pyop3.axis_tree.tree.LoopContextFreeAxisTreeLike[source]¶
Bases:
LoopContextAwareAxisTreeLike,AbstractLabeledTreeLikeBase class for axis trees and forests that are independent of loop context.
- abstract property block_shape¶
- property block_size¶
- abstractmethod buffer_size(*, include_ghosts)[source]¶
The number of entries that a buffer built on this axis tree would have.
Since an axis tree may contain degenerate entries (entries that map to the same offsets), this size may be less than the size of the tree itself.
- abstractmethod buffer_slice(*, include_ghosts)[source]¶
Indices of the buffer entries corresponding to this axis tree.
- abstract property is_nested¶
- abstract property owned¶
- abstract property region_sets¶
- abstract property sf¶
- abstract property trees¶
- abstract property unconstrained¶
- abstract property unindexed¶
- pyop3.axis_tree.tree.UNIT_AXIS_TREE = _UnitAxisTree()¶
Placeholder value for an axis tree that is guaranteed to have a single entry.
It is useful when handling scalar indices that ‘consume’ axes because we need a way to express a tree containing a single entry that does not need to be addressed using labels.
- class pyop3.axis_tree.tree.UnitIndexedAxisTree(unindexed, *, targets)[source]¶
Bases:
AbstractUnitAxisTree,AbstractIndexedAxisTreeAn indexed axis tree representing something indexed down to a scalar.
- property leaf_path¶
- property leaf_paths¶
- property leaf_subst_layouts¶
- property leaves¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- property unindexed¶
- class pyop3.axis_tree.tree._UnitAxisTree[source]¶
Bases:
AbstractUnindexedAxisTree,AbstractUnitAxisTreeAn axis tree representing a single value.
The singleton \(UNIT_AXIS_TREE\) should be used.
- buffer_slice = slice(0, 1, 1)¶
- property comm¶
- depth = 1¶
- get_instruction_executor_cache_key(visitor)¶
- leaf_path = immutabledict({})¶
- leaf_paths = (immutabledict({}),)¶
- property leaf_subst_layouts¶
- local_max_size = 1¶
- local_size = 1¶
- nest_indices = ()¶
- node_labels = frozenset({})¶
- node_map = immutabledict({immutabledict({}): None})¶
- nodes = ()¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- sf = StarForest(<petsc4py.PETSc.SF object>, 1)¶
- targets = immutabledict({immutabledict({}): ((),)})¶
- pyop3.axis_tree.tree.axis_tree_is_valid_subset(candidate, target)[source]¶
Return if one axis tree may be ‘overlaid’ on top of another.
We consider an axis tree to be a valid subset if all of its leaf paths have a (unique) matching leaf path in the target tree.
- Parameters:
candidate – The axis tree that may be a subset.
target – The (buffer) axis tree to test against.
- Returns:
Whether
candidateis a valid subset oftarget.- Return type:
- pyop3.axis_tree.tree.full_shape(axes)[source]¶
Augment axes with extra axes from the size expressions.
- pyop3.axis_tree.tree.merge_trees2(tree1, tree2, *, only_unit=False)[source]¶
Merge two axis trees together.
If the second tree has no common axes (share a lable) with the first then it is appended to every leaf of the first tree. Any common axes are skipped.
Case 1:
TODO: show example where axis_a = Axis({“x”: 2, “y”: 2}, “a”) axis_b = Axis({“x”: 2}, “b”) axis_c = Axis({“x”: 2}, “c”) AxisTree.from_nest({axis_a: [axis_b, axis_c]})
is added to axis_a: things should split up.
- Parameters:
only_unit – Whether or not the second tree is allowed to introduce new axes that are not ‘unit’ axes. This option is useful for when one is happy to have extra axes that do not materially affect the output shape.
- pyop3.axis_tree.tree.replace_exprs(treelike, replace_map)[source]¶
- pyop3.axis_tree.tree.replace_exprs(axis, /, replace_map)
- pyop3.axis_tree.tree.replace_exprs(component, /, replace_map)
- pyop3.axis_tree.tree.replace_exprs(region, /, replace_map)
