ramp-coreoperator 0.0.2__py3-none-any.whl

coreoperator/__init__.py

@@ -0,0 +1,14 @@
+"""
+Package for defining operations on core states and for maintaining an
+operational history for it.
+"""
+
+from .featherstate import FeatherState
+from .history import History, OperationalPeriod, StateParams
+from .mobilization import jsonable as mob_jsonable
+from .operational_state import OperationalState
+
+jsonable = mob_jsonable + [History, OperationalState, FeatherState, OperationalPeriod, StateParams]
+
+__all__ = ["jsonable", "OperationalState", "FeatherState", "History", "StateParams"]
+

coreoperator/example.py

@@ -0,0 +1,11 @@
+from coremaker.example import example_core
+
+from coreoperator.history import History, StateParams
+from coreoperator.operational_state import OperationalState
+
+blank_hist = History()
+example_state = OperationalState(history=blank_hist,
+                                 params=StateParams(power=0),
+                                 tags={"blank"},
+                                 core=example_core,
+                                 )

coreoperator/featherstate.py

@@ -0,0 +1,89 @@
+import pickle
+import zlib
+from typing import Any, Literal, Type, TypeVar
+
+try:
+    from typing import Self
+except ImportError:
+    Self = TypeVar("Self")
+
+from coremaker.core import Core
+
+from .operational_state import OperationalState
+
+Zlib_Compression = Literal[-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+DEFAULT_COMPRESSION = 2 # A sensible default, fast and still has an effect for us
+
+
+class FeatherState(OperationalState):
+    """An OperationalState that takes less space in memory and is much easier to
+    transmit over the wire.
+
+    This comes at the cost of slightly less comfortable ergonomics, because one
+    cannot directly edit `state.core` and has to explicitly reset the core with
+    a setter method to make changes stick.
+    To make the ergonomics similar, we made OperationalState similarly complex,
+    but deem the tradeoff to be worth the trouble.
+
+    """
+
+    ser_identifier = "FeatherState"
+    __zcore: bytes
+
+    def __init__(self, *, compression_level: Zlib_Compression = DEFAULT_COMPRESSION, **kw):
+        """
+        
+        Parameters
+        ----------
+        compression_level: Zlib_Compression
+            The compression level to use. See the `zlib` standard library documentation for details.
+            Defaults to a fast compression that still has a significant impact. Subject to change.
+        kw:
+            Keywords used to make an OperationalState. See that class for details.
+
+        """
+        self.compression_level = compression_level
+        super().__init__(**kw)
+
+    def serialize(self) -> tuple[str, dict[str, Any]]:
+        parent_serialized_data = super().serialize()[1]
+        parent_serialized_data["compression"] = self.compression_level
+        return self.ser_identifier, parent_serialized_data
+
+    @classmethod
+    def deserialize(cls: Type[Self], d: dict[str, Any], *args, **kwargs) -> Self:
+        compression = d.pop("compression")
+        return cls.from_state(super().deserialize(d=d, *args, **kwargs), compression_level=compression)
+
+    @classmethod
+    def from_state(cls: Type[Self], 
+                   state: OperationalState,
+                   compression_level: Zlib_Compression = DEFAULT_COMPRESSION,
+                   ) -> Self:
+        """Creates a FeatherState from an OperationalState
+
+        Parameters
+        ----------
+        state: OperationalState
+            The OperationalState to compress
+        compression_level: Zlib_Compression
+            The compression level to use. See the `zlib` standard library documentation for details.
+
+        """
+        if isinstance(state, FeatherState):
+            state.compression_level = compression_level
+            return state
+        return cls(**state.as_dict(), compression_level=compression_level)
+
+    @property
+    def core(self) -> Core:
+        return pickle.loads(zlib.decompress(self.__zcore))
+
+    @core.setter
+    def core(self, core):
+        self.__zcore = zlib.compress(pickle.dumps(core), self.compression_level)
+
+    @property
+    def _core(self) -> Core:
+        return self.core
+

coreoperator/history.py

@@ -0,0 +1,228 @@
+from dataclasses import dataclass, field, replace
+from datetime import timedelta
+from itertools import takewhile
+from typing import Any, ClassVar, Generator, Hashable, Type, TypeVar
+
+try:
+    from typing import Self
+except ImportError:
+    Self = TypeVar("Self")
+
+from ramp_core.serializable import Serializable, deserialize_default
+from scipy.constants import day
+
+from coreoperator.mobilization import Scheme
+
+MW = MWD = float
+
+
+class StateParams(Serializable):
+    """A container of operational parameters. Some are required, many are allowed.
+
+    Please use hashable values
+
+    """
+
+    ser_identifier = "StateParams"
+
+    def __init__(self, power: MW, **kwargs: dict[str, Hashable]):
+        self.power = power
+        self._attrs = kwargs
+
+    def serialize(self) -> tuple[str, dict[str, Any]]:
+        return self.ser_identifier, self.todict()
+
+    @classmethod
+    def deserialize(cls: Type[Self], d: dict[str, Any], *_, **__) -> Self:
+        return cls(**d)
+
+    def copy(self: Self, **kwargs: dict[str, Hashable]) -> Self:
+        """Creates a copy of these parameters, but allows changes.
+        Kind of like a dataclass' replace, but with arbitrary keywords.
+
+        """
+        kw = self.todict() | kwargs
+        return type(self)(**kw)
+
+    def __getitem__(self, item: str):
+        return self.power if item == "power" else self._attrs[item]
+
+    def __delitem__(self, key: str):
+        if key == "power":
+            raise KeyError("Not allowed to delete the power parameter from StateParams")
+        del self._attrs[key]
+
+    def __setitem__(self, key: str, value: Hashable):
+        if key == "power":
+            self.power = value
+        else:
+            self._attrs[key] = value
+
+    def __iter__(self) -> Generator[tuple[str, Hashable], None, None]:
+        yield "power", self.power
+        yield from self._attrs.items()
+
+    def __hash__(self):
+        return hash(frozenset((key, value) for key, value in self))
+
+    def __eq__(self, other):
+        if not isinstance(other, type(self)):
+            return NotImplemented
+        return self.todict() == other.todict()
+
+    def __repr__(self): return str(self.todict())
+
+    def todict(self) -> dict[str, Hashable]:
+        return dict(iter(self))
+
+
+@dataclass(frozen=True)
+class OperationalPeriod(Serializable):
+    """A segment of time with given operational parameters
+
+    Parameters
+    ----------
+    params: StateParams
+        The operational parameters during this period.
+    time: timedelta
+        Period length
+
+    """
+    params: StateParams
+    time: timedelta
+
+    ser_identifier: ClassVar[str] = "OpPeriod"
+
+    def serialize(self) -> tuple[str, dict[str, Any]]:
+        return self.ser_identifier, {"params": self.params.serialize(), "time": self.time.total_seconds()}
+
+    @classmethod
+    def deserialize(cls: Type[Self], d: dict[str, Any], *, supported: dict[str, Type[Serializable]]) -> Self:
+        params: StateParams = deserialize_default(d["params"], supported=supported, default=StateParams)
+        time = timedelta(seconds=d["time"])
+        return cls(params, time)
+
+    def copy(self: Self, 
+             params: StateParams | None = None, 
+             time: timedelta | None = None
+             ) -> Self:
+        """Creates a copy of this period with some changes.
+
+        Parameters
+        ----------
+        params: StateParams
+            Parameters to change from the original
+        time: timedelta
+            Period of time, if period changes.
+        """
+        pars = self.params.copy(**params.todict()) if params is not None else self.params
+        time = time if time is not None else self.time
+        return replace(self, params=pars, time=time)
+
+    @property
+    def burnup(self) -> MWD:
+        return self.params.power * self.time.total_seconds() / day
+
+
+@dataclass(frozen=True)
+class History(Serializable):
+    """Historical information about the core.
+
+    Basically a sequentially growing list of steps at piecewise constant parameters.
+
+    """
+
+    steps: list[OperationalPeriod | Scheme] = field(default_factory=list)
+
+    ser_identifier: ClassVar[str] = "OpHistory"
+
+    def serialize(self) -> tuple[str, dict[str, Any]]:
+        return self.ser_identifier, {"steps": [step.serialize() for step in self.steps]}
+
+    @classmethod
+    def deserialize(cls: Type[Self], d: dict[str, Any], *, supported: dict[str, Type[Serializable]]) -> Self:
+        steps = [deserialize_default(step, supported=supported) for step in d["steps"]]
+        return cls(steps)
+
+    def new_cycle(self: Self, scheme: Scheme) -> Self:
+        """Adds a new scheme to the history, marking the beginning of a new cycle.
+
+        Parameters
+        ----------
+        scheme: Scheme
+            The scheme to perform on the core between cycles.
+
+        Returns
+        -------
+        History
+            The new History created by adding the scheme to this history.
+            Steps are joined if the last step was a scheme, so we combine them into one bigger scheme.
+
+        """
+        cls = type(self)
+        if len(self) == 0:
+            return cls([scheme])
+        last = self.steps[-1]
+        if isinstance(last, Scheme):
+            return cls(self.steps[:-1] + [last @ scheme])
+        return cls(self.steps + [scheme])
+
+    def __len__(self) -> int: return len(self.steps)
+
+    def timestep(self: Self, params: StateParams, time: timedelta) -> Self:
+        """Adds a time step to the history, where the core worked with some parameters for some time.
+
+        Parameters
+        ----------
+        params: StateParams
+            The parameters the core worked under during this step
+        time: timedelta
+            Period of time the core worked under these parameters.
+
+        Returns
+        -------
+        History
+            The new history with the added step. Steps are joined if the last step matched this one's parameters.
+
+        """
+        cls = type(self)
+        if len(self) == 0:
+            return cls([OperationalPeriod(params, time)])
+        last = self.steps[-1]
+        if isinstance(last, OperationalPeriod) and last.params == params:
+            return cls(self.steps[:-1] + [last.copy(time=last.time + time)])
+        return cls(self.steps + [OperationalPeriod(params, time)])
+
+    @property
+    def current_params(self) -> StateParams | None:
+        """Returns the last known parameters, or None if there are none.
+
+        """
+        for step in self.steps[::-1]:
+            if isinstance(step, OperationalPeriod):
+                return step.params
+        else:
+            return None
+
+    @property
+    def cycles(self) -> int:
+        """The number of cycles in the history"""
+        return sum((1 for step in self.steps if isinstance(step, Scheme)))
+
+    @property
+    def cycle_burnup(self) -> MWD:
+        """The amount of burnup since the start of this cycle"""
+        cycle = takewhile(lambda x: isinstance(x, OperationalPeriod), self.steps[::-1])
+        return sum((self.burnup for step in cycle))
+
+    @property
+    def cycle_time(self) -> timedelta:
+        cycle = takewhile(lambda x: isinstance(x, OperationalPeriod), self.steps[::-1])
+        return sum((step.time for step in cycle), timedelta(0))
+
+    def __repr__(self) -> str:
+        return f"Cycles: {self.cycles}, Burnup: {self.cycle_burnup:.3f} MWD"
+
+    def __hash__(self) -> int:
+        return hash(tuple(self.steps))
+

coreoperator/mobilization/__init__.py

@@ -0,0 +1,8 @@
+from .cyclic_shuffle import CyclicShuffle
+from .grid_action import GridAction as GridAction
+from .load import LoadSite, LoadChain
+from .remove import Remove
+from .scheme import Scheme
+from .transform_inplace import TransformInPlace
+
+jsonable = [CyclicShuffle, LoadSite, LoadChain, Remove, Scheme, TransformInPlace]

coreoperator/mobilization/apply.py

@@ -0,0 +1,47 @@
+from typing import Hashable, MutableMapping, Sequence
+
+from coremaker.protocols.core import Site
+from coremaker.protocols.element import Element
+from coremaker.transform import Transform
+
+Alias = Hashable
+SCRAM = Element
+
+MaybeRod = Element | None
+SiteDict = MutableMapping[Site, Element]
+
+
+def _set_rods(coresites: SiteDict, new_sites: dict[Site, MaybeRod]):
+    for site, rod in new_sites.items():
+        if rod:
+            coresites[site] = rod
+        elif site in coresites:
+            del coresites[site]
+        elif site not in coresites:
+            raise ValueError(f"can't remove the contents of the unoccupied "
+                             f"site:{site}")
+
+
+def get_transformed_rods(sites: Sequence[tuple[Site, Transform]],
+                         rods_at_sites: SiteDict) -> Sequence[Element]:
+    """
+    Function that returns the transformed rods at the given sites under the
+    given transformation.
+
+    Parameters
+    ----------
+    sites: Sequence[Tuple[Site, Transform]]
+        Sequence of sites and the transforms at each site
+    rods_at_sites: SiteDict
+        Dict of sites and the rods at those sites.
+
+    Returns
+    -------
+    Sequence[Element]
+        Sequence of the rods at the given sites after the transforms.
+    """
+    rods = [rods_at_sites[site] for (site, _) in sites]
+    for (_, transform), rod in zip(sites, rods):
+        rod.transform(None, transform)
+    return rods
+

coreoperator/mobilization/cyclic_shuffle.py

@@ -0,0 +1,47 @@
+from operator import itemgetter
+from typing import Sequence
+
+from coremaker.protocols.core import Site
+from coremaker.transform import identity
+
+from coreoperator.mobilization.grid_action import (
+    DefinitePosition,
+    GridAction,
+    Position,
+    SiteDict,
+    _ensure_unique,
+    get_transformed_rods,
+    rotate_left,
+    rotate_right,
+    set_rods,
+)
+
+
+class CyclicShuffle(GridAction):
+    """represents a single connected right permutation of rods"""
+
+    ser_identifier = "CycShuffle"
+
+    def __init__(self, sites: Sequence[Position]):
+        _ensure_unique(sites)
+        self.sites: list[DefinitePosition] = [
+            (site, identity) if isinstance(site, Site) else site
+            for site in sites]
+        self._movement = frozenset(zip(rotate_left(self.sites), self.sites))
+
+    def apply(self, d: SiteDict) -> None:
+        sites = rotate_right(self.sites)
+        rods = get_transformed_rods(sites, d)
+        news = dict(zip(map(itemgetter(0), self.sites), rods))
+        set_rods(d, news)
+
+    def __eq__(self, other):
+        if not isinstance(other, type(self)):
+            return NotImplemented
+        return self._movement == other._movement
+
+    def __hash__(self):
+        return hash(self._movement)
+
+    def __repr__(self):
+        return 'Shuffle: ->' + '->'.join(map(repr, self.sites)) + '->'

coreoperator/mobilization/grid_action.py

@@ -0,0 +1,201 @@
+from collections import Counter
+from itertools import cycle, islice
+from typing import Any, Hashable, Iterable, Mapping, Protocol, Sequence, Type, TypeVar
+
+try:
+    from typing import Self
+except ImportError:
+    Self = TypeVar("Self")
+
+from coremaker.protocols.core import Site
+from coremaker.protocols.element import Element
+from coremaker.transform import Transform
+from ramp_core.serializable import Serializable
+
+DefinitePosition = tuple[Site, Transform]
+Position = Site | DefinitePosition
+T = TypeVar("T")
+
+
+class SiteDict(Protocol):
+    """Partial requirements from a mutable mapping of Site -> Element"""
+
+    def __getitem__(self, item: Site) -> Element: ...
+
+    def __setitem__(self, key: Site, value: Element) -> None: ...
+
+    def __delitem__(self, key: Site) -> None: ...
+
+
+class IllegalActionError(ValueError):
+    """Error class for illegal grid actions"""
+
+
+def _ensure_unique(positions: Sequence[Position]):
+    if not positions:
+        raise IllegalActionError("Cannot create an action with no sites")
+    sites = [pos if isinstance(pos, Site) else pos[0] for pos in positions]
+    counter = Counter(sites)
+    if set(counter.values()) != {1}:
+        repeats = {site for site, v in counter.items() if v > 1}
+        raise IllegalActionError(
+            f"Some sites appear more than once in an action: {repeats}"
+        )
+
+
+class GridAction(Hashable, Serializable, Protocol):
+    """
+    Protocol for an action preformed on sites in a Grid
+    """
+
+    sites: Sequence[Position]
+
+    def apply(self, d: SiteDict) -> None:
+        """Applies the action to the mapping.
+
+        Parameters
+        ----------
+        d: SiteDict
+            Mapping of sites to contents that will be edited
+
+        """
+        ...
+
+    def serialize(self) -> tuple[str, dict[str, Any]]:
+        return self.ser_identifier, {"sites": ser_sites(self.sites)}
+
+    @classmethod
+    def deserialize(cls: Type[Self], d: dict[str, Any], *_, **__) -> Self:
+        return cls(deser_sites(d["sites"]))
+
+
+def rotate_left(it: Iterable[T], n: int = 1) -> tuple[T, ...]:
+    """Return a tuple sequence that is a left-rotated version of a finite iterable.
+
+    Parameters
+    ----------
+    it: Iterable
+        Iterable of finite size to rotate.
+
+    n: int
+        The number of left rotations to perform.
+
+    Returns
+    -------
+    Tuple of the same items in the iterable but with a different order.
+
+    """
+    seq = tuple(it)
+    return tuple(islice(cycle(seq), n, n + len(seq)))
+
+
+def rotate_right(it: Iterable[T], n: int = 1) -> tuple[T, ...]:
+    """Return a tuple sequence that is the right-rotated version of a finite iterable.
+
+    Parameters
+    ----------
+    it: Iterable
+        Iterable of finite size to rotate
+    n: int
+        The number of right rotations to perform.
+
+    Returns
+    -------
+    Tuple of the same items in the iterable but with a different order.
+
+    """
+    seq = tuple(it)
+    return rotate_left(it, n=(-n) % len(seq))
+
+
+def set_rods(coresites: SiteDict, new_sites: Mapping[Site, Element | None]) -> None:
+    """Update rods in the mapping according to the new mapping
+
+    Parameters
+    ----------
+    coresites: SiteDict
+        Original mapping
+    new_sites: Mapping[Site, Element | None]
+        New information mapping.
+        Where a site points to an element, we set that in the new mapping.
+        Where it points to None, we eject the rod from that site.
+
+    Raises
+    ------
+    IllegalActionError
+        Raises if a site in new_sites points to None but that site isn't occupied
+        in the original mapping.
+
+    """
+    for site, rod in new_sites.items():
+        if rod:
+            coresites[site] = rod
+        elif site in coresites:
+            del coresites[site]
+        else:
+            raise IllegalActionError(
+                f"Can't remove the contents of the unoccupied site: {site}"
+            )
+
+
+def get_transformed_rods(
+    sites: Sequence[tuple[Site, Transform]], rods_at_sites: SiteDict
+) -> Sequence[Element]:
+    """Function that returns the transformed rods at the given sites under the given transformation.
+
+    Parameters
+    ----------
+    sites: Sequence[tuple[Site, Transform]]
+        Sequence of sites and the transforms at each site.
+    rods_at_sites: SiteDict
+        Mapping of sites and the rods therein.
+
+    Returns
+    -------
+    Sequence[Element]
+        Sequence of the rods at the given sites after the transforms.
+
+    """
+    rods = [rods_at_sites[site] for site, _ in sites]
+    for (_, transform), rod in zip(sites, rods):
+        rod.transform(None, transform)
+    return rods
+
+
+def ser_sites(sites: Iterable[Position]) -> list:
+    """Serialize sites as they are written in grid actions
+
+    Parameters
+    ----------
+    sites: Iterable[Position]
+        Sites to serialize
+
+    Returns
+    -------
+    Serialized form of the sites
+
+    """
+    return [
+        [ptup[0], ptup[1].serialize()] if isinstance(ptup, tuple) else ptup
+        for ptup in sites
+    ]
+
+
+def deser_sites(slist: list[tuple[str, dict]]) -> list[Position]:
+    """Deserialize sites from the common format made by ser_sites
+
+    Parameters
+    ----------
+    slist: list[tuple[str, dict]]
+        Actually a list of 2-lists of this form.
+
+    Returns
+    -------
+    list[Position]
+        The list of positions we started with.
+
+    """
+    return [
+        (ptup[0], Transform.deserialize(ptup[1])) if isinstance(ptup, list) else ptup
+        for ptup in slist
+    ]