from __future__ import annotations
import abc
import collections
import contextlib
import dataclasses
import functools
import itertools
import numbers
import operator
import warnings
from collections.abc import Hashable, Iterable, Mapping
from typing import Any
import loopy.tools
import numpy as np
import pytools
from immutabledict import immutabledict as idict
import pyop3.collections
import pyop3.config
import pyop3.constants
import pyop3.exceptions
from pyop3.collections import unique # noqa: F401
from pyop3.dtypes import IntType
from pyop3.exceptions import (
UnhashableObjectException,
)
from ._utils_cy import try_cast_slice # noqa: F401
ndarray_types = (np.ndarray,)
try:
import cupy as cp
except ImportError:
pass
else:
ndarray_types += (cp.ndarray,)
[docs]
class UniqueNameGenerator(pytools.UniqueNameGenerator):
"""Class for generating unique names."""
[docs]
def __call__(self, prefix: str) -> str:
# To skip using prefix as a unique name we declare it as already used
self.add_name(prefix, conflicting_ok=True)
return super().__call__(prefix)
_unique_name_generator = UniqueNameGenerator()
"""Generator for creating globally unique names."""
[docs]
def unique_name(prefix: str) -> str:
return _unique_name_generator(prefix)
[docs]
def maybe_generate_name(name, prefix, default_prefix, *, generator=_unique_name_generator):
if name is not None:
if prefix is not None:
raise ValueError("Can only specify one of 'name' and 'prefix'")
if name in generator.existing_names:
# TODO: log a warning
return generator(name)
else:
generator.add_name(name)
return name
else:
if prefix is not None:
return generator(prefix)
else:
return generator(default_prefix)
# NOTE: Python 3.13 has warnings.deprecated
[docs]
def deprecated(prefer=None, internal=False):
def decorator(fn):
def wrapper(*args, **kwargs):
msg = f"{fn.__qualname__} is deprecated and will be removed"
if prefer:
msg += f", please use {prefer} instead"
warning_type = DeprecationWarning if internal else FutureWarning
warnings.warn(msg, warning_type)
return fn(*args, **kwargs)
return wrapper
return decorator
# remove me
# class auto:
# pass
[docs]
class Labeled(abc.ABC):
[docs]
@classmethod
def unique_id(cls) -> str:
return unique_name(f"_id_{cls.__name__}")
[docs]
def split_at(iterable, index):
return iterable[:index], iterable[index:]
[docs]
def single_valued(iterable):
items = iter(iterable)
try:
first = next(items)
except StopIteration:
raise pyop3.exceptions.EmptyIterableException("Iterable is empty")
for item in items:
if not safe_equals(first, item):
raise pyop3.exceptions.MultipleUniqueEntriesException("Iterable contains more than one unique value")
return first
[docs]
def is_single_valued(iterable):
try:
single_valued(iterable)
except (pyop3.exceptions.EmptyIterableException, pyop3.exceptions.MultipleUniqueEntriesException):
return False
else:
return True
[docs]
def merge_dicts(dicts: Iterable[Mapping]) -> idict:
merged = pyop3.collections.StrictlyUniqueDict()
for dict_ in dicts:
merged.update(dict_)
return idict(merged)
[docs]
def has_unique_entries(iterable):
# duplicate the iterator in case it can only be iterated over once (e.g. a generator)
it1, it2 = itertools.tee(iterable, 2)
return len(pyop3.collections.unique(it1)) == len(list(it2))
[docs]
def is_sorted(array: np.ndarray) -> np.bool:
"""
Notes
-----
This function works even for empty arrays, which are reported as being
sorted.
"""
return np.all(array[:-1] <= array[1:])
[docs]
def reduce(func, *args, **kwargs):
if isinstance(func, str):
match func:
case "+":
func = operator.add
case "*":
func = operator.mul
case "|":
func = operator.or_
case _:
raise ValueError
return functools.reduce(func, *args, **kwargs)
[docs]
def is_sequence(item):
return isinstance(item, collections.abc.Sequence)
[docs]
def flatten(iterable):
"""Recursively flatten a nested iterable."""
if isinstance(iterable, tuple(ndarray_types)):
return iterable.flatten()
if not isinstance(iterable, (list, tuple)):
return (iterable,)
return tuple(item_ for item in iterable for item_ in flatten(item))
[docs]
def some_but_not_all(iterable):
# duplicate the iterable in case using any/all consumes it
it1, it2 = itertools.tee(iterable)
return any(it1) and not all(it2)
[docs]
def strictly_all(iterable):
"""Returns ``all(iterable)`` but raises an exception if values are inconsistent."""
if not isinstance(iterable, collections.abc.Iterable):
raise TypeError("Expecting an iterable")
# duplicate the iterable in case using any/all consumes it
it1, it2 = itertools.tee(iterable)
if (result := any(it1)) and not all(it2):
raise ValueError("Iterable contains inconsistent values")
return result
[docs]
def just_one(iterable: collections.abc.Iterable) -> Any:
"""Return the only entry in an iterable.
Parameters
----------
iterable
The container with only a single entry.
Returns
-------
Any
The single item in ``iterable``.
Raises
------
ValueError
If the iterable does not contain a single entry.
"""
iterator = iter(iterable)
try:
first = next(iterator)
except StopIteration:
raise pyop3.exceptions.EmptyIterableException("Iterable is empty")
try:
next(iterator)
except StopIteration:
return first
else:
raise pyop3.exceptions.NonUnitIterableException("Iterable contains too many values")
[docs]
def popwhen(predicate, iterable):
"""Pop the first instance from iterable where predicate is ``True``."""
if not isinstance(iterable, list):
raise TypeError("Expecting iterable to be a list")
for i, item in enumerate(iterable):
if predicate(item):
return iterable.pop(i)
raise KeyError("Predicate does not hold for any items in iterable")
[docs]
def steps(sizes, *, drop_last=True, dtype=None):
if isinstance(sizes, np.ndarray):
assert dtype is None
dtype = sizes.dtype
steps_ = np.concatenate([[0], np.cumsum(sizes)], dtype=dtype)
return readonly(steps_[:-1]) if drop_last else readonly(steps_)
[docs]
def strides(sizes, *, drop_last=True) -> np.ndarray[int]:
"""
Examples
--------
# I think...
(2, 2) returns (2, 2) - 2i + j
(1, 2) returns (2, 1) - 2i + j
(2, 1) returns (1, 1) - i + j
"""
assert drop_last, "old code otherwise"
# reversed_sizes = np.asarray(sizes, dtype=int)[::-1]
# strides_ = np.concatenate([[1], np.cumprod(reversed_sizes[:-1])], dtype=int)
reversed_sizes = np.asarray(sizes)[::-1]
strides_ = np.concatenate([[1], np.cumprod(reversed_sizes[:-1])])
return readonly(strides_[::-1])
[docs]
def pairwise(iterable, *, final=pyop3.constants.NOTHING):
if final is not pyop3.constants.NOTHING:
return itertools.zip_longest(iterable, iterable[1:], fillvalue=final)
else:
return zip(iterable, iterable[1:])
# stolen from stackoverflow
# https://stackoverflow.com/questions/11649577/how-to-invert-a-permutation-array-in-numpy
[docs]
def invert(p):
"""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.
"""
p = np.asanyarray(p) # in case p is a tuple, etc.
s = np.empty_like(p)
s[p] = np.arange(p.size)
return s
[docs]
def invert_mapping(mapping, *, mapping_type=dict):
return mapping_type((v, k) for k, v in mapping.items())
[docs]
def strict_cast(obj: Any, dtype: type | np.dtype) -> Any:
if isinstance(obj, numbers.Number):
return np.array([obj]).astype(dtype, casting="same_kind").item()
else:
return obj.astype(dtype, casting="same_kind")
[docs]
def strict_int(num: numbers.Number) -> np.dtype[IntType]:
return strict_cast(num, IntType)
[docs]
def strict_floordiv(num: numbers.Number, fac):
assert num % fac == 0
return num // fac
[docs]
def as_dtype(dtype, default: np.dtype) -> np.dtype:
return np.dtype(dtype) if dtype else default
[docs]
def apply_at(func, iterable, index):
if index < 0 or index >= len(iterable):
raise IndexError
result = []
for i, item in enumerate(iterable):
if i == index:
result.append(func(item))
else:
result.append(item)
return tuple(result)
[docs]
def map_when(func, when_func, iterable):
for item in iterable:
if when_func(item):
yield func(item)
else:
yield item
[docs]
def readonly(array):
"""Return a readonly view of a numpy/cupy array."""
view = array.view()
if isinstance(array, np.ndarray):
view.setflags(write=False)
return view
[docs]
def debug_assert(predicate, msg=None):
if pyop3.config.debug_checks:
if msg:
assert predicate(), msg
else:
assert predicate()
# TODO: case for using typing generics
# TODO: signature is slightly wrong, can pass anything that can be cast to a dict
[docs]
def expand_collection_of_iterables(compressed: Mapping[Hashable, collections.abc.Sequence[Any]]) -> tuple[idict[Hashable, Any], ...]:
"""
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 ``compressed`` include ordered mappings and iterables
of 2-tuples (i.e. things that can be parsed into a `dict`).
"""
# If `compressed` is not already a mapping then parse it to one
if not isinstance(compressed, Mapping):
compressed = dict(compressed)
if not compressed:
return (idict(),)
else:
compressed_mut = dict(compressed)
return _expand_dict_of_iterables_rec(compressed_mut)
def _expand_dict_of_iterables_rec(compressed_mut):
expanded = []
key, items = popfirst(compressed_mut)
if compressed_mut:
subexpanded = _expand_dict_of_iterables_rec(compressed_mut)
for item in items:
entry = idict({key: item})
for subentry in subexpanded:
expanded.append(entry | subentry)
else:
for item in items:
entry = idict({key: item})
expanded.append(entry)
return tuple(expanded)
[docs]
def split_by(condition, items):
"""Split an iterable in two according to some condition.
:arg condition: Callable applied to each item in ``items``, returning ``True``
or ``False``.
:arg items: Iterable to split apart.
:returns: A 2-tuple of the form ``(yess, nos)``, where ``yess`` is a tuple containing
the entries of ``items`` where ``condition`` is ``True`` and ``nos`` is a tuple
of those where ``condition`` is ``False``.
"""
result = [], []
for item in items:
if condition(item):
result[0].append(item)
else:
result[1].append(item)
return tuple(result[0]), tuple(result[1])
[docs]
def popfirst(dict_: dict) -> Any:
"""Remove the first item from a dictionary and return it with its key."""
if not dict_:
raise ValueError("Expected a non-empty dict")
key = next(iter(dict_))
return (key, dict_.pop(key))
[docs]
@functools.singledispatch
def freeze(obj: Any) -> Hashable:
raise UnhashableObjectException
@freeze.register
def _(tuple_: tuple) -> tuple:
return tuple(map(freeze, tuple_))
@freeze.register
def _(slice_: slice) -> pyop3.collections.HashableSlice:
return pyop3.collections.HashableSlice.from_slice(slice_)
@freeze.register
def _(list_: list) -> tuple:
return tuple(map(freeze, list_))
@freeze.register
def _(immutabledict_: idict) -> idict:
return idict({
key: freeze(value)
for key, value in immutabledict_.items()
})
@freeze.register
def _(dict_: dict) -> idict:
return idict({
key: freeze(value)
for key, value in dict_.items()
})
@freeze.register
def _(hashable: Hashable) -> Hashable:
return hashable
[docs]
def iterflat(iterable):
if isinstance(iterable, np.ndarray):
iterable = iterable.flatten()
return iter(iterable)
[docs]
def as_numpy_scalar(value: numbers.Number) -> np.number:
return just_one(np.asarray([value]))
[docs]
def filter_type(type_: type, iterable: Iterable):
return filter(lambda item: isinstance(item, type_), iterable)
[docs]
def ceildiv(a, b, /):
assert b != 0
if b == 1:
return a
else:
# See https://stackoverflow.com/a/17511341
return -(a // -b)
[docs]
def regexify(pattern: str):
"""Convert an expression pattern into a regex pattern.
This is useful for testing.
"""
# Escape common characters
for char in ["(", ")", "[", "]", "*", "+"]:
pattern = pattern.replace(char, f"\\{char}")
# Convert '#' to '\d+' (to avoid numbering issues with arrays)
pattern = pattern.replace("#", r"\d+")
return pattern
[docs]
def is_ellipsis_type(obj: Any) -> bool:
return (
obj is Ellipsis
or (
isinstance(obj, collections.abc.Sequence)
and all(item is Ellipsis for item in obj)
)
)
[docs]
@contextlib.contextmanager
def stack(list_, to_push):
list_.extend(to_push)
yield
for _ in to_push:
list_.pop(-1)
[docs]
@contextlib.contextmanager
def dict_stack(dict_, to_push):
for key, value in to_push.items():
dict_[key] = value
yield
for key in to_push:
dict_.pop(key)
[docs]
def pretty_type(obj: Any) -> str:
type_ = type(obj)
return f"{type_.__module__}.{type_.__name__}"
[docs]
def safe_equals(a, b, /) -> bool:
if any(isinstance(x, ndarray_types) for x in [a, b]):
return (a == b).all()
elif any(isinstance(x, Mapping) for x in [a, b]):
if a.keys() != b.keys():
return False
return all(safe_equals(a[k], b[k]) for k in a)
else:
return bool(a == b)
[docs]
def raise_missing_dispatch_handler(obj: Any) -> None:
raise TypeError(f"No handler defined for {pretty_type(obj)}")
_loopy_key_builder = loopy.tools.LoopyKeyBuilder()
"""Persistent object for computing hashes of loopy kernels."""
[docs]
@dataclasses.dataclass(frozen=True)
class Atom:
"""Wrapper 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: Any
[docs]
def atom(item):
return Atom(item)