Docs improvement, refactor analyzer, example added

Author: GioeleB00

README.md

@@ -1,6 +1,8 @@
 
 # AsyncFlow — Event-Loop Aware Simulator for Async Distributed Systems
 
+Created and maintained by @GioeleB00.
+
 [![PyPI](https://img.shields.io/pypi/v/asyncflow-sim)](https://pypi.org/project/asyncflow-sim/)
 [![Python](https://img.shields.io/pypi/pyversions/asyncflow-sim)](https://pypi.org/project/asyncflow-sim/)
 [![License](https://img.shields.io/github/license/AsyncFlow-Sim/AsyncFlow)](LICENSE)
@@ -110,43 +112,52 @@ Prefer building scenarios in Python? There’s a Python builder with the same se
 Save as `run_my_service.py`.
 
 ```python
+from __future__ import annotations
+
 from pathlib import Path
 import simpy
 import matplotlib.pyplot as plt
 
-from asyncflow.config.constants import LatencyKey
 from asyncflow.runtime.simulation_runner import SimulationRunner
 from asyncflow.metrics.analyzer import ResultsAnalyzer
 
-def print_latency_stats(res: ResultsAnalyzer) -> None:
-    order = [LatencyKey.TOTAL_REQUESTS, LatencyKey.MEAN, LatencyKey.MEDIAN,
-             LatencyKey.STD_DEV, LatencyKey.P95, LatencyKey.P99, LatencyKey.MIN, LatencyKey.MAX]
-    stats = res.get_latency_stats()
-    print("\n=== LATENCY STATS ===")
-    for k in order:
-        if k in stats:
-            print(f"{k.name:<18} = {stats[k]:.6f}")
-
-def save_plots(res: ResultsAnalyzer, out: Path) -> None:
-    fig, axes = plt.subplots(2, 2, figsize=(12, 8))
-    res.plot_latency_distribution(axes[0, 0])
-    res.plot_throughput(axes[0, 1])
-    res.plot_server_queues(axes[1, 0])
-    res.plot_ram_usage(axes[1, 1])
-    fig.tight_layout()
-    fig.savefig(out)
-    print(f"Plots saved to: {out}")
 
-if __name__ == "__main__":
-    yaml_path = Path("my_service.yml")
-    out_path  = Path("my_service_plots.png")
+def main() -> None:
+    script_dir = Path(__file__).parent
+    yaml_path = script_dir / "my_service.yml"
+    out_path = script_dir / "my_service_plots.png"
 
     env = simpy.Environment()
     runner = SimulationRunner.from_yaml(env=env, yaml_path=yaml_path)
     res: ResultsAnalyzer = runner.run()
 
-    print_latency_stats(res)
-    save_plots(res, out_path)
+    # Print a concise latency summary
+    print(res.format_latency_stats())
+
+    # 2x2: Latency | Throughput | Ready (first server) | RAM (first server)
+    fig, axes = plt.subplots(2, 2, figsize=(12, 8), dpi=160)
+
+    res.plot_latency_distribution(axes[0, 0])
+    res.plot_throughput(axes[0, 1])
+
+    sids = res.list_server_ids()
+    if sids:
+        sid = sids[0]
+        res.plot_single_server_ready_queue(axes[1, 0], sid)
+        res.plot_single_server_ram(axes[1, 1], sid)
+    else:
+        for ax in (axes[1, 0], axes[1, 1]):
+            ax.text(0.5, 0.5, "No servers", ha="center", va="center")
+            ax.axis("off")
+
+    fig.tight_layout()
+    fig.savefig(out_path)
+    print(f"Plots saved to: {out_path}")
+
+
+if __name__ == "__main__":
+    main()
+
 ```
 
 Run the python script
@@ -164,7 +175,7 @@ If you want to contribute or run the full test suite locally, follow these steps
 ### Requirements
 * **Python 3.12+** (tested on 3.12, 3.13)
 * **OS:** Linux, macOS, or Windows
-* **Installed with the package (runtime deps):** SimPy, NumPy, **Matplotlib**, Pydantic, PyYAML
+* **Installed with the package (runtime deps):** SimPy, NumPy, Matplotlib, Pydantic, PyYAML, pydantic-settings
 
 ### Install Poetry
 

docs/api/analyzer.md

@@ -0,0 +1,208 @@
+# ResultsAnalyzer — Public API Documentation
+
+Analyze and visualize the outcome of an AsyncFlow simulation.
+`ResultsAnalyzer` consumes raw runtime objects (client, servers, edges, settings),
+computes latency and throughput aggregates, exposes sampled series, and offers
+compact plotting helpers built on Matplotlib.
+
+---
+
+## Quick start
+
+```python
+import simpy
+from matplotlib import pyplot as plt
+from asyncflow.runtime.simulation_runner import SimulationRunner
+from asyncflow.metrics.analyzer import ResultsAnalyzer, SampledMetricName
+
+# 1) Run a simulation and get an analyzer
+env = simpy.Environment()
+runner = SimulationRunner.from_yaml(env=env, yaml_path="data/single_server.yml")
+res: ResultsAnalyzer = runner.run()
+
+# 2) Text summary
+print(res.format_latency_stats())
+
+# 3) Plot the dashboard (latency histogram + throughput)
+fig, (ax_lat, ax_rps) = plt.subplots(1, 2, figsize=(12, 4), dpi=160)
+res.plot_base_dashboard(ax_lat, ax_rps)
+fig.tight_layout()
+fig.savefig("dashboard.png")
+
+# 4) Single-server plots
+server_id = res.list_server_ids()[0]
+fig_rdy, ax_rdy = plt.subplots(figsize=(8, 4), dpi=160)
+res.plot_single_server_ready_queue(ax_rdy, server_id)
+fig_rdy.tight_layout()
+fig_rdy.savefig(f"ready_{server_id}.png")
+```
+
+---
+
+## Data model & units
+
+* **Latency**: seconds (s).
+* **Throughput**: requests per second (RPS).
+* **Sampled metrics** (per server/edge): series captured at a fixed sampling
+  period `settings.sample_period_s` (e.g., queue length, RAM usage).
+  Units depend on the metric (RAM is typically MB).
+
+---
+
+## Computed metrics
+
+* **Latency statistics** (global):
+  `TOTAL_REQUESTS, MEAN, MEDIAN, STD_DEV, P95, P99, MIN, MAX`.
+* **Throughput time series**: per-window RPS (default cached at 1 s buckets).
+* **Sampled metrics**: raw, per-entity series keyed by
+  `SampledMetricName` (or its string value).
+
+---
+
+## Class reference
+
+### Constructor
+
+```python
+ResultsAnalyzer(
+    *,
+    client: ClientRuntime,
+    servers: list[ServerRuntime],
+    edges: list[EdgeRuntime],
+    settings: SimulationSettings,
+)
+```
+
+The analyzer is **lazy**: metrics are computed on first access.
+
+### Core methods
+
+* `process_all_metrics() -> None`
+  Forces computation of latency stats, throughput cache (1 s), and sampled metrics.
+
+* `get_latency_stats() -> dict[LatencyKey, float]`
+  Returns the global latency stats. Computes them if needed.
+
+* `format_latency_stats() -> str`
+  Returns a ready-to-print block with latency statistics.
+
+* `get_throughput_series(window_s: float | None = None) -> tuple[list[float], list[float]]`
+  Returns `(timestamps, rps)`. If `window_s` is `None` or `1.0`, the cached
+  1-second series is returned; otherwise a fresh series is computed.
+
+* `get_sampled_metrics() -> dict[str, dict[str, list[float]]]`
+  Returns sampled metrics as `{metric_key: {entity_id: [values...]}}`.
+
+* `get_metric_map(key: SampledMetricName | str) -> dict[str, list[float]]`
+  Gets the per-entity series map for a metric. Accepts either the enum value or
+  the raw string key.
+
+* `get_series(key: SampledMetricName | str, entity_id: str) -> tuple[list[float], list[float]]`
+  Returns time/value series for a given metric and entity.
+  Time coordinates are `i * settings.sample_period_s`.
+
+* `list_server_ids() -> list[str]`
+  Returns server IDs in a stable, topology order.
+
+---
+
+## Plotting helpers
+
+All plotting methods draw on a **Matplotlib `Axes`** provided by the caller and
+do **not** manage figure lifecycles.
+
+> When there is no data for the requested plot, the axis is annotated with the
+> corresponding `no_data` message from `plot_constants`.
+
+### Dashboard
+
+* `plot_base_dashboard(ax_latency: Axes, ax_throughput: Axes) -> None`
+  Convenience: calls the two methods below.
+
+* `plot_latency_distribution(ax: Axes) -> None`
+  Latency histogram with **vertical overlays** (mean, P50, P95, P99) and a
+  **single legend box** (top-right) that shows each statistic with its matching
+  colored handle.
+
+* `plot_throughput(ax: Axes, *, window_s: float | None = None) -> None`
+  Throughput line with **horizontal overlays** (mean, P95, max) and a
+  **single legend box** (top-right) that shows values and colors for each line.
+
+### Single-server plots
+
+Each single-server plot:
+
+* draws the main series,
+
+* overlays **mean / min / max** as horizontal lines (distinct styles/colors),
+
+* shows a **single legend box** with values for mean/min/max,
+
+* **does not** include a legend entry for the main series (title suffices).
+
+* `plot_single_server_ready_queue(ax: Axes, server_id: str) -> None`
+  Ready queue length over time (per server).
+
+* `plot_single_server_io_queue(ax: Axes, server_id: str) -> None`
+  I/O queue/sleep metric over time (per server).
+
+* `plot_single_server_ram(ax: Axes, server_id: str) -> None`
+  RAM usage over time (per server).
+
+## Behavior & design notes
+
+* **Laziness & caching**
+
+  * Latency stats and the 1 s throughput series are cached on first use.
+  * Calling `get_throughput_series(window_s=...)` with a custom window computes
+    a fresh series (not cached).
+
+* **Stability**
+
+  * `list_server_ids()` follows the topology order for readability across runs.
+
+* **Error handling**
+
+  * Multi-server plotting methods validate the number of axes and raise
+    `ValueError` with a descriptive message.
+
+* **Matplotlib integration**
+
+  * The analyzer **does not** close figures or call `plt.show()`.
+  * Titles, axes labels, and “no data” messages are taken from
+    `asyncflow.config.plot_constants`.
+
+* **Thread-safety**
+
+  * The analyzer is not designed for concurrent mutation. Use from a single
+    thread after the simulation completes.
+
+---
+
+## Examples
+
+### Custom throughput window
+
+```python
+fig, ax = plt.subplots(figsize=(8, 3), dpi=160)
+res.plot_throughput(ax, window_s=2.0)  # 2-second buckets
+fig.tight_layout()
+fig.savefig("throughput_2s.png")
+```
+
+### Access a sampled metric series
+
+```python
+from asyncflow.metrics.analyzer import SampledMetricName
+
+server_id = res.list_server_ids()[0]
+t, qlen = res.get_series(SampledMetricName.READY_QUEUE_LEN, server_id)
+# t: [0.0, 0.1, 0.2, ...] (scaled by sample_period_s)
+# qlen: [.. values ..]
+```
+
+---
+
+If you need additional KPIs (e.g., tail latency over time, backlog, or
+utilization), the current structure makes it straightforward to add new helpers
+alongside the existing plotting methods.