Source code for pyop3.insn.visitors

from __future__ import annotations

import functools
import numbers
from typing import Any

import numpy as np
from immutabledict import immutabledict as idict

import pyop3.axis_tree
import pyop3.cc
import pyop3.expr
import pyop3.expr.visitors
import pyop3.insn
from pyop3 import utils
from pyop3.axis_tree import AxisForest
from pyop3.buffer import (
    ArrayBuffer,
    ConcreteBuffer,
    PetscMatBuffer,
)
from pyop3.constants import INC, MAX_RW, MAX_WRITE, MIN_RW, MIN_WRITE, READ, RW, WRITE
from pyop3.dtypes import dtype_limits
from pyop3.expr import (
    Dat,
    LinearDatBufferExpression,
    Mat,
    MatPetscMatBufferExpression,
    Scalar,
    Tensor,
)
from pyop3.expr.buffer import MatArrayBufferExpression
from pyop3.expr.tensor.dat import AggregateDat
from pyop3.expr.tensor.mat import AggregateMat
from pyop3.index_tree.parse import _as_context_free_indices
from pyop3.insn.base import (
    ArrayAccessType,
    AssignmentType,
    maybe_enlist,
)
from pyop3.node import NodeTransformer, NodeVisitor, postorder


[docs] class InstructionTransformer(NodeTransformer):
[docs] @functools.singledispatchmethod def process(self, insn: pyop3.insn.Instruction, /, **kwargs) -> pyop3.insn.Instruction: return super().process(insn, **kwargs)
# Instruction lists have a common pattern @process.register(pyop3.insn.InstructionList) @postorder def _(self, insn_list: pyop3.insn.InstructionList, /, *insns, **kwargs) -> pyop3.insn.Instruction: raise NotImplementedError return maybe_enlist(insns)
[docs] class LoopContextExpander(InstructionTransformer):
[docs] @functools.singledispatchmethod def process(self, insn: pyop3.insn.Instruction, /, **kwargs) -> pyop3.insn.Instruction: return super().process(insn, **kwargs)
@process.register(pyop3.insn.Loop) def _(self, loop: pyop3.insn.Loop, /, *, loop_context) -> pyop3.insn.Loop | pyop3.insn.InstructionList: expanded_loops = [] iterset = loop.index.iterset for leaf_path in iterset.leaf_paths: loop_context_ = {loop.index.id: leaf_path} restricted_loop_index = utils.just_one(_as_context_free_indices(loop.index, loop_context_)) # (not always safe to do) # # skip empty loops # if restricted_loop_index.iterset.size == 0: # continue loop_context_acc_ = loop_context | loop_context_ expanded_loop = type(loop)( restricted_loop_index, [ self(stmt, loop_context=loop_context_acc_) for stmt in loop.statements ] ) expanded_loops.append(expanded_loop) return maybe_enlist(expanded_loops) @process.register(pyop3.insn.CalledFunction) def _(self, func: pyop3.insn.CalledFunction, /, *, loop_context) -> pyop3.insn.CalledFunction: new_arguments = tuple(arg.with_context(loop_context) for arg in func.arguments) return func.record_new(_arguments=new_arguments) @process.register(pyop3.insn.Assignment) def _(self, assignment: pyop3.insn.Assignment, /, *, loop_context) -> pyop3.insn.Assignment: assignee = pyop3.expr.visitors.restrict_to_context(assignment.assignee, loop_context) expression = pyop3.expr.visitors.restrict_to_context(assignment.expression, loop_context) return assignment.record_new(_assignee=assignee, expression=expression) @process.register(pyop3.insn.Exscan) # for now assume we are fine def _(self, insn: pyop3.insn.Instruction, /, **kwargs) -> pyop3.insn.Instruction: return self.reuse_if_untouched(insn)
# NOTE: This is a bad name for this transformation. 'expand_multi_component_loops'?
[docs] def expand_loop_contexts(insn: pyop3.insn.Instruction, /) -> pyop3.insn.Instruction: return LoopContextExpander()(insn, loop_context=idict())
@functools.singledispatch def _requires_pack_unpack(arg: pyop3.insn.FunctionArgument) -> bool: utils.raise_missing_dispatch_handler(arg) @_requires_pack_unpack.register def _(opaque: pyop3.expr.OpaqueTerminal) -> bool: return False @_requires_pack_unpack.register(Scalar) def _(scalar: Scalar) -> bool: if scalar.transform: raise NotImplementedError return False @_requires_pack_unpack.register(Dat) def _(dat: Dat) -> bool: # This is overly restrictive since we could pass something contiguous like # dat[i0, :] directly to a local kernel return not (isinstance(dat.buffer, ConcreteBuffer) and _layouts_match(dat.axes) and not has_materialized_temporaries(dat)) @_requires_pack_unpack.register(Mat) def _(mat: Mat) -> bool: return not (not isinstance(mat.buffer, PetscMatBuffer) and _layouts_match(mat.row_axes) and _layouts_match(mat.column_axes) and not has_materialized_temporaries(mat)) @_requires_pack_unpack.register(AggregateDat) @_requires_pack_unpack.register(AggregateMat) def _(amat) -> bool: return True def _layouts_match(axes) -> bool: if isinstance(axes, AxisForest): return utils.strictly_all(map(_layouts_match, axes.trees)) else: return axes.leaf_subst_layouts == axes.unindexed.leaf_subst_layouts
[docs] @functools.singledispatch def expand_transforms(obj: Any, /) -> pyop3.insn.InstructionList: raise TypeError(f"No handler provided for {type(obj).__name__}")
@expand_transforms.register(pyop3.insn.InstructionList) def _(insn_list: pyop3.insn.InstructionList, /) -> pyop3.insn.InstructionList: return maybe_enlist(expand_transforms(insn) for insn in insn_list) @expand_transforms.register(pyop3.insn.Loop) def _(loop: pyop3.insn.Loop, /) -> pyop3.insn.Loop: return loop.record_new(statements=tuple(expand_transforms(s) for s in loop.statements)) @expand_transforms.register(pyop3.insn.StandaloneCalledFunction) @expand_transforms.register(pyop3.insn.NullInstruction) @expand_transforms.register(pyop3.insn.Exscan) # assume we are fine def _(func: pyop3.insn.StandaloneCalledFunction, /) -> pyop3.insn.StandaloneCalledFunction: return func def _intent_as_access_type(intent): if intent == READ: return ArrayAccessType.READ if intent == WRITE: return ArrayAccessType.WRITE else: assert intent == INC return ArrayAccessType.INC @expand_transforms.register(pyop3.insn.CalledFunction) def _(called_func: pyop3.insn.CalledFunction, /) -> pyop3.insn.InstructionList: bare_func_args = [] pack_insns = [] unpack_insns = [] for func_arg, intent in zip( called_func.arguments, called_func.function._access_descrs, strict=True ): arg_pack_insns = [] arg_unpack_insns = [] # function calls need materialised arrays if _requires_pack_unpack(func_arg): local_tensor = func_arg.materialize() if intent == READ: arg_pack_insns.append(local_tensor.assign(func_arg, _weakref=False)) elif intent == WRITE: # TODO: Some interpolation kernels for more exotic function # spaces (e.g. HHJ) do not write to all of their DoFs, and # this (somehow) results in NaNs. We get around this for # now by zeroing the temporary on entry, though I think # that this indicates an issue in the local kernel. arg_pack_insns.append(local_tensor.assign(0, _weakref=False)) arg_unpack_insns.insert(0, func_arg.assign(local_tensor, _weakref=False)) elif intent == RW: arg_pack_insns.append(local_tensor.assign(func_arg, _weakref=False)) arg_unpack_insns.insert(0, func_arg.assign(local_tensor, _weakref=False)) elif intent == INC: arg_pack_insns.append(local_tensor.assign(0, _weakref=False)) arg_unpack_insns.insert(0, func_arg.iassign(local_tensor, _weakref=False)) elif intent == MAX_RW: arg_pack_insns.append(local_tensor.assign(func_arg, _weakref=False)) arg_unpack_insns.insert(0, func_arg.assign(local_tensor, "max", _weakref=False)) elif intent == MIN_RW: arg_pack_insns.append(local_tensor.assign(func_arg, _weakref=False)) arg_unpack_insns.insert(0, func_arg.assign(local_tensor, "min", _weakref=False)) elif intent in {MAX_WRITE, MIN_WRITE}: # The temporary starts from the identity of the reduction, so # that the entries which the kernel does not write leave the # global data unchanged. mode = "max" if intent == MAX_WRITE else "min" if intent == MAX_WRITE: initial = dtype_limits(local_tensor.dtype).min else: initial = dtype_limits(local_tensor.dtype).max arg_pack_insns.append(local_tensor.assign(initial, _weakref=False)) arg_unpack_insns.insert(0, func_arg.assign(local_tensor, mode, _weakref=False)) else: raise NotImplementedError(f"Intent {intent} not handled") materialized_arg = LinearDatBufferExpression(local_tensor.buffer, 0) elif isinstance(func_arg, pyop3.expr.OpaqueTerminal): materialized_arg = func_arg else: materialized_arg = LinearDatBufferExpression(func_arg.buffer, 0) bare_func_args.append(materialized_arg) pack_insns.extend(arg_pack_insns) unpack_insns.extend(arg_unpack_insns) bare_called_func = pyop3.insn.StandaloneCalledFunction(called_func.function, bare_func_args) return maybe_enlist((*pack_insns, bare_called_func, *unpack_insns)) @expand_transforms.register(pyop3.insn.Assignment) def _(assignment: pyop3.insn.Assignment, /) -> pyop3.insn.InstructionList: # This function is complete magic and deserves some serious exposition: # # To begin with, consider the assignment: # # x <- y # # where 'y' is a transformed dat. To generate code for this assignment we # need to traverse the hierarchy of transformations and emit something like: # # t <- Y # f(t) -- in-place transform # u <- g(t) -- out-of-place transform # x <- u -- original assignment # # where 'Y' is the global data structure at the top of the transform hierarchy. # # To make this happen, in this function we 'expand' the expression 'y', # giving us back 'u' and the sequence of transformation instructions. Note # that here we are expanding the assignment *expression* (as opposed to the # assignee 'x') and so the transformation instructions are emitted in order # from global to local data structures. # # Now let's imagine what happens for 'x <- y' where the assignee ('x') is # the transformed object. We thus want to generate code like: # # t <- y # f(t) -- in-place transform # u <- g(t) -- out-of-place transform # X <- u # # where 'X' is the global data at the top of the transform hierarchy for 'x'. # Expanding the assignee will return 't' and the subsequent transformations. # Since the transformation here is applied to the assignee the transformation # instructions go from local data structures to global ones. # # Lastly, if we consider incrementing instead of assigning (i.e. 'x += y'), # then some changes are needed. We need to generate code like: # # t <- y # f(t) -- in-place transform # u <- g(t) -- out-of-place transform # X += u # # To make this work we extract the increment by materialising 'u'. bare_expression, expression_insns = pyop3.expr.visitors.expand_transforms( assignment.expression, ArrayAccessType.READ ) # AssignmentType and ArrayAccessType are different things because # you can't have assignment with READ mode. This should get cleaned up. match assignment.assignment_type: case AssignmentType.WRITE: access_type = ArrayAccessType.WRITE case AssignmentType.INC: access_type = ArrayAccessType.INC case AssignmentType.MAX: access_type = ArrayAccessType.MAX case AssignmentType.MIN: access_type = ArrayAccessType.MIN case _: raise AssertionError bare_assignee, assignee_insns = pyop3.expr.visitors.expand_transforms( assignment._assignee, access_type ) assignment_type = assignment.assignment_type if assignment_type != AssignmentType.WRITE and assignee_insns: # If we are emitting assignee transformation instruction for an # increment assignment then the final instruction must be the # increment into the global data structure. This means that we # should only write here, not increment. assert assignee_insns[-1].assignment_type != AssignmentType.WRITE assignment_type = AssignmentType.WRITE # PETSc matrix assignment requires the expression to be a materialised # temporary. Note that we expand literals at a later point, which is silly. # We should do this together. if ( # FIXME: only here because some things have a 'buffer_view' and others # a 'buffer' hasattr(bare_assignee, "buffer") and isinstance(bare_assignee.buffer, PetscMatBuffer) and isinstance(bare_expression, Mat) and not all( isinstance(t, pyop3.axis_tree.AbstractUnindexedAxisTree) for t in bare_expression.axis_trees ) ): assert not any( isinstance(t, pyop3.axis_tree.AxisForest) for t in bare_expression.axis_trees ) expression_temp = bare_expression.materialize() expression_insns += (expression_temp.assign(bare_expression),) bare_expression = expression_temp bare_assignment = assignment.record_new( _assignee=bare_assignee, expression=bare_expression, assignment_type=assignment_type, ) return maybe_enlist((*expression_insns, bare_assignment, *assignee_insns))
[docs] def has_materialized_temporaries(tensor: Tensor) -> bool: while tensor.transform: raise NotImplementedError # if isinstance(tensor.transform, pyop3.expr.OutOfPlaceTensorTransform): # return True # else: # tensor = tensor.transform.prev return False
[docs] class LiteralInserter(NodeTransformer):
[docs] @functools.singledispatchmethod def process(self, obj: Any) -> pyop3.insn.Instruction: return super().process(obj)
@process.register(pyop3.insn.InstructionList) @process.register(pyop3.insn.Loop) @process.register(pyop3.insn.Exscan) @process.register(pyop3.insn.StandaloneCalledFunction) @process.register(pyop3.insn.NullInstruction) def _(self, insn: pyop3.insn.Instruction) -> pyop3.insn.Instruction: return self.reuse_if_untouched(insn) @process.register(pyop3.insn.NonEmptyArrayAssignment) def _(self, assignment: pyop3.insn.NonEmptyArrayAssignment, /) -> pyop3.insn.NonEmptyArrayAssignment: # NOTE: This is not robust to if we have expressions that are not just ints, or # if the mat is on the rhs if ( isinstance(assignment.assignee, MatPetscMatBufferExpression) and isinstance(assignment.assignee.buffer_view.buffer, pyop3.buffer.PetscMatBuffer) and isinstance(assignment.expression, numbers.Number) ): # If we have an expression like # # mat[f(p), f(p)] <- 666 # # then we have to convert `666` into an appropriately sized temporary # for Mat{Get,Set}Values to work. row_axis_tree, column_axis_tree = assignment.axis_trees nrows = row_axis_tree.local_max_size ncols = column_axis_tree.local_max_size expr_data = np.full((nrows, ncols), assignment.expression, dtype=assignment.assignee.buffer_view.buffer.dtype) new_buffer = ArrayBuffer(expr_data, constant=True) new_expression = MatArrayBufferExpression(new_buffer, idict(), idict()) return assignment.record_new(expression=new_expression) else: return assignment
[docs] def insert_literals(insn: pyop3.insn.Instruction) -> pyop3.insn.Instruction: return LiteralInserter()(insn)
[docs] class CompilerOptionsCollector(NodeVisitor):
[docs] @functools.singledispatchmethod def process(self, obj: Any, /, *args, **kwargs): raise TypeError(f"No handler defined for {utils.pretty_type(obj)}")
@process.register @postorder def _(self, insn: pyop3.insn.InstructionList, /, visited) -> pyop3.cc.CompilerOptions: return sum(visited["instructions"], pyop3.cc.CompilerOptions()) @process.register def _(self, insn: pyop3.insn.TerminalInstruction) -> pyop3.cc.CompilerOptions: return insn.compiler_options @process.register @postorder def _(self, insn: pyop3.insn.Loop, /, visited) -> pyop3.cc.CompilerOptions: return sum(visited["statements"], pyop3.cc.CompilerOptions())
[docs] def collect_compiler_options(insn: pyop3.insn.Instruction) -> pyop3.cc.CompilerOptions: return CompilerOptionsCollector()(insn)