from __future__ import annotations
import abc
import typing
import weakref
from collections.abc import Callable, Hashable
from typing import ClassVar, Literal, Self
import numpy as np
from mpi4py import MPI
from petsc4py import PETSc
import pyop3.cache
import pyop3.record
from pyop3.axis_tree.tree import AbstractNonUnitAxisTree
from pyop3.cache import cached_method
from pyop3.exceptions import InvalidIndexCountException
from pyop3.expr import TerminalExpression
from pyop3.expr.base import ExpressionT
if typing.TYPE_CHECKING:
import pyop3.insn
import pyop3.insn.exec
[docs]
class Tensor(TerminalExpression, abc.ABC):
DEFAULT_PREFIX: ClassVar[str] = "array"
@property
def comm(self) -> MPI.Comm:
return self.buffer.comm
[docs]
def __getitem__(self, indices):
# Handle the fact that 'obj[123]' sets 'indices' to '123' (not a tuple)
# but 'obj[123, 456]' sets it to '(123, 456)' (a tuple).
if not isinstance(indices, tuple):
indices = (indices,)
if len(indices) != self.dim:
raise InvalidIndexCountException(
f"Wrong number of indices provided during indexing. Expected {self.dim} but got {len(indices)}.")
return self.getitem(*indices, strict=False)
# Since __getitem__ is implemented, this class is implicitly considered
# to be iterable (which it's not). This avoids some confusing behaviour.
__iter__ = None
# {{{ abstract methods
__abstract_record_attrs = ("name", "buffer")
@property
@abc.abstractmethod
def transform(self):
pass
@property
@abc.abstractmethod
def dim(self) -> int:
pass
@property
@abc.abstractmethod
def size(self) -> int:
pass
[docs]
@abc.abstractmethod
def getitem(self, *indices, strict=False):
pass
[docs]
@abc.abstractmethod
def with_axis_trees(self, trees):
pass
[docs]
def assemble(self) -> None:
"""Ensure that values are up-to-date."""
self.buffer.assemble()
@property
@abc.abstractmethod
def axis_trees(self) -> tuple[AbstractNonUnitAxisTree, ...]:
pass
# }}}
# {{{ arithmetic
def __iadd__(self, other: ExpressionT, /) -> Self:
if other != 0:
self.iassign(other, eager=True)
return self
def __isub__(self, other: ExpressionT, /) -> Self:
if other != 0:
self.iassign(-other, eager=True)
return self
def __imul__(self, other: ExpressionT, /) -> Self:
if other != 1:
self.assign(self*other, eager=True)
return self
def __itruediv__(self, other: ExpressionT, /) -> Self:
if other != 1:
self.assign(self/other, eager=True)
return self
# }}}
@property
def dtype(self) -> np.dtype:
return self.buffer.dtype
@property
def data_ro(self) -> np.ndarray:
"""Return a read-only view of the data stored by the dat."""
return self.as_array("ro")
@property
def data_wo(self) -> np.ndarray:
"""Return a write-only view of the data stored by the dat."""
return self.as_array("wo")
@property
def data_rw(self) -> np.ndarray:
"""Return a modifiable view of the data stored by the dat."""
return self.as_array("rw")
# TODO: eventually deprecate this
@property
def data(self):
return self.data_rw
[docs]
@PETSc.Log.EventDecorator()
def assign(
self,
other: ExpressionT,
/,
mode: Literal["write", "inc", "max", "min"] = "write",
*,
eager: bool = False,
eager_strategy: Literal["array", "compile"] | None = None,
compiler_parameters: pyop3.insn.exec.CompilerParametersT | None = None,
**kwargs,
) -> pyop3.insn.Assignment | None:
return self._assign(other, mode, eager=eager, eager_strategy=eager_strategy, compiler_parameters=compiler_parameters, **kwargs)
[docs]
def iassign(
self,
other: ExpressionT,
/,
*,
eager: bool = False,
eager_strategy: Literal["array", "compile"] | None = None,
compiler_parameters: pyop3.insn.exec.CompilerParametersT | None = None,
**kwargs,
) -> pyop3.insn.Assignment | None:
return self._assign(other, "inc", eager=eager, eager_strategy=eager_strategy, compiler_parameters=compiler_parameters, **kwargs)
def _assign(
self,
other: ExpressionT,
/,
mode: Literal["write", "inc", "max", "min"],
*,
eager: bool,
eager_strategy: Literal["array", "compile"] | None,
compiler_parameters: pyop3.insn.exec.CompilerParametersT | None,
**kwargs
) -> pyop3.insn.Assignment | None:
if compiler_parameters is not None and not eager:
raise ValueError("Compiler parameters can only be passed to eager operations")
if eager:
# Have we already compiled code for this assignment? If so then reuse it
# regardless of 'eager_strategy' (it will be faster).
try:
cache = self._pyop3_method_cache__symbolic_assign
except AttributeError:
pass
else:
cache_key = self._symbolic_assign.cache_key(self, other, mode, **kwargs)
try:
assign_insn = cache[cache_key]
except KeyError:
pass
else:
assign_insn(compiler_parameters=compiler_parameters)
return
if eager_strategy is None:
try:
self._array_assign(other, mode, **kwargs)
except BaseException as e:
raise e
# TODO: log a warning, or do something else sensible
self._symbolic_assign(other, mode, **kwargs)(compiler_parameters=compiler_parameters)
elif eager_strategy == "array":
self._array_assign(other, mode, **kwargs)
else:
assert eager_strategy == "compile"
self._symbolic_assign(other, mode, **kwargs)(compiler_parameters=compiler_parameters)
return
else:
if eager_strategy is not None:
raise ValueError(
"'eager_strategy' is only a valid option for eagerly evaluated assignments"
)
return self._symbolic_assign(other, mode, **kwargs)
def _symbolic_assign(self, other, /, mode: Literal["write", "inc"], **kwargs) -> pyop3.insn.Assignment:
import pyop3
from pyop3.insn import Assignment
if bool(pyop3.expr.visitors.collect_loop_index_vars(self)):
# Cannot count on self to persist, assume the assignment holds the main reference
return Assignment(self, other, mode)
else:
return self._symbolic_assign_cached(other, mode, **kwargs)
@cached_method(make_cache=lambda: pyop3.cache.LRUCache(5))
def _symbolic_assign_cached(
self,
other,
/,
mode: Literal["write", "inc"],
_weakref: bool = True,
) -> pyop3.insn.Assignment:
from pyop3.insn import Assignment
# We want to cache the assignment instruction for performance but the
# reference cycles this creates are so complicated that they seem to
# be entirely invisible to the garbage collector. We therefore pass
# a weakref here instead of self.
# We pass a weakref.ref instead of a weakref.proxy because consumers
# do actually need to know that they have been passed a weakref-ed
# object and weakref.proxy objects don't advertise that information.
# In some circumstances (e.g. during compiler passes) we generate
# assignments where the assignment persists and needs to hold a
# reference to the assignee, not the other way around. The '_weakref'
# flag allows us to control this.
assignee = weakref.ref(self) if _weakref else self
return Assignment(assignee, other, mode)
def _array_assign(self, other: ExpressionT, /, mode: Literal["write", "inc", "max", "min"]) -> None:
from pyop3.expr.visitors import evaluate_arraywise
other_eval = evaluate_arraywise(other)
match mode:
case "write":
self.data_wo[...] = other_eval
case "inc":
self.data_rw[...] += other_eval
case "max":
data = self.data_rw
np.maximum(data, other_eval, out=data)
case "min":
data = self.data_rw
np.minimum(data, other_eval, out=data)
case _:
raise AssertionError(f"Assignment mode '{mode}' not recognised")
[docs]
@PETSc.Log.EventDecorator()
def zero(self, **kwargs) -> pyop3.insn.Assignment | None:
return self.assign(0, **kwargs)
[docs]
def duplicate(self, *, copy: bool = False, constant: bool | None = None) -> Tensor:
"""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.
"""
name = f"{self.name}_copy"
buffer = self.buffer.duplicate(copy=copy, constant=constant)
return self.record_new(_name=name, _buffer=buffer)
[docs]
def copy(self, *, constant: bool | None = None) -> Tensor:
"""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.
"""
return self.duplicate(copy=True, constant=constant)
[docs]
def concretize(self):
"""Convert to an expression, can no longer be indexed properly"""
raise NotImplementedError
[docs]
def with_context(self, context) -> Self:
new_axis_trees = []
for axis_tree in self.axis_trees:
if isinstance(axis_tree, pyop3.index_tree.LoopContextSensitive):
cf_axis_tree = axis_tree.with_context(context)
else:
cf_axis_tree = axis_tree
new_axis_trees.append(cf_axis_tree)
return self.with_axis_trees(new_axis_trees)
# NOTE: No idea if this is where this should live, quite possibly this is wrong
# @property
# @abc.abstractmethod
# def nest_indices(self) -> tuple[tuple[int, int], ...]:
# pass