asimpy 0.1.0__py3-none-any.whl

asimpy/__init__.py

@@ -0,0 +1,8 @@
+"""Discrete event simulation using async/await."""
+
+from .environment import Environment as Environment
+from .gate import Gate as Gate
+from .interrupt import Interrupt as Interrupt
+from .process import Process as Process
+from .queue import Queue as Queue
+from .resource import Resource as Resource

asimpy/actions.py

@@ -0,0 +1,26 @@
+"""Awaitable actions."""
+
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .environment import Environment
+
+
+class BaseAction:
+    """
+    Base of all internal awaitable actions. Simulation authors should not use this directly.
+    """
+
+    def __init__(self, env: "Environment"):
+        """
+        Construct a new awaitable action.
+
+        Args:
+            env: simulation environment.
+        """
+        self._env = env
+
+    def __await__(self) -> Any:
+        """Handle `await`."""
+        yield self
+        return None

asimpy/environment.py

@@ -0,0 +1,121 @@
+"""Simulation environment."""
+
+from dataclasses import dataclass
+import heapq
+from .actions import BaseAction
+from .process import Process
+
+
+class Environment:
+    """Simulation environment."""
+
+    def __init__(self, logging: bool = False):
+        """
+        Construct a new simulation environment.
+
+        Args:
+            logging: print log messages while executing.
+        """
+        self.now = 0
+        self._queue = []
+        self._logging = logging
+
+    def immediate(self, proc: Process):
+        """
+        Start a new process immediately.
+
+        Args:
+            proc: `Process`-derived object to schedule and run.
+        """
+        self.schedule(self.now, proc)
+
+    def schedule(self, time: float | int, proc: Process):
+        """
+        Schedule a process to run at a specified time (*not* after a delay).
+
+        Args:
+            time: when the process should be scheduled to run.
+            proc: `Process`-derived object to run.
+        """
+        heapq.heappush(self._queue, _Pending(time, proc))
+
+    def sleep(self, delay: float | int) -> "_Sleep":
+        """
+        Suspend the caller for a specified length of time.
+
+        Args:
+            delay: how long to sleep.
+
+        Returns: awaitable representing delay.
+        """
+        return _Sleep(self, delay)
+
+    def run(self, until: float | int | None = None):
+        """
+        Run the whole simulation.
+
+        Args:
+            until: when to stop (run forever if not provided).
+        """
+        while self._queue:
+            if self._logging:
+                print(self)
+
+            pending = heapq.heappop(self._queue)
+
+            if until is not None and pending.time > until:
+                break
+
+            self.now = pending.time
+            proc = pending.proc
+
+            try:
+                if proc._interrupt is None:
+                    awaited = proc._coro.send(None)
+                else:
+                    exc, proc._interrupt = proc._interrupt, None
+                    awaited = proc._coro.throw(exc)
+
+                awaited.act(proc)
+
+            except StopIteration:
+                continue
+
+    def __str__(self) -> str:
+        """
+        Format environment as printable string.
+
+        Returns: string representation of environment time and queue.
+        """
+        return f"Env(t={self.now}, {' | '.join(str(p) for p in self._queue)})"
+
+
+# ----------------------------------------------------------------------
+
+
+@dataclass
+class _Pending:
+    """Keep track of a waiting process."""
+
+    time: float
+    proc: Process
+
+    def __lt__(self, other: "_Pending") -> bool:
+        return self.time < other.time
+
+    def __str__(self) -> str:
+        return f"Pend({self.time}, {self.proc})"
+
+
+class _Sleep(BaseAction):
+    """Wait for a specified simulated time."""
+
+    def __init__(self, env: Environment, delay: float | int):
+        super().__init__(env)
+        self._delay = delay
+
+    def act(self, proc: Process):
+        self._env.schedule(self._env.now + self._delay, proc)
+
+    def __str__(self) -> str:
+        return f"_Sleep({self._delay})"

asimpy/gate.py

@@ -0,0 +1,57 @@
+"""Gate that holds multiple processes until flagged."""
+
+from typing import TYPE_CHECKING
+from .actions import BaseAction
+from .process import Process
+
+if TYPE_CHECKING:
+    from .environment import Environment
+
+
+class Gate:
+    """Gate that multiple processes can wait on for simultaneous release."""
+
+    def __init__(self, env: "Environment"):
+        """
+        Construct a new gate.
+
+        Args:
+            env: simulation environment.
+        """
+        self._env = env
+        self._waiting = []
+
+    async def wait(self):
+        """Wait until gate is next opened."""
+        await _Wait(self)
+
+    async def release(self):
+        """Release all waiting processes."""
+        await _Release(self)
+
+
+# ----------------------------------------------------------------------
+
+
+class _Wait(BaseAction):
+    """Wait at the gate."""
+
+    def __init__(self, gate: Gate):
+        super().__init__(gate._env)
+        self._gate = gate
+
+    def act(self, proc: Process):
+        self._gate._waiting.append(proc)
+
+
+class _Release(BaseAction):
+    """Release processes waiting at gate."""
+
+    def __init__(self, gate: Gate):
+        super().__init__(gate._env)
+        self._gate = gate
+
+    def act(self, proc: Process):
+        while self._gate._waiting:
+            self._env.schedule(self._env.now, self._gate._waiting.pop())
+        self._env.schedule(self._env.now, proc)

