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, LoopContextSensitive

LoopContextSensitiveAxisTreeLike(trees: collections.abc.Mapping)

__getitem__(indices)[source]
property context_free[source]
property context_map
get_instruction_executor_cache_key(visitor)[source]
index()[source]
record_new(**attrs)

Create and initialise a new record from an existing one.

property sf[source]
trees
property unindexed[source]
pyop3.axis_tree.context_sensitive.iter_axis_trees(obj)[source]
pyop3.axis_tree.context_sensitive.iter_axis_trees(tree)
pyop3.axis_tree.context_sensitive.iter_axis_trees(forest)
pyop3.axis_tree.context_sensitive.iter_axis_trees(cs_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: LoopContextFreeAxisTreeLike

Base class for non-forest axis tree types.

property nest_labels[source]
property trees
class pyop3.axis_tree.tree.AbstractIndexedAxisTree[source]

Bases: LoopContextFreeAxisTreeLike

Base class for axis trees that are indexed.

restrict_nest(nest_label)[source]

Restrict an axis tree to a nested piece of it.

The idea here is to trim orig_axes with index such that we can pretend that the axes always looked truncated in that form.

property sf[source]
class pyop3.axis_tree.tree.AbstractNonUnitAxisTree[source]

Bases: LabeledTree, AbstractAxisTree

Base class for non-unit axis trees.

__getitem__(indices)[source]
as_axis()[source]
as_tree()[source]
property axes
property block_shape[source]
abstractmethod blocked(block_shape)[source]
component_size(path, component_label)[source]
getitem(indices, *, strict=False)[source]
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
iter(*, eager=False)[source]
abstract property layouts
property leaf_axis
property leaf_component
property leaf_subst_layouts
property local_max_size[source]
property local_size[source]
materialize()[source]

Return a new “unindexed” axis tree with the same shape.

property owned[source]

Return the owned portion of the axis tree.

prune()[source]
property pruned[source]
property region_sets[source]
abstract property regionless
abstractmethod section(path, component=<object object>, indices=immutabledict({}))[source]
property size[source]
abstract property targets
template_vec(block_shape)[source]

Dummy PETSc Vec of the right size for this set of axes.

property unconstrained[source]

Return the unconstrained portion of the axis tree.

with_region_label(region_label, *, allow_missing=False)[source]

TODO

with_region_labels(region_labels, *, allow_missing=False)[source]

TODO

class pyop3.axis_tree.tree.AbstractUnindexedAxisTree[source]

Bases: LoopContextFreeAxisTreeLike

Base class for axis trees that are not indexed.

property unindexed
class pyop3.axis_tree.tree.AbstractUnitAxisTree[source]

Bases: AbstractAxisTree

Base class for ‘unit’ (1-sized) axis trees.

__getitem__(indices)[source]
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
with_region_labels(*args, **kwargs)[source]
class pyop3.axis_tree.tree.Axis(components, label=DECIDE)[source]

Bases: LoopContextFreeAxisTreeLike, MultiComponentLabeledNode

Axis(components, label=DECIDE)

__call__(*args)[source]
__getitem__(indices)[source]
as_tree()[source]

Convert the axis to a tree that contains it.

axes(**kwargs)
property block_shape
buffer_size(**kwargs)[source]
buffer_slice(**kwargs)[source]
collect_buffers(visitor)[source]
property component
component_index(component)[source]
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_disk_cache_key(visitor)[source]
get_instruction_executor_cache_key(visitor)
property is_linear
property is_nested
iter(**kwargs)[source]
label
linearize(component_label)[source]
property local_size
localize()[source]
matching_component(component_label)[source]
property owned[source]
record_new(**attrs)

Create and initialise a new record from an existing one.

property region_sets[source]
regionless()[source]
property sf[source]
property size
property trees
property unconstrained[source]
property unindexed
with_region_labels(*args, **kwargs)[source]
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.

collect_buffers(visitor)[source]
property count
property flat_region_labels
get_disk_cache_key(visitor)[source]
get_instruction_executor_cache_key(visitor)
property has_non_trivial_regions
label
property local_max_size[source]
property local_size[source]
localize()[source]
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
regionless()[source]
regions
sf
property size[source]
class pyop3.axis_tree.tree.AxisComponentRegion(size, label=None)[source]

Bases: Object

AxisComponentRegion(size, label=None) -> ‘None’

collect_buffers(visitor)[source]
property comm[source]
get_disk_cache_key(visitor)[source]
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: LoopContextFreeAxisTreeLike

A 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.

__getitem__(indices)[source]
property block_shape
blocked(block_shape)[source]
buffer_size(**kwargs)[source]
buffer_slice(**kwargs)[source]
get_instruction_executor_cache_key(visitor)[source]
getitem(indices, *, strict=False)[source]
property global_numbering[source]
property global_size
property is_linear
property is_nested
property local_max_size
property local_size
localize()[source]
materialize()[source]
property nest_labels
property owned
prune()[source]
record_new(**attrs)

Create and initialise a new record from an existing one.

property region_sets[source]
regionless()[source]
restrict_nest(index)[source]
property root
property sf
property size
template_vec(block_shape)[source]
property trees
property unconstrained
property unindexed[source]
with_context(context)[source]
with_region_labels(labels, **kwargs)[source]
class pyop3.axis_tree.tree.AxisTarget(axis, component, expr)[source]

Bases: Object

TODO.

(this is hard to explain)

axis
collect_buffers(visitor)[source]
component
expr
get_disk_cache_key(visitor)[source]
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, AbstractNonUnitAxisTree

Data layout descriptor.

Parameters:
add_axis(path, axis)[source]
append_axis(axis)[source]
blocked(block_shape)[source]
buffer_size(*, include_ghosts)[source]
buffer_slice(*, include_ghosts)[source]
collect_buffers(visitor)[source]
property comm
classmethod from_iterable(iterable, comm=None)[source]
classmethod from_nest(nest, *, comm=None)[source]
get_disk_cache_key(visitor)[source]
get_instruction_executor_cache_key(visitor)
property global_numbering[source]
property layout_axes
property layouts[source]
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.

localize()[source]
node_map
record_new(**attrs)

Create and initialise a new record from an existing one.

regionless()[source]
section(path, component=<object object>, indices=immutabledict({}))[source]
property sf[source]
property targets[source]
class pyop3.axis_tree.tree.EquivalentAxisTargetSet(iterable=(), /)[source]

Bases: tuple

class pyop3.axis_tree.tree.IndexedAxisTree(node_map, unindexed, *, targets, _validate=True)[source]

Bases: AbstractNonUnitAxisTree, AbstractIndexedAxisTree

An 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.

buffer_size(*, include_ghosts)[source]
buffer_slice(*, include_ghosts)[source]
collect_buffers(visitor)[source]
property comm
get_disk_cache_key(visitor)[source]
get_instruction_executor_cache_key(visitor)[source]
property global_numbering
property layouts
property layouts2[source]
linearize(path, *, partial=False)[source]

Return the axis tree dropping all components not specified in the path.

localize()[source]
materialize()[source]

Return a new “unindexed” axis tree with the same shape.

node_map
record_new(**attrs)

Create and initialise a new record from an existing one.

regionless()[source]
section(path, component=<object object>, indices=immutabledict({}))[source]
property targets[source]
property unindexed
property unique_markers
class pyop3.axis_tree.tree.LoopContextAwareAxisTreeLike[source]

Bases: Object

Base class for things that look like axis trees or forests.

abstract property __getitem__
class pyop3.axis_tree.tree.LoopContextFreeAxisTreeLike[source]

Bases: LoopContextAwareAxisTreeLike, AbstractLabeledTreeLike

Base 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.

property free[source]
abstract property is_nested
abstract property owned
abstract property region_sets
abstract property sf
abstract property trees
abstract property unconstrained
abstract property unindexed
abstractmethod with_region_labels(*args, **kwargs)[source]
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, AbstractIndexedAxisTree

An indexed axis tree representing something indexed down to a scalar.

as_axis()[source]
buffer_slice(**kwargs)[source]
get_instruction_executor_cache_key(visitor)[source]
getitem(indices, *, strict=False)[source]
property layouts2[source]
property leaf_path
property leaf_paths
property leaf_subst_layouts
property leaves
localize()[source]
materialize()[source]
path_with_nodes(leaf)[source]
record_new(**attrs)

Create and initialise a new record from an existing one.

regionless()[source]
property targets[source]
property unindexed
with_context(context)[source]
class pyop3.axis_tree.tree._UnitAxisTree[source]

Bases: AbstractUnindexedAxisTree, AbstractUnitAxisTree

An axis tree representing a single value.

The singleton \(UNIT_AXIS_TREE\) should be used.

add_axis(path, axis)[source]
add_subtree(path, subtree)[source]
buffer_slice = slice(0, 1, 1)
collect_buffers(visitor)[source]
property comm
depth = 1
get_disk_cache_key(visitor)[source]
get_instruction_executor_cache_key(visitor)
index()[source]
property layouts2[source]
leaf_path = immutabledict({})
leaf_paths = (immutabledict({}),)
property leaf_subst_layouts
linearize(path)[source]
local_max_size = 1
local_size = 1
localize()[source]
materialize()[source]
nest_indices = ()
node_labels = frozenset({})
node_map = immutabledict({immutabledict({}): None})
nodes = ()
path_with_nodes(node)[source]
prune()[source]
record_new(**attrs)

Create and initialise a new record from an existing one.

regionless()[source]
sf = StarForest(<petsc4py.PETSc.SF object>, 1)
targets = immutabledict({immutabledict({}): ((),)})
with_context(*args, **kwargs)[source]
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 candidate is a valid subset of target.

Return type:

bool

pyop3.axis_tree.tree.complete_axis_targets(targets)[source]
pyop3.axis_tree.tree.full_shape(axes)[source]

Augment axes with extra axes from the size expressions.

pyop3.axis_tree.tree.gather_loop_indices_from_targets(targets)[source]
pyop3.axis_tree.tree.inner_loop_indices(axes, targets, path)[source]
pyop3.axis_tree.tree.loopify_axis_tree(axis_tree)[source]
pyop3.axis_tree.tree.match_target(source_axes, target_axes, target_set)[source]
pyop3.axis_tree.tree.matching_axis_tree(candidate, target)[source]
pyop3.axis_tree.tree.merge_axis_trees(trees, *, only_unit=False)[source]
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.prune_zero_sized_branches(axis_tree, *, path=immutabledict({}))[source]
pyop3.axis_tree.tree.relabel_path(path, suffix)[source]
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)
pyop3.axis_tree.tree.subst_layouts(axes, targets, layouts, *, path=immutabledict({}), target_paths_and_exprs_acc=None, loop_vars=frozenset({}))[source]
pyop3.axis_tree.tree.trim_axis_targets(targets, to_trim)[source]

Module contents