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 package¶
Subpackages¶
- pyop3.axis_tree package
- Subpackages
- Submodules
- pyop3.axis_tree.context_sensitive module
LoopContextSensitiveAxisTreeLikeLoopContextSensitiveAxisTreeLike.__getitem__()LoopContextSensitiveAxisTreeLike.context_freeLoopContextSensitiveAxisTreeLike.context_mapLoopContextSensitiveAxisTreeLike.get_instruction_executor_cache_key()LoopContextSensitiveAxisTreeLike.index()LoopContextSensitiveAxisTreeLike.record_new()LoopContextSensitiveAxisTreeLike.sfLoopContextSensitiveAxisTreeLike.treesLoopContextSensitiveAxisTreeLike.unindexed
iter_axis_trees()
- pyop3.axis_tree.parse module
- pyop3.axis_tree.tree module
AbstractAxisTreeAbstractIndexedAxisTreeAbstractNonUnitAxisTreeAbstractNonUnitAxisTree.__getitem__()AbstractNonUnitAxisTree.as_axis()AbstractNonUnitAxisTree.as_tree()AbstractNonUnitAxisTree.axesAbstractNonUnitAxisTree.block_shapeAbstractNonUnitAxisTree.blocked()AbstractNonUnitAxisTree.component_size()AbstractNonUnitAxisTree.getitem()AbstractNonUnitAxisTree.global_numberingAbstractNonUnitAxisTree.global_sizeAbstractNonUnitAxisTree.index()AbstractNonUnitAxisTree.is_nestedAbstractNonUnitAxisTree.iter()AbstractNonUnitAxisTree.layoutsAbstractNonUnitAxisTree.leaf_axisAbstractNonUnitAxisTree.leaf_componentAbstractNonUnitAxisTree.leaf_subst_layoutsAbstractNonUnitAxisTree.local_max_sizeAbstractNonUnitAxisTree.local_sizeAbstractNonUnitAxisTree.materialize()AbstractNonUnitAxisTree.ownedAbstractNonUnitAxisTree.prune()AbstractNonUnitAxisTree.prunedAbstractNonUnitAxisTree.region_setsAbstractNonUnitAxisTree.regionlessAbstractNonUnitAxisTree.section()AbstractNonUnitAxisTree.sizeAbstractNonUnitAxisTree.targetsAbstractNonUnitAxisTree.template_vec()AbstractNonUnitAxisTree.unconstrainedAbstractNonUnitAxisTree.with_region_label()AbstractNonUnitAxisTree.with_region_labels()
AbstractUnindexedAxisTreeAbstractUnitAxisTreeAbstractUnitAxisTree.__getitem__()AbstractUnitAxisTree.block_shapeAbstractUnitAxisTree.buffer_sizeAbstractUnitAxisTree.is_emptyAbstractUnitAxisTree.is_linearAbstractUnitAxisTree.is_nestedAbstractUnitAxisTree.node_mapAbstractUnitAxisTree.ownedAbstractUnitAxisTree.region_setsAbstractUnitAxisTree.sizeAbstractUnitAxisTree.unconstrainedAbstractUnitAxisTree.with_region_labels()
AxisAxis.__call__()Axis.__getitem__()Axis.as_tree()Axis.axes()Axis.block_shapeAxis.buffer_size()Axis.buffer_slice()Axis.collect_buffers()Axis.componentAxis.component_index()Axis.component_labelsAxis.componentsAxis.countAxis.get_disk_cache_key()Axis.get_instruction_executor_cache_key()Axis.is_linearAxis.is_nestedAxis.iter()Axis.labelAxis.linearize()Axis.local_sizeAxis.localize()Axis.matching_component()Axis.ownedAxis.record_new()Axis.region_setsAxis.regionless()Axis.sfAxis.sizeAxis.treesAxis.unconstrainedAxis.unindexedAxis.with_region_labels()
AxisComponentAxisComponent.collect_buffers()AxisComponent.countAxisComponent.flat_region_labelsAxisComponent.get_disk_cache_key()AxisComponent.get_instruction_executor_cache_key()AxisComponent.has_non_trivial_regionsAxisComponent.labelAxisComponent.local_max_sizeAxisComponent.local_sizeAxisComponent.localize()AxisComponent.rank_equalAxisComponent.record_new()AxisComponent.region_labelsAxisComponent.regionless()AxisComponent.regionsAxisComponent.sfAxisComponent.size
AxisComponentRegionAxisForestAxisForest.__getitem__()AxisForest.block_shapeAxisForest.blocked()AxisForest.buffer_size()AxisForest.buffer_slice()AxisForest.get_instruction_executor_cache_key()AxisForest.getitem()AxisForest.global_numberingAxisForest.global_sizeAxisForest.is_linearAxisForest.is_nestedAxisForest.local_max_sizeAxisForest.local_sizeAxisForest.localize()AxisForest.materialize()AxisForest.nest_labelsAxisForest.ownedAxisForest.prune()AxisForest.record_new()AxisForest.region_setsAxisForest.regionless()AxisForest.restrict_nest()AxisForest.rootAxisForest.sfAxisForest.sizeAxisForest.template_vec()AxisForest.treesAxisForest.unconstrainedAxisForest.unindexedAxisForest.with_context()AxisForest.with_region_labels()
AxisTargetAxisTreeAxisTree.add_axis()AxisTree.append_axis()AxisTree.blocked()AxisTree.buffer_size()AxisTree.buffer_slice()AxisTree.collect_buffers()AxisTree.commAxisTree.from_iterable()AxisTree.from_nest()AxisTree.get_disk_cache_key()AxisTree.get_instruction_executor_cache_key()AxisTree.global_numberingAxisTree.layout_axesAxisTree.layoutsAxisTree.layouts2AxisTree.linearize()AxisTree.localize()AxisTree.node_mapAxisTree.record_new()AxisTree.regionless()AxisTree.section()AxisTree.sfAxisTree.targets
EquivalentAxisTargetSetIndexedAxisTreeIndexedAxisTree.blocked()IndexedAxisTree.buffer_size()IndexedAxisTree.buffer_slice()IndexedAxisTree.collect_buffers()IndexedAxisTree.commIndexedAxisTree.get_disk_cache_key()IndexedAxisTree.get_instruction_executor_cache_key()IndexedAxisTree.global_numberingIndexedAxisTree.layoutsIndexedAxisTree.layouts2IndexedAxisTree.linearize()IndexedAxisTree.localize()IndexedAxisTree.materialize()IndexedAxisTree.node_mapIndexedAxisTree.record_new()IndexedAxisTree.regionless()IndexedAxisTree.section()IndexedAxisTree.targetsIndexedAxisTree.unindexedIndexedAxisTree.unique_markers
LoopContextAwareAxisTreeLikeLoopContextFreeAxisTreeLikeLoopContextFreeAxisTreeLike.block_shapeLoopContextFreeAxisTreeLike.block_sizeLoopContextFreeAxisTreeLike.buffer_size()LoopContextFreeAxisTreeLike.buffer_slice()LoopContextFreeAxisTreeLike.freeLoopContextFreeAxisTreeLike.is_nestedLoopContextFreeAxisTreeLike.ownedLoopContextFreeAxisTreeLike.region_setsLoopContextFreeAxisTreeLike.sfLoopContextFreeAxisTreeLike.treesLoopContextFreeAxisTreeLike.unconstrainedLoopContextFreeAxisTreeLike.unindexedLoopContextFreeAxisTreeLike.with_region_labels()
UNIT_AXIS_TREEUnitIndexedAxisTreeUnitIndexedAxisTree.as_axis()UnitIndexedAxisTree.buffer_slice()UnitIndexedAxisTree.get_instruction_executor_cache_key()UnitIndexedAxisTree.getitem()UnitIndexedAxisTree.layouts2UnitIndexedAxisTree.leaf_pathUnitIndexedAxisTree.leaf_pathsUnitIndexedAxisTree.leaf_subst_layoutsUnitIndexedAxisTree.leavesUnitIndexedAxisTree.localize()UnitIndexedAxisTree.materialize()UnitIndexedAxisTree.path_with_nodes()UnitIndexedAxisTree.record_new()UnitIndexedAxisTree.regionless()UnitIndexedAxisTree.targetsUnitIndexedAxisTree.unindexedUnitIndexedAxisTree.with_context()
_UnitAxisTree_UnitAxisTree.add_axis()_UnitAxisTree.add_subtree()_UnitAxisTree.buffer_slice_UnitAxisTree.collect_buffers()_UnitAxisTree.comm_UnitAxisTree.depth_UnitAxisTree.get_disk_cache_key()_UnitAxisTree.get_instruction_executor_cache_key()_UnitAxisTree.index()_UnitAxisTree.layouts2_UnitAxisTree.leaf_path_UnitAxisTree.leaf_paths_UnitAxisTree.leaf_subst_layouts_UnitAxisTree.linearize()_UnitAxisTree.local_max_size_UnitAxisTree.local_size_UnitAxisTree.localize()_UnitAxisTree.materialize()_UnitAxisTree.nest_indices_UnitAxisTree.node_labels_UnitAxisTree.node_map_UnitAxisTree.nodes_UnitAxisTree.path_with_nodes()_UnitAxisTree.prune()_UnitAxisTree.record_new()_UnitAxisTree.regionless()_UnitAxisTree.sf_UnitAxisTree.targets_UnitAxisTree.with_context()
axis_tree_is_valid_subset()complete_axis_targets()full_shape()gather_loop_indices_from_targets()inner_loop_indices()loopify_axis_tree()match_target()matching_axis_tree()merge_axis_trees()merge_trees2()prune_zero_sized_branches()relabel_path()replace_exprs()subst_layouts()trim_axis_targets()
- Module contents
- pyop3.compile package
- Submodules
- pyop3.compile.context module
CodegenContextCodegenContext.add_assignment()CodegenContext.add_buffer()CodegenContext.add_domain()CodegenContext.add_function_call()CodegenContext.add_leaf_assignment()CodegenContext.add_subkernel()CodegenContext.argumentsCodegenContext.domainsCodegenContext.instructionsCodegenContext.lower_buffer_access()CodegenContext.lower_expr()CodegenContext.register_extent()CodegenContext.set_temporary_shapes()CodegenContext.subkernelsCodegenContext.unique_name()CodegenContext.var()
- pyop3.compile.core module
- pyop3.compile.loopy module
INVCallableLACallableLoopyCodegenContextLoopyCodegenContext.add_assignment()LoopyCodegenContext.add_buffer()LoopyCodegenContext.add_cinstruction()LoopyCodegenContext.add_domain()LoopyCodegenContext.add_function_call()LoopyCodegenContext.add_leaf_assignment()LoopyCodegenContext.add_opaque()LoopyCodegenContext.add_subkernel()LoopyCodegenContext.add_temporary()LoopyCodegenContext.argumentsLoopyCodegenContext.domainsLoopyCodegenContext.finalize_kernel()LoopyCodegenContext.instructionsLoopyCodegenContext.lower_buffer_access()LoopyCodegenContext.lower_expr()LoopyCodegenContext.maybe_multiindex()LoopyCodegenContext.register_extent()LoopyCodegenContext.set_temporary_shapes()LoopyCodegenContext.subkernelsLoopyCodegenContext.var()LoopyCodegenContext.within_inames()
SolveCallable
- pyop3.compile.transform module
- Module contents
- pyop3.expr package
- Subpackages
- Submodules
- pyop3.expr.base module
AbsAddAxisVarBinaryOperatorComparisonConditionalDivExpressionFloorDivGreaterThanGreaterThanOrEqualLessThanLessThanOrEqualLoopIndexVarModuloMulNaNNameVarNamedTerminalExpressionNegOperatorOrPowSubTerminalExpressionTernaryOperatorTernaryOperator.aTernaryOperator.bTernaryOperator.cTernaryOperator.child_attrsTernaryOperator.collect_buffers()TernaryOperator.dtypeTernaryOperator.get_disk_cache_key()TernaryOperator.get_instruction_executor_cache_key()TernaryOperator.operandsTernaryOperator.record_new()TernaryOperator.with_operands()
UnaryOperatorUnaryOperator.aUnaryOperator.child_attrsUnaryOperator.collect_buffers()UnaryOperator.dtypeUnaryOperator.get_disk_cache_key()UnaryOperator.get_instruction_executor_cache_key()UnaryOperator.operandUnaryOperator.operandsUnaryOperator.record_new()UnaryOperator.symbolUnaryOperator.with_operands()
as_str()conditional()get_loop_tree()loopified_shape()
- pyop3.expr.buffer module
BufferExpressionDatBufferExpressionLinearBufferExpressionLinearDatBufferExpressionLinearDatBufferExpression.buffer_viewLinearDatBufferExpression.child_attrsLinearDatBufferExpression.collect_buffers()LinearDatBufferExpression.commLinearDatBufferExpression.concretize()LinearDatBufferExpression.get_disk_cache_key()LinearDatBufferExpression.get_instruction_executor_cache_key()LinearDatBufferExpression.layoutLinearDatBufferExpression.local_maxLinearDatBufferExpression.local_minLinearDatBufferExpression.record_new()
MatArrayBufferExpressionMatArrayBufferExpression.buffer_viewMatArrayBufferExpression.child_attrsMatArrayBufferExpression.collect_buffers()MatArrayBufferExpression.column_layoutsMatArrayBufferExpression.get_disk_cache_key()MatArrayBufferExpression.local_maxMatArrayBufferExpression.local_minMatArrayBufferExpression.record_new()MatArrayBufferExpression.row_layouts
MatBufferExpressionMatPetscMatBufferExpressionMatPetscMatBufferExpression.buffer_viewMatPetscMatBufferExpression.child_attrsMatPetscMatBufferExpression.collect_buffers()MatPetscMatBufferExpression.column_layoutMatPetscMatBufferExpression.get_disk_cache_key()MatPetscMatBufferExpression.local_maxMatPetscMatBufferExpression.local_minMatPetscMatBufferExpression.record_new()MatPetscMatBufferExpression.row_layout
NonlinearBufferExpressionNonlinearDatBufferExpressionNonlinearDatBufferExpression.buffer_viewNonlinearDatBufferExpression.child_attrsNonlinearDatBufferExpression.collect_buffers()NonlinearDatBufferExpression.commNonlinearDatBufferExpression.get_disk_cache_key()NonlinearDatBufferExpression.layoutsNonlinearDatBufferExpression.leaf_layoutsNonlinearDatBufferExpression.linearize()NonlinearDatBufferExpression.local_maxNonlinearDatBufferExpression.local_minNonlinearDatBufferExpression.record_new()
ScalarBufferExpressionScalarBufferExpression.buffer_viewScalarBufferExpression.child_attrsScalarBufferExpression.collect_buffers()ScalarBufferExpression.get_disk_cache_key()ScalarBufferExpression.get_instruction_executor_cache_key()ScalarBufferExpression.local_maxScalarBufferExpression.local_minScalarBufferExpression.record_new()ScalarBufferExpression.value
as_linear_buffer_expression()
- pyop3.expr.opaque module
OpaqueTerminalOpaqueTerminal.DEFAULT_PREFIXOpaqueTerminal.bufferOpaqueTerminal.buffer_viewOpaqueTerminal.collect_buffers()OpaqueTerminal.commOpaqueTerminal.get_disk_cache_key()OpaqueTerminal.get_instruction_executor_cache_key()OpaqueTerminal.nameOpaqueTerminal.nest_indicesOpaqueTerminal.record_new()OpaqueTerminal.with_context()
- Module contents
- pyop3.index_tree package
- Submodules
- pyop3.index_tree.apply module
- pyop3.index_tree.parse module
- pyop3.index_tree.tree module
AbstractCalledMapAbstractLoopIndexAbstractMapAffineSliceComponentAxisIndependentIndexCalledMapIndexIndexTreeInvalidIterationSetExceptionLoopContextFreeLoopIndexLoopContextFreeLoopIndex.collect_buffers()LoopContextFreeLoopIndex.commLoopContextFreeLoopIndex.component_labelsLoopContextFreeLoopIndex.context_free()LoopContextFreeLoopIndex.dtypeLoopContextFreeLoopIndex.get_disk_cache_key()LoopContextFreeLoopIndex.get_instruction_executor_cache_key()LoopContextFreeLoopIndex.is_context_freeLoopContextFreeLoopIndex.itersetLoopContextFreeLoopIndex.labelLoopContextFreeLoopIndex.leaf_target_pathsLoopContextFreeLoopIndex.record_new()LoopContextFreeLoopIndex.with_context()
LoopContextSensitiveLoopIndexMapMapComponentRegionSliceComponentScalarIndexScalarMapSliceSliceComponentSubsetSliceComponentTabulatedMapComponentUnitCalledMapUnitIndexhas_loop_indices()
- Module contents
- pyop3.insn package
- Submodules
- pyop3.insn.base module
AbstractAssignmentAbstractAssignmentLikeAbstractCalledFunctionAbstractCalledFunction.argspecAbstractCalledFunction.argument_intentsAbstractCalledFunction.argument_shapesAbstractCalledFunction.axis_treesAbstractCalledFunction.compiler_optionsAbstractCalledFunction.function_argumentsAbstractCalledFunction.nameAbstractCalledFunction.shapeAbstractCalledFunction.with_arguments()
ArgumentSpecArrayAccessTypeAssignmentAssignmentTypeCalledFunctionExscanFunctionFunctionArgumentInstructionInstructionListIntentMismatchErrorKernelArgumentLoopNonEmptyArrayAssignmentNonEmptyArrayAssignment.assigneeNonEmptyArrayAssignment.assignment_typeNonEmptyArrayAssignment.axis_treesNonEmptyArrayAssignment.collect_buffers()NonEmptyArrayAssignment.commNonEmptyArrayAssignment.expressionNonEmptyArrayAssignment.get_disk_cache_key()NonEmptyArrayAssignment.record_new()NonEmptyArrayAssignment.with_arguments()
NonEmptyTerminalNonTerminalInstructionNullInstructionStandaloneCalledFunctionTerminalInstructionUnprocessedExpressionExceptionassignment_type_as_intent()enlist()exscan()filter_null()fix_intents()loop_()maybe_enlist()non_null()
- pyop3.insn.exec module
CompiledCodeExecutorCompilerParametersExecutableInstructionExecutionContextInstructionExecutionContext.__call__()InstructionExecutionContext.commInstructionExecutionContext.compile()InstructionExecutionContext.disk_cache_keyInstructionExecutionContext.named_terminal_buffer_intentsInstructionExecutionContext.preprocess()InstructionExecutionContext.preprocessed_buffersInstructionExecutionContext.root_insn
META_COMPILER_PARAMETERSParsedCompilerParameterscast_loopy_arg_to_ctypes_type()parse_compiler_parameters()
- pyop3.insn.visitors module
- Module contents
- pyop3.visitors package
- Submodules
- pyop3.visitors.base module
- pyop3.visitors.comm module
- pyop3.visitors.compress_indirections module
- pyop3.visitors.concretize module
- pyop3.visitors.identity module
- pyop3.visitors.relabel module
- pyop3.visitors.replace module
- Module contents
Submodules¶
pyop3.arrayref module¶
pyop3.buffer module¶
- class pyop3.buffer.AbstractArrayBuffer[source]¶
Bases:
AbstractBuffer- abstract property ordered¶
- abstract property shape¶
- property size¶
- class pyop3.buffer.AbstractBuffer[source]¶
Bases:
Object- DEFAULT_DTYPE = dtype('float64')¶
- DEFAULT_PREFIX = 'buffer'¶
- abstract property dtype¶
- abstract property name¶
- class pyop3.buffer.ArrayBuffer(data, sf=None, *, name=None, prefix=None, constant=False, rank_equal=False, ordered=False)[source]¶
Bases:
AbstractArrayBuffer,ConcreteBufferA buffer whose underlying data structure is a lazily-evaluated NumPy/CuPy array.
- Parameters:
data – Note that the arrays passed here should be unique to this array. Do not use the same array between buffers as it will disrupt the state tracking done by the buffer.
- DEFAULT_PREFIX = 'array'¶
- broadcast_roots_to_leaves()[source]¶
Unconditionally update leaves.
This will overwrite any existing parallel state tracking.
- property comm¶
- property constant¶
- property data_ro¶
- property data_rw¶
- property data_wo¶
Have to be careful. If not setting all values (i.e. subsets) should call \(reduce_leaves_to_roots\) first.
When this is called we set roots_valid, claiming that any (lazy) ‘in-flight’ writes can be dropped.
- property dtype¶
- property is_frozen¶
- is_nested = False¶
- property name¶
- property ordered¶
- property rank_equal¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- reduce_leaves_to_roots(op)[source]¶
Unconditionally update roots.
This will overwrite any existing parallel state tracking.
- Parameters:
op – The MPI reduction operation to apply when pulling leaves onto roots.
- sf¶
- property shape¶
- property state¶
- class pyop3.buffer.ConcreteBuffer[source]¶
Bases:
AbstractBufferAbstract class representing buffers that carry actual data.
- abstract property constant¶
- abstract property state¶
Counter used to keep track of modifications.
- class pyop3.buffer.DenseBlockPythonMatContext(buffer)[source]¶
Bases:
DensePythonMatContext- property sizes¶
- class pyop3.buffer.DenseColumnPythonMatContext(buffer)[source]¶
Bases:
DensePythonMatContext- property sizes¶
- class pyop3.buffer.DensePythonMatContext(buffer)[source]¶
Bases:
objectMatrix context for storing narrow and dense (usually Nx1 or 1xN) matrices as PETSc Vecs.
This is important in massively parallel settings where a single dense row would live on a single process and hence be a significant performance bottleneck.
- property comm¶
- property data_ro¶
- class pyop3.buffer.DenseRowPythonMatContext(buffer)[source]¶
Bases:
DensePythonMatContext- property sizes¶
- class pyop3.buffer.IndexedBuffer(buffer, nest_indices)[source]¶
Bases:
ObjectClass collecting buffer and nest information.
This class is important during code generation because we want to emit code that matches the wrapped, non-nested types, but we still want to be able to refer to the actual buffer data structure.
- buffer¶
- property denested¶
- get_instruction_executor_cache_key(visitor)¶
- property handle¶
Return the underlying data structure.
This method will introspect the buffer and pull out the object needed by the compiler/executor.
- property name¶
- nest_indices¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- class pyop3.buffer.MonolithicPetscMatBufferSpec(mat_type, row_spec, column_spec)[source]¶
Bases:
PetscMatBufferSpecMonolithicPetscMatBufferSpec(mat_type: ‘str’, row_spec: ‘PetscMatAxisSpec | pyop3.axis_tree.AbstractAxisTree’, column_spec: ‘PetscMatAxisSpec | pyop3.axis_tree.AbstractAxisTree’)
- column_spec¶
- property comm¶
- mat_type¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- row_spec¶
- class pyop3.buffer.MonolithicPetscMatInitBufferSpec(mat_type, block_shape=((), ()))[source]¶
Bases:
PetscMatInitBufferSpecMonolithicPetscMatInitBufferSpec(mat_type: ‘str’, block_shape: ‘tuple[tuple[int, …], tuple[int, …]]’ = ((), ()))
- block_shape = ((), ())¶
- mat_type¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- class pyop3.buffer.NestedPetscMatBufferSpec(submat_specs)[source]¶
Bases:
PetscMatBufferSpecNestedPetscMatBufferSpec(submat_specs: ‘np.ndarray’)
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- property shape¶
- submat_specs¶
- class pyop3.buffer.NestedPetscMatInitBufferSpec(submat_specs)[source]¶
Bases:
PetscMatInitBufferSpecNestedPetscMatInitBufferSpec(submat_specs: ‘np.ndarray’)
- mat_type = 'nest'¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- submat_specs¶
- class pyop3.buffer.NullBuffer(shape, dtype=None, *, name=None, prefix=None, ordered=False)[source]¶
Bases:
AbstractArrayBufferA buffer that does not carry data.
This is useful for handling temporaries when we generate code. For much of the compilation we want to treat temporaries like ordinary arrays but they are not passed as kernel arguments nor do they have any parallel semantics.
- DEFAULT_PREFIX = 'tmp'¶
- property comm¶
- property dtype¶
- property name¶
- property ordered¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- property shape¶
- class pyop3.buffer.PetscMatAxisSpec(size, lgmap, block_shape=())[source]¶
Bases:
ObjectPetscMatAxisSpec(size: ‘int’, lgmap: ‘PETSc.LGMap’, block_shape: ‘tuple[int, …]’ = ())
- block_shape = ()¶
- property block_size¶
- lgmap¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- size¶
- class pyop3.buffer.PetscMatBuffer(mat, *, comm, mat_spec=None, name=None, prefix=None, constant=False)[source]¶
Bases:
ConcreteBufferA buffer whose underlying data structure is a PETSc Mat.
- Parameters:
mat_spec (pyop3.buffer.PetscMatBufferSpec | None) – Only used for preallocation matrices… and actually the only real information is the matrix type, which could be an argument to materialize…
- DEFAULT_PREFIX = 'petscmat'¶
- property comm¶
- property constant¶
- dtype = dtype('float64')¶
- property insert_mode¶
- property is_nested¶
- property mat¶
- mat_spec¶
- property mat_type¶
- property name¶
- rank_equal = False¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- property state¶
- class pyop3.buffer.PetscMatBufferSpec[source]¶
Bases:
ObjectA complete specification of how to build a PETSc Mat.
pyop3.cache module¶
Provides common base classes for cached objects.
- class pyop3.cache.DictLikeDiskAccess(cachedir, extension='.pickle')[source]¶
Bases:
MutableMappingA Dictionary like interface for storing and retrieving objects from a disk cache.
- class pyop3.cache.WeakHeavyObjectCacheStore[source]¶
Bases:
objectKeys are heavy cache objects, values are caches. If the heavy object dies then the cache must die too.
WeakKeyDictionary doesn’t work because of hashing
obj1 = myfunc() obj2 = myfunc() obj1 == obj2 # True hash(obj1) == hash(obj2) # True obj1 is obj2 # False
weakref.ref(obj1) == weakref.ref(obj2) # True hash(weakref.ref(obj1)) == hash(weakref.ref(obj2)) # True!!!
We need a cache that truly works on identity hashing.
- pyop3.cache.as_hexdigest(*args)[source]¶
Return
argsas a hash string.Notes
This function is relatively expensive to compute so one should avoid calling it wherever possible.
- pyop3.cache.cache_filter(comm=None, comm_name=None, alive=False, function=None, cache_type=None)[source]¶
Filter PyOP2 caches based on communicator, function or cache type.
- pyop3.cache.cached_method_until(key)[source]¶
Decorator for a method whose results are cached until some value changes.
This is the counterpart of \(cached_property_until\) but for methods. When a decorated method is called, its results are cached against the set of arguments it was called with. All cached results are discarded when the value of the key changes.
- pyop3.cache.cached_on(get_obj, get_key=<function hashkey>, *, multi=False, make_cache=<class 'dict'>, get_version=<function <lambda>>)[source]¶
Decorator that caches function results on an object.
- Parameters:
get_obj (Callable) – Function returning the object that holds the cache.
get_key (Callable) – Function returning the cache key.
multi (bool) – Does
get_objreturn multiple objects? Default is \(False\).make_cache (Callable) – Function called to create a new cache.
get_version (Callable) – Function returning the cache ‘version’. If this changes then previous caches are discarded. Default is to return \(None\).
- pyop3.cache.cached_property_until(key)[source]¶
Decorator for a property that is cached until some value changes.
For example, the
expensive_propertybelow will be cached untilself.valuechanges, and will be recomputed with the newself.valueand cached when accessed again.class MyClass: def __init__(self, value): self.value = value @cached_property_until(lambda self: self.value) def expensive_property(self): # Some expensive computation that depends on self.value ...
- pyop3.cache.clear_memory_cache(comm)[source]¶
Completely remove all PyOP2 caches on a given communicator.
- pyop3.cache.default_get_comm(*args, **kwargs)[source]¶
A sensible default comm fetcher for use with \(parallel_cache\).
- pyop3.cache.default_parallel_hashkey(*args, **kwargs)[source]¶
A sensible default hash key for use with \(parallel_cache\).
- class pyop3.cache.gc_disabled[source]¶
Bases:
ContextDecoratorContext manager for temporarily disabling the garbage collector.
It may also be used as a function decorator.
- pyop3.cache.get_comm_caches(comm)[source]¶
Return the collection of caches that are stored on a comm.
If a cache stash has not already been created then a new \(dict\) is created and stored.
- Parameters:
comm – The communicator to get the caches from.
- Returns:
The collection of caches.
- Return type:
- class pyop3.cache.heavy_caches(objs)[source]¶
Bases:
objectContext manager that pushes and pops lifetime objects.
For this to be parallel safe, the contract here is that, by using this decorator, you are guaranteeing that all operations within the context manager are at most collective to the level of the the communicator of the lifetime objects.
- counter = count(0)¶
- pyop3.cache.memory_cache(hashkey=<function default_parallel_hashkey>, get_comm=<function default_get_comm>, make_cache=<function <lambda>>, bcast=False, heavy=False)¶
Parallel cache decorator.
- Parameters:
hashkey – Callable taking
*argsand**kwargsand returning a hash.get_comm – Callable taking
*argsand**kwargsand returning the appropriate communicator.make_cache – Callable that will build a new cache (if one does not exist). This will be called every time the decorated function is called, and must return an instance of the same type every time it is called.
bcast – If \(True\), then generate the new cache value on one rank and broadcast to the others. If \(False\) then values are generated on all ranks. This option can only be \(True\) if the operation can be executed in serial; else it will deadlock.
heavy – Do the objects stored in the cache have a large memory footprint? If yes then this cache is only used when a ‘heavy’ cache is set (see the \(heavy_cache\) context manager) and the lifetime of the objects in the cache are tied to the lifetime of the cache.
- pyop3.cache.parallel_cache(hashkey=<function default_parallel_hashkey>, get_comm=<function default_get_comm>, make_cache=<function <lambda>>, bcast=False, heavy=False)[source]¶
Parallel cache decorator.
- Parameters:
hashkey – Callable taking
*argsand**kwargsand returning a hash.get_comm – Callable taking
*argsand**kwargsand returning the appropriate communicator.make_cache – Callable that will build a new cache (if one does not exist). This will be called every time the decorated function is called, and must return an instance of the same type every time it is called.
bcast – If \(True\), then generate the new cache value on one rank and broadcast to the others. If \(False\) then values are generated on all ranks. This option can only be \(True\) if the operation can be executed in serial; else it will deadlock.
heavy – Do the objects stored in the cache have a large memory footprint? If yes then this cache is only used when a ‘heavy’ cache is set (see the \(heavy_cache\) context manager) and the lifetime of the objects in the cache are tied to the lifetime of the cache.
- pyop3.cache.with_heavy_caches(get_obj)[source]¶
Function decorator that pushes and pops lifetime objects.
- pyop3.cache.with_self_heavy_cache(func)¶
Method decorator that sets
selfas a heavy cache.
pyop3.cc module¶
- class pyop3.cc.AnonymousCompiler(extra_compiler_flags=(), extra_linker_flags=(), version=None, debug=False)[source]¶
Bases:
CompilerCompiler for building a shared library on systems with unknown compiler. The properties of this compiler are entirely controlled through environment variables
- class pyop3.cc.Compiler(extra_compiler_flags=(), extra_linker_flags=(), version=None, debug=False)[source]¶
Bases:
ABCA compiler for shared libraries.
- Parameters:
extra_compiler_flags – A list of arguments to the C compiler (CFLAGS) or the C++ compiler (CXXFLAGS) (optional, prepended to any flags specified as the cflags configuration option). The environment variables
PYOP2_CFLAGSandPYOP2_CXXFLAGScan also be used to extend these options.extra_linker_flags – A list of arguments to the linker (LDFLAGS) (optional, prepended to any flags specified as the ldflags configuration option). The environment variable
PYOP2_LDFLAGScan also be used to extend these options.version – (Optional) usually sniffed by loader.
debug – Whether to use debugging compiler flags.
- property bugfix_cflags¶
- property cc¶
- property cflags¶
- property cxx¶
- property cxxflags¶
- property ld¶
- property ldflags¶
- class pyop3.cc.CompilerDiskAccess(cachedir, extension='.pickle')[source]¶
Bases:
DictLikeDiskAccess
- class pyop3.cc.CompilerOptions(*, include_dirs=(), lib_dirs=(), libs=())[source]¶
Bases:
objectCompiler options associated with a pyop3 object.
- include_dirs = ()¶
- lib_dirs = ()¶
- libs = ()¶
- class pyop3.cc.LinuxClangCompiler(extra_compiler_flags=(), extra_linker_flags=(), version=None, debug=False)[source]¶
Bases:
CompilerThe clang for building a shared library on Linux systems.
- class pyop3.cc.LinuxCrayCompiler(extra_compiler_flags=(), extra_linker_flags=(), version=None, debug=False)[source]¶
Bases:
CompilerThe Cray compiler for building a shared library on Linux systems.
- property ldflags¶
- class pyop3.cc.LinuxGnuCompiler(extra_compiler_flags=(), extra_linker_flags=(), version=None, debug=False)[source]¶
Bases:
CompilerThe GNU compiler for building a shared library on Linux systems.
- property bugfix_cflags¶
Flags to work around bugs in compilers.
- class pyop3.cc.LinuxIntelCompiler(extra_compiler_flags=(), extra_linker_flags=(), version=None, debug=False)[source]¶
Bases:
CompilerThe Intel compiler for building a shared library on Linux systems.
- class pyop3.cc.MacClangARMCompiler(extra_compiler_flags=(), extra_linker_flags=(), version=None, debug=False)[source]¶
Bases:
MacClangCompilerA compiler for building a shared library on ARM based Mac systems.
- class pyop3.cc.MacClangCompiler(extra_compiler_flags=(), extra_linker_flags=(), version=None, debug=False)[source]¶
Bases:
CompilerA compiler for building a shared library on Mac systems.
- class pyop3.cc.MacGNUCompiler(extra_compiler_flags=(), extra_linker_flags=(), version=None, debug=False)[source]¶
Bases:
MacClangCompilerA compiler for building a shared library on Mac systems with a GNU compiler.
- pyop3.cc.add_profiling_events(dll, events)[source]¶
If PyOP2 is in profiling mode, events are attached to dll to profile the local linear algebra calls. The event is generated here in python and then set in the shared library, so that memory is not allocated over and over again in the C kernel. The naming convention is that the event ids are named by the event name prefixed by
"ID_".
- pyop3.cc.check_source_hashes(compiler, code, extension, comm)[source]¶
A check to see whether code generated on all ranks is identical.
- Parameters:
compiler – The compiler to use to create the shared library.
code – The code to compile.
filename – The filename of the library to create.
extension – extension of the source file (c, cpp).
comm – Communicator over which to perform compilation.
- pyop3.cc.clear_compiler_disk_cache(prompt=False)[source]¶
Clear the PyOP2 compiler disk cache.
- Parameters:
prompt – if
Trueprompt before removing any files
- pyop3.cc.expandWl(ldflags)[source]¶
Generator to expand the \(-Wl\) compiler flags for use as linker flags :arg ldflags: linker flags for a compiler command
- pyop3.cc.load(code, extension, cppargs=(), ldargs=(), comm=<mpi4py.MPI.Intracomm object>)[source]¶
Build a shared library and return a function pointer from it.
- Parameters:
code – The code to compile.
extension – extension of the source file (c, cpp)
cppargs – A tuple of arguments to the C compiler (optional)
ldargs – A tuple of arguments to the linker (optional)
- Keyword Arguments:
comm – Optional communicator to compile the code on (only rank 0 compiles code) (defaults to mpi4py.MPI.COMM_WORLD).
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.
- pyop3.cc.make_so(compiler, code, extension, comm)[source]¶
Build a shared library and load it
- Parameters:
compiler – The compiler to use to create the shared library.
code – The code to compile.
filename – The filename of the library to create.
extension – extension of the source file (c, cpp).
comm – Communicator over which to perform compilation.
Returns a
ctypes.CDLLobject of the resulting shared library.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.
- pyop3.cc.set_default_compiler(compiler)[source]¶
Set the PyOP2 default compiler, globally over COMM_WORLD.
- Parameters:
compiler – String with name or path to compiler executable OR a subclass of the Compiler class
pyop3.collections module¶
- class pyop3.collections.HashableSlice(start, stop, step)[source]¶
Bases:
objectA hashable slice.
This class is needed because in Python <3.12 slices are not hashable.
- start¶
- step¶
- stop¶
- class pyop3.collections.OrderedFrozenSet(values=(), /)[source]¶
Bases:
AbstractOrderedSet
- class pyop3.collections.OrderedSet(values=None, /)[source]¶
Bases:
AbstractOrderedSetA mutable ordered set.
- class pyop3.collections.StrictlyUniqueDefaultDict[source]¶
Bases:
defaultdict
- class pyop3.collections.StrictlyUniqueDict[source]¶
Bases:
dictA dictionary where overwriting entries will raise an error.
pyop3.config module¶
- class pyop3.config.ConfigOption(typ, default_value, description, from_str=<function ConfigOption.<lambda>>, default_debug_value=<object object>, value_getter=None, value_setter=None)[source]¶
Bases:
objectConfigOption(typ: ‘Any’, default_value: ‘Any’, description: ‘str’, from_str: ‘Callable’ = <function ConfigOption.<lambda> at 0x70fc926021f0>, default_debug_value: ‘Any’ = <object object at 0x70fcb021f330>, value_getter: ‘Callable | None’ = None, value_setter: ‘Callable | None’ = None)
- default_debug_value = <object object>¶
- default_value¶
- description¶
- from_str()¶
- typ¶
- value_getter = None¶
- value_setter = None¶
- class pyop3.config.Pyop3Configuration(**kwargs)[source]¶
Bases:
objectGlobal configuration options for pyop3.
- OPTIONS = immutabledict({'max_static_array_size': ConfigOption(typ=<class 'int'>, default_value=128, description='The maximum size of hard-coded constant arrays.\n\n Constant arrays that exceed this limit are passed to the kernel as\n arguments instead.\n\n ', from_str=<function Pyop3Configuration.<lambda>>, default_debug_value=<object object>, value_getter=None, value_setter=None), 'extra_cflags': ConfigOption(typ=tuple[str, ...], default_value=(), description='Extra flags to be passed to the C compiler.', from_str=<function Pyop3Configuration.<lambda>>, default_debug_value=<object object>, value_getter=None, value_setter=None), 'extra_cxxflags': ConfigOption(typ=tuple[str, ...], default_value=(), description='Extra flags to be passed to the C++ compiler.', from_str=<function Pyop3Configuration.<lambda>>, default_debug_value=<object object>, value_getter=None, value_setter=None), 'extra_ldflags': ConfigOption(typ=tuple[str, ...], default_value=(), description='Extra flags to be passed to the linker.', from_str=<function Pyop3Configuration.<lambda>>, default_debug_value=<object object>, value_getter=None, value_setter=None), 'cache_dir': ConfigOption(typ=<class 'pathlib.Path'>, default_value=PosixPath('/tmp/pyop3-cache-uid0'), description='Location of the generated code (libraries).', from_str=<function ConfigOption.<lambda>>, default_debug_value=<object object>, value_getter=None, value_setter=None), 'node_local_compilation': ConfigOption(typ=<class 'bool'>, default_value=True, description='Compile generated code separately on each node.\n\n If set it is likely that ``cache_dir`` will have to be set to to a\n node-local filesystem too.\n\n ', from_str=<function strtobool>, default_debug_value=<object object>, value_getter=None, value_setter=None), 'log_level': ConfigOption(typ=str | int, default_value='WARNING', description='Level used by the pyop3 logger.', from_str=<function ConfigOption.<lambda>>, default_debug_value='DEBUG', value_getter=None, value_setter=<function _log_level_setter>), 'print_cache_stats': ConfigOption(typ=<class 'bool'>, default_value=False, description='Print cache statistics at the end of the program.', from_str=<function strtobool>, default_debug_value=True, value_getter=None, value_setter=None), 'debug_checks': ConfigOption(typ=<class 'bool'>, default_value=False, description='Enable additional correctness checks.\n\n This option is enabled in debug mode.\n\n ', from_str=<function strtobool>, default_debug_value=True, value_getter=None, value_setter=None), 'compiler_use_debug_flags': ConfigOption(typ=<class 'bool'>, default_value=False, description="Pass debugging options (i.e. '-O0' and '-g') to the compiler.\n\n This option is enabled in debug mode.\n\n ", from_str=<function strtobool>, default_debug_value=True, value_getter=None, value_setter=None), 'check_src_hashes': ConfigOption(typ=<class 'bool'>, default_value=True, description='Check that generated code is the same on all processes.', from_str=<function strtobool>, default_debug_value=<object object>, value_getter=None, value_setter=None), 'spmd_strict': ConfigOption(typ=<class 'bool'>, default_value=False, description='Turn on additional parallel correctness checks.\n\n Setting this option will enable barriers for calls marked with @collective\n and for cache accesses. This adds considerable overhead, but is useful for\n tracking down deadlocks.\n\n This option is enabled in debug mode.\n\n ', from_str=<function strtobool>, default_debug_value=True, value_getter=None, value_setter=None)})¶
- property cache_dir¶
Location of the generated code (libraries).
- property check_src_hashes¶
Check that generated code is the same on all processes.
- property compiler_use_debug_flags¶
Pass debugging options (i.e. ‘-O0’ and ‘-g’) to the compiler.
This option is enabled in debug mode.
- property debug_checks¶
Enable additional correctness checks.
This option is enabled in debug mode.
- property extra_cflags¶
Extra flags to be passed to the C compiler.
- property extra_cxxflags¶
Extra flags to be passed to the C++ compiler.
- property extra_ldflags¶
Extra flags to be passed to the linker.
- property log_level¶
Level used by the pyop3 logger.
- property max_static_array_size¶
The maximum size of hard-coded constant arrays.
Constant arrays that exceed this limit are passed to the kernel as arguments instead.
- property node_local_compilation¶
Compile generated code separately on each node.
If set it is likely that
cache_dirwill have to be set to to a node-local filesystem too.
- property print_cache_stats¶
Print cache statistics at the end of the program.
- property spmd_strict¶
Turn on additional parallel correctness checks.
Setting this option will enable barriers for calls marked with @collective and for cache accesses. This adds considerable overhead, but is useful for tracking down deadlocks.
This option is enabled in debug mode.
pyop3.constants module¶
- pyop3.constants.DECIDE = DECIDE¶
Placeholder indicating that a value should be set by pyop3.
This is important in cases where the more traditional \(None\) is actually meaningful.
- class pyop3.constants.Intent(*values)[source]¶
Bases:
Enum- INC = 'inc'¶
- MAX_RW = 'max_rw'¶
- MAX_WRITE = 'max_write'¶
- MIN_RW = 'min_rw'¶
- MIN_WRITE = 'min_write'¶
- READ = 'read'¶
- RW = 'rw'¶
- WRITE = 'write'¶
- pyop3.constants.NOTHING = <object object>¶
Sentinel value indicating nothing should be done.
This is useful in cases where \(None\) holds some meaning.
pyop3.debug module¶
- exception pyop3.debug.TodoWarning[source]¶
Bases:
UserWarning
pyop3.device module¶
- class pyop3.device.CPU[source]¶
Bases:
DeviceCPU Class, designed to be host object, inheriting Device - Plausible to have multiple CPUs, functionally similar to having GPU
- asarray(arr, *, constant=False)[source]¶
Convert GPU/CuPy/NumPy input array to CPU-compliant NumPy array
- name = 'CPU'¶
- class pyop3.device.CUDAGPU[source]¶
Bases:
DeviceGPU class for Nvidia GPUs. inheriting Device. - All offloading will be done through CuPy - Multiple instantiations will be independent of each other
- property cp¶
- name = 'CudaGPU'¶
- pyop3.device.DEVICE_TO_ARRAY_TYPE = {<pyop3.device.CPU object>: <class 'numpy.ndarray'>}¶
Mapping between device and array type.
When new devices are created they should register themselves here.
Note that this mapping is not invertible. A single array type could map to multiple devices.
- class pyop3.device.Device[source]¶
Bases:
ABCDevice - Abstract class - Base for future GPU implementations - All device-specific logic should be kept in here
- name¶
- pyop3.device.flag_constant(array)[source]¶
- pyop3.device.flag_constant(array)
Mark an array as being constant.
- pyop3.device.offloading(dev)[source]¶
Context Manager for offloading components to select device This function should be the only way to modfiy the current device variable
Updates current context to the given \(dev\) variable. Former device is stored in stack, to be restored when finished - This also allows for stacking of context windows
Context variables are also async safe.
— Example:
gpu = op3.CUDAGPU() with op3.offloading(gpu): g.dat.assign(23, eager=True, eager_strategy="array")
pyop3.dtypes module¶
- class pyop3.dtypes.DTypeLimit(min, max)¶
Bases:
tupleDTypeLimit(min, max)
- max¶
Alias for field number 1
- min¶
Alias for field number 0
- pyop3.dtypes.dtype_limits(dtype)[source]¶
Attempt to determine the min and max values of a datatype.
- Parameters:
dtype – A numpy datatype.
- Returns:
a 2-tuple of min, max
- Raises:
ValueError – If numeric limits could not be determined.
pyop3.exceptions module¶
- exception pyop3.exceptions.CacheException[source]¶
Bases:
Pyop3ExceptionError during caching.
- exception pyop3.exceptions.CommMismatchException[source]¶
Bases:
Pyop3ExceptionException raised when MPI communicators do not match.
- exception pyop3.exceptions.CommNotFoundException[source]¶
Bases:
Pyop3Exception
- exception pyop3.exceptions.CompilationException[source]¶
Bases:
Pyop3ExceptionError during compilation.
- exception pyop3.exceptions.ContextMismatchException[source]¶
Bases:
Pyop3Exception
- exception pyop3.exceptions.EmptyIterableException[source]¶
Bases:
Pyop3Exception
- exception pyop3.exceptions.ExpectedLinearAxisTreeException[source]¶
Bases:
Pyop3Exception
- exception pyop3.exceptions.ExpressionUnchangedException[source]¶
Bases:
Pyop3Exception
- exception pyop3.exceptions.IncompatibleAxisTargetException[source]¶
Bases:
Pyop3Exception
- exception pyop3.exceptions.InvalidArrayAccessException[source]¶
Bases:
Pyop3ExceptionException raised when a data structure cannot be viewed as an array.
- exception pyop3.exceptions.InvalidExpressionException[source]¶
Bases:
Pyop3Exception
- exception pyop3.exceptions.InvalidIndexCountException[source]¶
Bases:
Pyop3ExceptionException raised when too few/many indices are used to index an object.
- exception pyop3.exceptions.InvalidIndexTargetException[source]¶
Bases:
Pyop3ExceptionException raised when we try to match index information to a mismatching axis tree.
- exception pyop3.exceptions.InvalidIntentException[source]¶
Bases:
Pyop3ExceptionError raised if an argument cannot be accessed using the declared intent.
- exception pyop3.exceptions.InvalidMapTargetException[source]¶
Bases:
Pyop3Exception
- exception pyop3.exceptions.InvalidScalarTypeException[source]¶
Bases:
Pyop3Exception,TypeErrorException raised when an operation does not support the scalar type of its data.
- exception pyop3.exceptions.LoopContextSensitiveException[source]¶
Bases:
Pyop3ExceptionException raised when an index is sensitive to the loop index.
- exception pyop3.exceptions.MissingVariableException[source]¶
Bases:
Pyop3ExceptionException raised when information about an axis variable is missing.
- exception pyop3.exceptions.MultipleUniqueEntriesException[source]¶
Bases:
Pyop3Exception
- exception pyop3.exceptions.NonUnitAxisException[source]¶
Bases:
Pyop3Exception
- exception pyop3.exceptions.NonUnitIterableException[source]¶
Bases:
Pyop3Exception
- exception pyop3.exceptions.SizeMismatchException[source]¶
Bases:
Pyop3ExceptionException raised when the size of an array does not match what is expected.
- exception pyop3.exceptions.UnhashableObjectException[source]¶
Bases:
Pyop3Exception,TypeError
- exception pyop3.exceptions.UnspecialisedCalledMapException[source]¶
Bases:
Pyop3ExceptionException raised when an unspecialised map is used in place of a specialised one.
This is important for cases like closure(cell) where the result can be either a set of points, or sets of cells, edges, and vertices. We say that it is ‘unspecialised’ because it cannot be put into an \(IndexTree\) and instead should yield two trees as an \(IndexForest\).
- exception pyop3.exceptions.UnsupportedArrayException[source]¶
Bases:
Pyop3Exception,TypeError
- exception pyop3.exceptions.ValueMismatchException[source]¶
Bases:
Pyop3Exception
pyop3.labeled_tree module¶
- class pyop3.labeled_tree.AbstractLabeledTreeLike[source]¶
Bases:
Object- abstract property is_linear¶
- exception pyop3.labeled_tree.InvalidTreeException[source]¶
Bases:
ValueError
- class pyop3.labeled_tree.LabeledTree[source]¶
Bases:
AbstractLabeledTreeLike- ancestors(node, component_label)[source]¶
Return the ancestors of a
(node_id, component_label)2-tuple.
- property depth¶
- find_component(node_label, cpt_label, also_node=False)[source]¶
Return the first component in the tree matching the given labels.
Notes
This will return the first component matching the labels. Multiple may exist but we assume that they are identical.
- property is_empty¶
- property is_linear¶
- property leaf_path¶
- property root¶
- class pyop3.labeled_tree.MultiComponentLabeledNode[source]¶
-
- property component_label¶
- abstract property component_labels¶
- property degree¶
- exception pyop3.labeled_tree.TreeMutationException[source]¶
Bases:
Pyop3Exception
- pyop3.labeled_tree.as_path(obj)[source]¶
- pyop3.labeled_tree.as_path(path)
- pyop3.labeled_tree.as_path(path)
- pyop3.labeled_tree.postvisit(tree, fn, path=immutabledict({}), **kwargs)[source]¶
Traverse the tree in postorder.
- Parameters:
tree (LabeledTree) – The tree to be visited.
fn (collections.abc.Callable) – A function to be applied at each node. The function should take the node to be visited as its first argument, and the results of visiting its children as any further arguments.
pyop3.log module¶
The PyOP2 logger, based on the Python standard library logging module.
- pyop3.log.log(level, msg, *args, **kwargs)[source]¶
Print ‘msg % args’ with the severity ‘level’.
- Parameters:
level – the log level. Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL
msg – the message
- pyop3.log.progress(level, msg, *args, **kwargs)[source]¶
A context manager to print a progress message.
The block is wrapped in
msg...,msg...donelog messages with an appropriate indent (to distinguish nested message).- Parameters:
level – the log level. See
log()for valid valuesmsg – the message.
See
log()for more details.
pyop3.mpi module¶
PyOP2 MPI communicator.
pyop3.node module¶
- class pyop3.node.NodeCollector(*, reuse_results=True)[source]¶
Bases:
NodeVisitor,ABC
- class pyop3.node.NodeTransformer(*, reuse_results=True)[source]¶
Bases:
NodeVisitor,ABC
- class pyop3.node.Visitor(*, reuse_results=True)[source]¶
Bases:
ABCBase class for DAG traversers.
- Parameters:
compress – If True,
result_cachewill be used.visited_cache – cache of intermediate results; expr -> r = self.process(expr, …).
result_cache – cache of result objects for memory reuse, r -> r.
- __call__(node, *args, **kwargs)[source]¶
Perform memoised DAG traversal with
processsingledispatch method.- Parameters:
node – Expression to start DAG traversal from.
*args – Positional arguments for the
processsingledispatchmethod.**kwargs – keyword arguments for the
processsingledispatchmethod.
- Returns:
Processed Expression.
- pyop3.node.postorder(method)[source]¶
Postorder decorator.
It is more natural for users to write a post-order singledispatchmethod whose arguments are
(self, o, *processed_operands, **kwargs), while \(DAGTraverser\) expects one whose arguments are(self, o, **kwargs). This decorator takes the former and converts to the latter, processingo.ufl_operandsbehind the users.
pyop3.obj module¶
pyop3.pyop2_utils module¶
Common utility classes/functions.
- pyop3.pyop2_utils.as_type(obj, typ)[source]¶
Return obj if it is of dtype typ, otherwise return a copy type-cast to typ.
- pyop3.pyop2_utils.parse_args(*args, **kwargs)[source]¶
Return parsed arguments as variables for later use.
ARGS and KWARGS are passed into the parser instantiation. The only recognised options are \(group\) and \(description\).
pyop3.record module¶
pyop3.sf module¶
- class pyop3.sf.AbstractStarForest[source]¶
Bases:
Object- abstract property ileaf¶
- abstract property num_ghost¶
- abstract property num_owned¶
- class pyop3.sf.NullStarForest(size)[source]¶
Bases:
AbstractStarForest- property comm¶
- property ileaf¶
- property num_ghost¶
- property num_owned¶
- class pyop3.sf.StarForest(sf, comm)[source]¶
Bases:
AbstractStarForestConvenience wrapper for a \(petsc4py.SF\).
- property comm¶
- property graph¶
- property ileaf¶
- property ilocal¶
- property iremote¶
- property nleaves¶
- property num_ghost¶
- property num_owned¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- sf¶
- property size¶
pyop3.types module¶
- pyop3.types.AxisComponentLabelT¶
Type alias for axis component labels.
- pyop3.types.AxisComponentLike = pyop3.axis_tree.tree.AxisComponent | collections.abc.Hashable¶
Type alias for things that can be parsed into axis components.
- pyop3.types.AxisComponentRegionLabelT¶
Type alias for axis component region labels.
- pyop3.types.AxisLabelT¶
Type alias for axis labels.
- pyop3.types.ConcretePathT¶
Type alias for a tree path.
alias of
immutabledict[Hashable,Hashable]
- pyop3.types.LabelT¶
Something that may be used as a label.
- pyop3.types.NodeComponentLabelT¶
Something that may be used as a label for a node component.
- pyop3.types.NodeLabelT¶
Something that may be used as a label for a node.
pyop3.utils module¶
- class pyop3.utils.Atom(item)[source]¶
Bases:
objectWrapper object indicating that something should not be subdivided.
This class is necessary because the special-casing of tuples in
__getitem__by Python breaks the syntactic sugar we have for slices. For example consider an axis component with (tuple) label ‘(2, 1)’. We would like to be able to take this slice by executing:dat[(2, 1)]
However,
__getitem__turns this into the very different:dat[2, 1]
Turning the tuple (2, 1) into an atom resolves this.
- item¶
- class pyop3.utils.UniqueNameGenerator(existing_names=None, forced_prefix='', forced_suffix='')[source]¶
Bases:
UniqueNameGeneratorClass for generating unique names.
- pyop3.utils.expand_collection_of_iterables(compressed)[source]¶
Expand target paths written in ‘compressed’ form like:
{key1: [item1, item2], key2: [item3]}
Instead to the ‘expanded’ form:
({key1: item1, key2: item3}, {key1: item2, key2: item3})
Valid input types for
compressedinclude ordered mappings and iterables of 2-tuples (i.e. things that can be parsed into a \(dict\)).
- pyop3.utils.freeze(obj)[source]¶
- pyop3.utils.freeze(tuple_)
- pyop3.utils.freeze(slice_)
- pyop3.utils.freeze(list_)
- pyop3.utils.freeze(immutabledict_)
- pyop3.utils.freeze(dict_)
- pyop3.utils.freeze(hashable)
- pyop3.utils.invert(p)[source]¶
Return an array s with which np.array_equal(arr[p][s], arr) is True. The array_like argument p must be some permutation of 0, 1, …, len(p)-1.
- pyop3.utils.is_sorted(array)[source]¶
Notes
This function works even for empty arrays, which are reported as being sorted.
- pyop3.utils.just_one(iterable)[source]¶
Return the only entry in an iterable.
- Parameters:
iterable – The container with only a single entry.
- Returns:
The single item in
iterable.- Return type:
Any
- Raises:
ValueError – If the iterable does not contain a single entry.
- pyop3.utils.maybe_generate_name(name, prefix, default_prefix, *, generator=<pyop3.utils.UniqueNameGenerator object>)[source]¶
- pyop3.utils.popfirst(dict_)[source]¶
Remove the first item from a dictionary and return it with its key.
- pyop3.utils.popwhen(predicate, iterable)[source]¶
Pop the first instance from iterable where predicate is
True.
- pyop3.utils.regexify(pattern)[source]¶
Convert an expression pattern into a regex pattern.
This is useful for testing.
- pyop3.utils.split_by(condition, items)[source]¶
Split an iterable in two according to some condition.
- Parameters:
condition – Callable applied to each item in
items, returningTrueorFalse.items – Iterable to split apart.
- Returns:
A 2-tuple of the form
(yess, nos), whereyessis a tuple containing the entries ofitemswhereconditionisTrueandnosis a tuple of those whereconditionisFalse.
- pyop3.utils.strictly_all(iterable)[source]¶
Returns
all(iterable)but raises an exception if values are inconsistent.
Module contents¶
- class pyop3.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.AggregateDat(subdats, axis, *, name=None, prefix=None)[source]¶
Bases:
ObjectA dat formed of multiple subdats concatenated together.
- DEFAULT_PREFIX = 'aggdat'¶
- axis¶
- property comm¶
- property dtype¶
- name¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- property size¶
- subdats¶
- property subtensors¶
- class pyop3.AggregateMat(submats, row_axis, column_axis, *, name=None, prefix=None)[source]¶
Bases:
ObjectA matrix formed of multiple submatrices concatenated together.
- DEFAULT_PREFIX = 'aggmat'¶
- column_axis¶
- property comm¶
- property dtype¶
- name¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- row_axis¶
- submats¶
- property subtensors¶
- class pyop3.ArrayBuffer(data, sf=None, *, name=None, prefix=None, constant=False, rank_equal=False, ordered=False)[source]¶
Bases:
AbstractArrayBuffer,ConcreteBufferA buffer whose underlying data structure is a lazily-evaluated NumPy/CuPy array.
- Parameters:
data – Note that the arrays passed here should be unique to this array. Do not use the same array between buffers as it will disrupt the state tracking done by the buffer.
- DEFAULT_PREFIX = 'array'¶
- broadcast_roots_to_leaves()[source]¶
Unconditionally update leaves.
This will overwrite any existing parallel state tracking.
- property comm¶
- property constant¶
- property data_ro¶
- property data_rw¶
- property data_wo¶
Have to be careful. If not setting all values (i.e. subsets) should call \(reduce_leaves_to_roots\) first.
When this is called we set roots_valid, claiming that any (lazy) ‘in-flight’ writes can be dropped.
- property dtype¶
- property is_frozen¶
- is_nested = False¶
- property name¶
- property ordered¶
- property rank_equal¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- reduce_leaves_to_roots(op)[source]¶
Unconditionally update roots.
This will overwrite any existing parallel state tracking.
- Parameters:
op – The MPI reduction operation to apply when pulling leaves onto roots.
- sf¶
- property shape¶
- property state¶
- class pyop3.Assignment(assignee, expression, assignment_type)[source]¶
Bases:
AbstractAssignmentAssignment(assignee: ‘Any’, expression: ‘Any’, assignment_type: ‘AssignmentType | str’) -> ‘None’
- property assignee¶
- assignment_type¶
- expression¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- class pyop3.AssignmentType(*values)[source]¶
Bases:
Enum- INC = 'inc'¶
- MAX = 'max'¶
- MIN = 'min'¶
- WRITE = 'write'¶
- class pyop3.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.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.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.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.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.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.AxisVar(axis)[source]¶
Bases:
TerminalExpressionAxisVar(axis: ‘pyop3.axis_tree.Axis’)
- axis¶
- property dtype¶
- get_instruction_executor_cache_key(visitor)¶
- property local_max¶
- property local_min¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- class pyop3.CUDAGPU[source]¶
Bases:
DeviceGPU class for Nvidia GPUs. inheriting Device. - All offloading will be done through CuPy - Multiple instantiations will be independent of each other
- property cp¶
- name = 'CudaGPU'¶
- class pyop3.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.Dat(axes, buffer=None, *, data=None, name=None, prefix=None, buffer_kwargs=None, constant=False, transform=None)[source]¶
Bases:
TensorMulti-dimensional, hierarchical array.
- DEFAULT_PREFIX = 'dat'¶
- axes¶
- property axis_trees¶
- axpy(alpha, other)[source]¶
Compute the operation \(y = \alpha x + y\).
In this case,
selfisyandotherisx.
- buffer¶
- property comm¶
- property context_free¶
- property dat_version¶
- property data_ro_with_halos¶
Return a read-only view of the data stored by the dat.
This view includes ghost entries.
- property data_rw_with_halos¶
Return a modifiable view of the data stored by the dat.
This view includes ghost entries.
- property data_with_halos¶
- property data_wo_with_halos¶
Return a write-only view of the data stored by the dat.
This view includes ghost entries.
- dim = 1¶
- property dtype¶
- classmethod empty(axes, dtype=dtype('float64'), *, buffer_kwargs=immutabledict({}), **kwargs)[source]¶
- classmethod from_array(array, *, sf=None, comm=<mpi4py.MPI.Intracomm object>, buffer_kwargs=None, constant=False, rank_equal=False, **kwargs)[source]¶
- classmethod full(axes, fill_value, dtype=dtype('float64'), *, buffer_kwargs=immutabledict({}), **kwargs)[source]¶
- property global_data¶
Return all the data for the Dat gathered onto individual ranks.
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.
- inner(other, /)[source]¶
Compute the l2 inner product against another dat.
- Parameters:
other – The other \(Dat\) to compute the inner product against. Its complex conjugate is taken.
- Returns:
The l2 inner product.
- Return type:
- property local_max¶
- property local_min¶
- property max¶
Return the global maximum value held by the dat.
- maxpy(alphas, dats)[source]¶
Compute a sequence of axpy operations.
This is equivalent to calling
axpyfor each pair of scalars and \(Dat\) in the input sequences.- Parameters:
alphas – A sequence of scalars.
dats – A sequence of \(Dat\).
- property min¶
Return the global minimum value held by the dat.
- name¶
- property nbytes¶
Return an estimate of the size of the data associated with this
Datin bytes. This will be the correct size of the data payload, but does not take into account the (presumably small) overhead of the object and its metadata.Note that this is the process local memory usage, not the sum over all MPI processes.
- property norm¶
Compute the l2 norm of this \(Dat\).
Note
This acts on the flattened data (see also
inner()).
- classmethod null(axes, dtype=dtype('float64'), *, buffer_kwargs=immutabledict({}), **kwargs)[source]¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- property sf¶
- property size¶
- property transform¶
- property vec¶
- property vec_ro¶
- property vec_rw¶
- property vec_wo¶
- class pyop3.DenseBlockPythonMatContext(buffer)[source]¶
Bases:
DensePythonMatContext- property sizes¶
- class pyop3.DenseColumnPythonMatContext(buffer)[source]¶
Bases:
DensePythonMatContext- property sizes¶
- class pyop3.DensePythonMatContext(buffer)[source]¶
Bases:
objectMatrix context for storing narrow and dense (usually Nx1 or 1xN) matrices as PETSc Vecs.
This is important in massively parallel settings where a single dense row would live on a single process and hence be a significant performance bottleneck.
- property comm¶
- property data_ro¶
- class pyop3.DenseRowPythonMatContext(buffer)[source]¶
Bases:
DensePythonMatContext- property sizes¶
- class pyop3.Function(loopy_kernel, access_descrs, *, include_dirs=(), lib_dirs=(), libs=())[source]¶
Bases:
ObjectA callable function.
- Parameters:
loopy_kernel – The loopy kernel that implements the function.
access_descrs – The access descriptor of each kernel argument.
include_dirs – The include directories that are needed to compile the kernel.
lib_dirs – The library directories that are needed to link the kernel.
libs – The libraries that are needed to link the kernel.
- property argspec¶
- code¶
- property comm¶
- property compiler_options¶
- get_instruction_executor_cache_key(visitor)¶
- property intents¶
- property name¶
- property num_flops¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- class pyop3.Index[source]¶
Bases:
MultiComponentLabeledNode
- class pyop3.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.
- class pyop3.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.Intent(*values)[source]¶
Bases:
Enum- INC = 'inc'¶
- MAX_RW = 'max_rw'¶
- MAX_WRITE = 'max_write'¶
- MIN_RW = 'min_rw'¶
- MIN_WRITE = 'min_write'¶
- READ = 'read'¶
- RW = 'rw'¶
- WRITE = 'write'¶
- class pyop3.LinearDatBufferExpression(buffer_view, layout)[source]¶
Bases:
DatBufferExpression,LinearBufferExpressionA dat with fixed (?) layout.
It cannot be indexed.
This class is useful for describing arrays used in index expressions, at which point it has a fixed set of axes.
- buffer_view¶
- child_attrs = ('layout',)¶
- property comm¶
- layout¶
- property local_max¶
- property local_min¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- class pyop3.Loop(*args, **kwargs)[source]¶
Bases:
NonTerminalInstructionA loop.
- child_attrs = ('statements',)¶
- index¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- statements¶
- class pyop3.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.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.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.Mat(row_axes, column_axes, buffer, *, name=None, prefix=None, transform=None)[source]¶
Bases:
TensorA matrix.
- DEFAULT_MAT_INIT_BUFFER_SPEC = MonolithicPetscMatInitBufferSpec(mat_type='aij', block_shape=((), ()))¶
- DEFAULT_PREFIX = 'mat'¶
- buffer¶
- column_axes¶
- property comm¶
- property dim¶
- property dtype¶
- classmethod empty(row_axes, column_axes, *, buffer_spec=None, preallocator=False, buffer_kwargs=immutabledict({}), **kwargs)[source]¶
- property handle¶
- property local_max¶
- property local_min¶
- name¶
- classmethod null(row_axes, column_axes, dtype=dtype('float64'), *, buffer_kwargs=immutabledict({}), **kwargs)[source]¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- row_axes¶
- property transform¶
- property values¶
- class pyop3.MonolithicPetscMatBufferSpec(mat_type, row_spec, column_spec)[source]¶
Bases:
PetscMatBufferSpecMonolithicPetscMatBufferSpec(mat_type: ‘str’, row_spec: ‘PetscMatAxisSpec | pyop3.axis_tree.AbstractAxisTree’, column_spec: ‘PetscMatAxisSpec | pyop3.axis_tree.AbstractAxisTree’)
- column_spec¶
- property comm¶
- mat_type¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- row_spec¶
- class pyop3.MonolithicPetscMatInitBufferSpec(mat_type, block_shape=((), ()))[source]¶
Bases:
PetscMatInitBufferSpecMonolithicPetscMatInitBufferSpec(mat_type: ‘str’, block_shape: ‘tuple[tuple[int, …], tuple[int, …]]’ = ((), ()))
- block_shape = ((), ())¶
- mat_type¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- class pyop3.NaN[source]¶
Bases:
TerminalExpressionNaN()
- property dtype¶
- get_instruction_executor_cache_key(visitor)¶
- property local_max¶
- property local_min¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- class pyop3.NestedPetscMatBufferSpec(submat_specs)[source]¶
Bases:
PetscMatBufferSpecNestedPetscMatBufferSpec(submat_specs: ‘np.ndarray’)
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- property shape¶
- submat_specs¶
- class pyop3.NestedPetscMatInitBufferSpec(submat_specs)[source]¶
Bases:
PetscMatInitBufferSpecNestedPetscMatInitBufferSpec(submat_specs: ‘np.ndarray’)
- mat_type = 'nest'¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- submat_specs¶
- class pyop3.NullBuffer(shape, dtype=None, *, name=None, prefix=None, ordered=False)[source]¶
Bases:
AbstractArrayBufferA buffer that does not carry data.
This is useful for handling temporaries when we generate code. For much of the compilation we want to treat temporaries like ordinary arrays but they are not passed as kernel arguments nor do they have any parallel semantics.
- DEFAULT_PREFIX = 'tmp'¶
- property comm¶
- property dtype¶
- property name¶
- property ordered¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- property shape¶
- class pyop3.OpaqueTerminal(buffer_view, *, name=None, prefix=None)[source]¶
Bases:
NamedTerminalExpressionA data object that we don’t know anything about but the local kernel does.
This class is useful for blindly passing arguments into local kernels without doing any packing/unpacking.
- DEFAULT_PREFIX = 'opaque'¶
- property buffer¶
- buffer_view¶
- property comm¶
- get_instruction_executor_cache_key(visitor)¶
- name¶
- nest_indices = ()¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- class pyop3.OutOfPlaceCallableTensorTransform(transform_in, transform_out, prev=None)[source]¶
Bases:
CallableTensorTransformOutOfPlaceCallableTensorTransform(transform_in: ‘Callable[[Tensor, Tensor], None]’, transform_out: ‘Callable[[Tensor, Tensor], None]’, prev: ‘TensorTransform | None’ = None)
- prev = None¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- transform_in¶
- transform_out¶
- class pyop3.PetscMatBuffer(mat, *, comm, mat_spec=None, name=None, prefix=None, constant=False)[source]¶
Bases:
ConcreteBufferA buffer whose underlying data structure is a PETSc Mat.
- Parameters:
mat_spec (pyop3.buffer.PetscMatBufferSpec | None) – Only used for preallocation matrices… and actually the only real information is the matrix type, which could be an argument to materialize…
- DEFAULT_PREFIX = 'petscmat'¶
- property comm¶
- property constant¶
- dtype = dtype('float64')¶
- property insert_mode¶
- property is_nested¶
- property mat¶
- mat_spec¶
- property mat_type¶
- property name¶
- rank_equal = False¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- property state¶
- class pyop3.Scalar(value=None, comm=None, *, buffer=None, constant=None, name=None, prefix=None)[source]¶
Bases:
TensorA scalar value.
- DEFAULT_DTYPE = dtype('float64')¶
- DEFAULT_PREFIX = 'scalar'¶
- as_array(mode)[source]¶
Return a view of the scalar’s buffer.
- Parameters:
mode – The access mode: read-only, write-only, or read-write.
- Returns:
A view of the buffer with the requested access mode.
- Return type:
- axis_trees = ()¶
- buffer¶
- property comm¶
- property constant¶
- dim = 0¶
- property local_max¶
- property local_min¶
- loop_axes = immutabledict({})¶
- name¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- shape = (_UnitAxisTree(),)¶
- size = 1¶
- transform = None¶
- property value¶
- class pyop3.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.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.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.SliceComponent[source]¶
Bases:
LabeledNodeComponent,ABC- abstract property component¶
- abstract property is_full_slice¶
- class pyop3.StarForest(sf, comm)[source]¶
Bases:
AbstractStarForestConvenience wrapper for a \(petsc4py.SF\).
- property comm¶
- property graph¶
- property ileaf¶
- property ilocal¶
- property iremote¶
- property nleaves¶
- property num_ghost¶
- property num_owned¶
- record_new(**attrs)¶
Create and initialise a new record from an existing one.
- sf¶
- property size¶
- class pyop3.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.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.Tensor[source]¶
Bases:
TerminalExpression,ABC- DEFAULT_PREFIX = 'array'¶
- assign(other, /, mode='write', *, eager=False, eager_strategy=None, compiler_parameters=None, **kwargs)[source]¶
- abstract property axis_trees¶
- property comm¶
- copy(*, constant=None)[source]¶
Return a copy of the tensor.
- Parameters:
constant – Is the copy mutable or not? If \(None\) then default to the const-ness of the original object.
- property data¶
- property data_ro¶
Return a read-only view of the data stored by the dat.
- property data_rw¶
Return a modifiable view of the data stored by the dat.
- property data_wo¶
Return a write-only view of the data stored by the dat.
- abstract property dim¶
- property dtype¶
- duplicate(*, copy=False, constant=None)[source]¶
Return a duplicate of the tensor.
- Parameters:
copy – Whether to copy values to the new object.
constant – Is the duplicate mutable or not? If \(None\) then default to the const-ness of the original object.
- abstract property size¶
- abstract property transform¶
- pyop3.collect_axis_vars(obj, /)[source]¶
- pyop3.collect_axis_vars(op)
- pyop3.collect_axis_vars(var)
- pyop3.collect_axis_vars(var)
- pyop3.collect_axis_vars(var)
- pyop3.collect_axis_vars(var)
- pyop3.collect_axis_vars(dat, /)
- pyop3.collect_axis_vars(dat, /)
- pyop3.evaluate(expr, *, axis_vars=None, loop_indices=None, name_vars=immutabledict({}), allow_missing=False)[source]¶
- pyop3.loop(*args, eager=False, **kwargs)¶
Notes
This function has a trailing underscore to avoid clashing with any variables called
loop. It is exported asop3.loop.
- pyop3.offloading(dev)[source]¶
Context Manager for offloading components to select device This function should be the only way to modfiy the current device variable
Updates current context to the given \(dev\) variable. Former device is stored in stack, to be restored when finished - This also allows for stacking of context windows
Context variables are also async safe.
— Example:
gpu = op3.CUDAGPU() with op3.offloading(gpu): g.dat.assign(23, eager=True, eager_strategy="array")
