MM1 comparison UX + Sweep analytics (global & per-server) + public Sweep + guided notebook

[GioeleB00]

Summary

This PR makes it much easier to validate AsyncFlow against M/M/1 theory and to analyze scalability by sweeping concurrent users. It adds a pretty, one-call MM1 comparison, a new SweepAnalyzer for plotting results across a user grid, exposes Sweep in the public facade, and ships a guided Jupyter notebook.

---

What’s new

1) MM1 “theory vs observed” pretty print (built-in)

• MM1.print_comparison(payload, results)
  Prints a nicely formatted table (λ, μ, ρ, L, Lq, W, Wq) with abs/rel deltas.
  Uses the class’ validation (single server, CPU-exp step, tiny deterministic edges, Poisson arrivals).
• MM1.compare_and_format(...) returns the string version (for logs/CLI).
• The builder example was updated to print the MM1 table before rendering plots.

2) User-sweep analysis & plots

• New module: asyncflow.metrics.sweep_analyzer

  • Global (system) plots vs mean concurrent users:

    • Throughput (mean RPS)
    • Mean latency W (+ optional P50/P95/P99)

  • Per-server overlay plots (works with 1+ servers):

    • Utilization ρᵢ, waiting time Wqᵢ, service rate μᵢ, throughput λᵢ
    • NEW: server latency (waiting+service) mean

  • One-time caching of collected metrics to avoid recomputation across plot calls.

  • Neutral Matplotlib styling (no seaborn, no forced colors), one metric per axes.

• Public convenience: precollect() warms caches once.

• Robust selection of “top” servers for overlays (_select_top_servers) based on a chosen metric.

3) Public API

• asyncflow.__init__ now exports Sweep:

  from asyncflow import AsyncFlow, SimulationRunner, Sweep

4) Guided Jupyter notebook (MM1 end-to-end)

• Build an M/M/1-friendly scenario (single CPU-exp step, tiny deterministic edges).

• Explain the arrival sampler (windowed users → piecewise Poisson within windows).

• Run & compare with MM1.print_comparison(...) (theory vs observed).

• Plot standard dashboards (latency hist, throughput; server time-series & event metrics).

• Do a sweep (e.g., 50→250 users, step 5) and render:

  • Global throughput & latency (+ percentiles)
  • Per-server overlays (ρᵢ, Wqᵢ, μᵢ, λᵢ, server latency)

---

Tests & quality

• Added unit tests for SweepAnalyzer (global and per-server paths) using lightweight fakes.
• Tests are Ruff-compliant (naming, import style, assertions) and mypy-clean (explicit types, TYPE_CHECKING blocks, Matplotlib typing via Axes/Figure).
• Avoid repeated data collection; plotters read from cached results.

---

Usage snippets

# MM1 comparison (single call)
from asyncflow.analysis import MM1
mm1 = MM1()
mm1.print_comparison(payload, results)  # pretty table in stdout

# Sweep & plots
from asyncflow.runner.sweep import Sweep
from asyncflow.metrics.sweep_analyzer import SweepAnalyzer

pairs = Sweep().sweep_on_user(payload, user_lower_bound=50, user_upper_bound=250, step=5)
sa = SweepAnalyzer(pairs)
sa.precollect()

fig = sa.plot_global_dashboard()               # throughput & mean latency
fig = sa.plot_server_dashboard()               # ρᵢ, Wqᵢ, μᵢ, λᵢ overlays
# Optional: server latency overlay
# sa.plot_server_latency_overlay(ax, server_ids=[...])

---

Notes / Backwards compatibility

• No breaking changes to existing APIs.
• Sweep is now publicly importable from asyncflow (in addition to its original module path).
• The MM1 comparison is opt-in (one call) and prints only when invoked.

---

Why this matters

• Validating queueing-theory fidelity is now a one-liner with an immediately legible table.
• Teams can sweep load and visualize how throughput and latency evolve, plus per-server hot spots, without writing custom glue.
• The guided notebook accelerates onboarding and makes the MM1 mapping explicit.