diff --git a/bandwidth-comparison-topologies.ipynb b/bandwidth-comparison-topologies.ipynb
new file mode 100644
index 0000000..e1c57ed
--- /dev/null
+++ b/bandwidth-comparison-topologies.ipynb
@@ -0,0 +1,668 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "1e953690",
+ "metadata": {},
+ "source": [
+ "# Bandwidth Comparison Across Topologies\n",
+ "\n",
+ "Compare gossipsub, WFR-enhanced gossipsub, and grid topologies across bandwidth caps. Each combination runs across multiple seeds (averages recorded) and feeds into summary plots."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 38,
+ "id": "fc0d5e1e",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Ensure the stdlib random module is available despite the local random.py helper.\n",
+ "import importlib.machinery\n",
+ "import importlib.util\n",
+ "import os\n",
+ "import subprocess\n",
+ "import sys\n",
+ "\n",
+ "def ensure_stdlib_random() -> None:\n",
+ " stdlib_random_path = os.path.join(os.path.dirname(os.__file__), \"random.py\")\n",
+ " loader = importlib.machinery.SourceFileLoader(\"random\", stdlib_random_path)\n",
+ " spec = importlib.util.spec_from_loader(\"random\", loader)\n",
+ " module = importlib.util.module_from_spec(spec)\n",
+ " loader.exec_module(module)\n",
+ " sys.modules[\"random\"] = module\n",
+ "\n",
+ "ensure_stdlib_random()\n",
+ "\n",
+ "try:\n",
+ " import pandas as pd\n",
+ " import seaborn as sns\n",
+ "except ModuleNotFoundError:\n",
+ " subprocess.check_call([sys.executable, \"-m\", \"pip\", \"install\", \"pandas\", \"seaborn\"])\n",
+ " import pandas as pd\n",
+ " import seaborn as sns\n",
+ "\n",
+ "import numpy as np\n",
+ "import matplotlib.pyplot as plt\n",
+ "import beamsim\n",
+ "from concurrent.futures import ThreadPoolExecutor, as_completed\n",
+ "\n",
+ "sns.set_theme(style=\"whitegrid\")\n",
+ "plt.rcParams[\"figure.figsize\"] = (12, 6)\n",
+ "plt.rcParams[\"axes.titlesize\"] = 13"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 39,
+ "id": "0157592a",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "DEFAULT_CONFIG = {\n",
+ " \"backend\": \"ns3-direct\",\n",
+ " \"snark1_pull\": True,\n",
+ " \"snark1_half_direct\": True,\n",
+ " \"signature_half_direct\": 0,\n",
+ " \"shuffle\": False,\n",
+ " \"random_seed\": 42,\n",
+ " \"group_count\": 8,\n",
+ " \"group_validator_count\": 1024,\n",
+ " \"group_local_aggregator_count\": \"10%\",\n",
+ " \"global_aggregator_count\": 102,\n",
+ " \"mesh_n\": 8,\n",
+ " \"non_mesh_n\": 4,\n",
+ " \"idontwant\": False,\n",
+ " \"signature_time\": \"20ms\",\n",
+ " \"signature_size\": 3072,\n",
+ " \"snark_size\": 131072,\n",
+ " \"snark1_threshold\": 0.9,\n",
+ " \"snark2_threshold\": 0.66,\n",
+ " \"aggregation_rate_per_sec\": 1000,\n",
+ " \"snark_recursion_aggregation_rate_per_sec\": 10,\n",
+ " \"pq_signature_verification_time\": \"30us\",\n",
+ " \"snark_proof_verification_time\": \"5ms\",\n",
+ " \"gml\": \"shadow-atlas.bin\",\n",
+ " \"max_bitrate\": \"50Mbps\",\n",
+ "}\n",
+ "\n",
+ "BANDWIDTH_CAPS = [\"25Mbps\", \"50Mbps\", \"100Mbps\", \"200Mbps\"]\n",
+ "\n",
+ "# Adjust MAX_WORKERS to tune concurrency across topology/bandwidth combinations.\n",
+ "MAX_WORKERS = 3\n",
+ "SEED_BASE = 42\n",
+ "NUM_SEEDS = 1\n",
+ "SEED_VALUES = [SEED_BASE + i for i in range(NUM_SEEDS)]\n",
+ "\n",
+ "TOPOLOGY_VARIANTS = [\n",
+ " {\n",
+ " \"name\": \"gossipsub\",\n",
+ " \"label\": \"gossipsub\",\n",
+ " \"topology\": \"gossip\",\n",
+ " \"config_overrides\": {},\n",
+ " \"wfr_overrides\": None,\n",
+ " },\n",
+ " {\n",
+ " \"name\": \"wfr-gossipsub\",\n",
+ " \"label\": \"wfr-gossipsub\",\n",
+ " \"topology\": \"gossip\",\n",
+ " \"config_overrides\": {},\n",
+ " \"wfr_overrides\": {\n",
+ " \"robust\": 4,\n",
+ " },\n",
+ " },\n",
+ " {\n",
+ " \"name\": \"grid\",\n",
+ " \"label\": \"grid\",\n",
+ " \"topology\": \"grid\",\n",
+ " \"config_overrides\": {},\n",
+ " \"wfr_overrides\": None,\n",
+ " },\n",
+ "]\n",
+ "\n",
+ "def bool_to_yaml(value: bool) -> str:\n",
+ " if not isinstance(value, bool):\n",
+ " raise TypeError(f\"Expected a bool, got {type(value)!r}\")\n",
+ " return str(value).lower()\n",
+ "\n",
+ "def generate_yaml_config(*, topology: str = \"gossip\", wfr: dict | None = None, **overrides) -> str:\n",
+ " config = {**DEFAULT_CONFIG, **overrides}\n",
+ " config[\"topology\"] = topology\n",
+ " lines = [\n",
+ " \"# Simulation Backend Configuration\",\n",
+ " f\"backend: {config['backend']}\",\n",
+ " \"\",\n",
+ " f\"snark1_pull: {bool_to_yaml(config['snark1_pull'])}\",\n",
+ " f\"snark1_half_direct: {bool_to_yaml(config['snark1_half_direct'])}\",\n",
+ " f\"signature_half_direct: {config['signature_half_direct']}\",\n",
+ " \"\",\n",
+ " \"# Network Topology Configuration\",\n",
+ " f\"topology: {config['topology']}\",\n",
+ " \"\",\n",
+ " \"# Whether to shuffle validators from the same group to different routers\",\n",
+ " f\"shuffle: {bool_to_yaml(config['shuffle'])}\",\n",
+ " \"\",\n",
+ " \"# Seed for reproducible simulation results\",\n",
+ " f\"random_seed: {config['random_seed']}\",\n",
+ " \"\",\n",
+ " \"# Role Assignment Configuration\",\n",
+ " \"roles:\",\n",
+ " f\" group_count: {config['group_count']}\",\n",
+ " f\" group_validator_count: {config['group_validator_count']}\",\n",
+ " f\" group_local_aggregator_count: {config['group_local_aggregator_count']}\",\n",
+ " f\" global_aggregator_count: {config['global_aggregator_count']}\",\n",
+ " \"\",\n",
+ " \"# Gossipsub Network Configuration\",\n",
+ " \"gossip:\",\n",
+ " f\" mesh_n: {config['mesh_n']}\",\n",
+ " f\" non_mesh_n: {config['non_mesh_n']}\",\n",
+ " f\" idontwant: {bool_to_yaml(config['idontwant'])}\",\n",
+ " ]\n",
+ " if topology == \"gossip\" and wfr:\n",
+ " lines.append(\" wfr:\")\n",
+ " if \"robust\" in wfr:\n",
+ " lines.append(f\" robust: {wfr['robust']}\")\n",
+ " lines.extend(\n",
+ " [\n",
+ " \"\",\n",
+ " \"# Cryptographic Constants\",\n",
+ " \"consts:\",\n",
+ " f\" signature_time: {config['signature_time']}\",\n",
+ " f\" signature_size: {config['signature_size']}\",\n",
+ " f\" snark_size: {config['snark_size']}\",\n",
+ " f\" snark1_threshold: {config['snark1_threshold']}\",\n",
+ " f\" snark2_threshold: {config['snark2_threshold']}\",\n",
+ " f\" aggregation_rate_per_sec: {config['aggregation_rate_per_sec']}\",\n",
+ " f\" snark_recursion_aggregation_rate_per_sec: {config['snark_recursion_aggregation_rate_per_sec']}\",\n",
+ " f\" pq_signature_verification_time: {config['pq_signature_verification_time']}\",\n",
+ " f\" snark_proof_verification_time: {config['snark_proof_verification_time']}\",\n",
+ " \"\",\n",
+ " \"# Network Simulation Parameters\",\n",
+ " \"network:\",\n",
+ " f\" gml: \\\"{config['gml']}\\\"\",\n",
+ " ]\n",
+ " )\n",
+ " if config[\"max_bitrate\"] is not None:\n",
+ " lines.append(f\" max_bitrate: {config['max_bitrate']}\")\n",
+ " return beamsim.yaml(\"\\n\".join(lines))\n",
+ "\n",
+ "def extract_metrics(items):\n",
+ " snark1_rows = beamsim.get_snark1_received(items)\n",
+ " snark1_completion = None\n",
+ " if snark1_rows:\n",
+ " snark1_completion = snark1_rows[-1][0]\n",
+ " else:\n",
+ " snark1_sent_xs, _ = beamsim.get_snark1_sent(items)\n",
+ " if snark1_sent_xs and len(snark1_sent_xs) > 1:\n",
+ " snark1_completion = snark1_sent_xs[-1]\n",
+ " duplicates = None\n",
+ " duplicates_avg = None\n",
+ " try:\n",
+ " duplicates, duplicates_avg = beamsim.get_signature_duplicates(items)\n",
+ " except Exception:\n",
+ " pass\n",
+ " validator_count = None\n",
+ " snark1_threshold = None\n",
+ " try:\n",
+ " info_row = beamsim.filter_report(items, \"info\")[0]\n",
+ " validator_count = info_row[2]\n",
+ " snark1_threshold = info_row[3]\n",
+ " except Exception:\n",
+ " pass\n",
+ " return snark1_completion, duplicates, duplicates_avg, validator_count, snark1_threshold\n",
+ "\n",
+ "def run_single_configuration(topo_cfg: dict, bandwidth: str, seeds: list[int]) -> dict:\n",
+ " snark1_times = []\n",
+ " duplicate_counts = []\n",
+ " duplicate_avgs = []\n",
+ " validator_count = None\n",
+ " snark1_threshold = None\n",
+ " errors = []\n",
+ " for seed in seeds:\n",
+ " overrides = {\n",
+ " **topo_cfg.get(\"config_overrides\", {}),\n",
+ " \"max_bitrate\": bandwidth,\n",
+ " \"random_seed\": seed,\n",
+ " }\n",
+ " try:\n",
+ " yaml_path = generate_yaml_config(\n",
+ " topology=topo_cfg[\"topology\"],\n",
+ " wfr=topo_cfg.get(\"wfr_overrides\"),\n",
+ " **overrides,\n",
+ " )\n",
+ " items = beamsim.run(\n",
+ " b=DEFAULT_CONFIG[\"backend\"],\n",
+ " t=topo_cfg[\"topology\"],\n",
+ " c=yaml_path,\n",
+ " local_aggregation_only=True,\n",
+ " )\n",
+ " snark1_completion, dup_count, dup_avg, validator_count, snark1_threshold = extract_metrics(items)\n",
+ " if snark1_completion is not None:\n",
+ " snark1_times.append(snark1_completion)\n",
+ " if dup_count is not None:\n",
+ " duplicate_counts.append(dup_count)\n",
+ " if dup_avg is not None:\n",
+ " duplicate_avgs.append(dup_avg)\n",
+ " except Exception as exc:\n",
+ " errors.append(str(exc))\n",
+ " num_successes = len(snark1_times)\n",
+ " result = {\n",
+ " \"topology\": topo_cfg[\"label\"],\n",
+ " \"topology_key\": topo_cfg[\"name\"],\n",
+ " \"bandwidth\": bandwidth,\n",
+ " \"snark1_completion_ms\": float(np.mean(snark1_times)) if snark1_times else np.nan,\n",
+ " \"snark1_completion_std_ms\": float(np.std(snark1_times, ddof=1)) if len(snark1_times) > 1 else (0.0 if snark1_times else np.nan),\n",
+ " \"duplicate_count\": float(np.mean(duplicate_counts)) if duplicate_counts else np.nan,\n",
+ " \"duplicate_avg\": float(np.mean(duplicate_avgs)) if duplicate_avgs else np.nan,\n",
+ " \"num_seeds\": num_successes,\n",
+ " \"total_seeds\": len(seeds),\n",
+ " \"validator_count\": validator_count,\n",
+ " \"snark1_threshold\": snark1_threshold,\n",
+ " \"error\": \"; \".join(errors) if errors else None,\n",
+ " }\n",
+ " return result"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 40,
+ "id": "520576a3",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "run: build/beamsim -c /var/folders/r9/53ggp_3x6w51pqj8_kv1_lb00000gn/T/beamsim-yaml-md5/adc588fe00488365fb54d07cc6749225 -b ns3-direct -t gossip --local-aggregation-only --report\n"
+ ]
+ },
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " topology | \n",
+ " topology_key | \n",
+ " bandwidth | \n",
+ " snark1_completion_ms | \n",
+ " snark1_completion_std_ms | \n",
+ " duplicate_count | \n",
+ " duplicate_avg | \n",
+ " num_seeds | \n",
+ " total_seeds | \n",
+ " validator_count | \n",
+ " snark1_threshold | \n",
+ " error | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | 0 | \n",
+ " gossipsub | \n",
+ " gossipsub | \n",
+ " 25Mbps | \n",
+ " 4605.0 | \n",
+ " 0.0 | \n",
+ " 1027.0 | \n",
+ " 1.116304 | \n",
+ " 1 | \n",
+ " 1 | \n",
+ " 1024 | \n",
+ " 921 | \n",
+ " None | \n",
+ "
\n",
+ " \n",
+ " | 1 | \n",
+ " gossipsub | \n",
+ " gossipsub | \n",
+ " 50Mbps | \n",
+ " 2980.0 | \n",
+ " 0.0 | \n",
+ " 1168.0 | \n",
+ " 1.269565 | \n",
+ " 1 | \n",
+ " 1 | \n",
+ " 1024 | \n",
+ " 921 | \n",
+ " None | \n",
+ "
\n",
+ " \n",
+ " | 2 | \n",
+ " gossipsub | \n",
+ " gossipsub | \n",
+ " 100Mbps | \n",
+ " 2404.0 | \n",
+ " 0.0 | \n",
+ " 688.0 | \n",
+ " 0.747826 | \n",
+ " 1 | \n",
+ " 1 | \n",
+ " 1024 | \n",
+ " 921 | \n",
+ " None | \n",
+ "
\n",
+ " \n",
+ " | 3 | \n",
+ " gossipsub | \n",
+ " gossipsub | \n",
+ " 200Mbps | \n",
+ " 2306.0 | \n",
+ " 0.0 | \n",
+ " 1366.0 | \n",
+ " 1.483170 | \n",
+ " 1 | \n",
+ " 1 | \n",
+ " 1024 | \n",
+ " 921 | \n",
+ " None | \n",
+ "
\n",
+ " \n",
+ " | 4 | \n",
+ " wfr-gossipsub | \n",
+ " wfr-gossipsub | \n",
+ " 25Mbps | \n",
+ " 4198.0 | \n",
+ " 0.0 | \n",
+ " 1061.0 | \n",
+ " 1.139635 | \n",
+ " 1 | \n",
+ " 1 | \n",
+ " 1024 | \n",
+ " 921 | \n",
+ " None | \n",
+ "
\n",
+ " \n",
+ " | 5 | \n",
+ " wfr-gossipsub | \n",
+ " wfr-gossipsub | \n",
+ " 50Mbps | \n",
+ " 2660.0 | \n",
+ " 0.0 | \n",
+ " 784.0 | \n",
+ " 0.850325 | \n",
+ " 1 | \n",
+ " 1 | \n",
+ " 1024 | \n",
+ " 921 | \n",
+ " None | \n",
+ "
\n",
+ " \n",
+ " | 6 | \n",
+ " wfr-gossipsub | \n",
+ " wfr-gossipsub | \n",
+ " 100Mbps | \n",
+ " 2345.0 | \n",
+ " 0.0 | \n",
+ " 971.0 | \n",
+ " 1.052004 | \n",
+ " 1 | \n",
+ " 1 | \n",
+ " 1024 | \n",
+ " 921 | \n",
+ " None | \n",
+ "
\n",
+ " \n",
+ " | 7 | \n",
+ " wfr-gossipsub | \n",
+ " wfr-gossipsub | \n",
+ " 200Mbps | \n",
+ " 2177.0 | \n",
+ " 0.0 | \n",
+ " 893.0 | \n",
+ " 0.970652 | \n",
+ " 1 | \n",
+ " 1 | \n",
+ " 1024 | \n",
+ " 921 | \n",
+ " None | \n",
+ "
\n",
+ " \n",
+ " | 8 | \n",
+ " grid | \n",
+ " grid | \n",
+ " 25Mbps | \n",
+ " 2838.0 | \n",
+ " 0.0 | \n",
+ " 451.0 | \n",
+ " 0.490217 | \n",
+ " 1 | \n",
+ " 1 | \n",
+ " 1024 | \n",
+ " 921 | \n",
+ " None | \n",
+ "
\n",
+ " \n",
+ " | 9 | \n",
+ " grid | \n",
+ " grid | \n",
+ " 50Mbps | \n",
+ " 2313.0 | \n",
+ " 0.0 | \n",
+ " 437.0 | \n",
+ " 0.475000 | \n",
+ " 1 | \n",
+ " 1 | \n",
+ " 1024 | \n",
+ " 921 | \n",
+ " None | \n",
+ "
\n",
+ " \n",
+ " | 10 | \n",
+ " grid | \n",
+ " grid | \n",
+ " 100Mbps | \n",
+ " 1830.0 | \n",
+ " 0.0 | \n",
+ " 415.0 | \n",
+ " 0.451087 | \n",
+ " 1 | \n",
+ " 1 | \n",
+ " 1024 | \n",
+ " 921 | \n",
+ " None | \n",
+ "
\n",
+ " \n",
+ " | 11 | \n",
+ " grid | \n",
+ " grid | \n",
+ " 200Mbps | \n",
+ " 1394.0 | \n",
+ " 0.0 | \n",
+ " 501.0 | \n",
+ " 0.544565 | \n",
+ " 1 | \n",
+ " 1 | \n",
+ " 1024 | \n",
+ " 921 | \n",
+ " None | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "