phyelds-mesa 8.1.0__tar.gz

phyelds_mesa-8.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.1
+Name: phyelds-mesa
+Version: 8.1.0
+Summary: Mesa integration for phyelds: aggregate programs on the agents of a Mesa model
+Home-page: https://github.com/phyelds/phyelds
+License: Apache-2.0
+Author: Davide Domini
+Author-email: davide.domini@unibo.it
+Requires-Python: >=3.12,<3.14
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: mesa[network] (>=3.5.1,<4.0.0)
+Requires-Dist: phyelds (>=8.0.0,<9.0.0)
+Project-URL: Repository, https://github.com/phyelds/phyelds
+Description-Content-Type: text/markdown
+
+# phyelds-mesa
+
+[Mesa](https://mesa.readthedocs.io) integration for [phyelds](https://pypi.org/project/phyelds/):
+run aggregate programs on the agents of a Mesa model.
+
+## Installation
+
+```bash
+pip install phyelds-mesa
+```
+
+`phyelds-mesa` installs a compatible `phyelds` release and Mesa.
+
+## Usage
+
+```python
+from phyelds.calculus import aggregate
+from phyelds.libraries.device import sense
+from phyelds.libraries.distances import hops_distance
+from phyelds.libraries.spreading import distance_to
+from phyelds.mesa import AggregateRuntime, within
+
+
+@aggregate
+def hops_to_source():
+    return distance_to(sense("source"), hops_distance())
+
+
+runtime = AggregateRuntime(
+    hops_to_source,
+    neighbors=within(1.5),                                 # or cell_neighbors in a grid
+    sensors=lambda agent: {"source": agent.unique_id == 1},
+)
+# In Model.step(): one synchronous round on every agent.
+hops = runtime.run_round(model.agents)                     # {unique_id: result}
+```
+
+See the [documentation](https://phyelds.github.io/phyelds/integration/mesa/).
+

phyelds_mesa-8.1.0/README.md

@@ -0,0 +1,38 @@
+# phyelds-mesa
+
+[Mesa](https://mesa.readthedocs.io) integration for [phyelds](https://pypi.org/project/phyelds/):
+run aggregate programs on the agents of a Mesa model.
+
+## Installation
+
+```bash
+pip install phyelds-mesa
+```
+
+`phyelds-mesa` installs a compatible `phyelds` release and Mesa.
+
+## Usage
+
+```python
+from phyelds.calculus import aggregate
+from phyelds.libraries.device import sense
+from phyelds.libraries.distances import hops_distance
+from phyelds.libraries.spreading import distance_to
+from phyelds.mesa import AggregateRuntime, within
+
+
+@aggregate
+def hops_to_source():
+    return distance_to(sense("source"), hops_distance())
+
+
+runtime = AggregateRuntime(
+    hops_to_source,
+    neighbors=within(1.5),                                 # or cell_neighbors in a grid
+    sensors=lambda agent: {"source": agent.unique_id == 1},
+)
+# In Model.step(): one synchronous round on every agent.
+hops = runtime.run_round(model.agents)                     # {unique_id: result}
+```
+
+See the [documentation](https://phyelds.github.io/phyelds/integration/mesa/).

phyelds_mesa-8.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[tool.poetry]
+name = "phyelds-mesa"
+version = "8.1.0"
+description = "Mesa integration for phyelds: aggregate programs on the agents of a Mesa model"
+license = "Apache-2.0"
+authors = [
+  "Davide Domini <davide.domini@unibo.it>",
+  "Gianluca Aguzzi <gianluca.aguzzi@unibo.it>"
+]
+homepage = "https://github.com/phyelds/phyelds"
+repository = "https://github.com/phyelds/phyelds"
+readme = "README.md"
+
+packages = [
+    { include = "phyelds/mesa", from = "src" },
+]
+
+classifiers = [
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[tool.poetry.dependencies]
+python = ">=3.12,<3.14"
+phyelds = ">=8.0.0,<9.0.0"
+# Mesa imports networkx when it starts, but declares it only in its network extra.
+mesa = { version = ">=3.5.1,<4.0.0", extras = ["network"] }
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+pylint = "^3.0.0"
+flake8 = "^7.0.0"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

phyelds_mesa-8.1.0/src/phyelds/mesa/__init__.py

@@ -0,0 +1,5 @@
+"""Run phyelds programs on the agents of a [Mesa](https://mesa.readthedocs.io) model."""
+
+from phyelds.mesa.runtime import AggregateRuntime, cell_neighbors, within
+
+__all__ = ["AggregateRuntime", "cell_neighbors", "within"]

phyelds_mesa-8.1.0/src/phyelds/mesa/runtime.py

@@ -0,0 +1,124 @@
+"""
+Run phyelds programs on the agents of a Mesa model.
+
+Each agent is a device: its ``unique_id`` is the device id, its neighbors are chosen by a
+function of the agent, and the program runs once per agent in each round.
+"""
+from collections.abc import Callable, Iterable, Mapping
+from typing import Any
+
+from mesa import Agent
+
+from phyelds import engine
+from phyelds.data import State
+from phyelds.vm import NodeContext
+from phyelds.vm.internal import MutableEngine
+
+Neighbors = Callable[[Agent], Iterable[Agent]]
+Sensors = Callable[[Agent], Mapping[str, Any]]
+
+
+class AggregateRuntime:
+    """
+    Runs an aggregate program on Mesa agents, one synchronous round at a time.
+
+    In a round every agent receives what its neighbors sent in the previous round, so the
+    result does not depend on the order of the agents. Call ``run_round`` from the
+    ``step`` of the model.
+
+    Args:
+        program: The ``@aggregate`` function to run on each agent.
+        neighbors: The agents a given agent talks to, e.g. ``within(radius)`` in a
+            continuous space or ``cell_neighbors`` in a grid.
+        sensors: Extra sensors of a given agent, added to ``position`` (its position, or
+            the coordinate of its cell) and ``time`` (the time of the model).
+    """
+
+    def __init__(
+        self, program: Callable[[], Any], *, neighbors: Neighbors, sensors: Sensors | None = None
+    ):
+        self.program = program
+        self.neighbors = neighbors
+        self.sensors = sensors
+        self.outputs: dict[int, dict[str, Any]] = {}
+        """What the program stored with ``store`` on each agent, in the last round."""
+        self._states: dict[int, dict[str, Any]] = {}
+        self._outboxes: dict[int, dict[str, Any]] = {}
+
+    def run_round(self, agents: Iterable[Agent]) -> dict[int, Any]:
+        """
+        Run the program once on each of ``agents``.
+
+        Agents missing from a round are forgotten: their state and messages are dropped.
+
+        Args:
+            agents: The agents of this round, e.g. ``model.agents``.
+
+        Returns:
+            The result of the program on each agent, by ``unique_id``.
+        """
+        states, outboxes, outputs, results = {}, {}, {}, {}
+        for agent in agents:
+            inbox = {
+                neighbor.unique_id: self._outboxes[neighbor.unique_id]
+                for neighbor in self.neighbors(agent)
+                if neighbor.unique_id in self._outboxes
+            }
+            node_engine = MutableEngine()
+            engine.set(node_engine)
+            context = NodeContext(agent.unique_id, self._sense(agent))
+            node_engine.setup(context, inbox, self._states.get(agent.unique_id, {}))
+            result = self.program()
+            outboxes[agent.unique_id] = node_engine.cooldown()
+            states[agent.unique_id] = node_engine.state_trace()
+            outputs[agent.unique_id] = context.outputs
+            results[agent.unique_id] = result.value if isinstance(result, State) else result
+        self._states, self._outboxes, self.outputs = states, outboxes, outputs
+        return results
+
+    def reset(self) -> None:
+        """Forget the state and the messages of every agent."""
+        self._states, self._outboxes, self.outputs = {}, {}, {}
+
+    def _sense(self, agent: Agent) -> dict[str, Any]:
+        """The default sensors of ``agent``, updated with the extra ones."""
+        sensors = {"position": _position(agent), "time": agent.model.time}
+        if self.sensors is not None:
+            sensors.update(self.sensors(agent))
+        return sensors
+
+
+def within(radius: float) -> Neighbors:
+    """
+    Neighbors in a continuous space: the agents closer than ``radius``.
+
+    Args:
+        radius: The communication range.
+
+    Returns:
+        A function giving the neighbors of a ``ContinuousSpaceAgent``.
+    """
+    return lambda agent: agent.get_neighbors_in_radius(radius)[0]
+
+
+def cell_neighbors(agent: Agent) -> list[Agent]:
+    """
+    Neighbors in a grid or network: the other agents in the cell of ``agent`` and around it.
+
+    Args:
+        agent: A ``CellAgent``.
+
+    Returns:
+        The agents of its cell, but itself, and of the neighborhood of its cell.
+    """
+    same_cell = [other for other in agent.cell.agents if other is not agent]
+    return same_cell + list(agent.cell.neighborhood.agents)
+
+
+def _position(agent: Agent) -> tuple | None:
+    """Where ``agent`` is: its position in a continuous space, or the coordinate of its cell."""
+    position = getattr(agent, "position", None)
+    if position is not None:
+        return tuple(float(coordinate) for coordinate in position)
+    cell = getattr(agent, "cell", None)
+    return None if cell is None else cell.coordinate