smolpy 0.1.0__py3-none-any.whl

smolpy/__init__.py

@@ -0,0 +1,4 @@
+from smolpy.dsl.mqtt_broker import MQTTBroker
+from smolpy.dsl.network import Network
+
+__all__ = ["Network", "MQTTBroker"]

smolpy/cli.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import argparse
+import runpy
+import sys
+import time
+import traceback
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+from rich.text import Text
+from rich.theme import Theme
+
+_THEME = Theme(
+    {
+        "banner.title": "bold cyan",
+        "banner.sub": "dim white",
+        "info": "bold white",
+        "success": "bold green",
+        "error": "bold red",
+        "dim": "dim white",
+    }
+)
+
+console = Console(theme=_THEME)
+
+_BANNER = Text.assemble(
+    ("██████╗ ██╗   ██╗███████╗███╗   ███╗ ██████╗ ██╗\n", "bold cyan"),
+    ("██╔══██╗╚██╗ ██╔╝██╔════╝████╗ ████║██╔═══██╗██║\n", "bold cyan"),
+    ("██████╔╝ ╚████╔╝ ███████╗██╔████╔██║██║   ██║██║\n", "bold cyan"),
+    ("██╔═══╝   ╚██╔╝  ╚════██║██║╚██╔╝██║██║   ██║██║\n", "bold cyan"),
+    ("██║        ██║   ███████║██║ ╚═╝ ██║╚██████╔╝███████╗\n", "bold cyan"),
+    ("╚═╝        ╚═╝   ╚══════╝╚═╝     ╚═╝ ╚═════╝ ╚══════╝\n", "bold cyan"),
+    ("  Network Description Language & Discrete-Event Simulator", "dim white"),
+)
+
+
+def _print_banner() -> None:
+    console.print()
+    console.print(Panel(_BANNER, border_style="cyan", padding=(0, 2)))
+    console.print()
+
+
+def _cmd_run(script: str, output: str | None, text_mode: bool, extra_args: list[str]) -> None:
+    _print_banner()
+    console.print(f"  [info]Script[/]   [dim]{script}[/]")
+    console.print()
+
+    import os
+
+    if text_mode:
+        os.environ["SMOLPY_TEXT_MODE"] = "1"
+
+    start = time.perf_counter()
+    namespace: dict = {}
+
+    with Progress(
+        SpinnerColumn(spinner_name="dots", style="cyan"),
+        TextColumn("[bold white]{task.description}"),
+        TimeElapsedColumn(),
+        console=console,
+        transient=False,
+    ) as progress:
+        task = progress.add_task("Running simulation…", total=None)
+
+        try:
+            sys.argv = [script] + extra_args
+            namespace = runpy.run_path(script, run_name="__main__")
+            progress.update(task, description="Simulation complete")
+        except Exception:
+            progress.stop()
+            console.print()
+            console.print(
+                Panel(
+                    traceback.format_exc(),
+                    title="[error]Error[/]",
+                    border_style="red",
+                    padding=(1, 2),
+                )
+            )
+            sys.exit(1)
+
+    elapsed = time.perf_counter() - start
+    console.print()
+    console.print(
+        Panel(
+            f"[success]Finished in {elapsed:.2f}s[/]",
+            border_style="green",
+            padding=(0, 2),
+        )
+    )
+    console.print()
+
+    if output:
+        result = namespace.get("result")
+        if result is not None:
+            result.export(output)
+            console.print(f"  Results exported → {output}")
+            console.print()
+
+
+def _cmd_demo() -> None:
+    """Run a built-in 3-client saturation demo in text mode."""
+    from smolpy import Network
+
+    _print_banner()
+    console.print("  [info]Demo[/]   3 clients → switch → server  (10 s, text mode)\n")
+
+    net = Network("demo")
+    sw = net.switch("core-sw", ports=8, mode="store-and-forward")
+    server = net.adapter("server", ip="10.0.0.100")
+    net.link(server, sw, speed=1_000, length=2)
+
+    fps = int(100_000_000 / (1_518 * 8))
+    for i in range(1, 4):
+        c = net.adapter(f"client-{i}", ip=f"10.0.0.{i}")
+        net.link(c, sw, speed=100, length=10)
+        c.sends(to=server, rate=fps, size=1_518, pattern="constant", delay_ms=(i - 1) * 2_000)
+        net.observe("bytes_sent", on=c, every=500)
+
+    net.observe("throughput", on=server, every=200)
+    net.observe("latency", on=server, every=200)
+    net.observe("queue_depth", on=sw, every=200)
+    net.observe("bytes_received", on=server, every=500)
+
+    result = net.simulate(duration=10_000, text=True)
+    result.report()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="smolpy",
+        description="SMOLPy — Network simulation DSL and discrete-event simulator",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    run_cmd = sub.add_parser(
+        "run",
+        help="Execute a SMOLPy simulation script",
+        description="Load and run a Python script that uses the SMOLPy DSL.",
+    )
+    run_cmd.add_argument("script", help="Path to the .py script to run")
+    run_cmd.add_argument(
+        "--output",
+        "-o",
+        default=None,
+        metavar="FILE",
+        help="Write metric time-series to FILE (.csv or .json)",
+    )
+    run_cmd.add_argument(
+        "--text",
+        "-t",
+        action="store_true",
+        default=False,
+        help="Force text-mode dashboard even if the script uses live=True",
+    )
+    run_cmd.add_argument(
+        "args",
+        nargs=argparse.REMAINDER,
+        help="Extra arguments forwarded to the script via sys.argv",
+    )
+
+    sub.add_parser(
+        "demo",
+        help="Run a built-in 3-client saturation demo (no script needed)",
+        description="Quick sanity-check: 3 clients ramping onto a shared switch, text-mode output.",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "run":
+        # REMAINDER captures flags that appear after the script name, so check both
+        text = args.text or "--text" in args.args or "-t" in args.args
+        extra = [a for a in args.args if a not in ("--text", "-t")]
+        _cmd_run(args.script, args.output, text, extra)
+    elif args.command == "demo":
+        _cmd_demo()

smolpy/dsl/__init__.py

@@ -0,0 +1,7 @@
+from smolpy.dsl.adapter import Adapter
+from smolpy.dsl.hub import Hub
+from smolpy.dsl.link import Link
+from smolpy.dsl.network import Network
+from smolpy.dsl.switch import Switch
+
+__all__ = ["Network", "Adapter", "Switch", "Hub", "Link"]

smolpy/dsl/adapter.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from smolpy.dsl.node import Node
+
+if TYPE_CHECKING:
+    pass
+
+TrafficPattern = Literal["constant", "poisson", "bursty"]
+FrameSize = int | Literal["imix"]
+
+
+class TrafficSpec:
+    def __init__(
+        self,
+        destination: Adapter,
+        rate: float,
+        size: FrameSize,
+        pattern: TrafficPattern,
+        delay_ms: float = 0.0,
+    ) -> None:
+        self.destination = destination
+        self.rate = rate  # frames/s
+        self.size = size  # bytes or "imix"
+        self.pattern = pattern
+        self.delay_ms = delay_ms
+
+
+class MQTTSpec:
+    def __init__(
+        self,
+        broker,  # MQTTBroker
+        topic: str,
+        rate_hz: float,  # messages per second
+        payload_bytes: int,
+        qos: int,
+        delay_ms: float = 0.0,
+    ) -> None:
+        self.broker = broker
+        self.topic = topic
+        self.rate_hz = rate_hz
+        self.payload_bytes = payload_bytes
+        self.qos = qos
+        self.delay_ms = delay_ms
+        # Wire-level frame size:
+        # Ethernet+IPv4+TCP overhead = 54 B
+        # MQTT fixed header = 2 B, topic-length field = 2 B
+        # topic name = len(topic) B, packet-ID (QoS>0) = 2 B
+        ethernet_ip_tcp = 54
+        mqtt_overhead = 2 + 2 + len(topic) + (2 if qos > 0 else 0)
+        self.frame_size: int = ethernet_ip_tcp + mqtt_overhead + payload_bytes
+
+
+class Adapter(Node):
+    """NIC — generates and receives Ethernet frames."""
+
+    def __init__(self, name: str, ip: str, mac: str | None = None) -> None:
+        super().__init__(name)
+        self.ip = ip
+        self.mac = mac or _derive_mac(ip)
+        self.traffic_specs: list[TrafficSpec] = []
+        self.mqtt_specs: list[MQTTSpec] = []
+
+    def sends(
+        self,
+        to: Adapter,
+        rate: float,
+        size: FrameSize = 512,
+        pattern: TrafficPattern = "constant",
+        delay_ms: float = 0.0,
+    ) -> None:
+        self.traffic_specs.append(TrafficSpec(to, rate, size, pattern, delay_ms))
+
+    def publishes(
+        self,
+        to,  # MQTTBroker
+        topic: str,
+        rate: float = 1.0,  # messages / second
+        payload: int = 20,  # payload bytes
+        qos: int = 0,
+        delay_ms: float = 0.0,
+    ) -> None:
+        self.mqtt_specs.append(MQTTSpec(to, topic, rate, payload, qos, delay_ms))
+
+
+def _derive_mac(ip: str) -> str:
+    octets = ip.split(".")[-3:]
+    return f"02:00:{':'.join(f'{int(o):02x}' for o in octets)}"

smolpy/dsl/hub.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from smolpy.dsl.node import Node
+
+
+class Hub(Node):
+    """Layer-1 hub — shared collision domain."""
+
+    def __init__(self, name: str, ports: int) -> None:
+        super().__init__(name)
+        self.ports = ports

smolpy/dsl/link.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from smolpy.dsl.node import Node
+
+
+@dataclass
+class Link:
+    """Point-to-point cable between two nodes."""
+
+    endpoint_a: Node
+    endpoint_b: Node
+    speed: float  # Mb/s
+    length: float  # metres
+    duplex: bool = True
+
+    @property
+    def speed_bps(self) -> float:
+        return self.speed * 1_000_000
+
+    @property
+    def propagation_delay_us(self) -> float:
+        """One-way propagation delay in microseconds."""
+        return (self.length / 2e8) * 1_000_000

smolpy/dsl/mqtt_broker.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from smolpy.dsl.adapter import _derive_mac
+from smolpy.dsl.node import Node
+
+
+class MQTTBroker(Node):
+    """Application-layer MQTT message broker.
+
+    Receives PUBLISH frames from client adapters and forwards copies
+    to all registered subscribers for each topic.
+    Supports QoS 0 (fire-and-forget) and QoS 1 (PUBACK acknowledgement).
+    """
+
+    def __init__(self, name: str, ip: str, mac: str | None = None) -> None:
+        super().__init__(name)
+        self.ip = ip
+        self.mac = mac or _derive_mac(ip)
+        self._routes: dict[str, list] = {}  # topic → [Adapter, ...]
+
+    def routes(self, topic: str, to: list) -> None:
+        """Register subscriber adapters for *topic*."""
+        self._routes[topic] = list(to)

smolpy/dsl/network.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import networkx as nx
+
+from smolpy.dsl.adapter import Adapter
+from smolpy.dsl.hub import Hub
+from smolpy.dsl.link import Link
+from smolpy.dsl.mqtt_broker import MQTTBroker
+from smolpy.dsl.node import Node
+from smolpy.dsl.observation import MetricName, Observation
+from smolpy.dsl.switch import Switch, SwitchMode
+
+
+class SimulationResult:
+    def __init__(
+        self,
+        metrics: dict[str, list[tuple[float, float]]],
+        network: Network,
+    ) -> None:
+        self.metrics = metrics
+        self._network = network
+
+    def export(self, path: str, format: str | None = None) -> None:
+        """Write all metric time-series to *path*.
+
+        Format is inferred from the file extension when *format* is omitted.
+        Supported: ``"csv"`` (long format: time_ms, metric, value)
+        and ``"json"`` (dict of lists-of-pairs).
+        """
+        import csv
+        import json
+        import pathlib
+
+        p = pathlib.Path(path)
+        fmt = (format or p.suffix.lstrip(".")).lower()
+
+        if fmt == "csv":
+            with open(p, "w", newline="", encoding="utf-8") as fh:
+                w = csv.writer(fh)
+                w.writerow(["time_ms", "metric", "value"])
+                for key in sorted(self.metrics):
+                    for t, v in self.metrics[key]:
+                        w.writerow([f"{t:.3f}", key, f"{v:.6f}"])
+        elif fmt == "json":
+            payload = {
+                "network": self._network.name,
+                "metrics": {
+                    k: [[round(t, 3), round(v, 6)] for t, v in s] for k, s in self.metrics.items()
+                },
+            }
+            with open(p, "w", encoding="utf-8") as fh:
+                json.dump(payload, fh, indent=2)
+        else:
+            raise ValueError(f"Unknown format {fmt!r}. Supported formats: 'csv', 'json'.")
+
+    def plot(self) -> None:
+        from smolpy.viz.dashboard import show
+
+        show(self)
+
+    def report(self) -> None:
+        if not self.metrics:
+            print("No metrics collected. Add net.observe(...) calls before simulating.")
+            return
+        _UNITS = {
+            "throughput": "Mb/s",
+            "latency": "µs",
+            "frame_loss": "%",
+            "collision_rate": "/s",
+            "queue_depth": "fr",
+            "utilization": "%",
+            "bytes_sent": "MB",
+            "bytes_received": "MB",
+        }
+        col = max(len(k) for k in self.metrics) + 2
+        header = f"{'Metric':<{col}}  {'n':>6}  {'avg':>10}  {'min':>10}  {'max':>10}"
+        print(f"\n{header}")
+        print("-" * len(header))
+        for key in sorted(self.metrics):
+            vals = [v for _, v in self.metrics[key]]
+            if not vals:
+                continue
+            unit = next((u for m, u in _UNITS.items() if m in key), "")
+            avg = sum(vals) / len(vals)
+            print(
+                f"{key:<{col}}  {len(vals):>6}  {avg:>9.3f}{unit:>5}"
+                f"  {min(vals):>9.3f}{unit:>5}  {max(vals):>9.3f}{unit:>5}"
+            )
+        print()
+
+
+class Network:
+    """Top-level container — describes topology, traffic, and observations."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self._graph: nx.Graph = nx.Graph()
+        self._nodes: dict[str, Node] = {}
+        self._links: list[Link] = []
+        self._observations: list[Observation] = []
+
+    # --- topology builders ---
+
+    def adapter(self, name: str, ip: str, mac: str | None = None) -> Adapter:
+        node = Adapter(name, ip=ip, mac=mac)
+        self._register(node)
+        return node
+
+    def switch(self, name: str, ports: int, mode: SwitchMode = "store-and-forward") -> Switch:
+        node = Switch(name, ports=ports, mode=mode)
+        self._register(node)
+        return node
+
+    def hub(self, name: str, ports: int) -> Hub:
+        node = Hub(name, ports=ports)
+        self._register(node)
+        return node
+
+    def mqtt_broker(self, name: str, ip: str, mac: str | None = None) -> MQTTBroker:
+        node = MQTTBroker(name, ip=ip, mac=mac)
+        self._register(node)
+        return node
+
+    def link(self, a: Node, b: Node, speed: float, length: float, duplex: bool = True) -> Link:
+        lnk = Link(endpoint_a=a, endpoint_b=b, speed=speed, length=length, duplex=duplex)
+        a.links.append(lnk)
+        b.links.append(lnk)
+        self._links.append(lnk)
+        self._graph.add_edge(a.name, b.name, link=lnk)
+        return lnk
+
+    # --- observation builder ---
+
+    def observe(self, metric: MetricName, on: Node, every: float) -> None:
+        self._observations.append(Observation(metric=metric, target=on, interval_ms=every))
+
+    # --- simulation control ---
+
+    def simulate(
+        self,
+        duration: float,
+        *,
+        live: bool = False,
+        text: bool = False,
+    ) -> SimulationResult:
+        import os
+
+        if os.environ.get("SMOLPY_TEXT_MODE") == "1":
+            live, text = False, True
+        if live:
+            from smolpy.viz.dashboard import show_live
+
+            return show_live(self, duration)
+        if text:
+            from smolpy.viz.text_dashboard import show_text
+
+            return show_text(self, duration)
+        from smolpy.sim.engine import run_simulation
+
+        return run_simulation(self, duration_ms=duration)
+
+    # --- internals ---
+
+    def _register(self, node: Node) -> None:
+        if node.name in self._nodes:
+            raise ValueError(f"Node {node.name!r} already exists in network {self.name!r}")
+        self._nodes[node.name] = node
+        self._graph.add_node(node.name, node=node)

smolpy/dsl/node.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from abc import ABC
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from smolpy.dsl.link import Link
+
+
+class Node(ABC):
+    """Base class for all network nodes (Adapter, Switch, Hub)."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.links: list[Link] = []
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.name!r})"

smolpy/dsl/observation.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from smolpy.dsl.node import Node
+
+MetricName = Literal[
+    "throughput",
+    "latency",
+    "frame_loss",
+    "collision_rate",
+    "queue_depth",
+    "utilization",
+    "bytes_sent",
+    "bytes_received",
+    "broker_queue",
+]
+
+
+@dataclass
+class Observation:
+    metric: MetricName
+    target: Node
+    interval_ms: float

smolpy/dsl/switch.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from smolpy.dsl.node import Node
+
+SwitchMode = Literal["store-and-forward", "cut-through"]
+
+
+class Switch(Node):
+    """Layer-2 switch with MAC table and per-port queues."""
+
+    def __init__(self, name: str, ports: int, mode: SwitchMode = "store-and-forward") -> None:
+        super().__init__(name)
+        self.ports = ports
+        self.mode = mode
+        self.mac_table: dict[str, int] = {}  # mac -> port index