Source code for pyop3.buffer

from __future__ import annotations

import abc
import contextlib
import dataclasses
import functools
import numbers
from collections.abc import Callable, Hashable, Iterable, Mapping
from types import GeneratorType
from typing import Any, ClassVar, Literal, Self

import numpy as np
from mpi4py import MPI
from petsc4py import PETSc

import pyop3.config
import pyop3.device
import pyop3.obj
import pyop3.record
import pyop3.sf
from pyop3 import utils
from pyop3.cache import cached_method
from pyop3.collections import OrderedFrozenSet
from pyop3.device import Device, get_current_device, on_host
from pyop3.dtypes import IntType, ScalarType
from pyop3.sf import NullStarForest, StarForest
from pyop3.utils import (
    readonly,
)

from ._buffer_cy import set_petsc_mat_diagonal


MatTypeT = str | np.ndarray["MatTypeT"]


[docs] class IncompatibleStarForestException(Exception): pass
[docs] class DataTransferInFlightException(Exception): pass
[docs] class BadOrderingException(Exception): pass
def _not_in_flight(func): """Ensure that a method cannot be called when a transfer is in progress.""" @functools.wraps(func) def wrapper(self, *args, **kwargs): if self._finalizer is not None: raise DataTransferInFlightException( f"Not valid to call {func.__name__} with messages in-flight, " f"please call {self._finalizer.__name__} first" ) return func(self, *args, **kwargs) return wrapper def _check_finalizer(func): @functools.wraps(func) def wrapper(self, *args, **kwargs): if self._finalizer.__qualname__ != func.__qualname__: raise DataTransferInFlightException("Wrong finalizer called") return func(self, *args, **kwargs) return wrapper
[docs] class AbstractBuffer(pyop3.obj.Object): DEFAULT_PREFIX = "buffer" DEFAULT_DTYPE = ScalarType # {{{ abstract methods @property @abc.abstractmethod def name(self) -> str: pass @property @abc.abstractmethod def dtype(self) -> np.dtype: pass
[docs] @abc.abstractmethod def duplicate(self, *, copy: bool = False, constant: bool | None = None) -> AbstractBuffer: pass
[docs] @abc.abstractmethod def nest_shape( self, nest_indices: Iterable[tuple[int, ...], ...] = (), ) -> tuple[int, ...] | None: """Return the nest shape at a given level of nesting."""
# }}}
[docs] def copy(self) -> AbstractBuffer: return self.duplicate(copy=True)
[docs] class AbstractArrayBuffer(AbstractBuffer, metaclass=abc.ABCMeta): # {{{ abstract methods @property @abc.abstractmethod def shape(self) -> tuple[int, ...]: pass @property @abc.abstractmethod def ordered(self) -> bool: pass # }}} @property def size(self) -> int: return np.prod(self.shape, dtype=int)
[docs] @pyop3.record.record() class NullBuffer(AbstractArrayBuffer): """A 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. """ # {{{ instance attrs _shape: tuple[int, ...] _name: str _dtype: np.dtype _ordered: bool # unused?
[docs] def collect_buffers(self, visitor) -> OrderedFrozenSet: return OrderedFrozenSet()
[docs] def get_disk_cache_key(self, visitor) -> Hashable: return (type(self), self._shape, visitor.renamer.add_obj(self), self._dtype)
[docs] def instruction_executor_cache_key(self, buffer_counter: Mapping[AbstractBuffer, int]) -> Hashable: return (type(self), self._shape, self._dtype, self._ordered, buffer_counter[self])
def __init__( self, shape: tuple[numbers.Integral, ...] | numbers.Integral, dtype=None, *, name: str | None = None, prefix: str | None = None, ordered: bool = False, ) -> None: if isinstance(shape, numbers.Integral): shape = (shape,) name = utils.maybe_generate_name(name, prefix, self.DEFAULT_PREFIX) dtype = utils.as_dtype(dtype, self.DEFAULT_DTYPE) self._shape = shape self._name = name self._dtype = dtype self._ordered = ordered def __record_post_init(self) -> None: assert isinstance(self.shape, tuple) # }}} # {{{ pyop3.obj.Object interface impls @property def comm(self) -> MPI.Comm: return MPI.COMM_SELF # }}} # {{{ class attrs DEFAULT_PREFIX: ClassVar[str] = "tmp" # }}} # {{{ interface impls shape: ClassVar[property] = pyop3.record.attr("_shape") name: ClassVar[property] = pyop3.record.attr("_name") dtype: ClassVar[property] = pyop3.record.attr("_dtype") ordered: ClassVar[property] = pyop3.record.attr("_ordered")
[docs] def duplicate(self, *, copy: bool = False, constant: bool | None = None) -> NullBuffer: if constant is None: raise NotImplementedError name = f"{self.name}_copy" return self.record_new(_name=name)
# }}}
[docs] def nest_shape(self, *args): return None
[docs] class ConcreteBuffer(AbstractBuffer, metaclass=abc.ABCMeta): """Abstract class representing buffers that carry actual data.""" @property @abc.abstractmethod def constant(self) -> bool: pass @property @abc.abstractmethod def state(self) -> int: """Counter used to keep track of modifications."""
[docs] @abc.abstractmethod def inc_state(self) -> None: pass
[docs] @abc.abstractmethod def zero(self) -> None: pass
[docs] @pyop3.record.record() class ArrayBuffer(AbstractArrayBuffer, ConcreteBuffer): """A 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. """ # {{{ instance attrs _device_arrays_private: dict[Device, np.ndarray] = dataclasses.field(repr=False) """ Note that this attribute is mega private to reduce the risk of correctness issues in parallel and between devices. Device arrays should be accessed via other methods. """ sf: StarForest _name: str _constant: bool _rank_equal: bool _ordered: bool
[docs] def collect_buffers(self, visitor): return OrderedFrozenSet([self])
[docs] def get_disk_cache_key(self, visitor) -> Hashable: return ( type(self), self.dtype, visitor.renamer.add_obj(self), self._constant, self._rank_equal, self._ordered, )
[docs] def get_instruction_executor_cache_key(self, visitor) -> Hashable: # Consider the expression: # # dat1[i] <- dat2[map1[map2[i]]] # # We may end up optimising the repeated indirections to give: # # dat1[i] <- dat2[map3[i]] # # It would be really nice to cache this and reuse the result for different # objects in place of dat1 and dat2. The cache key therefore can be somewhat # generic for those arguments. However, *it cannot be for the dats that make # up map1 and map2*. If those change then we need to recompute map3 from # scratch. The cache key here therefore distinguishes between outermost buffers # and inner ones. if visitor._identity_hash_buffers: # Inside an axis tree or similar, we aren't allowed to change buffers here return self else: return ( type(self), self.dtype, visitor.renamer.add_obj(self), self._constant, self._rank_equal, self._ordered, )
def __init__( self, data: Mapping[pyop3.device.Device, Any] | np.ndarray, sf: StarForest | None = None, *, name: str | None = None, prefix: str | None = None, constant: bool = False, rank_equal: bool = False, ordered: bool = False ) -> None: if isinstance(data, Mapping): assert len(data) > 0 if len(data) > 1: raise NotImplementedError("which is up to date?") raise NotImplementedError if constant: pyop3.device.flag_constant(data) if type(data) != pyop3.device.DEVICE_TO_ARRAY_TYPE[get_current_device()]: raise NotImplementedError( "Current device does not match the array type, need to provide " "data as a mapping so we know the right device" ) device_arrays = {get_current_device(): data} if sf is None: sf = NullStarForest(data.size) name = utils.maybe_generate_name(name, prefix, self.DEFAULT_PREFIX) if rank_equal and not constant: raise ValueError self._device_arrays_private = device_arrays self.sf = sf self._name = name self._constant = constant self._rank_equal = rank_equal self._ordered = ordered def __record_post_init(self) -> None: # state tracking attrs self._state = {pyop3.device.get_current_device(): 0} self._state_locks = 0 self._device_locks = [] # parallel semaphores self._semaphore_locks = 0 self._leaves_valid_private = True self._pending_reduction_private = None self._finalizer_private: Callable | None = None #### assert isinstance(self.sf, pyop3.sf.AbstractStarForest) if isinstance(self.sf, pyop3.sf.StarForest): assert self.sf.size == self.size curr_dev = get_current_device() if self.rank_equal: assert self.constant if self.ordered: utils.debug_assert(lambda: utils.is_sorted(self._device_arrays_private)) if self.constant and isinstance(self._device_arrays_private[curr_dev], np.ndarray): self._device_arrays_private[curr_dev].flags.writeable = False self._debug_is_poisoned = False @property def comm(self) -> MPI.Comm: return self.sf.comm # }}} # {{{ Class attrs DEFAULT_PREFIX: ClassVar[str] = "array" # }}} # {{{ interface impls name: ClassVar[property] = pyop3.record.attr("_name") constant: ClassVar[property] = pyop3.record.attr("_constant") rank_equal: ClassVar[property] = pyop3.record.attr("_rank_equal") # TODO: make an abstract property ordered: ClassVar[property] = pyop3.record.attr("_ordered") @property def shape(self) -> tuple[int, ...]: return next(a.shape for a in self._device_arrays_private.values()) @property def dtype(self) -> np.dtype: return next(a.dtype for a in self._device_arrays_private.values())
[docs] def duplicate(self, *, copy: bool = False, constant: bool | None = None, **kwargs) -> Self: # make sure that there are no pending transfers before we copy self.assemble() name = f"{self.name}_copy" current_device = get_current_device() if copy: data = self._current_device_array.copy() else: data = current_device.zeros_like(self._current_device_array) if constant is None: constant = self.constant # NOTE: be careful here that arguments aren't being dropped return type(self)( data=data, sf=self.sf, name=name, constant=constant, **kwargs, )
is_nested: ClassVar[bool] = False
[docs] def zero(self) -> None: self.data_wo[...] = 0
# }}} # {{{ constructors
[docs] @classmethod def empty(cls, shape, dtype=None, **kwargs): if dtype is None: dtype = cls.DEFAULT_DTYPE if pyop3.config.debug_checks: data = np.full(shape, 666, dtype=dtype) else: data = np.empty(shape, dtype=dtype) return cls(data, **kwargs)
[docs] @classmethod def zeros(cls, shape, dtype=None, **kwargs): if dtype is None: dtype = cls.DEFAULT_DTYPE data = np.zeros(shape, dtype=dtype) return cls(data, **kwargs)
[docs] @classmethod def full(cls, size: numbers.Integral, fill_value: numbers.Number, dtype=None, **kwargs): if not isinstance(fill_value, int) or dtype != IntType: raise NotImplementedError("Casting") data = np.full(size, fill_value, dtype=dtype) return cls(data, **kwargs)
[docs] @classmethod def from_scalar(cls, value: numbers.Number, *, dtype=None, **kwargs): data = np.array([value], dtype=dtype) return cls(data, **kwargs)
# }}} # {{{ semaphores def _lock_semaphores(self) -> None: self._semaphore_locks += 1 def _unlock_semaphores(self) -> None: assert self._semaphore_locks > 0 self._semaphore_locks -= 1 def _semaphores_unlocked(self) -> bool: return self._semaphore_locks == 0 @property def _leaves_valid(self) -> bool: return self._leaves_valid_private @_leaves_valid.setter def _leaves_valid(self, value: bool, /) -> None: assert self._semaphores_unlocked self._leaves_valid_private = value @property def _pending_reduction(self) -> pyop3.constant.Intent | None: return self._pending_reduction_private @_pending_reduction.setter def _pending_reduction(self, value: pyop3.constant.Intent | None) -> None: assert self._semaphores_unlocked self._pending_reduction_private = value @property def _roots_valid(self) -> bool: return self._pending_reduction is None @property def _finalizer(self) -> Callable[[], None] | None: return self._finalizer_private @_finalizer.setter def _finalizer(self, value: Callable[[], None] | None) -> None: assert self._semaphores_unlocked self._finalizer_private = value # }}} # {{{ data accessors @property def data_rw(self): return self.get_array("rw") @property def data_ro(self): return readonly(self.get_array("ro")) @property def data_wo(self): """ 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. """ return self.get_array("wo") # TODO: It would be good to be able to get data_ro but without updating the # halos. This would necessitate adding a .data_ro_with_ghosts API or similar
[docs] @_not_in_flight def get_array(self, intent: Literal["ro", "rw", "wo"] = "ro"): match intent: case "ro": if not self._roots_valid: self.sync_roots() if not self._leaves_valid: self.sync_leaves() case "rw": if not self._roots_valid: self.sync_roots() if not self._leaves_valid: self.sync_leaves() # modifying owned values invalidates ghosts self._leaves_valid = False case "wo": # pending writes can be dropped, note that this has implications for subset assignment self._pending_reduction = None self._leaves_valid = False if self._debug_is_poisoned: breakpoint() if intent in {"wo", "rw"}: self.inc_state() array = self._current_device_array return readonly(array) if intent == "ro" else array
# TODO: this would be nice to avoid halo exchanges # @property # def _owned_data(self): # if self.sf and self.sf.nleaves > 0: # return self._data[: -self.sf.nleaves] # else: # return self._data
[docs] def freeze(self) -> None: """Freeze the buffer, turning any modifying accesses into errors.""" self._lock_state()
[docs] def unfreeze(self) -> None: """Unfreeze the buffer.""" self._unlock_state()
@property def is_frozen(self) -> bool: return self._state_is_locked def _lock_state(self) -> None: """ Note that we have two methods for fixing the state: `freeze` and `_lock_state`. Both methods exist to make it clear that locking the state variable is not necessarily the same as 'freezing' the buffer. For example, if we want to do the following: buffer.reduce_leaves_to_roots_begin() # modify core values in 'buffer' buffer.reduce_leaves_to_roots_end() Then we certainly want to modify the buffer data but we also want to make sure that we don't change the state value - and hence mess with host/device transfers - in the interim. For 'expert' buffer access patterns like this then the state should be modified manually using `inc_state`. """ self._state_locks += 1 def _unlock_state(self) -> None: assert self._state_locks > 0, "Buffer must be locked to unlock it" self._state_locks -= 1 @property def _state_is_locked(self) -> bool: return self._state_locks > 0 # }}} # {{{ parallel communication
[docs] @_not_in_flight def sync_roots(self) -> None: """Update roots.""" # With no pending reduction there is nothing to do if self._roots_valid: return self.sync_roots_begin() self.sync_roots_end()
[docs] @_not_in_flight def sync_roots_begin(self) -> None: """Start updating roots.""" if not self._roots_valid: self._reduce_leaves_to_roots_begin(pyop3.mpi.REDUCTION_OPS[self._pending_reduction]) self._leaves_valid = False self._finalizer = self.sync_roots_end self._lock_semaphores()
[docs] @_check_finalizer def sync_roots_end(self) -> None: """Finish updating roots.""" self._unlock_semaphores() if not self._roots_valid: self._reduce_leaves_to_roots_end(pyop3.mpi.REDUCTION_OPS[self._pending_reduction]) self._pending_reduction = None self._finalizer = None
[docs] def reduce_leaves_to_roots(self, op: MPI.Op) -> None: """Unconditionally update roots. This will overwrite any existing parallel state tracking. Parameters ---------- op The MPI reduction operation to apply when pulling leaves onto roots. """ self.reduce_leaves_to_roots_begin(op) self.reduce_leaves_to_roots_end(op)
[docs] @_not_in_flight def reduce_leaves_to_roots_begin(self, op: MPI.Op) -> None: """Start unconditionally updating roots.""" self._reduce_leaves_to_roots_begin(op) self._leaves_valid = False self._finalizer = self.reduce_leaves_to_roots_end self._lock_semaphores()
[docs] @_check_finalizer def reduce_leaves_to_roots_end(self, op: MPI.Op) -> None: """Finish unconditionally updating roots.""" self._unlock_semaphores() self._reduce_leaves_to_roots_end(op) self._pending_reduction = None self._finalizer = None
@on_host def _reduce_leaves_to_roots_begin(self, op: MPI.Op) -> None: """Start updating roots. This routine does not modify any parallel state-tracking variables. """ self._lock_current_device() self.sf.reduce_begin(self._current_device_array, op) @on_host def _reduce_leaves_to_roots_end(self, op: MPI.Op) -> None: """Finish updating roots. This routine does not modify any parallel state-tracking variables. """ self.sf.reduce_end(self._current_device_array, op) self._unlock_current_device()
[docs] def sync_leaves(self) -> None: """Update leaves.""" self.sync_leaves_begin() self.sync_leaves_end()
[docs] @_not_in_flight def sync_leaves_begin(self) -> None: """Start updating leaves.""" assert self._roots_valid, "Must call sync_roots() beforehand" if not self._leaves_valid: self._broadcast_roots_to_leaves_begin() self._finalizer = self.sync_leaves_end self._lock_semaphores()
[docs] @_check_finalizer def sync_leaves_end(self) -> None: """Finish updating leaves.""" self._unlock_semaphores() if not self._leaves_valid: self._broadcast_roots_to_leaves_end() self._leaves_valid = True self._finalizer = None
[docs] def broadcast_roots_to_leaves(self) -> None: """Unconditionally update leaves. This will overwrite any existing parallel state tracking. """ self.broadcast_roots_to_leaves_begin() self.broadcast_roots_to_leaves_end()
[docs] @_not_in_flight def broadcast_roots_to_leaves_begin(self) -> None: """Start unconditionally updating leaves.""" self._pending_reduction = None # claim this, otherwise broadcasting makes no sense self._broadcast_roots_to_leaves_begin() self._finalizer = self.broadcast_roots_to_leaves_end self._lock_semaphores()
[docs] @_check_finalizer def broadcast_roots_to_leaves_end(self) -> None: self._unlock_semaphores() self._broadcast_roots_to_leaves_end() self._leaves_valid = True self._finalizer = None
@on_host def _broadcast_roots_to_leaves_begin(self): """Start updating leaves. This routine does not modify any parallel state-tracking variables. """ self._lock_current_device() self.sf.broadcast_begin(self._current_device_array, MPI.REPLACE) @on_host def _broadcast_roots_to_leaves_end(self): """Finish updating leaves. This routine does not modify any parallel state-tracking variables. """ self.sf.broadcast_end(self._current_device_array, MPI.REPLACE) self._unlock_current_device()
[docs] def assemble(self) -> None: """Update roots and leaves.""" self.sync_roots() self.sync_leaves()
# TODO: This is a good idea, we just don't use it # @not_in_flight # def _reduce_then_broadcast(self): # self.reduce_then_broadcast_begin() # self.reduce_then_broadcast_end() # # @not_in_flight # def reduce_then_broadcast_begin(self): # # TODO: To make this non-blocking we can use Python's 'threading' library # # # # For example: # # # # lock = threading.Lock() # # with lock: # # trigger nonblocking send/recvs # # # # For now do the dumb thing. # self.reduce_leaves_to_roots() # self.broadcast_roots_to_leaves_begin() # # def reduce_then_broadcast_end(self): # self.broadcast_roots_to_leaves_end() # }}} # {{{ cross-device state tracking @property def state(self) -> int: return max(self._state.values()) @state.setter def state(self, new_state) -> None: if self.is_frozen: raise pyop3.exceptions.FrozenBufferException( "Buffer is frozen and cannot be modified" ) assert new_state >= self.state, "State must always be increasing" self._state[get_current_device()] = new_state
[docs] def inc_state(self) -> None: self.state += 1
@property def _current_device_array(self) -> pyop3.types.DeviceArrayT: current_device = get_current_device() last_updated_device = max(self._state, key=self._state.get) if current_device in self._device_arrays_private: if self._state[current_device] == self.state: # current entry is up-to-date, do nothing pass else: assert not self.constant new_values = current_device.asarray( self._device_arrays_private[last_updated_device] ) self._device_arrays_private[current_device][...] = new_values self._state[current_device] = self.state # First time seeing the current device - allocate and insert, don't copy else: new_values = current_device.asarray( self._device_arrays_private[last_updated_device], constant=self.constant ) self._device_arrays_private[current_device] = new_values self._state[current_device] = self.state return self._device_arrays_private[current_device] def _lock_current_device(self): """Raise an error if we try to change the current device.""" self._lock_state() assert all(d == get_current_device() for d in self._device_locks) self._device_locks.append(get_current_device()) def _unlock_current_device(self): """Undo a device lock.""" assert len(self._device_locks) > 0 self._device_locks.pop(-1) self._unlock_state() # }}} # {{{ PETSc interop @cached_method() @on_host # for now def _work_vec(self, block_shape: tuple[numbers.Integral, ...]) -> PETSc.Vec: size = self.sf.num_owned block_size = np.prod(block_shape, dtype=int) return PETSc.Vec().createWithArray( self._current_device_array[:size], (size, None), block_size, comm=self.comm, )
[docs] def vec_ro(self, /, block_shape: Iterable[int] = ()) -> GeneratorType[PETSc.Vec]: return self.as_vec("ro", block_shape)
[docs] def vec_wo(self, /, block_shape: Iterable[int]) -> GeneratorType[PETSc.Vec]: return self.as_vec("wo", block_shape)
[docs] def vec_rw(self, /, block_shape: Iterable[int]) -> GeneratorType[PETSc.Vec]: return self.as_vec("rw", block_shape)
# TODO: This is very similar to what a Dat does, refactor to share functionality
[docs] @contextlib.contextmanager def as_vec( self, mode: Literal["ro", "rw", "wo"], block_shape: Iterable[int] | int = (), ) -> GeneratorType[PETSc.Vec]: if self.dtype != PETSc.ScalarType: raise RuntimeError( f"Cannot create a PETSc Vec with data type '{self.dtype}', " f"must be '{PETSc.ScalarType}'" ) self.assemble() # TODO: how should we handle the state of the work vec? # TODO: catch nested contexts yield self._work_vec(block_shape) if mode in {"wo", "rw"}: self.inc_state() self._leaves_valid = False
# TODO # self._work_vec.stateIncrease() # }}} # {{{ other methods
[docs] def nest_shape( self, nest_indices=(), ) -> tuple[tuple[int, ...]] | None: assert not nest_indices return None
[docs] @cached_method() def localize(self) -> Self: return self.record_new(sf=None)
# }}} # {{{ debugging helper methods # def _debug_poison_array(self) -> None: # """Turn the next array access into an error.""" # return # if self._debug_is_poisoned: # return # self.olddata = self._device_arrays_private # self._debug_is_poisoned = True # self._device_arrays_private = {pyop3.device.HOST_DEVICE: "NOTHING"} # # def _debug_unpoison_array(self) -> None: # return # """Undo array poisoning.""" # self._debug_is_poisoned = False # self._device_arrays_private = self.olddata # }}}
[docs] class PetscMatInitBufferSpec(pyop3.obj.Object): """Abstract class for a 'partial' specification of how to build a PETSc Mat. This class differs from the 'full' `PetscMatBufferSpec` class where information like the sizes and lgmaps have been determined from the axis trees. """
[docs] @pyop3.record.frozenrecord() class MonolithicPetscMatInitBufferSpec(PetscMatInitBufferSpec): mat_type: str block_shape: tuple[tuple[int, ...], tuple[int, ...]] = ((), ())
[docs] @pyop3.record.frozenrecord() class NestedPetscMatInitBufferSpec(PetscMatInitBufferSpec): submat_specs: np.ndarray mat_type: ClassVar[str] = "nest"
[docs] class PetscMatBufferSpec(pyop3.obj.Object): """A complete specification of how to build a PETSc Mat."""
# TODO: Perhaps also need a nested type here too # TODO: This nested dependence suggests that this type belongs elsewhere? # I think this does need to have a weird dependency cycle because we inject this # into the matrix constructor logic, which belongs on the buffer.
[docs] @pyop3.record.frozenrecord() class MonolithicPetscMatBufferSpec(PetscMatBufferSpec): mat_type: str row_spec: PetscMatAxisSpec | pyop3.axis_tree.AbstractAxisTree # TODO: drop axis tree as valid type here column_spec: PetscMatAxisSpec | pyop3.axis_tree.AbstractAxisTree # TODO: drop axis tree as valid type here
[docs] def get_instruction_executor_cache_key(self, visitor) -> Hashable: return (type(self), self.mat_type, visitor(self.row_spec), visitor(self.column_spec))
@property def comm(self) -> MPI.Comm: return pyop3.mpi.common_comm([self.row_spec.comm, self.column_spec.comm])
[docs] @pyop3.record.frozenrecord() class NestedPetscMatBufferSpec(PetscMatBufferSpec): submat_specs: np.ndarray
[docs] def get_instruction_executor_cache_key(self, visitor) -> Hashable: return (type(self), tuple(map(visitor, self.submat_specs.ravel())), self.shape)
def __hash__(self) -> int: return hash((type(self), tuple(self.submat_specs.ravel()), self.shape)) @property def shape(self) -> tuple[int, int]: return self.submat_specs.shape
[docs] @pyop3.record.frozenrecord() class PetscMatAxisSpec(pyop3.obj.Object): size: int lgmap: PETSc.LGMap block_shape: tuple[int, ...] = ()
[docs] def get_instruction_executor_cache_key(self, visitor) -> Hashable: # The size and lgmap attributes don't matter for this cache return (type(self), self.block_shape)
def __hash__(self) -> int: # Need a custom hash because lgmaps aren't hashable return hash((type(self), self.size, id(self.lgmap), self.block_shape)) @property def block_size(self) -> int: return np.prod(self.block_shape, dtype=int)
[docs] @pyop3.record.record() class PetscMatBuffer(ConcreteBuffer): """A buffer whose underlying data structure is a PETSc Mat. Parameters ---------- mat_spec Only used for preallocation matrices... and actually the only real information is the matrix type, which could be an argument to materialize... """ # {{{ instance attrs _mat: tuple[PETSc.Mat, PETSc.InsertMode] mat_spec: PetscMatBufferSpec | None _name: str _constant: bool _comm: MPI.Comm
[docs] def get_disk_cache_key(self, visitor) -> Hashable: return (type(self), visitor.renamer.add_obj(self), self._constant)
[docs] def get_instruction_executor_cache_key(self, visitor) -> Hashable: # we can hit buffers in multiple places... # on the outside these are allowed to differ but inside they aren't if visitor._identity_hash_buffers: # Inside an axis tree or similar, we aren't allowed to change buffers here return self else: mat, _ = self._mat return ( type(self), visitor.renamer.add_obj(self), mat.type, visitor(self.mat_spec), self._constant, )
[docs] def collect_buffers(self, visitor): return OrderedFrozenSet([self])
def __init__( self, mat: PETSc.Mat, *, comm: MPI.Comm, mat_spec: pyop3.buffer.PetscMatBufferSpec = None, name: str | None = None, prefix: str | None = None, constant: bool = False, ) -> None: name = utils.maybe_generate_name(name, prefix, self.DEFAULT_PREFIX) self._mat = (mat, PETSc.InsertMode.NOT_SET_VALUES) self.mat_spec = mat_spec self._name = name self._constant = constant self._comm = comm # }}} @property def mat(self) -> PETSc.Mat: mat_, _ = self._mat return mat_ @property def insert_mode(self) -> PETSc.InsertMode: _, mode = self._mat return mode @insert_mode.setter def insert_mode(self, new_insert_mode: PETSc.InsertMode, /) -> None: mat, _ = self._mat self._mat = (mat, new_insert_mode) @property def comm(self) -> MPI.Comm: return self._comm
[docs] def nest_shape(self, nest_indices: Iterable[tuple[int, int], ...] = ()): nest_indices = tuple(nest_indices) submat = self.mat for ri, ci in nest_indices: submat = submat.getNestSubMatrix(ri, ci) if submat.type == PETSc.Mat.Type.NEST: return submat.getNestSize() else: return None
# {{{ class attrs DEFAULT_PREFIX = "petscmat" # }}} # {{{ factory methods
[docs] @classmethod def empty(cls, mat_spec: PetscMatBufferSpec, *, comm, preallocator: bool = False, **kwargs): # can get comm from mat spec? mat = cls._make_petsc_mat(mat_spec, comm=comm, preallocator=preallocator) if preallocator: return cls(mat, mat_spec=mat_spec, comm=comm, **kwargs) else: return cls(mat, comm=comm, **kwargs)
@classmethod def _make_petsc_mat( cls, mat_spec: PetscMatBufferSpec, *, comm, preallocator: bool = False, ): if isinstance(mat_spec, NestedPetscMatBufferSpec): submats = np.empty(mat_spec.shape, dtype=object) for (i, j), submat_spec in np.ndenumerate(mat_spec.submat_specs): submat = cls._make_petsc_mat(submat_spec, comm=comm, preallocator=preallocator) submats[i, j] = submat return PETSc.Mat().createNest(submats, comm=comm) else: assert isinstance(mat_spec, MonolithicPetscMatBufferSpec) return cls._make_non_nested_petsc_mat(mat_spec, comm=comm, preallocator=preallocator) @classmethod def _make_non_nested_petsc_mat(cls, mat_spec: MonolithicPetscMatBufferSpec, *, comm, preallocator: bool): mat_type = mat_spec.mat_type row_spec = mat_spec.row_spec column_spec = mat_spec.column_spec # TODO: just want the sf here, don't need more than that. Can clean up matspec stuff # Maybe can then even set lgmaps in the same way... if mat_type in {"denseblock", "denserow", "densecol"}: if mat_type == "denserow": # a row vec (horizontal) has #columns entries mat_context = DenseRowPythonMatContext.empty(column_spec.sf) elif mat_type == "densecol": # a column vec (vertical) has #rows entries mat_context = DenseColumnPythonMatContext.empty(row_spec.sf) else: mat_context = DenseBlockPythonMatContext.empty(comm) mat = PETSc.Mat().createPython(mat_context.sizes, mat_context, comm=comm) else: if preallocator: mat_type = PETSc.Mat.Type.PREALLOCATOR mat = PETSc.Mat().create(comm) mat.setType(mat_type) # None is for the global size, PETSc will figure it out for us sizes = ((row_spec.size, None), (column_spec.size, None)) mat.setSizes(sizes) # It is important that the block size is the same in both directions rbsize = row_spec.block_size cbsize = column_spec.block_size bsize = rbsize if rbsize == cbsize else 1 mat.setBlockSizes(bsize, bsize) mat.setLGMap(row_spec.lgmap, column_spec.lgmap) mat.setUp() return mat # }}} # {{{ interface impls name: ClassVar[property] = pyop3.record.attr("_name") constant: ClassVar[property] = pyop3.record.attr("_constant") dtype = ScalarType rank_equal = False
[docs] def duplicate(self, **kwargs) -> PetscMatBuffer: raise NotImplementedError("TODO")
@property def is_nested(self) -> bool: return self.mat_type == PETSc.Mat.Type.NEST
[docs] def zero(self) -> None: self.mat.zeroEntries()
# }}} # {{{ state tracking
[docs] def maybe_flush_assemble(self, insert_mode: PETSc.InsertMode) -> None: """Prepare the matrix for a particular insert mode.""" self.maybe_flush_assemble_begin(insert_mode) self.maybe_flush_assemble_end(insert_mode)
[docs] def maybe_flush_assemble_begin(self, insert_mode: PETSc.InsertMode) -> None: assert insert_mode in {PETSc.InsertMode.INSERT_VALUES, PETSc.InsertMode.ADD_VALUES} if self.insert_mode not in {insert_mode, PETSc.InsertMode.NOT_SET_VALUES}: zero_ghosts = insert_mode == PETSc.InsertMode.ADD_VALUES self._petscmat_assemble( self.mat, self.insert_mode, final=False, mode="begin", zero_ghosts=zero_ghosts )
[docs] def maybe_flush_assemble_end(self, insert_mode: PETSc.InsertMode) -> None: assert insert_mode in {PETSc.InsertMode.INSERT_VALUES, PETSc.InsertMode.ADD_VALUES} if self.insert_mode not in {insert_mode, PETSc.InsertMode.NOT_SET_VALUES}: zero_ghosts = insert_mode == PETSc.InsertMode.ADD_VALUES self._petscmat_assemble( self.mat, self.insert_mode, final=False, mode="end", zero_ghosts=zero_ghosts ) self.insert_mode = insert_mode
[docs] def assemble(self, *, final: bool = True) -> None: self.assemble_begin(final=final) self.assemble_end(final=final)
[docs] def assemble_begin(self, *, final: bool = True) -> None: self._petscmat_assemble(self.mat, self.insert_mode, final=final, mode="begin")
[docs] def assemble_end(self, *, final: bool = True) -> None: # TODO: It would be nice to assert that assemble_begin has been # called first (and with the same value for 'final') self._petscmat_assemble(self.mat, self.insert_mode, final=final, mode="end") self.insert_mode = PETSc.InsertMode.NOT_SET_VALUES
@classmethod def _petscmat_assemble( cls, mat: PETSc.Mat, insert_mode: PETSc.InsertMode, *, final: bool, mode: Literal["begin", "end"], zero_ghosts: bool = False, ) -> None: if mat.type == PETSc.Mat.Type.NEST: for i, j in np.ndindex(mat.getNestSize()): submat = mat.getNestSubMatrix(i, j) cls._petscmat_assemble(submat, insert_mode, final=final, mode=mode, zero_ghosts=zero_ghosts) elif mat.type == PETSc.Mat.Type.PYTHON: ctx = mat.getPythonContext() if isinstance(ctx, DensePythonMatContext): match insert_mode: case PETSc.InsertMode.NOT_SET_VALUES: return case PETSc.InsertMode.INSERT_VALUES: reduction = MPI.REPLACE case PETSc.InsertMode.ADD_VALUES: reduction = MPI.SUM case _: raise AssertionError if mode == "begin": ctx.buffer.reduce_leaves_to_roots_begin(reduction) ctx.buffer.reduce_leaves_to_roots_end(reduction) if zero_ghosts: ctx.buffer[ctx.buffer.sf.ileaf] = 0 else: ctx.buffer.broadcast_roots_to_leaves_begin() else: # "end" if not zero_ghosts: ctx.buffer.broadcast_roots_to_leaves_end() else: raise NotImplementedError else: if final: assembly_type = PETSc.Mat.AssemblyType.FINAL else: assembly_type = PETSc.Mat.AssemblyType.FLUSH if mode == "begin": mat.assemblyBegin(assembly_type) else: # end mat.assemblyEnd(assembly_type) @property def state(self) -> int: return self.mat.stateGet()
[docs] def inc_state(self) -> None: self.mat.stateIncrease()
# }}} @property def mat_type(self) -> str: return self.mat.type
[docs] def set_diagonal(self, value: np.ndarray | numbers.Number) -> None: if isinstance(value, numbers.Number): value = utils.strict_cast(value, PETSc.ScalarType) else: value = value.astype(PETSc.ScalarType) set_petsc_mat_diagonal(self.mat, value)
[docs] def materialize(self) -> PetscMatBuffer: if not hasattr(self, "_lazy_template"): self.assemble() template = self._make_petsc_mat(self.mat_spec, comm=self.comm) self._preallocate(self.mat, template) # We can safely set these options since by using a sparsity we # are asserting that we know where the non-zeros are going. template.setOption(PETSc.Mat.Option.NEW_NONZERO_LOCATION_ERR, True) template.setOption(PETSc.Mat.Option.IGNORE_ZERO_ENTRIES, True) template.assemble() self._lazy_template = template mat = duplicate_mat(self._lazy_template, copy=False) return PetscMatBuffer(mat, comm=self.comm)
def _preallocate(self, preallocator: PETSc.Mat, template: PETSc.Mat) -> None: if template.type == PETSc.Mat.Type.NEST: for i, j in np.ndindex(template.getNestSize()): subpreallocator = preallocator.getNestSubMatrix(i, j) submat = template.getNestSubMatrix(i, j) self._preallocate(subpreallocator, submat) elif template.type == PETSc.Mat.Type.PYTHON: pass else: if preallocator.type != PETSc.Mat.Type.PREALLOCATOR: raise TypeError("Can only materialize preallocator mats") preallocator.preallocatorPreallocate(template)
[docs] def duplicate_mat(mat: PETSc.Mat, copy: bool = False) -> PETSc.Mat: """Duplicate a PETSc Mat. This function is temporarily needed because ``MATNEST`` matrices do not currently support ``MatDuplicate``. """ if mat.type == "nest": shape = mat.getNestSize() duplicated_submats = np.empty(shape, dtype=object) for i, j in np.ndindex(shape): submat = mat.getNestSubMatrix(i, j) duplicated_submat = duplicate_mat(submat, copy=copy) duplicated_submats[i, j] = duplicated_submat return PETSc.Mat().createNest(duplicated_submats, comm=mat.comm) elif mat.type == "python": mat_context = mat.getPythonContext() duplicated_mat = PETSc.Mat().createPython(mat_context.sizes, comm=mat.comm) duplicated_mat.setPythonContext(mat_context.duplicate(copy=copy)) return duplicated_mat else: return mat.duplicate(copy=copy)
[docs] class DensePythonMatContext: """Matrix 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. """ # IMPORTANT: There is a nasty parallel bug hidden in this code. We currently # make the assumption that the data is always owned by rank 0 (e.g. look for # anywhere we write 'if comm.rank == 0'). This assumption breaks down for # the case where rank 0 is empty and the data then lives on another rank. def __init__(self, buffer: ArrayBuffer) -> None: self.buffer = buffer
[docs] def duplicate(self, *, copy: bool = False) -> Self: return type(self)(self.buffer.duplicate(copy=copy))
@property def comm(self) -> MPI.Comm: return self.buffer.comm # {{{ Mat context routines
[docs] def __getitem__(self, key): raise NotImplementedError
[docs] @abc.abstractmethod def mult(self, mat: PETSc.Mat, x: PETSc.Vec, y: PETSc.Vec) -> None: """Set y = self @ x."""
[docs] def multTranspose(self, mat, x, y): raise NotImplementedError
# if self.mode == "row": # with self.dat.vec_ro as v: # if self.sizes[0][0] is None: # # Row matrix # if x.sizes[1] == 1: # v.copy(y) # a = np.zeros(1, dtype=dtypes.ScalarType) # if x.comm.rank == 0: # a[0] = x.array_r # else: # x.array_r # with mpi.temp_internal_comm(x.comm) as comm: # comm.bcast(a) # y.scale(a) # else: # v.pointwiseMult(x, y) # else: # # Column matrix # out = v.dot(x) # if y.comm.rank == 0: # y.array[0] = out # else: # y.array[...]
[docs] def multTransposeAdd(self, mat, x, y, z): ''' z = y + mat^Tx ''' raise NotImplementedError
# if self.mode == "row": # if self.sizes[0][0] is None: # # Row matrix # if x.sizes[1] == 1: # v.copy(z) # a = np.zeros(1, dtype=dtypes.ScalarType) # if x.comm.rank == 0: # a[0] = x.array_r # else: # x.array_r # with mpi.temp_internal_comm(x.comm) as comm: # comm.bcast(a) # if y == z: # # Last two arguments are aliased. # tmp = y.duplicate() # y.copy(tmp) # y = tmp # z.scale(a) # z.axpy(1, y) # else: # if y == z: # # Last two arguments are aliased. # tmp = y.duplicate() # y.copy(tmp) # y = tmp # v.pointwiseMult(x, z) # return z.axpy(1, y) # else: # # Column matrix # out = v.dot(x) # y = y.array_r # if z.comm.rank == 0: # z.array[0] = out + y[0] # else: # z.array[...]
[docs] def getDiagonal(self, mat: PETSc.Mat, result: PETSc.Vec | None = None) -> PETSc.Vec: # Think this might be wrong if result is None: with self.buffer.vec_ro() as vec: result = vec.duplicate() result.array_w[...] = self.buffer.data_ro return result
[docs] def zeroEntries(self, mat: PETSc.Mat) -> None: self.buffer.zero()
# }}} @property def data_ro(self) -> np.ndarray: return self.buffer.data_ro
[docs] def set_diagonal(self, value: numbers.Number) -> None: data = self.buffer.data_wo # do collectively so state is tracked collectively if self.comm.rank == 0: data[0] = value
[docs] class DenseRowPythonMatContext(DensePythonMatContext):
[docs] @classmethod @abc.abstractmethod def empty(cls, sf: pyop3.sf.StarForest) -> Self: buffer = ArrayBuffer.empty((1, sf.size), sf=sf, dtype=ScalarType) return cls(buffer)
@property def sizes(self) -> tuple[pyop3.types.PetscSizeT, pyop3.types.PetscSizeT]: return ((None, 1), (self.buffer.sf.num_owned, None))
[docs] def mult(self, mat: PETSc.Mat, x: PETSc.Vec, y: PETSc.Vec) -> None: # Example: # * 'A' (self) has global size (m, n) # * 'x' has global size (n,) # * 'y' has global size (m,) # # Where, because this is a row matrix, we know that 'm' must be 1: # # A ⊗ x ➜ yt # ■ ■ ■ ■ ■ ■ ■ # ■ # ■ # ■ # ■ y_array = y.array_w with self.buffer.vec_ro() as A: result = A.dot(x) if self.comm.rank == 0: y_array[...] = result
[docs] class DenseColumnPythonMatContext(DensePythonMatContext):
[docs] @classmethod @abc.abstractmethod def empty(cls, sf: pyop3.sf.StarForest) -> Self: buffer = ArrayBuffer.empty((sf.size, 1), sf=sf, dtype=ScalarType) return cls(buffer)
@property def sizes(self) -> tuple[pyop3.types.PetscSizeT, pyop3.types.PetscSizeT]: return ((self.buffer.sf.num_owned, None), (None, 1))
[docs] def mult(self, mat: PETSc.Mat, x: PETSc.Vec, y: PETSc.Vec) -> None: # Example: # * 'A' (self) has global size (m, n) # * 'x' has global size (n,) # * 'y' has global size (m,) # # Where, because this is a column matrix, we know that 'n' must be 1: # # A ⊗ x ➜ y # ■ ■ ■ # ■ ■ # ■ ■ # ■ ■ # ■ ■ # Send the single 'x' value to all ranks with pyop3.mpi.temp_internal_comm(self.comm) as icomm: xval = icomm.bcast(x.array_r) with self.buffer.vec_ro() as A: y.array_w[...] = A.array_r * xval
[docs] class DenseBlockPythonMatContext(DensePythonMatContext):
[docs] @classmethod @abc.abstractmethod def empty(cls, comm: MPI.Comm) -> Self: sf = pyop3.sf.single_star_sf(comm, 1) buffer = ArrayBuffer.empty((1, 1), sf=sf, dtype=ScalarType) return cls(buffer)
@property def sizes(self) -> tuple[pyop3.types.PetscSizeT, pyop3.types.PetscSizeT]: return ((None, 1), (None, 1))
[docs] def mult(self, mat: PETSc.Mat, x: PETSc.Vec, y: PETSc.Vec) -> None: # Example: # * 'A' (self) has global size (1, 1) # * 'x' has global size (n,) # * 'y' has global size (1,) # # A ⊗ x ➜ y # ■ ■ ■ # ■ # ■ # ■ # ■ y_array = y.array_w with self.buffer.vec_ro() as A: result = A.dot(x) if self.comm.rank == 0: y_array[...] = result
@functools.singledispatch def _denest(buffer: AbstractBuffer, nest_indices: tuple): utils.raise_missing_dispatch_handler(buffer) @_denest.register def _(mat_buf: PetscMatBuffer, nest_indices): mat = mat_buf.mat for ri, ci in nest_indices: mat = mat.getNestSubMatrix(ri, ci) return mat @_denest.register def _(array_buf: ArrayBuffer, nest_indices): assert not nest_indices return array_buf._current_device_array @functools.singledispatch def _extract_handle(data: Any): utils.raise_missing_dispatch_handler(data) @_extract_handle.register def _(mat: PETSc.Mat, /): if mat.type == PETSc.Mat.Type.PYTHON: return mat.getPythonContext().buffer._current_device_array else: return mat @_extract_handle.register def _(array: np.ndarray, /) -> np.ndarray: return array
[docs] @pyop3.record.frozenrecord() class IndexedBuffer(pyop3.obj.Object): """Class 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: AbstractBuffer nest_indices: tuple[tuple[int, ...], ...]
[docs] def collect_buffers(self, visitor): return visitor(self.buffer)
[docs] def get_disk_cache_key(self, visitor) -> Hashable: return (type(self), visitor(self.buffer), self.nest_indices)
get_instruction_executor_cache_key = get_disk_cache_key @property def name(self): return self.buffer.name @property def denested(self): return _denest(self.buffer, self.nest_indices) @property def handle(self): """Return the underlying data structure. This method will introspect the buffer and pull out the object needed by the compiler/executor. """ return _extract_handle(self.denested)