asimpy/interrupt.py

@@ -0,0 +1,25 @@
+"""Interruption exceptions."""
+
+from typing import Any
+
+
+class Interrupt(Exception):
+    """Custom exception class for interruptions."""
+
+    def __init__(self, cause: Any):
+        """
+        Construct a new interruption exception.
+
+        Args:
+            cause: reason for interruption.
+        """
+        super().__init__()
+        self.cause = cause
+
+    def __str__(self) -> str:
+        """
+        Format interruption as printable string.
+
+        Returns: string representation of interruption and cause.
+        """
+        return f"Interrupt({self.cause})"

asimpy/process.py

@@ -0,0 +1,56 @@
+"""Base class for processes."""
+
+from abc import ABC, abstractmethod
+from typing import Any, TYPE_CHECKING
+
+from .interrupt import Interrupt
+
+if TYPE_CHECKING:
+    from .environment import Environment
+
+
+class Process(ABC):
+    """Base class for active processes."""
+
+    def __init__(self, env: "Environment", *args: Any):
+        """
+        Construct a new process by performing common initialization,
+        calling the user-defined `init()` method (no underscores),
+        and registering the coroutine created by the `run()` method
+        with the environment.
+
+        Args:
+            env: simulation environment.
+            *args: to be passed to `init()` for custom initialization.
+        """
+        self.env = env
+        self._interrupt = None
+
+        self.init(*args)
+
+        self._coro = self.run()
+        self.env.immediate(self)
+
+    def init(self, *args: Any, **kwargs: Any) -> None:
+        """
+        Default (do-nothing) post-initialization method.
+
+        To satisfy type-checking, derived classes must also declare `*args`
+        rather than listing specific parameters by name.
+        """
+        pass
+
+    def interrupt(self, cause: Any):
+        """
+        Interrupt this process by raising an `Interrupt` exception the
+        next time the process is scheduled to run.
+
+        Args:
+            cause: reason for interrupt (attacked to `Interrupt` exception).
+        """
+        self._interrupt = Interrupt(cause)
+
+    @abstractmethod
+    def run(self):
+        """Actions for this process."""
+        pass

asimpy/queue.py

@@ -0,0 +1,87 @@
+"""Queues."""
+
+from abc import ABC, abstractmethod
+from .actions import BaseAction
+
+
+class BaseQueue(ABC):
+    def __init__(self, env):
+        self._env = env
+        self._gets = []
+
+    async def get(self):
+        return await _Get(self)
+
+    async def put(self, obj):
+        await _Put(self, obj)
+
+    @abstractmethod
+    def _dequeue(self):
+        pass
+
+    @abstractmethod
+    def _empty(self):
+        pass
+
+    @abstractmethod
+    def _enqueue(self, obj):
+        pass
+
+
+class Queue(BaseQueue):
+    def __init__(self, env):
+        super().__init__(env)
+        self._items = []
+
+    def _dequeue(self):
+        assert len(self._items) > 0
+        return self._items.pop(0)
+
+    def _enqueue(self, obj):
+        self._items.append(obj)
+
+    def _empty(self):
+        return len(self._items) == 0
+
+    def __str__(self):
+        return f"Queue({', '.join(str(i) for i in self._items)})"
+
+
+# ----------------------------------------------------------------------
+
+
+class _Get(BaseAction):
+    def __init__(self, queue):
+        super().__init__(queue._env)
+        self._queue = queue
+        self._proc = None
+        self._item = None
+
+    def act(self, proc):
+        if self._queue._empty():
+            self._proc = proc
+            self._queue._gets.append(self)
+        else:
+            self._item = self._queue._dequeue()
+            self._env.schedule(self._env.now, proc)
+
+    def __await__(self):
+        yield self
+        return self._item
+
+
+class _Put(BaseAction):
+    def __init__(self, queue, obj):
+        super().__init__(queue._env)
+        self._queue = queue
+        self.obj = obj
+
+    def act(self, proc):
+        self._queue._enqueue(self.obj)
+
+        if len(self._queue._gets) > 0:
+            waiting_get = self._queue._gets.pop(0)
+            waiting_get._item = self._queue._dequeue()
+            self._env.schedule(self._env.now, waiting_get._proc)
+
+        self._env.schedule(self._env.now, proc)

