from __future__ import annotations
import itertools
import numbers
import operator
import weakref
from collections.abc import Hashable
from functools import cached_property
from typing import TYPE_CHECKING, Any, ClassVar, Self
import numpy as np
from immutabledict import immutabledict as idict
from mpi4py import MPI
from petsc4py import PETSc
import pyop3.buffer
import pyop3.dtypes
import pyop3.index_tree
import pyop3.record
from pyop3 import utils
from pyop3.axis_tree import (
AbstractNonUnitAxisTree,
Axis,
AxisTree,
as_axis_tree,
as_axis_tree_type,
)
from pyop3.dtypes import ScalarType
from .base import ReshapeTensorTransform, Tensor, TensorTransform
if TYPE_CHECKING:
from pyop3.types import *
[docs]
@pyop3.record.record()
class Mat(Tensor):
"""A matrix."""
# {{{ instance attributes
row_axes: pyop3.axis_tree.LoopContextAwareAxisTreeLike
column_axes: pyop3.axis_tree.LoopContextAwareAxisTreeLike
buffer: pyop3.buffer.AbstractBuffer
name: str
_transform: TensorTransform | None
[docs]
def get_instruction_executor_cache_key(self, visitor) -> Hashable:
# buffers in the axis trees aren't allowed to change
with visitor.identity_hash_buffers():
row_axes_key = visitor(self.row_axes)
column_axes_key = visitor(self.column_axes)
return (
type(self),
row_axes_key,
column_axes_key,
visitor(self.buffer),
visitor(self._transform),
)
def __init__(
self,
row_axes: pyop3.axis_tree.LoopContextAwareAxisTreeLike,
column_axes: pyop3.axis_tree.LoopContextAwareAxisTreeLike,
buffer: pyop3.buffer.AbstractBuffer,
*,
name: str | None = None,
prefix: str | None = None,
transform=None,
) -> None:
if not isinstance(buffer, pyop3.buffer.AbstractBuffer):
raise TypeError(f"Provided buffer has the wrong type ({type(buffer).__name__})")
row_axes = as_axis_tree_type(row_axes)
column_axes = as_axis_tree_type(column_axes)
name = utils.maybe_generate_name(name, prefix, self.DEFAULT_PREFIX)
object.__setattr__(self, "row_axes", row_axes)
object.__setattr__(self, "column_axes", column_axes)
object.__setattr__(self, "buffer", buffer)
object.__setattr__(self, "name", name)
object.__setattr__(self, "_transform", transform)
def __record_post_init(self) -> None:
if isinstance(self.buffer, pyop3.buffer.AbstractArrayBuffer):
assert len(self.buffer.shape) == 2
# }}}
@property
def comm(self) -> MPI.Comm:
return pyop3.mpi.common_comm([self.row_axes.comm, self.column_axes.comm])
# {{{ class attrs
DEFAULT_PREFIX: ClassVar[str] = "mat"
DEFAULT_MAT_INIT_BUFFER_SPEC: ClassVar[pyop3.buffer.PetscMatInitBufferSpec] = pyop3.buffer.MonolithicPetscMatInitBufferSpec(PETSc.Mat.Type.AIJ)
# }}}
# {{{ interface impls
transform: ClassVar[property] = pyop3.record.attr("_transform")
@property
def local_max(self) -> numbers.Number:
raise NotImplementedError
@property
def local_min(self) -> numbers.Number:
raise NotImplementedError
@property
def _full_str(self) -> str:
return f"{self.name}[?, ?]"
# }}}
# {{{ factory methods
[docs]
@classmethod
def empty(
cls,
row_axes,
column_axes,
*,
buffer_spec: pyop3.buffer.PetscMatInitBufferSpec | None = None,
preallocator: bool = False,
buffer_kwargs: KwargsT = idict(),
**kwargs,
) -> Mat:
if isinstance(row_axes, pyop3.axis_tree.Axis):
row_axes = row_axes.as_tree()
if isinstance(column_axes, pyop3.axis_tree.Axis):
column_axes = column_axes.as_tree()
if buffer_spec is None:
buffer_spec = cls.DEFAULT_MAT_INIT_BUFFER_SPEC
comm = pyop3.mpi.common_comm([row_axes.comm, column_axes.comm])
full_spec = make_full_mat_buffer_spec(buffer_spec, row_axes, column_axes)
buffer = pyop3.buffer.PetscMatBuffer.empty(full_spec, preallocator=preallocator, comm=comm, **buffer_kwargs)
return cls(row_axes, column_axes, buffer=buffer, **kwargs)
[docs]
@classmethod
def sparsity(cls, row_axes, column_axes, **kwargs) -> Mat:
return cls.empty(row_axes, column_axes, preallocator=True, **kwargs)
[docs]
@classmethod
def null(cls, row_axes, column_axes, dtype=pyop3.buffer.AbstractBuffer.DEFAULT_DTYPE, *, buffer_kwargs: KwargsT = idict(), **kwargs) -> Mat:
row_axes = as_axis_tree(row_axes)
column_axes = as_axis_tree(column_axes)
buffer = pyop3.buffer.NullBuffer(
(row_axes.unindexed.local_max_size, column_axes.unindexed.local_max_size),
dtype=dtype,
**buffer_kwargs,
)
return cls(row_axes, column_axes, buffer=buffer, **kwargs)
# }}}
# {{{ (more) interface impls (tidy me)
[docs]
def materialize(self) -> Mat:
"""Return a new "unindexed" array with the same shape."""
# TODO: use axis forests instead of trees here
return type(self).null(
self.row_axes.materialize().regionless(),
self.column_axes.materialize().regionless(),
dtype=self.dtype,
prefix="t",
)
@property
def dim(self) -> int:
return 2
# NOTE: We overload here because PetscMat.dtype doesn't exist. We should wrap Mats in
# a different buffer type.
@property
def dtype(self) -> np.dtype:
return ScalarType
# NOTE: is this used?
[docs]
@cached_property
def nrows(self) -> int:
"The number of local rows in the matrix (including ghosts)."
return self.row_axes.local_size
# NOTE: is this used?
[docs]
@cached_property
def ncols(self) -> int:
"The number of local columns in the matrix (including ghosts)."
return self.column_axes.local_size
[docs]
def getitem(self, row_index, column_index, *, strict=False):
# (old comment, still useful exposition)
# Combine the loop contexts of the row and column indices. Consider
# a loop over a multi-component axis with components "a" and "b":
#
# loop(p, mat[p, p])
#
# The row and column index forests with "merged" loop contexts would
# look like:
#
# {
# {p: "a"}: [rtree0, ctree0],
# {p: "b"}: [rtree1, ctree1]
# }
#
# By contrast, distinct loop indices are combined as a product, not
# merged. For example, the loop
#
# loop(p, loop(q, mat[p, q]))
#
# with p still a multi-component loop over "a" and "b" and q the same
# over "x" and "y". This would give the following combined set of
# index forests:
#
# {
# {p: "a", q: "x"}: [rtree0, ctree0],
# {p: "a", q: "y"}: [rtree0, ctree1],
# {p: "b", q: "x"}: [rtree1, ctree0],
# {p: "b", q: "y"}: [rtree1, ctree1],
# }
indexed_row_axes = self.row_axes.getitem(row_index, strict=strict)
indexed_column_axes = self.column_axes.getitem(column_index, strict=strict)
return self.record_new(row_axes=indexed_row_axes, column_axes=indexed_column_axes)
[docs]
def with_axis_trees(self, axis_trees):
row_axes, column_axes = axis_trees
return self.record_new(row_axes=row_axes, column_axes=column_axes)
[docs]
def with_axes(self, row_axes, column_axes) -> Self:
"""Return a view of the current mat with new axes."""
return self.with_axis_trees([row_axes, column_axes])
[docs]
def null_like(self, **kwargs) -> Mat:
return self.null(self.row_axes, self.column_axes, dtype=self.dtype, **kwargs)
# }}}
[docs]
def reshape(self, row_axes: AxisTree, column_axes: AxisTree) -> Mat:
"""Return a reshaped view of the `Mat`.
TODO
"""
assert isinstance(row_axes, AxisTree), "not indexed"
assert isinstance(column_axes, AxisTree), "not indexed"
return self.record_new(
row_axes=row_axes,
column_axes=column_axes,
_transform=ReshapeTensorTransform((self.row_axes, self.column_axes), self.transform)
)
[docs]
@cached_property
def size(self) -> Any:
return self.row_axes.size * self.column_axes.size
[docs]
@cached_property
def axis_trees(self) -> tuple[AbstractNonUnitAxisTree, AbstractNonUnitAxisTree]:
return (self.row_axes, self.column_axes)
[docs]
@classmethod
def from_sparsity(cls, sparsity, **kwargs):
buffer = sparsity.buffer.materialize()
return cls(sparsity.row_axes, sparsity.column_axes, buffer, **kwargs)
def _array_assign(self, other: ExpressionT, /, mode: Literal[write, inc]) -> None:
try:
# In some cases mat.data_XX is allowed. For example for read-only access
# or if the mat is a MATPYTHON and thus holds a buffer
super()._array_assign(other, mode)
except pyop3.exceptions.InvalidArrayAccessException:
# TODO: This is a generic property of axis trees
is_unindexed = all(
ax.buffer_size(include_ghosts=True) == ax.unindexed.buffer_size(include_ghosts=True)
for ax in [self.row_axes, self.column_axes]
)
if is_unindexed and other == 0:
if mode == "write":
self.buffer.zero()
else:
# inc-ing zero means to do nothing
pass
else:
raise NotImplementedError("Matrix assignment needs special consideration")
# TODO: better to have .data? but global vs local?
@property
def values(self):
if self.comm.size > 1:
raise RuntimeError("Only valid in serial")
return self.as_array("ro")
[docs]
def as_array(self, mode):
self.assemble()
if isinstance(self.buffer, pyop3.buffer.PetscMatBuffer):
mat = self.buffer.mat
row_axes = self.row_axes
column_axes = self.column_axes
nest_indices = iter(self.nest_indices)
while mat.type == PETSc.Mat.Type.NEST:
(row_label, irow), (col_label, icol) = next(nest_indices)
mat = mat.getNestSubMatrix(irow, icol)
if row_label is not None:
row_axes = row_axes.restrict_nest(row_label)
if col_label is not None:
column_axes = column_axes.restrict_nest(col_label)
if mat.type == PETSc.Mat.Type.PYTHON:
context = mat.getPythonContext()
if isinstance(context, pyop3.buffer.DenseRowPythonMatContext):
row_indices = slice(None)
column_indices = column_axes.buffer_slice(include_ghosts=True)
elif isinstance(context, pyop3.buffer.DenseColumnPythonMatContext):
row_indices = row_axes.buffer_slice(include_ghosts=True)
column_indices = slice(None)
elif isinstance(context, pyop3.buffer.DenseBlockPythonMatContext):
row_indices = slice(None)
column_indices = slice(None)
else:
raise NotImplementedError
match mode:
case "ro":
array = mat.getPythonContext().buffer.data_ro
case "rw":
array = mat.getPythonContext().buffer.data_rw
case "wo":
array = mat.getPythonContext().buffer.data_wo
case _:
raise AssertionError
return self._array_view(array, row_indices, column_indices, mode)
else:
if mode != "ro":
raise pyop3.exceptions.InvalidArrayAccessException
row_indices = row_axes.buffer_slice(include_ghosts=True)
column_indices = column_axes.buffer_slice(include_ghosts=True)
return mat[row_indices, column_indices]
elif isinstance(self.buffer, pyop3.buffer.ArrayBuffer):
match mode:
case "ro":
getter = operator.attrgetter("data_ro")
case "rw":
getter = operator.attrgetter("data_rw")
case "wo":
getter = operator.attrgetter("data_wo")
case _:
raise AssertionError
row_indices = self.row_axes.buffer_slice(include_ghosts=True)
column_indices = self.column_axes.buffer_slice(include_ghosts=True)
return getter(self.buffer)[row_indices, column_indices]
else:
raise NotImplementedError
@staticmethod
def _array_view(array, row_indices, column_indices, mode):
block_shape = () # for now
if mode == "ro" or all(isinstance(idxs, slice) for idxs in [row_indices, column_indices]):
# Either using a view or readonly, safe to use numpy indexing as
# writeback issues are not relevant
array = array[row_indices, column_indices]
# trick to get around a numpy error for zero sized things
shape = (-1, *block_shape) if array.size > 0 else (0, *block_shape)
return array.reshape(shape, copy=False)
else:
return pyop3.arrayref.ArrayReference(array, (row_indices, column_indices), block_shape)
# For PyOP2 compatibility
@property
def handle(self):
return self.buffer.mat
[docs]
@cached_property
def nest_indices(self):
indices = []
row_axes = self.row_axes
column_axes = self.column_axes
for row_nest_label, col_nest_label in itertools.zip_longest(
self.row_axes.nest_labels, self.column_axes.nest_labels
):
if row_nest_label:
row_axis, row_component = row_nest_label
root = row_axes.unindexed.root
assert root.label == row_axis
irow = root.component_labels.index(row_component)
row_axes = row_axes.restrict_nest(row_component)
else:
row_component = None
irow = 0
if col_nest_label:
col_axis, col_component = col_nest_label
root = column_axes.unindexed.root
assert root.label == col_axis
icol = root.component_labels.index(col_component)
column_axes = column_axes.restrict_nest(col_component)
else:
col_component = None
icol = 0
indices.append(((row_component, irow), (col_component, icol)))
indices = tuple(indices)
if self.transform:
return self.transform.nest_indices + indices
else:
return indices
[docs]
def make_full_mat_buffer_spec(
partial_spec: pyop3.buffer.PetscMatInitBufferSpec,
row_axes: AbstractNonUnitAxisTree,
column_axes: AbstractNonUnitAxisTree,
) -> pyop3.buffer.PetscMatBufferSpec:
import pyop3.visitors
if isinstance(partial_spec, pyop3.buffer.MonolithicPetscMatInitBufferSpec):
comm = pyop3.visitors.common_comm([row_axes, column_axes])
if partial_spec.mat_type in {"denserow", "densecol"}:
row_spec = row_axes
column_spec = column_axes
else:
nrows = row_axes.free.buffer_size(include_ghosts=False)
ncolumns = column_axes.free.buffer_size(include_ghosts=False)
row_block_shape, column_block_shape = partial_spec.block_shape
if row_block_shape:
blocked_row_axes = row_axes.blocked(row_block_shape)
else:
blocked_row_axes = row_axes
if column_block_shape:
blocked_column_axes = column_axes.blocked(column_block_shape)
else:
blocked_column_axes = column_axes
row_block_size = np.prod(row_block_shape, dtype=pyop3.dtypes.IntType)
column_block_size = np.prod(column_block_shape, dtype=pyop3.dtypes.IntType)
row_lgmap = PETSc.LGMap().create(blocked_row_axes.global_numbering.data_ro_with_halos.copy(), bsize=row_block_size, comm=comm)
column_lgmap = PETSc.LGMap().create(blocked_column_axes.global_numbering.data_ro_with_halos.copy(), bsize=column_block_size, comm=comm)
row_spec = pyop3.buffer.PetscMatAxisSpec(nrows, row_lgmap, row_block_shape)
column_spec = pyop3.buffer.PetscMatAxisSpec(ncolumns, column_lgmap, column_block_shape)
full_spec = pyop3.buffer.MonolithicPetscMatBufferSpec(partial_spec.mat_type, row_spec, column_spec)
else: # MATNEST
assert isinstance(partial_spec, pyop3.buffer.NestedPetscMatInitBufferSpec)
full_spec = np.empty_like(partial_spec.submat_specs)
for i, (index_key, sub_partial_spec) in np.ndenumerate(partial_spec.submat_specs):
row_index, column_index = index_key
if row_index is not Ellipsis:
sub_row_axes = row_axes[row_index].restrict_nest(row_index)
else:
sub_row_axes = row_axes
if column_index is not Ellipsis:
sub_column_axes = column_axes[column_index].restrict_nest(column_index)
else:
sub_column_axes = column_axes
sub_spec = make_full_mat_buffer_spec(sub_partial_spec, sub_row_axes, sub_column_axes)
full_spec[i] = sub_spec
full_spec = pyop3.buffer.NestedPetscMatBufferSpec(full_spec)
return full_spec
# TODO: Should inherit from SymbolicTensor/SymbolicMat
[docs]
@pyop3.record.record()
class AggregateMat(pyop3.obj.Object):
"""A matrix formed of multiple submatrices concatenated together."""
# {{{ instance attrs
submats: np.ndarray[Mat]
row_axis: Axis
column_axis: Axis
name: str
[docs]
def get_instruction_executor_cache_key(self, visitor) -> Hashable:
return (
type(self),
tuple(map(visitor, self.submats.flatten())),
visitor(self.row_axis),
visitor(self.column_axis),
)
def __init__(
self,
submats,
row_axis: Axis,
column_axis: Axis,
*,
name: str | None = None,
prefix: str | None = None,
) -> None:
name = utils.maybe_generate_name(name, prefix, self.DEFAULT_PREFIX)
# TODO: check size 1 for each axis component and # components must match # subdats
object.__setattr__(self, "submats", submats)
object.__setattr__(self, "row_axis", row_axis)
object.__setattr__(self, "column_axis", column_axis)
object.__setattr__(self, "name", name)
# }}}
@property
def comm(self) -> MPI.Comm:
return utils.single_valued(m.comm for m in self.submats.flatten())
DEFAULT_PREFIX: ClassVar[str] = "aggmat"
def __iter__(self):
subitems = []
for (ri, ci), submat in np.ndenumerate(self.submats):
row_index = pyop3.index_tree.ScalarIndex(
self.row_axis.label, self.row_axis.component_labels[ri], 0
)
column_index = pyop3.index_tree.ScalarIndex(
self.column_axis.label, self.column_axis.component_labels[ci], 0
)
subitems.append(((row_index, column_index), submat))
return iter(subitems)
@property
def subtensors(self):
return self.submats
[docs]
def with_context(self, context):
cf_submats = np.empty_like(self.submats)
for loc, submat in np.ndenumerate(self.submats):
cf_submats[loc] = submat.with_context(context)
return self.record_new(submats=cf_submats)
[docs]
@cached_property
def row_axes(self) -> AxisTree:
sub_axess = tuple(
utils.single_valued(
row_submat.row_axes.materialize() for row_submat in row_submats
)
for row_submats in self.submats
)
axes = AxisTree(self.row_axis)
for leaf_path, subtree in zip(axes.leaf_paths, sub_axess, strict=True):
axes = axes.add_subtree(leaf_path, subtree)
return axes
[docs]
@cached_property
def column_axes(self) -> AxisTree:
sub_axess = tuple(
utils.single_valued(
column_submat.column_axes.materialize()
for column_submat in column_submats
)
for column_submats in self.submats.T
)
axes = AxisTree(self.column_axis)
for leaf_path, subtree in zip(axes.leaf_paths, sub_axess, strict=True):
axes = axes.add_subtree(leaf_path, subtree)
return axes
@property
def dtype(self):
return utils.single_valued(submat.dtype for submat in self.submats.flatten())
[docs]
def materialize(self):
return Mat.null(self.row_axes, self.column_axes, dtype=self.dtype)
[docs]
def assign(self, other, *, _weakref: bool = True):
from pyop3.insn import Assignment
assignee = weakref.ref(self) if _weakref else self
return Assignment(assignee, other, "write")
[docs]
def iassign(self, other, *, _weakref: bool = True):
from pyop3.insn import Assignment
assignee = weakref.ref(self) if _weakref else self
return Assignment(assignee, other, "inc")