phyelds-simulator 8.0.0__tar.gz

phyelds_simulator-8.0.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.1
+Name: phyelds-simulator
+Version: 8.0.0
+Summary: A discrete-event simulator, with live rendering, for phyelds programs
+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
+Provides-Extra: jupyter
+Requires-Dist: ipython (>=7.34.0,<8.0.0) ; extra == "jupyter"
+Requires-Dist: matplotlib (>=3.10.1,<3.11.0)
+Requires-Dist: pandas (>=2.2.3,<3.0.0)
+Requires-Dist: phyelds (>=8.0.0,<9.0.0)
+Requires-Dist: pydantic (==2.12.5)
+Project-URL: Repository, https://github.com/phyelds/phyelds
+Description-Content-Type: text/markdown
+
+# phyelds-simulator
+
+A discrete-event simulator for [phyelds](https://pypi.org/project/phyelds/) programs,
+with live rendering, animation export and data export.
+
+## Installation
+
+```bash
+pip install phyelds-simulator                # simulator and a compatible phyelds
+pip install "phyelds-simulator[jupyter]"     # live rendering inside Jupyter
+```
+
+## Usage
+
+```python
+from phyelds.calculus import aggregate, neighbors
+from phyelds.simulator import Simulator
+from phyelds.simulator.deployments import grid_generation
+from phyelds.simulator.neighborhood import radius_neighborhood
+from phyelds.simulator.runner import schedule_program_for_all
+```
+
+The import paths are those of phyelds 7, where the simulator was part of `phyelds`.
+See the [documentation](https://phyelds.github.io/phyelds/simulator/).
+

phyelds_simulator-8.0.0/README.md

@@ -0,0 +1,24 @@
+# phyelds-simulator
+
+A discrete-event simulator for [phyelds](https://pypi.org/project/phyelds/) programs,
+with live rendering, animation export and data export.
+
+## Installation
+
+```bash
+pip install phyelds-simulator                # simulator and a compatible phyelds
+pip install "phyelds-simulator[jupyter]"     # live rendering inside Jupyter
+```
+
+## Usage
+
+```python
+from phyelds.calculus import aggregate, neighbors
+from phyelds.simulator import Simulator
+from phyelds.simulator.deployments import grid_generation
+from phyelds.simulator.neighborhood import radius_neighborhood
+from phyelds.simulator.runner import schedule_program_for_all
+```
+
+The import paths are those of phyelds 7, where the simulator was part of `phyelds`.
+See the [documentation](https://phyelds.github.io/phyelds/simulator/).

phyelds_simulator-8.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[tool.poetry]
+name = "phyelds-simulator"
+version = "8.0.0"
+description = "A discrete-event simulator, with live rendering, for phyelds programs"
+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/simulator", 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"
+matplotlib = ">=3.10.1,<3.11.0"
+pandas = "^2.2.3"
+pydantic = "2.12.5"
+ipython = { version = "^7.34.0", optional = true }
+
+[tool.poetry.extras]
+jupyter = ["ipython"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

phyelds_simulator-8.0.0/src/phyelds/simulator/__init__.py

@@ -0,0 +1,238 @@
+"""
+A simple simulator for aggregate computing systems in phyelds.
+This simulator allows you to create nodes, set their positions and data,
+and define their neighborhoods.
+It also provides a way to schedule events and run the simulation.
+"""
+
+from abc import ABC
+import heapq
+import uuid
+from typing import Dict, Callable, Any, Optional, Tuple, List
+
+
+class Node:
+    """
+    A class to represent a node in the simulation.
+    """
+
+    def __init__(
+        self, position: Tuple[float, ...], data: Any = None, node_id: any = None
+    ):
+        if node_id == 0:
+            self.id = 0
+        else:
+            self.id = node_id or str(uuid.uuid4())
+        self.position = position
+        if data is None:
+            data = {}
+        self.data = data
+        self.environment = None
+
+    def update(
+        self, new_position: Optional[Tuple[float, ...]] = None, new_data: Any = None
+    ):
+        """Update node position and/or data"""
+        if new_position is not None:
+            self.position = new_position
+        if new_data is not None:
+            self.data = new_data
+
+    def get_neighbors(self):
+        """Get neighboring nodes from the environment"""
+        if self.environment:
+            return self.environment.get_neighbors(self)
+        return []
+
+    def __eq__(self, other):
+        """Define equality based on node id"""
+        if not isinstance(other, Node):
+            return False
+        return self.id == other.id
+
+    def __hash__(self):
+        """Hash based on node id"""
+        return hash(self.id)
+
+    def __str__(self):
+        return f"Node(id={self.id}, position={self.position}, data={self.data})"
+
+
+class Environment:
+    """
+    A class to represent the environment in which nodes exist.
+    It manages the nodes and their neighborhoods.
+    It also provides a way to set the neighborhood function.
+    """
+
+    def __init__(
+        self, neighborhood_function: Callable[[Node, "Environment"], List[Node]] = None
+    ):
+        self.nodes: Dict[any, Node] = {}
+        self.neighborhood_function = neighborhood_function or self.no_neighbors
+
+    def add_data_for_all_nodes(self, data: Dict[str, Any]):
+        """Add data to all nodes in the environment"""
+        for node in self.nodes.values():
+            node.data.update(data)
+
+    def node_list(self) -> List[Node]:
+        """Return a list of all nodes in the environment"""
+        return list(self.nodes.values())
+
+    def add_node(self, node: Node):
+        """Add a node to the environment"""
+        self.nodes[node.id] = node
+        node.environment = self
+
+    def remove_node(self, node_id: str):
+        """Remove a node from the environment"""
+        if node_id in self.nodes:
+            self.nodes[node_id].environment = None
+            del self.nodes[node_id]
+
+    def set_neighborhood_function(self, func: Callable[[Node, "Environment"], List[Node]]):
+        """Set the function that determines neighborhoods"""
+        self.neighborhood_function = func
+
+    def get_neighbors(self, node: Node) -> List[Node]:
+        """Get neighbors for a node using the neighborhood function"""
+        return self.neighborhood_function(node, self)
+
+    @staticmethod
+    def no_neighbors(
+            node: Node,  # pylint: disable=unused-argument
+            all_node: List[Node]  # pylint: disable=unused-argument
+    ) -> List[Node]:
+        """Default neighborhood function (no neighbors)"""
+        return []
+
+
+class Event:
+    """
+    A class to represent an event in the simulation.
+    An event has a time, an action (function), and optional arguments.
+    """
+
+    def __init__(self, time: float, action: Callable[..., None], *args, **kwargs):
+        self.time = time
+        self.action = action
+        self.args = args
+        self.kwargs = kwargs
+
+    def execute(self):
+        """Execute the event's action"""
+        return self.action(*self.args, **self.kwargs)
+
+    def __lt__(self, other):
+        """For priority queue ordering"""
+        return self.time < other.time
+
+    def __str__(self):
+        return f"Event(time={self.time}, action={self.action.__name__})"
+
+    def __repr__(self):
+        return self.__str__()
+
+
+class Monitor(ABC):
+    """
+    An abstract base class for monitors that can observe the simulation.
+    """
+    def __init__(self, simulator):
+        self.simulator = simulator
+        self.simulator.add_monitor(monitor=self)
+
+    def on_start(self) -> None:
+        """Called when the simulation starts"""
+
+    def on_finish(self) -> None:
+        """Called when the simulation finishes"""
+
+    def update(self) -> None:
+        """Called after each event execution"""
+
+
+class Simulator:
+    """
+    A class to represent the simulator for a simple aggregate computing system.
+    """
+    def __init__(self, environment: Environment = None):
+        self.event_queue = []
+        self.current_time = 0.0
+        self.running = False
+        if environment is None:
+            self.environment = Environment()
+        else:
+            self.environment = environment
+        self.monitors = []
+
+    def schedule_event(
+        self, time_delta: float, action: Callable[..., None], *args, **kwargs
+    ):
+        """Schedule an event to occur after time_delta"""
+        event_time = self.current_time + time_delta
+        event = Event(event_time, action, *args, **kwargs)
+        heapq.heappush(self.event_queue, event)
+        return event
+
+    def run(self, until_time: Optional[float] = None):
+        """Run the simulation until the specified time or until no more events"""
+        self.running = True
+
+        for monitor in self.monitors:
+            monitor.on_start()
+
+        while self.running and self.event_queue:
+            event = heapq.heappop(self.event_queue)
+            if until_time is not None and event.time > until_time:
+                heapq.heappush(self.event_queue, event)  # Put the event back
+                break
+
+            self.current_time = event.time
+            event.execute()
+
+            for monitor in self.monitors:
+                monitor.update()
+
+        self.running = False
+
+        for monitor in self.monitors:
+            monitor.on_finish()
+
+    def continue_run(self, until_time: Optional[float] = None):
+        """Continue running the simulation until the specified time or until no more events"""
+        if self.running:
+            return  # Already running
+        self.run(self.current_time + until_time)
+
+    def add_monitor(self, monitor: Monitor) -> None:
+        """Add a monitor to the simulator"""
+        self.monitors.append(monitor)
+
+    def stop(self):
+        """Stop the simulation"""
+        self.running = False
+
+    def cancel_event(self, event: Event):
+        """Cancel a scheduled event"""
+        if event in self.event_queue:
+            self.event_queue.remove(event)
+            heapq.heapify(self.event_queue)
+        else:
+            raise ValueError("Event not found in the queue")
+
+    def reset(self):
+        """Reset the simulator"""
+        self.event_queue = []
+        self.current_time = 0.0
+        self.running = False
+        self.environment = Environment()
+
+    def create_node(
+        self, position: Tuple[float, ...], data: Any = None, node_id=None
+    ) -> Node:
+        """Helper method to create and add a node to the environment"""
+        node = Node(position, data, node_id)
+        self.environment.add_node(node)
+        return node

phyelds_simulator-8.0.0/src/phyelds/simulator/actions.py

@@ -0,0 +1,38 @@
+"""
+Sent of actions related to node movements and interactions in the simulator
+"""
+import random
+from typing import Tuple
+
+from phyelds.simulator import Simulator, Node
+
+
+def move_with_velocity(
+    simulator: Simulator,
+    delta_time: float,
+    node: Node,
+    velocity: Tuple[float, tuple]
+):
+    """
+    Move the node with a given velocity.
+    """
+    # Update the node's position based on its velocity and the delta time
+    (x, y) = node.position
+    (vx, vy) = velocity
+    new_position = (x + vx * delta_time, y + vy * delta_time)
+    node.update(new_position)
+    simulator.schedule_event(
+        delta_time, move_with_velocity, simulator, delta_time, node, velocity
+    )
+
+
+def gaussian_movement(
+    simulator: Simulator, node: Node, mean: Tuple[float, ...], stddev: float
+):
+    """
+    Move a node according to a Gaussian distribution.
+    """
+    new_position = tuple(random.gauss(mean[i], stddev) for i in range(len(mean)))
+    node.update(new_position)
+    # next schedule the event
+    simulator.schedule_event(1.0, gaussian_movement, simulator, node, mean, stddev)

phyelds_simulator-8.0.0/src/phyelds/simulator/deployments.py

@@ -0,0 +1,64 @@
+"""
+This module contains various functions to generate different types of node distributions
+in a simulation environment.
+These functions can be used to create specific patterns or random distributions of nodes
+for testing and simulation purposes.
+"""
+
+import math
+import random
+
+from phyelds.simulator import Simulator
+
+
+def grid_generation(simulator: Simulator, width: int, height: int, spacing: float):
+    """
+    Generate a grid of nodes in the simulator's environment.
+    """
+    for x in range(0, width):
+        for y in range(0, height):
+            position = (x * spacing, y * spacing)
+            simulator.create_node(position, node_id=x * height + y)
+
+
+def deformed_lattice(
+    simulator: Simulator,
+    width: int,
+    height: int,
+    spacing: float,
+    deformation_factor: float,
+):
+    """
+    Generate a deformed lattice of nodes in the simulator's environment.
+    """
+    for x in range(0, width):
+        for y in range(0, height):
+            # Randomly deform the position
+            dx = random.uniform(-deformation_factor, deformation_factor)
+            dy = random.uniform(-deformation_factor, deformation_factor)
+            position = (x * spacing + dx, y * spacing + dy)
+            simulator.create_node(position, node_id=x * height + y)
+
+
+def random_walk(simulator: Simulator, num_steps: int, step_size: float):
+    """
+    Perform a random walk and create nodes at each step.
+    """
+    position = (0.0, 0.0)
+    for _ in range(num_steps):
+        dx = random.uniform(-step_size, step_size)
+        dy = random.uniform(-step_size, step_size)
+        position = (position[0] + dx, position[1] + dy)
+        simulator.create_node(position)
+
+
+def random_in_circle(simulator: Simulator, num_nodes: int, radius: float):
+    """
+    Generate nodes randomly distributed within a circle.
+    """
+    for index in range(num_nodes):
+        angle = random.uniform(0, 2 * math.pi)
+        r = random.uniform(0, radius)
+        x = r * math.cos(angle)
+        y = r * math.sin(angle)
+        simulator.create_node((x, y), node_id=index)

phyelds_simulator-8.0.0/src/phyelds/simulator/effects.py

@@ -0,0 +1,262 @@
+"""
+This module contains the effects that can be applied to the simulation rendering.
+"""
+
+import math
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Literal, Optional, Any, Annotated, Tuple, List
+from matplotlib import colormaps
+from matplotlib.colors import Normalize, to_rgba
+from pydantic import BaseModel, Field, BeforeValidator, SerializeAsAny
+from phyelds.simulator import Environment
+
+
+class Link:
+    """
+    A class to represent a link between two nodes.
+    The link is represented as a tuple of two nodes.
+    Note!
+    Link(node1, node2) == Link(node2, node1)
+    """
+
+    def __init__(self, node1: Tuple[float, ...], node2: Tuple[float, ...]):
+        self.node1 = node1
+        self.node2 = node2
+
+    def __hash__(self):
+        return hash(frozenset((self.node1, self.node2)))
+
+    def __eq__(self, other):
+        if isinstance(other, Link):
+            return frozenset((self.node1, self.node2)) == frozenset(
+                (other.node1, other.node2)
+            )
+        return False
+
+
+class Effect(BaseModel, ABC):
+    """
+    Abstract base class for effects.
+    """
+    z_order: int = 0
+
+    @abstractmethod
+    def apply(self, ax, environment: Environment):
+        """
+        Apply the effect to the matplotlib axis.
+        """
+
+
+class DrawEdges(Effect):
+    """
+    Draw edges between nodes.
+    """
+    type: Literal["DrawEdges"] = "DrawEdges"
+    alpha: float = 0.6
+    z_order: int = 0
+
+    def apply(self, ax, environment: Environment):
+        """
+        Draw edges between nodes.
+        """
+        all_neighbors_tuple = set()
+        for node in environment.nodes.values():
+            neighbors = node.get_neighbors()
+            for neighbor in neighbors:
+                all_neighbors_tuple.add(Link(node.position, neighbor.position))
+        for link in all_neighbors_tuple:
+            ax.plot(
+                [link.node1[0], link.node2[0]],
+                [link.node1[1], link.node2[1]],
+                alpha=self.alpha,
+                color="gray",
+                zorder=self.z_order,
+            )
+
+
+def _is_finite_number(value: Any) -> bool:
+    """True for real numbers that are not infinite or NaN (booleans excluded)."""
+    return (
+        isinstance(value, (int, float))
+        and not isinstance(value, bool)
+        and math.isfinite(value)
+    )
+
+
+class DrawNodes(Effect):
+    """
+    Draw nodes.
+
+    With ``color_from`` alone, ``node.data[color_from]`` is used as a matplotlib color.
+    With ``cmap`` too, it is read as a number and mapped onto that colormap between
+    ``vmin`` and ``vmax`` (by default, the finite values on screen); nodes whose value is
+    missing, infinite or not a number are drawn in ``missing_color``.
+    """
+    type: Literal["DrawNodes"] = "DrawNodes"
+    color_from: Optional[str] = None
+    cmap: Optional[str] = None
+    vmin: Optional[float] = None
+    vmax: Optional[float] = None
+    missing_color: str = "lightgray"
+    z_order: int = 10
+
+    def apply(self, ax, environment: Environment):
+        """
+        Draw nodes.
+        """
+        positions = [node.position for node in environment.nodes.values()]
+        if not positions:
+            return
+        x, y = zip(*positions)
+
+        if self.color_from and self.cmap:
+            values = [node.data.get(self.color_from) for node in environment.nodes.values()]
+            ax.scatter(x, y, c=self._map_to_colors(values), zorder=self.z_order)
+        elif self.color_from:
+            colors = [
+                node.data.get(self.color_from, "blue")
+                for node in environment.nodes.values()
+            ]
+            ax.scatter(x, y, c=colors, zorder=self.z_order)
+        else:
+            ax.scatter(x, y, c="blue", zorder=self.z_order)
+
+    def _map_to_colors(self, values: List[Any]) -> List[Tuple[float, float, float, float]]:
+        finite = [value for value in values if _is_finite_number(value)]
+        vmin = self.vmin if self.vmin is not None else min(finite, default=0.0)
+        vmax = self.vmax if self.vmax is not None else max(finite, default=1.0)
+        normalize = Normalize(vmin=vmin, vmax=vmax, clip=True)
+        colormap = colormaps[self.cmap]
+        missing = to_rgba(self.missing_color)
+        return [
+            colormap(normalize(value)) if _is_finite_number(value) else missing
+            for value in values
+        ]
+
+
+class DrawIDs(Effect):
+    """
+    Draw node IDs.
+    """
+    type: Literal["DrawIDs"] = "DrawIDs"
+    z_order: int = 20
+
+    def apply(self, ax, environment: Environment):
+        """
+        Draw node IDs.
+        """
+        # Add node IDs as text labels
+        for node in environment.nodes.values():
+            ax.text(
+                node.position[0] + 0.02,
+                node.position[1],
+                str(node.id),
+                fontsize=8,
+                ha="center",
+                va="center",
+                bbox={"facecolor": "white", "alpha": 0.1, "edgecolor": "none"},
+                zorder=self.z_order,
+            )
+
+
+class DrawValues(Effect):
+    """
+    Draw the value ``node.data[value_from]`` next to each node.
+    Floats are rounded to ``precision`` decimals, infinity is shown as ``∞``
+    and nodes without a value are skipped. ``offset`` is the vertical distance
+    between a node and its label, in data units.
+    """
+    type: Literal["DrawValues"] = "DrawValues"
+    value_from: str = "result"
+    precision: int = 1
+    offset: float = 0.15
+    fontsize: int = 8
+    z_order: int = 20
+
+    def apply(self, ax, environment: Environment):
+        """
+        Draw node values.
+        """
+        for node in environment.nodes.values():
+            value = node.data.get(self.value_from)
+            if value is None:
+                continue
+            ax.text(
+                node.position[0],
+                node.position[1] + self.offset,
+                self._format(value),
+                fontsize=self.fontsize,
+                ha="center",
+                va="bottom",
+                zorder=self.z_order,
+            )
+
+    def _format(self, value: Any) -> str:
+        if isinstance(value, float) and math.isinf(value):
+            return "∞" if value > 0 else "-∞"
+        if isinstance(value, float):
+            return f"{value:.{self.precision}f}"
+        return str(value)
+
+
+def validate_effect(v: Any) -> Any:
+    """
+    Validate the effect type.
+    """
+    if isinstance(v, dict):
+        effect_type = v.get("type")
+        for sub in Effect.__subclasses__():
+            # pylint: disable=unsupported-membership-test, unsubscriptable-object
+            if (
+                "type" in sub.model_fields
+                and sub.model_fields["type"].default == effect_type
+            ):
+                return sub.model_validate(v)
+        raise ValueError(f"Unknown effect type: {effect_type}")
+    return v
+
+
+EffectType = Annotated[Effect, BeforeValidator(validate_effect)]
+
+
+class RenderMode(str, Enum):
+    """
+    Enum for render modes.
+    """
+    SHOW = "show"
+    SAVE = "save"
+    SAVE_ALL = "save_all"
+
+
+class RenderConfig(BaseModel):
+    """
+    Configuration for the RenderMonitor.
+    """
+
+    effects: List[SerializeAsAny[EffectType]] = Field(default_factory=list)
+    dt: float = 1.0
+    skip: float = 0.0
+    pause_duration: float = 0.001
+    xlim: Optional[Tuple[float, float]] = None
+    ylim: Optional[Tuple[float, float]] = None
+    mode: RenderMode = RenderMode.SHOW
+    save_as: str = "simulation.mp4"
+    snapshot_prefix: str = "snapshot"
+    show_axis: bool = True
+    title: Optional[str] = None
+
+    def save(self, path: str):
+        """
+        Save the configuration to a file.
+        """
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(self.model_dump_json(indent=4))
+
+    @classmethod
+    def load(cls, path: str):
+        """
+        Load the configuration from a file.
+        """
+        with open(path, "r", encoding="utf-8") as f:
+            return cls.model_validate_json(f.read())

phyelds_simulator-8.0.0/src/phyelds/simulator/exporter.py

@@ -0,0 +1,73 @@
+"""Exporter module for saving simulation metrics to CSV during simulation."""
+
+import os
+import itertools
+from pathlib import Path
+from dataclasses import dataclass, replace
+import pandas as pd
+from phyelds.simulator import Simulator
+
+
+__all__ = ["csv_exporter", "ExporterConfig"]
+
+
+@dataclass
+class ExporterConfig:
+    """Configuration for CSV exporting of simulation metrics."""
+    output_directory: str
+    experiment_name: str
+    metrics: list[str]
+    aggregators: list[str]
+    precision: int
+    initial: bool = True
+
+
+def csv_exporter(
+    simulator: Simulator, time_delta: float, config: ExporterConfig, **kwargs
+):
+    """Exporter module for saving simulation metrics to CSV."""
+    file_path = f'{config.output_directory}{config.experiment_name}.csv'
+    if not os.path.exists(file_path) or config.initial:
+        Path(config.output_directory).mkdir(parents=True, exist_ok=True)
+        df = init_dataframe(config, file_path)
+    else:
+        df = pd.read_csv(file_path)
+    new_data = {}
+    nodes = simulator.environment.nodes.values()
+    for metric in config.metrics:
+        nodes_data = [node.data['outputs'][metric] for node in nodes]
+        for aggregator in config.aggregators:
+            column = f'{metric}_{aggregator}'
+            new_data[column] = aggregate_values(nodes_data, config.precision, aggregator)
+    df = pd.concat([df, pd.DataFrame([new_data])], ignore_index=True)
+    df.to_csv(file_path, mode='w', index=False)
+    config = replace(config, initial=False)
+    simulator.schedule_event(
+        time_delta, csv_exporter, simulator, time_delta, config, **kwargs
+    )
+
+
+def aggregate_values(values: list[float], precision, aggregator: str):
+    """Aggregates a list of values using the given method and rounds to the specified precision."""
+    if aggregator == "mean":
+        value = sum(values) / len(values)
+    elif aggregator == "std":
+        mean = sum(values) / len(values)
+        value = sum((v - mean) ** 2 for v in values) / len(values)
+    elif aggregator == "min":
+        value = min(values)
+    elif aggregator == "max":
+        value = max(values)
+    else:
+        raise ValueError(f"Invalid aggregator: {aggregator}")
+    return round(value, precision)
+
+
+def init_dataframe(config, file_path):
+    """Initializes an empty DataFrame with appropriate columns based on config."""
+    columns = list(f'{s}_{a}' for s, a in itertools.product(config.metrics, config.aggregators))
+    try:
+        os.remove(file_path)
+    except OSError:
+        pass
+    return pd.DataFrame(columns=columns).astype('float64')

phyelds_simulator-8.0.0/src/phyelds/simulator/neighborhood.py

@@ -0,0 +1,61 @@
+"""
+Neighborhood functions for the phyelds simulator.
+A neighborhood function is simply a function that takes a node and a list of all nodes,
+and returns a list of neighbors.
+"""
+
+from typing import List
+from phyelds.simulator import Node, Environment
+
+
+def radius_neighborhood(radius: float):
+    """Create a neighborhood function that includes nodes within a certain radius"""
+
+    def neighborhood_func(node: Node, environment: Environment) -> List[Node]:
+        all_nodes: List[Node] = environment.node_list()
+        neighbors = []
+        for other in all_nodes:
+            if other.id == node.id:  # Skip self
+                continue
+
+            # Calculate Euclidean distance
+            distance = (
+                sum((a - b) ** 2 for a, b in zip(node.position, other.position)) ** 0.5
+            )
+
+            if distance <= radius:
+                neighbors.append(other)
+        return neighbors
+
+    return neighborhood_func
+
+
+def k_nearest_neighbors(k: int):
+    """Create a neighborhood function that includes the k nearest nodes"""
+
+    def neighborhood_func(node: Node, environment: Environment) -> List[Node]:
+        all_nodes: List[Node] = environment.node_list()
+        others = [n for n in all_nodes if n.id != node.id]
+        if not others:
+            return []
+
+        # Calculate distances
+        distances = [
+            (
+                sum((a - b) ** 2 for a, b in zip(node.position, other.position)) ** 0.5,
+                other,
+            )
+            for other in others
+        ]
+
+        # Sort by distance and take k nearest
+        distances.sort()
+        return [other for _, other in distances[:k]]
+
+    return neighborhood_func
+
+
+def full_neighborhood(node: Node, environment: Environment) -> List[Node]:
+    """Include all nodes as neighbors"""
+    all_nodes: List[Node] = environment.node_list()
+    return [n for n in all_nodes if n.id != node.id]

phyelds_simulator-8.0.0/src/phyelds/simulator/render.py

@@ -0,0 +1,156 @@
+"""
+Render the nodes in the simulator's environment.
+"""
+import sys
+from pathlib import Path
+
+from matplotlib import pyplot as plt
+from matplotlib.animation import AbstractMovieWriter, FFMpegWriter, PillowWriter
+from matplotlib.figure import Figure
+
+from phyelds.simulator import Simulator, Monitor
+from phyelds.simulator.effects import RenderConfig, RenderMode
+
+
+def make_writer(config: RenderConfig) -> AbstractMovieWriter:
+    """
+    Create the movie writer matching the extension of ``config.save_as``.
+
+    Args:
+        config: the render configuration.
+
+    Returns:
+        A ``PillowWriter`` for ``.gif`` files, an ``FFMpegWriter`` otherwise.
+    """
+    fps = 1 / config.dt if config.dt > 0 else 15
+    if Path(config.save_as).suffix.lower() == ".gif":
+        return PillowWriter(fps=fps)
+    metadata = {"title": "Simulation", "artist": "Phyelds"}
+    return FFMpegWriter(fps=fps, metadata=metadata)
+
+
+def _padded_limits(values: tuple[float, ...], pad: float = 0.05) -> tuple[float, float]:
+    """
+    Axis limits enclosing ``values`` with a margin of ``pad`` times their range.
+    When all values coincide (e.g. nodes on a line) the margin is 1, so the limits
+    never collapse into a single point.
+    """
+    low, high = min(values), max(values)
+    margin = pad * (high - low) if high > low else 1.0
+    return low - margin, high + margin
+
+
+def _show_in_notebook(figure: Figure) -> None:
+    """
+    Replace the output of the current notebook cell with ``figure``.
+    IPython is imported here, and not at module level, because it is only
+    available inside Jupyter: rendering to a file must work without it.
+    """
+    # IPython is the optional `jupyter` extra, so it may be missing where pylint runs.
+    # pylint: disable=import-outside-toplevel,import-error
+    from IPython.display import clear_output, display
+
+    clear_output(wait=True)
+    display(figure)
+
+
+class RenderMonitor(Monitor):
+    """
+    Render the nodes in the simulator's environment.
+    """
+
+    def __init__(self, simulator: Simulator, config: RenderConfig):
+        super().__init__(simulator)
+        self.config = config
+        self.config.effects.sort(key=lambda e: e.z_order)
+        self.last_render_time = 0
+        self.fig, self.ax = plt.subplots()
+        self.writer = None
+
+    def on_start(self):
+        if self.config.mode in [RenderMode.SAVE, RenderMode.SAVE_ALL]:
+            self.writer = make_writer(self.config)
+            self.writer.setup(self.fig, self.config.save_as, dpi=100)
+        elif self.config.mode == RenderMode.SHOW:
+            plt.ion()
+            plt.show()
+
+    def update(self):
+        if self.simulator.current_time < self.config.skip or self._instant_in_progress():
+            return
+        if self.simulator.current_time - self.last_render_time >= self.config.dt:
+            self._render()
+            self.last_render_time = self.simulator.current_time
+
+    def _instant_in_progress(self) -> bool:
+        """True while other events are still queued for the current time."""
+        queue = self.simulator.event_queue
+        return bool(queue) and queue[0].time <= self.simulator.current_time
+
+    def on_finish(self):
+        if self.config.mode in [RenderMode.SAVE, RenderMode.SAVE_ALL]:
+            self.writer.finish()
+            if self.config.mode == RenderMode.SAVE:
+                self.fig.savefig(Path(self.config.save_as).with_suffix(".png"))
+        elif self.config.mode == RenderMode.SHOW:
+            if 'ipykernel' in sys.modules:
+                _show_in_notebook(self.fig)
+            else:
+                plt.ioff()
+                plt.show()
+        plt.close(self.fig)
+
+    def _render(self):
+        self.ax.clear()
+
+        for effect in self.config.effects:
+            effect.apply(self.ax, self.simulator.environment)
+
+        self._setup_axis()
+        self._setup_limits()
+
+        if self.config.mode == RenderMode.SAVE_ALL:
+            self.fig.savefig(
+                f"{self.config.snapshot_prefix}_{self.simulator.current_time:.2f}.png"
+            )
+
+        if self.config.mode in [RenderMode.SAVE, RenderMode.SAVE_ALL]:
+            self.writer.grab_frame()
+        elif self.config.mode == RenderMode.SHOW:
+            if 'ipykernel' in sys.modules:
+                _show_in_notebook(self.fig)
+            else:
+                plt.draw()
+                plt.pause(self.config.pause_duration)
+
+    def _setup_axis(self):
+        if self.config.show_axis:
+            if self.config.title:
+                self.ax.set_title(self.config.title)
+            self.ax.set_xlabel("X Position")
+            self.ax.set_ylabel("Y Position")
+            self.ax.axis("on")
+        else:
+            self.ax.axis("off")
+            if self.config.title:
+                self.ax.set_title(self.config.title)
+                self.fig.subplots_adjust(left=0.01, right=0.99, bottom=0.01, top=0.9)
+            else:
+                self.fig.subplots_adjust(left=0, right=1, bottom=0, top=1)
+
+    def _setup_limits(self):
+        if self.config.xlim:
+            self.ax.set_xlim(self.config.xlim)
+        if self.config.ylim:
+            self.ax.set_ylim(self.config.ylim)
+        elif not self.config.xlim and not self.config.ylim:
+            positions = [
+                node.position for node in self.simulator.environment.nodes.values()
+            ]
+            if positions:
+                x, y = zip(*positions)
+                self.ax.set_xlim(*_padded_limits(x))
+                self.ax.set_ylim(*_padded_limits(y))
+                self.ax.set_aspect("equal")
+        else:
+            self.ax.axis("equal")

phyelds_simulator-8.0.0/src/phyelds/simulator/runner.py

@@ -0,0 +1,84 @@
+"""
+This module contains the event to run the aggregate program in the simulator
+"""
+from abc import ABC
+
+from phyelds.vm.internal import MutableEngine
+
+from phyelds import engine
+from phyelds.vm import NodeContext
+from phyelds.data import State
+from phyelds.simulator import Simulator, Node
+
+
+class SimulatorNodeContext(NodeContext, ABC):
+    """
+    A class to represent the context of a node in the simulator.
+    This class is used to pass the node's data and messages to the aggregate program.
+    """
+
+    @staticmethod
+    def from_node(node: Node):
+        """
+        Create a SimulatorNodeContext from a Node.
+        :param node: The node to create the context from.
+        :return: The SimulatorNodeContext.
+        """
+        sensors = {
+            "position": node.position,
+            **node.data,
+        }
+        return SimulatorNodeContext(node.id, sensors)
+
+
+def aggregate_program_runner(
+    simulator: Simulator, time_delta: float, node: Node, program: callable, **kwargs
+):
+    """
+    Run the program for a node.
+    """
+    if node.id not in simulator.environment.nodes.keys():
+        # If the node is not in the environment, do not run the program
+        return
+    # get neighbors
+    all_neighbors = simulator.environment.get_neighbors(node)
+    # take the messages from the neighbors, create a dict like id -> messages (that is a dict)
+    neighbors_messages = {
+        neighbor.id: neighbor.data.get("messages", {}) for neighbor in all_neighbors
+    }
+    node.data["time"] = simulator.current_time  # prepare time sensor
+    engine.set(MutableEngine())
+    engine.get().setup(
+        SimulatorNodeContext.from_node(node),
+        neighbors_messages,
+        node.data.get("state", {})
+    )
+    result = program(**kwargs)
+    if isinstance(result, State):
+        result = result.value
+    node.data["result"] = result
+    node.data["messages"] = engine.get().cooldown()
+    node.data["state"] = engine.get().state_trace()
+    node.data["outputs"] = engine.get().node_context.outputs
+    simulator.schedule_event(
+        time_delta, aggregate_program_runner, simulator, time_delta, node, program, **kwargs
+    )
+
+
+def schedule_program_for_all(
+    simulator: Simulator,
+    start: float,
+    frequency: float,
+    program: callable, **kwargs
+):
+    """
+    Schedule the program for all nodes in the simulator.
+    :param simulator: The simulator to schedule the program for.
+    :param start: The time to start the program.
+    :param frequency: The frequency to run the program.
+    :param program: The program to run.
+    """
+    for node in simulator.environment.nodes.values():
+        simulator.schedule_event(
+            start, aggregate_program_runner, simulator, frequency, node, program, **kwargs
+        )