asimpy/resource.py

@@ -0,0 +1,76 @@
+"""Shared resource with limited capacity."""
+
+from typing import TYPE_CHECKING
+from .actions import BaseAction
+from .process import Process
+
+if TYPE_CHECKING:
+    from .environment import Environment
+
+
+class Resource:
+    """Shared resource with limited capacity."""
+
+    def __init__(self, env: "Environment", capacity: int = 1):
+        """
+        Create a new resource.
+
+        Args:
+            env: simulation environment.
+            capacity: maximum simultaneous users.
+        """
+        self._env = env
+        self._capacity = capacity
+        self._count = 0
+        self._waiting = []
+
+    async def acquire(self):
+        """Acquire one unit of the resource."""
+        await _Acquire(self)
+
+    async def release(self):
+        """Release one unit of the resource."""
+        await _Release(self)
+
+    async def __aenter__(self):
+        """Acquire one unit of the resource using `async with`."""
+        await self.acquire()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        """Release one unit of the resource acquired with `async with`."""
+        await self.release()
+
+
+# ----------------------------------------------------------------------
+
+
+class _Acquire(BaseAction):
+    """Acquire a resource."""
+
+    def __init__(self, resource: Resource):
+        super().__init__(resource._env)
+        self._resource = resource
+
+    def act(self, proc: Process):
+        if self._resource._count < self._resource._capacity:
+            self._resource._count += 1
+            self._env.schedule(self._env.now, proc)
+        else:
+            self._resource._waiting.append(proc)
+
+
+class _Release(BaseAction):
+    """Release a resource."""
+
+    def __init__(self, resource: Resource):
+        super().__init__(resource._env)
+        self._resource = resource
+
+    def act(self, proc: Process):
+        self._resource._count -= 1
+        if self._resource._waiting:
+            next_proc = self._resource._waiting.pop(0)
+            self._resource._count += 1
+            self._env.schedule(self._env.now, next_proc)
+        self._env.schedule(self._env.now, proc)

asimpy-0.1.0.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: asimpy
+Version: 0.1.0
+Summary: A simple discrete event simulator using async/await
+Author-email: Greg Wilson <gvwilson@third-bit.com>
+Maintainer-email: Greg Wilson <gvwilson@third-bit.com>
+License-File: LICENSE.md
+Keywords: discrete event simulation,open source
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.13
+Provides-Extra: dev
+Requires-Dist: build>=1.4.0; extra == 'dev'
+Requires-Dist: markdown-include>=0.8.1; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.7.1; extra == 'dev'
+Requires-Dist: mkdocs>=1.6.1; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=1.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.14.10; extra == 'dev'
+Requires-Dist: taskipy>=1.14.1; extra == 'dev'
+Requires-Dist: twine>=6.2.0; extra == 'dev'
+Requires-Dist: ty>=0.0.11; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# asimpy
+
+A simple discrete event simulation framework in Python using `async`/`await`.

asimpy-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+asimpy/__init__.py,sha256=BJoqSPhuG6zSHkEqYh8OBZPrqbAn52EYg9Hjf236xRk,298
+asimpy/actions.py,sha256=G9f4Zt3Mgt1dvwOgXKbdZwmoy8Z-7pxVvre2C1J-WD0,546
+asimpy/environment.py,sha256=9KooPy0v4gERqyX7H1O7cJQyYmTA04wWT8WExrqHAGI,3098
+asimpy/gate.py,sha256=MFepFLcb8TNhzbaRAF5jJFFbprbRB-Q5phf1uMdl3LA,1381
+asimpy/interrupt.py,sha256=G925y6jHB6b6y30sbq4e3jjutZDIW7Dwg9YY0mgf24Y,572
+asimpy/process.py,sha256=6LRQRHzHI8PVt_AtckSQgsAPqv65BlUNJ8xOOVx9bXs,1550
+asimpy/queue.py,sha256=qQOmQfuZ_MBS5aRax7pEuWrR6swlRmI-MU0iiWD6s-0,1938
+asimpy/resource.py,sha256=O18VJARLIZHbvntOxtTfYefGO5Zibz3EcsKWretIlxE,2107
+asimpy-0.1.0.dist-info/METADATA,sha256=oArpUAofvClqpvODhBOE_DyY2vyPWPZikHOTSQrA8MY,1044
+asimpy-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+asimpy-0.1.0.dist-info/licenses/LICENSE.md,sha256=IjTDUvBk8xdl_n50CG1Vtk4FYdrS-C3uEYrRWAoOQqQ,1066
+asimpy-0.1.0.dist-info/RECORD,,

asimpy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

asimpy-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,24 @@
+# MIT License
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+Copyright (c) Greg Wilson.