Upload 17 files

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+venv/
+.env
+.DS_Store

CITATION.cff

@@ -0,0 +1,19 @@
+cff-version: 1.2.0
+message: "If you use SocialDynamics Lab in teaching or research, please cite this software."
+title: "SocialDynamics Lab: Interactive Opinion Dynamics and Misinformation Simulator"
+type: software
+authors:
+  - family-names: "Imel"
+    given-names: "Anouar"
+version: "1.0.0"
+date-released: "2026-09-23"
+license: "MIT"
+url: "https://huggingface.co/spaces/imvirus/SocialDynamics_Lab"
+repository-code: "https://huggingface.co/spaces/imvirus/SocialDynamics_Lab/tree/main"
+abstract: "A reproducible multi-agent simulator for exploring opinion dynamics across network topology, confirmation bias, committed minorities, and directional misinformation."
+keywords:
+  - "opinion dynamics"
+  - "social computing"
+  - "multi-agent systems"
+  - "network science"
+  - "misinformation"

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anouar Imel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

app.py

@@ -0,0 +1,831 @@
+from __future__ import annotations
+
+import csv
+import html
+import os
+import sys
+import tempfile
+import traceback
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+SRC = ROOT / "src"
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+import gradio as gr
+import numpy as np
+import plotly.graph_objects as go
+
+try:
+    import spaces
+
+    @spaces.GPU(duration=1)
+    def _zerogpu_startup_probe():
+        return "ready"
+except ImportError:
+    def _zerogpu_startup_probe():
+        return "ready"
+
+from socialdynamics.presets import PRESETS
+from socialdynamics.simulation import OpinionSimulation, SimulationConfig
+from socialdynamics.visualization import (
+    BLUE,
+    GREEN,
+    INK,
+    INK_2,
+    MUTED,
+    OCHRE,
+    PAPER,
+    PAPER_2,
+    PLUM,
+    VERMILION,
+    base_layout,
+    distribution_figure,
+    evolution_figure,
+    influence_figure,
+    metric_figure,
+    network_figure,
+    style_axes,
+)
+
+VERSION = "1.1.0"
+
+PRESET_META = {
+    "Healthy Discussion": ("01", "Baseline", "Low confirmation bias, no external signal. Social influence alone pulls the population together."),
+    "Echo Chamber": ("02", "Polarization", "A polarized start with strong cross-opinion attenuation. The graph stays fixed; exchange narrows."),
+    "Misinformation Cascade": ("03", "External signal", "A neutral population on a scale-free graph receives a persistent directional signal."),
+    "Stubborn Minority": ("04", "Committed agents", "One agent in ten holds +1 permanently while everyone else keeps adapting."),
+}
+
+
+# ── Configuration helpers ───────────────────────────────────────────────────
+
+def _direction(label: str) -> float:
+    return 1.0 if str(label).startswith("Positive") else -1.0
+
+
+def _config(
+    n_agents,
+    network,
+    initial_opinion,
+    stubborn_fraction,
+    stubborn_mode,
+    misinformation_exposure,
+    misinformation_strength,
+    misinformation_direction,
+    confirmation_bias,
+    social_influence,
+    noise,
+    steps,
+    seed,
+):
+    return SimulationConfig(
+        n_agents=int(n_agents),
+        network=network,
+        initial_opinion=initial_opinion,
+        stubborn_fraction=float(stubborn_fraction),
+        stubborn_mode=stubborn_mode,
+        misinformation_exposure=float(misinformation_exposure),
+        misinformation_strength=float(misinformation_strength),
+        misinformation_direction=_direction(misinformation_direction),
+        confirmation_bias=float(confirmation_bias),
+        social_influence=float(social_influence),
+        noise=float(noise),
+        steps=int(steps),
+        seed=int(seed if seed is not None else 42),
+    )
+
+
+def _composition(opinions: np.ndarray) -> tuple[float, float, float]:
+    negative = float(np.mean(opinions < -0.2))
+    neutral = float(np.mean(np.abs(opinions) <= 0.2))
+    positive = max(0.0, 1.0 - negative - neutral)
+    return negative, neutral, positive
+
+
+def _delta(value: float, threshold: float = 0.005) -> str:
+    if value > threshold:
+        return f"▲ {value:+.3f}"
+    if value < -threshold:
+        return f"▼ {value:+.3f}"
+    return "— ≈ 0.000"
+
+
+def _spark(values: list[float], lo: float, hi: float, color: str) -> str:
+    w, h = 140, 30
+    vals = list(values) if len(values) > 1 else list(values) * 2
+    n = len(vals)
+    span = (hi - lo) or 1.0
+    pts = " ".join(
+        f"{i / (n - 1) * w:.1f},{h - 3 - (min(hi, max(lo, v)) - lo) / span * (h - 6):.1f}" for i, v in enumerate(vals)
+    )
+    mid = ""
+    if lo < 0 < hi:
+        y0 = h - 3 - (0 - lo) / span * (h - 6)
+        mid = f'<line x1="0" y1="{y0:.1f}" x2="{w}" y2="{y0:.1f}" stroke="rgba(27,26,23,.18)" stroke-dasharray="2 3"/>'
+    return (
+        f'<svg class="spark" viewBox="0 0 {w} {h}" aria-hidden="true">{mid}'
+        f'<polyline points="{pts}" fill="none" stroke="{color}" stroke-width="1.6" stroke-linejoin="round"/></svg>'
+    )
+
+
+# ── HTML fragments ──────────────────────────────────────────────────────────
+
+READOUTS = (
+    ("mean_opinion", "Mean opinion", BLUE, (-1.0, 1.0), "{:+.3f}"),
+    ("polarization", "Polarization", VERMILION, (0.0, 1.0), "{:.3f}"),
+    ("consensus", "Consensus", GREEN, (0.0, 1.0), "{:.3f}"),
+    ("echo_chamber", "Echo-chamber index", PLUM, (0.0, 1.0), "{:.3f}"),
+)
+
+
+def _cards(sim: OpinionSimulation, step: int, running: bool = True) -> str:
+    first = sim.metric_history[0]
+    current = sim.metric_history[-1]
+    exposed = int(np.sum(sim.misinformation_mask))
+    stubborn = int(np.sum(sim.stubborn_mask))
+    progress = 100.0 * step / max(1, sim.config.steps)
+    negative, neutral, positive = _composition(sim.opinions)
+    state = "Running" if running else "Complete"
+    state_cls = "live" if running else "done"
+
+    cells = []
+    for key, label, color, (lo, hi), fmt in READOUTS:
+        series = [float(m[key]) for m in sim.metric_history]
+        cells.append(
+            f'<div class="ro"><div class="ro-label"><i style="background:{color}"></i>{label}</div>'
+            f'<div class="ro-val">{fmt.format(current[key])}</div>'
+            f'<div class="ro-delta">{_delta(current[key] - first[key])} <span>since t=0</span></div>'
+            f'{_spark(series, lo, hi, color)}</div>'
+        )
+    cells.append(
+        f'<div class="ro"><div class="ro-label"><i style="background:{OCHRE}"></i>Special agents</div>'
+        f'<div class="ro-val">{stubborn}<small> stubborn</small></div>'
+        f'<div class="ro-delta">{exposed} exposed to signal</div>'
+        f'<div class="ro-note">{stubborn / sim.config.n_agents:.0%} fixed · {exposed / sim.config.n_agents:.0%} exposed</div></div>'
+    )
+
+    return f"""
+<div class="status">
+  <div class="status-state"><span class="dot {state_cls}"></span>{state}</div>
+  <div class="status-meta">{sim.config.n_agents:,} agents · {html.escape(sim.config.network)} · {html.escape(sim.config.initial_opinion)} start · seed {sim.config.seed}</div>
+  <div class="status-step">t = {step:03d} / {sim.config.steps:03d}</div>
+</div>
+<div class="progress"><div class="progress-fill {state_cls}" style="width:{progress:.2f}%"></div></div>
+<div class="readouts">{''.join(cells)}</div>
+<div class="comp">
+  <div class="comp-label">Population<br>composition</div>
+  <div class="comp-body">
+    <div class="comp-track"><span style="width:{negative * 100:.2f}%;background:{BLUE}"></span><span style="width:{neutral * 100:.2f}%;background:#DCD6C8"></span><span style="width:{positive * 100:.2f}%;background:{VERMILION}"></span></div>
+    <div class="comp-legend"><span><b>{negative:.0%}</b> negative &lt; −0.2</span><span><b>{neutral:.0%}</b> neutral band</span><span><b>{positive:.0%}</b> positive &gt; +0.2</span></div>
+  </div>
+</div>
+"""
+
+
+def _regime(sim: OpinionSimulation) -> tuple[str, str]:
+    o = sim.opinions
+    m = sim.metric_history[-1]
+    mean = float(m["mean_opinion"])
+    strong_neg = float(np.mean(o < -0.5))
+    strong_pos = float(np.mean(o > 0.5))
+    if m["consensus"] >= 0.8:
+        return "Consensus", f"The population converges to a shared position near <b>{mean:+.2f}</b>."
+    if min(strong_neg, strong_pos) >= 0.2 and m["polarization"] >= 0.25:
+        return "Polarized split", f"<b>{strong_neg:.0%}</b> of agents hold strongly negative and <b>{strong_pos:.0%}</b> strongly positive views."
+    if abs(mean) >= 0.3:
+        side = "positive" if mean > 0 else "negative"
+        return "Directional drift", f"The population leans <b>{side}</b> overall (<b>{mean:+.2f}</b>) without reaching full agreement."
+    return "Plural / dispersed", "Opinions stay spread across the scale, with no dominant pole and no shared position."
+
+
+def _summary(sim: OpinionSimulation) -> str:
+    first = sim.metric_history[0]
+    last = sim.metric_history[-1]
+    dmean = last["mean_opinion"] - first["mean_opinion"]
+    dpol = last["polarization"] - first["polarization"]
+    dcons = last["consensus"] - first["consensus"]
+    decho = last["echo_chamber"] - first["echo_chamber"]
+    regime, regime_sentence = _regime(sim)
+
+    if abs(dmean) <= 0.03:
+        mean_sentence = "Net directional movement is negligible."
+    else:
+        mean_sentence = f"The mean shifts <b>{'positive' if dmean > 0 else 'negative'}</b> by <b>{dmean:+.3f}</b>."
+    if dpol > 0.03:
+        pol_sentence = "Dispersion increases."
+    elif dpol < -0.03:
+        pol_sentence = "Dispersion decreases."
+    else:
+        pol_sentence = "Dispersion is broadly stable."
+    if decho > 0.05:
+        echo_sentence = "Influence concentrates among like-minded neighbours."
+    elif decho < -0.05:
+        echo_sentence = "Selective same-opinion filtering weakens."
+    else:
+        echo_sentence = "Selective filtering changes only modestly."
+
+    c = sim.config
+    record = (
+        f"β {c.confirmation_bias:.2f} · α {c.social_influence:.2f} · stubborn {c.stubborn_fraction:.0%} ({html.escape(c.stubborn_mode)}) · "
+        f"signal {c.misinformation_exposure:.0%} × {c.misinformation_strength:.2f} ({'+' if c.misinformation_direction > 0 else '−'}1) · "
+        f"σ {c.noise:.3f} · T {c.steps}"
+    )
+    return f"""
+<div class="findings">
+  <div class="f-left">
+    <div class="kicker">Finding · t = {len(sim.history) - 1}</div>
+    <div class="f-regime">{regime}</div>
+    <p class="f-lead">{regime_sentence}</p>
+  </div>
+  <div class="f-right">
+    <p class="f-copy">{mean_sentence} {pol_sentence} {echo_sentence}</p>
+    <div class="f-deltas">
+      <span><i style="background:{BLUE}"></i>Δ mean <b>{dmean:+.3f}</b></span>
+      <span><i style="background:{VERMILION}"></i>Δ polarization <b>{dpol:+.3f}</b></span>
+      <span><i style="background:{GREEN}"></i>Δ consensus <b>{dcons:+.3f}</b></span>
+      <span><i style="background:{PLUM}"></i>Δ echo index <b>{decho:+.3f}</b></span>
+    </div>
+    <div class="f-record"><span>Run record</span>{record}</div>
+    <div class="f-note">Diagnostics describe this synthetic run only; they are not estimates of a real population.</div>
+  </div>
+</div>
+"""
+
+
+def _waiting(title: str, sub: str) -> str:
+    return f'<div class="waiting"><span class="dot live"></span><b>{title}</b><span>{sub}</span></div>'
+
+
+def _error_panel(exc: Exception) -> str:
+    return f"""
+<div class="error-card"><div class="kicker err">Simulation interrupted</div>
+<code>{html.escape(type(exc).__name__)}: {html.escape(str(exc))}</code>
+<div class="f-note">The full traceback was written to the Space logs.</div></div>
+"""
+
+
+def _export_csv(sim: OpinionSimulation) -> str:
+    c = sim.config
+    prefix = f"socialdynamics_{c.network.replace(' ', '').lower()}_n{c.n_agents}_seed{c.seed}_"
+    fd, path = tempfile.mkstemp(prefix=prefix, suffix=".csv")
+    history = sim.history_array
+    with os.fdopen(fd, "w", newline="", encoding="utf-8") as fh:
+        writer = csv.writer(fh)
+        writer.writerow(["step", "mean_opinion", "polarization", "consensus", "echo_chamber", "share_negative", "share_neutral", "share_positive"])
+        for m, row in zip(sim.metric_history, history):
+            neg, neu, pos = _composition(row)
+            writer.writerow([int(m["step"]), f"{m['mean_opinion']:.6f}", f"{m['polarization']:.6f}", f"{m['consensus']:.6f}", f"{m['echo_chamber']:.6f}", f"{neg:.4f}", f"{neu:.4f}", f"{pos:.4f}"])
+    return path
+
+
+# ── Event handlers ──────────────────────────────────────────────────────────
+
+def run_simulation(*values):
+    try:
+        cfg = _config(*values)
+        sim = OpinionSimulation(cfg)
+        yield (
+            _cards(sim, 0, running=True),
+            network_figure(sim),
+            evolution_figure(sim),
+            metric_figure(sim),
+            distribution_figure(sim),
+            influence_figure(sim),
+            _waiting("Simulation running", "Charts refresh at a population-aware cadence."),
+            gr.DownloadButton(value=None, interactive=False),
+        )
+
+        if cfg.n_agents >= 1000:
+            update_every = 40
+        elif cfg.n_agents >= 500:
+            update_every = 25
+        else:
+            update_every = 4 if cfg.steps <= 120 else 6
+
+        for step in sim.stream(update_every=update_every):
+            final = step == cfg.steps
+            refresh_network = final if cfg.n_agents >= 500 else (final or step <= update_every or step % (update_every * 3) == 0)
+            yield (
+                _cards(sim, step, running=not final),
+                network_figure(sim) if refresh_network else gr.skip(),
+                evolution_figure(sim),
+                metric_figure(sim),
+                distribution_figure(sim),
+                influence_figure(sim),
+                _summary(sim) if final else _waiting("Dynamics in progress", "Every step is executed; only visual refreshes are throttled."),
+                gr.DownloadButton(value=_export_csv(sim), interactive=True) if final else gr.skip(),
+            )
+    except Exception as exc:
+        traceback.print_exc()
+        yield (
+            '<div class="status err"><div class="status-state"><span class="dot err"></span>Interrupted</div><div class="status-meta">See the error below.</div><div></div></div>',
+            gr.skip(), gr.skip(), gr.skip(), gr.skip(), gr.skip(), _error_panel(exc), gr.skip(),
+        )
+
+
+def _compare_figure(rows: list[dict[str, float | str]]) -> go.Figure:
+    fig = go.Figure()
+    colors = {"Polarization": VERMILION, "Consensus": GREEN, "Echo-chamber index": PLUM}
+    for col in ("Polarization", "Consensus", "Echo-chamber index"):
+        fig.add_trace(go.Bar(
+            x=[r["Network"] for r in rows], y=[r[col] for r in rows], name=col.lower(), marker_color=colors[col],
+            marker_line_width=0, hovertemplate=f"%{{x}}<br>{col.lower()} %{{y:.3f}}<extra></extra>",
+        ))
+    fig.update_layout(**base_layout("Final-state scores", "Same parameters, different topology", height=440))
+    fig.update_layout(barmode="group", bargap=0.34, bargroupgap=0.08)
+    style_axes(fig, "", "Score", yrange=[0, 1])
+    return fig
+
+
+def _compare_table(rows: list[dict[str, float | str]]) -> str:
+    metrics = (("Polarization", VERMILION), ("Consensus", GREEN), ("Echo-chamber index", PLUM))
+    tops = {name: max(float(r[name]) for r in rows) for name, _ in metrics}
+    body = []
+    for r in rows:
+        cells = [f"<td class='net'>{html.escape(str(r['Network']))}</td><td class='num'>{float(r['Mean opinion']):+.3f}</td>"]
+        for name, color in metrics:
+            v = float(r[name])
+            top = " top" if abs(v - tops[name]) < 1e-9 else ""
+            cells.append(f"<td class='num{top}'><span class='cbar' style='width:{max(2, v * 64):.0f}px;background:{color}'></span>{v:.3f}</td>")
+        body.append("<tr>" + "".join(cells) + "</tr>")
+    return (
+        "<table class='ctable'><thead><tr><th>Network</th><th>Mean</th><th>Polarization</th><th>Consensus</th><th>Echo index</th></tr></thead>"
+        f"<tbody>{''.join(body)}</tbody></table><div class='f-note'>Bold marks the highest value in each column.</div>"
+    )
+
+
+def compare_networks(*values):
+    try:
+        base = _config(*values)
+        rows: list[dict[str, float | str]] = []
+        for network in ("Random", "Small World", "Scale Free"):
+            cfg = SimulationConfig(**{**base.__dict__, "network": network})
+            sim = OpinionSimulation(cfg)
+            sim.run()
+            m = sim.metric_history[-1]
+            rows.append({"Network": network, "Mean opinion": float(m["mean_opinion"]), "Polarization": float(m["polarization"]), "Consensus": float(m["consensus"]), "Echo-chamber index": float(m["echo_chamber"])})
+        return _compare_table(rows), _compare_figure(rows), '<div class="compare-ok">✓ Comparison complete — seed and every non-topology parameter held fixed.</div>'
+    except Exception as exc:
+        traceback.print_exc()
+        return _error_panel(exc), gr.skip(), ""
+
+
+def _preset_params(p: dict) -> str:
+    return f"{p['network']} · {p['initial_opinion']} · β {p['confirmation_bias']:.2f} · α {p['social_influence']:.2f}"
+
+
+def _banner(name: str | None) -> str:
+    if name is None:
+        return '<div class="active-scn"><span class="tag">Custom</span><b>Your own configuration</b><span class="hint">Adjust parameters, then run — or load a scenario above.</span></div>'
+    num, tag, _ = PRESET_META[name]
+    return f'<div class="active-scn"><span class="tag on">Scenario {num}</span><b>{name}</b><span class="hint">{_preset_params(PRESETS[name])} · loaded and running</span></div>'
+
+
+def preset_values(name: str):
+    p = PRESETS[name]
+    return (
+        p["network"], p["initial_opinion"], p["stubborn_fraction"], p["stubborn_mode"],
+        p["misinformation_exposure"], p["misinformation_strength"], p["misinformation_direction"],
+        p["confirmation_bias"], p["social_influence"], p["noise"], p["steps"], _banner(name),
+    )
+
+
+# ── Theme ───────────────────────────────────────────────────────────────────
+
+def _theme() -> gr.themes.Base:
+    theme = gr.themes.Base(
+        primary_hue="orange",
+        neutral_hue="stone",
+        radius_size="sm",
+        font=[gr.themes.GoogleFont("IBM Plex Sans"), "ui-sans-serif", "system-ui", "sans-serif"],
+        font_mono=[gr.themes.GoogleFont("IBM Plex Mono"), "ui-monospace", "monospace"],
+    )
+    rule = "rgba(27,26,23,0.20)"
+    settings = {
+        "body_background_fill": PAPER, "body_text_color": INK, "body_text_color_subdued": MUTED,
+        "background_fill_primary": PAPER, "background_fill_secondary": PAPER_2,
+        "border_color_primary": rule, "border_color_accent": INK, "border_color_accent_subdued": rule,
+        "color_accent": VERMILION, "color_accent_soft": "#F6DED7",
+        "link_text_color": VERMILION, "link_text_color_hover": INK,
+        "block_background_fill": "transparent", "block_border_width": "0px", "block_border_color": "transparent",
+        "block_shadow": "none", "block_radius": "0px", "container_radius": "0px", "embed_radius": "0px",
+        "block_label_background_fill": "transparent", "block_label_text_color": INK_2, "block_label_border_width": "0px",
+        "block_title_text_color": INK, "block_title_text_weight": "500", "block_info_text_color": MUTED,
+        "panel_background_fill": "transparent", "panel_border_width": "0px", "panel_border_color": "transparent",
+        "input_background_fill": "#FFFFFF", "input_background_fill_focus": "#FFFFFF",
+        "input_border_color": "rgba(27,26,23,0.24)", "input_border_color_focus": INK, "input_border_width": "1px",
+        "input_radius": "0px", "input_shadow": "none", "input_shadow_focus": "none",
+        "slider_color": VERMILION,
+        "checkbox_label_background_fill": "#FFFFFF", "checkbox_label_background_fill_hover": PAPER_2,
+        "checkbox_label_background_fill_selected": INK, "checkbox_label_text_color": INK,
+        "checkbox_label_text_color_selected": PAPER, "checkbox_label_border_color": "rgba(27,26,23,0.24)",
+        "checkbox_label_border_color_selected": INK, "checkbox_background_color_selected": VERMILION,
+        "checkbox_border_color_selected": VERMILION, "checkbox_label_shadow": "none",
+        "button_primary_background_fill": INK, "button_primary_background_fill_hover": VERMILION,
+        "button_primary_text_color": PAPER, "button_primary_text_color_hover": PAPER, "button_primary_border_color": INK,
+        "button_secondary_background_fill": "transparent", "button_secondary_background_fill_hover": PAPER_2,
+        "button_secondary_text_color": INK, "button_secondary_border_color": INK,
+        "button_large_radius": "0px", "button_small_radius": "0px", "button_shadow": "none", "button_shadow_hover": "none",
+        "shadow_drop": "none", "shadow_drop_lg": "none", "shadow_spread": "0px",
+        "table_border_color": rule, "table_even_background_fill": PAPER, "table_odd_background_fill": PAPER_2,
+        "loader_color": VERMILION,
+    }
+    # Apply one variable at a time (and mirror into *_dark) so an unknown name in a
+    # future Gradio release is skipped instead of breaking start-up. The lab is
+    # deliberately a single light "paper" theme regardless of OS dark mode.
+    for key, value in settings.items():
+        for name in (key, f"{key}_dark"):
+            try:
+                theme.set(**{name: value})
+            except (TypeError, AttributeError, ValueError):
+                pass
+    return theme
+
+
+CSS = r"""
+:root{--paper:#FBF9F4;--paper-2:#F4F1E9;--paper-3:#EAE5D8;--ink:#1B1A17;--ink-2:#3F3B34;--muted:#6B665C;--rule:rgba(27,26,23,.14);--rule-2:rgba(27,26,23,.08);--blue:#2B59C3;--verm:#D2462C;--ochre:#B7811F;--green:#2F7D5B;--plum:#6E4AA8;--serif:"Newsreader",Georgia,"Times New Roman",serif;--sans:"IBM Plex Sans",ui-sans-serif,system-ui,sans-serif;--mono:"IBM Plex Mono",ui-monospace,SFMono-Regular,Menlo,monospace}
+html,body,gradio-app{background:var(--paper)!important;color-scheme:light}
+.gradio-container{max-width:1480px!important;margin:0 auto!important;padding:0 32px 24px!important;background:var(--paper)!important;color:var(--ink)!important;font-family:var(--sans)!important}
+.gradio-container a{color:var(--verm);text-decoration:underline;text-underline-offset:2px}.gradio-container a:hover{color:var(--ink)}
+footer{display:none!important}
+.gradio-container .prose{color:var(--ink)!important}
+.gradio-container .prose p{margin:0}
+
+/* masthead */
+.mast{padding:20px 0 34px;border-bottom:1px solid var(--ink);margin-bottom:28px}
+.mast-rule{display:flex;justify-content:space-between;flex-wrap:wrap;gap:8px 20px;font:500 11px/1.2 var(--mono);letter-spacing:.09em;text-transform:uppercase;color:var(--ink-2);padding-bottom:11px;border-bottom:3px double var(--ink)}
+.mast-rule b{font-weight:600;color:var(--ink)}
+.mast-grid{display:grid;grid-template-columns:minmax(0,1.55fr) minmax(0,1fr);gap:56px;align-items:end;margin-top:38px}
+.eyebrow{display:flex;align-items:center;gap:12px;font:500 11px/1.2 var(--mono);letter-spacing:.14em;text-transform:uppercase;color:var(--verm)}
+.eyebrow:before{content:"";width:32px;height:1px;background:var(--verm)}
+.gradio-container .mast h1{font-family:var(--serif)!important;font-weight:400!important;font-size:clamp(2.7rem,5.6vw,5.1rem)!important;line-height:.97!important;letter-spacing:-.028em!important;color:var(--ink)!important;margin:18px 0 20px!important;text-wrap:balance}
+.gradio-container .mast h1 em{font-style:italic;color:var(--verm)}
+.gradio-container .lede{font-family:var(--serif);font-size:19.5px;line-height:1.5;color:var(--ink-2);max-width:38em;text-wrap:pretty;margin:0}
+.facts{display:flex;flex-wrap:wrap;margin-top:28px;border-top:1px solid var(--rule)}
+.facts div{padding:14px 26px 0 0;margin-right:26px;border-right:1px solid var(--rule)}
+.facts div:last-child{border-right:0;margin-right:0}
+.facts b{display:block;font:400 30px/1 var(--serif);color:var(--ink);font-variant-numeric:lining-nums}
+.facts span{display:block;margin-top:6px;font:500 10.5px/1.2 var(--mono);letter-spacing:.1em;text-transform:uppercase;color:var(--muted)}
+.eq-card{border:1px solid var(--ink);background:var(--paper-2);padding:22px 24px 20px}
+.eq-label{display:flex;justify-content:space-between;font:500 10.5px/1 var(--mono);letter-spacing:.12em;text-transform:uppercase;color:var(--muted)}
+.eq{font-family:var(--serif);font-style:italic;font-size:clamp(19px,1.9vw,24px);line-height:1.4;color:var(--ink);margin:16px 0 14px;white-space:nowrap;overflow-x:auto}
+.eq .n{font-style:normal}
+.eq-terms{display:grid;grid-template-columns:auto 1fr;gap:5px 14px;font:400 12.5px/1.45 var(--sans);color:var(--ink-2)}
+.eq-terms i{font-family:var(--serif);font-size:16px;color:var(--ink)}
+.scale{margin-top:18px}
+.scale-bar{height:8px;background:linear-gradient(90deg,#1F3F8F,#5B83D6 25%,#DCD6C8 50%,#E8876F 75%,#B8321C)}
+.scale-ticks{display:flex;justify-content:space-between;margin-top:6px;font:500 10.5px/1 var(--mono);color:var(--muted)}
+
+/* section heads */
+.sec-head{display:flex;align-items:baseline;flex-wrap:wrap;gap:6px 16px;border-top:1px solid var(--ink);padding-top:12px;margin:6px 0 16px}
+.sec-num{font:500 11px/1 var(--mono);letter-spacing:.1em;color:var(--verm)}
+.sec-title{font:400 28px/1.1 var(--serif);color:var(--ink);letter-spacing:-.01em}
+.sec-sub{margin-left:auto;font:400 13px/1.4 var(--sans);color:var(--muted);max-width:44em;text-wrap:pretty}
+
+/* scenario presets */
+.preset-row{gap:0!important;border:1px solid var(--ink)!important;background:var(--paper)!important}
+.preset-card{padding:18px 20px 18px!important;border-right:1px solid var(--rule)!important;gap:14px!important;justify-content:space-between!important;transition:background .15s}
+.preset-card:last-child{border-right:0!important}
+.preset-card:hover{background:var(--paper-2)!important}
+.pc-top{display:flex;justify-content:space-between;font:500 10.5px/1 var(--mono);letter-spacing:.1em;text-transform:uppercase;color:var(--muted)}
+.pc-top b{color:var(--verm);font-weight:500}
+.pc-title{font:400 24px/1.12 var(--serif);color:var(--ink);margin:12px 0 8px;letter-spacing:-.01em}
+.pc-copy{font:400 13px/1.5 var(--sans);color:var(--ink-2);text-wrap:pretty}
+.pc-params{margin-top:12px;font:400 11px/1.4 var(--mono);color:var(--muted)}
+button.preset-btn,.preset-btn button{background:transparent!important;border:1px solid var(--ink)!important;color:var(--ink)!important;border-radius:0!important;font:500 11.5px/1 var(--mono)!important;letter-spacing:.08em!important;text-transform:uppercase!important;min-height:40px!important;box-shadow:none!important}
+button.preset-btn:hover,.preset-btn button:hover{background:var(--ink)!important;color:var(--paper)!important}
+.active-scn{display:flex;flex-wrap:wrap;align-items:baseline;gap:6px 14px;padding:12px 0 2px;font:400 13px/1.4 var(--sans);color:var(--ink-2)}
+.active-scn .tag{font:500 10.5px/1 var(--mono);letter-spacing:.1em;text-transform:uppercase;padding:5px 8px;border:1px solid var(--ink);color:var(--ink)}
+.active-scn .tag.on{background:var(--ink);color:var(--paper)}
+.active-scn b{font:400 18px/1.2 var(--serif);color:var(--ink)}
+.active-scn .hint{font:400 11.5px/1.4 var(--mono);color:var(--muted)}
+
+/* layout */
+.lab-row{gap:28px!important;margin-top:30px!important}
+.control-panel{position:sticky!important;top:14px;align-self:flex-start!important;border:1px solid var(--ink)!important;background:var(--paper-2)!important;padding:20px 20px 20px!important;gap:6px!important}
+.ctl-head{padding-bottom:12px}
+.ctl-head small{display:block;font:500 10.5px/1 var(--mono);letter-spacing:.12em;text-transform:uppercase;color:var(--verm)}
+.ctl-head strong{display:block;margin-top:8px;font:400 24px/1.1 var(--serif);color:var(--ink)}
+.ctl-head p{margin-top:6px!important;font:400 12.5px/1.45 var(--sans);color:var(--muted)}
+.param-group{border:0!important;border-top:1px solid var(--rule)!important;border-radius:0!important;background:transparent!important;padding:12px 0 6px!important;margin:0!important;box-shadow:none!important}
+.param-group>button,.param-group>.label-wrap,.param-group button.label-wrap{font:500 11px/1.2 var(--mono)!important;letter-spacing:.1em!important;text-transform:uppercase!important;color:var(--ink)!important;background:transparent!important;padding:4px 0!important}
+.control-panel label>span,.control-panel [data-testid="block-info"]{font-family:var(--sans)!important}
+.control-panel input[type="number"]{font-family:var(--mono)!important}
+button.run-button,.run-button button{background:var(--ink)!important;color:var(--paper)!important;border:0!important;border-radius:0!important;font:500 13px/1 var(--mono)!important;letter-spacing:.12em!important;text-transform:uppercase!important;min-height:54px!important;box-shadow:none!important;margin-top:10px!important;transition:background .15s}
+button.run-button:hover,.run-button button:hover{background:var(--verm)!important}
+.ctl-foot{font:400 11px/1.5 var(--mono);color:var(--muted);padding-top:8px}
+
+/* status + readouts */
+.status{display:grid;grid-template-columns:auto 1fr auto;gap:18px;align-items:center;font:500 11px/1.3 var(--mono);letter-spacing:.07em;text-transform:uppercase;color:var(--ink-2);padding-bottom:10px}
+.status-state{display:flex;align-items:center;gap:8px;color:var(--ink)}
+.status-meta{color:var(--muted);text-align:center}
+.status-step{font-variant-numeric:tabular-nums;color:var(--ink)}
+.status.err{color:var(--verm)}
+.dot{display:inline-block;width:8px;height:8px;border-radius:50%;flex:none}
+.dot.live{background:var(--verm);animation:sdpulse 1.2s ease-in-out infinite}
+.dot.done{background:var(--green)}
+.dot.err{background:var(--verm)}
+@keyframes sdpulse{50%{opacity:.25}}
+.progress{height:2px;background:var(--rule)}
+.progress-fill{height:100%;background:var(--ink);transition:width .4s ease}
+.progress-fill.live{background:var(--verm)}
+.readouts{display:grid;grid-template-columns:repeat(5,minmax(0,1fr));border-bottom:1px solid var(--rule);margin-top:0}
+.ro{padding:16px 18px 12px 0;margin-right:18px;border-right:1px solid var(--rule);min-width:0}
+.ro:last-child{border-right:0;margin-right:0}
+.ro-label{display:flex;align-items:center;gap:8px;font:500 10.5px/1.2 var(--mono);letter-spacing:.09em;text-transform:uppercase;color:var(--muted);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.ro-label i,.f-deltas i{display:inline-block;width:8px;height:8px;flex:none}
+.ro-val{margin:10px 0 6px;font:400 38px/1 var(--serif);color:var(--ink);font-variant-numeric:lining-nums tabular-nums;letter-spacing:-.01em}
+.ro-val small{font:400 13px var(--sans);color:var(--muted);letter-spacing:0}
+.ro-delta{font:400 11.5px/1.3 var(--mono);color:var(--ink-2);white-space:nowrap}
+.ro-delta span{color:var(--muted)}
+.ro-note{margin-top:14px;font:400 11px/1.3 var(--mono);color:var(--muted)}
+.spark{display:block;width:100%;height:auto;margin-top:10px}
+.comp{display:grid;grid-template-columns:120px minmax(0,1fr);gap:18px;align-items:center;padding:14px 0;border-bottom:1px solid var(--rule)}
+.comp-label{font:500 10.5px/1.35 var(--mono);letter-spacing:.09em;text-transform:uppercase;color:var(--muted)}
+.comp-track{display:flex;height:12px;background:var(--paper-3);overflow:hidden}
+.comp-track span{height:100%;transition:width .4s ease}
+.comp-legend{display:flex;justify-content:space-between;flex-wrap:wrap;gap:4px 16px;margin-top:7px;font:400 11.5px/1.3 var(--mono);color:var(--muted)}
+.comp-legend b{color:var(--ink);font-weight:500}
+.legend{display:flex;flex-wrap:wrap;gap:8px 22px;padding:14px 0 10px;font:400 12.5px/1.3 var(--sans);color:var(--ink-2)}
+.legend span{display:flex;align-items:center;gap:8px}
+.lg-dot{width:10px;height:10px;border-radius:50%}
+.lg-dia{width:9px;height:9px;transform:rotate(45deg);background:#DCD6C8;border:1px solid var(--ink)}
+.lg-ring{width:10px;height:10px;border-radius:50%;border:2px solid var(--ochre);background:#DCD6C8}
+
+/* chart tabs */
+.viz-tabs{border:1px solid var(--ink)!important;border-radius:0!important;background:var(--paper)!important;padding:0 6px 6px!important}
+.viz-tabs [role="tablist"]{border-bottom:1px solid var(--rule)!important;gap:2px!important;padding:0 4px!important;background:transparent!important}
+.viz-tabs button[role="tab"]{font:500 11.5px/1 var(--mono)!important;letter-spacing:.07em!important;text-transform:uppercase!important;color:var(--muted)!important;border-radius:0!important;padding:14px 12px!important;background:transparent!important;border:0!important}
+.viz-tabs button[role="tab"]:hover{color:var(--ink)!important}
+.viz-tabs button[role="tab"][aria-selected="true"],.viz-tabs button[role="tab"].selected{color:var(--ink)!important}
+
+/* findings */
+.waiting{display:flex;flex-wrap:wrap;align-items:center;gap:10px 14px;border-top:1px solid var(--ink);padding:18px 0;margin-top:18px;font:400 12px/1.4 var(--mono);color:var(--muted)}
+.waiting b{font:400 20px/1.1 var(--serif);color:var(--ink)}
+.findings{display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1.5fr);gap:40px;border-top:1px solid var(--ink);padding:20px 0 6px;margin-top:18px}
+.kicker{font:500 10.5px/1 var(--mono);letter-spacing:.12em;text-transform:uppercase;color:var(--verm)}
+.kicker.err{margin-bottom:10px}
+.f-regime{margin-top:12px;font:400 44px/1 var(--serif);color:var(--ink);letter-spacing:-.02em}
+.gradio-container .f-lead{margin-top:12px!important;font:400 17px/1.5 var(--serif);color:var(--ink-2);text-wrap:pretty}
+.gradio-container .f-copy{font:400 15px/1.6 var(--sans);color:var(--ink-2);text-wrap:pretty}
+.f-lead b,.f-copy b{color:var(--ink);font-weight:600}
+.f-deltas{display:flex;flex-wrap:wrap;gap:8px;margin-top:14px}
+.f-deltas span{display:flex;align-items:center;gap:8px;padding:7px 10px;border:1px solid var(--rule);background:#fff;font:400 11.5px/1 var(--mono);color:var(--muted)}
+.f-deltas b{color:var(--ink);font-weight:500}
+.f-record{margin-top:14px;padding:10px 12px;background:var(--paper-2);font:400 11.5px/1.55 var(--mono);color:var(--ink-2)}
+.f-record span{display:block;font-weight:500;letter-spacing:.1em;text-transform:uppercase;font-size:10px;color:var(--muted);margin-bottom:3px}
+.f-note{margin-top:10px;font:400 11.5px/1.45 var(--mono);color:var(--muted)}
+button.dl-btn,.dl-btn button{align-self:flex-start;background:transparent!important;border:1px solid var(--ink)!important;border-radius:0!important;color:var(--ink)!important;font:500 11px/1 var(--mono)!important;letter-spacing:.08em!important;text-transform:uppercase!important;box-shadow:none!important;min-height:38px!important;max-width:280px}
+button.dl-btn:hover:not(:disabled),.dl-btn button:hover:not(:disabled){background:var(--ink)!important;color:var(--paper)!important}
+button.dl-btn:disabled{opacity:.4}
+.error-card{border:1px solid var(--verm);background:#FBEEEA;padding:16px 18px;margin-top:18px}
+.error-card code{font:400 12.5px/1.5 var(--mono);color:var(--ink)}
+
+/* compare */
+.compare-sec{margin-top:48px!important;gap:12px!important}
+button.compare-button,.compare-button button{align-self:flex-start;background:var(--ink)!important;color:var(--paper)!important;border:0!important;border-radius:0!important;font:500 12px/1 var(--mono)!important;letter-spacing:.1em!important;text-transform:uppercase!important;min-height:46px!important;max-width:360px;box-shadow:none!important}
+button.compare-button:hover,.compare-button button:hover{background:var(--verm)!important}
+.compare-ok{font:400 11.5px/1.4 var(--mono);color:var(--green)}
+.ctable{width:100%;border-collapse:collapse;font:400 13.5px/1.3 var(--sans);color:var(--ink-2)}
+.ctable th{font:500 10.5px/1 var(--mono);letter-spacing:.09em;text-transform:uppercase;color:var(--muted);text-align:right;padding:12px 10px;border-bottom:1px solid var(--ink)}
+.ctable th:first-child,.ctable td:first-child{text-align:left;padding-left:0}
+.ctable td{padding:16px 10px;border-bottom:1px solid var(--rule)}
+.ctable td.net{font:400 19px/1.1 var(--serif);color:var(--ink)}
+.ctable td.num{text-align:right;font-family:var(--mono);font-variant-numeric:tabular-nums;white-space:nowrap}
+.ctable td.top{color:var(--ink);font-weight:600}
+.cbar{display:inline-block;height:6px;vertical-align:middle;margin-right:10px}
+.empty-note{padding:26px 0;font:400 12px/1.5 var(--mono);color:var(--muted);border-bottom:1px solid var(--rule)}
+
+/* methods */
+.methods{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));border-top:1px solid var(--ink);margin-top:56px}
+.m-col{padding:18px 24px 24px 0;margin-right:24px;border-right:1px solid var(--rule);min-width:0}
+.m-col:last-child{border-right:0;margin-right:0}
+.m-num{font:500 10.5px/1 var(--mono);letter-spacing:.1em;color:var(--verm)}
+.gradio-container .m-col h3{margin:10px 0 10px!important;font:400 23px/1.15 var(--serif)!important;color:var(--ink)!important}
+.gradio-container .m-col p{font:400 13.5px/1.6 var(--sans);color:var(--ink-2);margin:0 0 10px!important;text-wrap:pretty}
+.fx{font-family:var(--serif);font-style:italic;font-size:18px;color:var(--ink);padding:6px 0 8px;white-space:nowrap;overflow-x:auto}
+.fx .n{font-style:normal}
+.m-list{display:grid;gap:8px;margin-top:4px}
+.m-list div{display:grid;grid-template-columns:96px 1fr;gap:10px;font:400 12.5px/1.45 var(--sans);color:var(--ink-2);padding-bottom:8px;border-bottom:1px solid var(--rule-2)}
+.m-list b{font:500 11px/1.45 var(--mono);color:var(--ink);letter-spacing:.03em}
+.refs{margin:0;padding-left:18px;font:400 12.5px/1.5 var(--sans);color:var(--ink-2)}
+.refs li{margin-bottom:8px}
+.refs i{font-family:var(--serif);font-size:14px}
+.colophon{display:flex;justify-content:space-between;flex-wrap:wrap;gap:10px 24px;margin-top:40px;padding-top:12px;border-top:3px double var(--ink);font:400 11px/1.5 var(--mono);letter-spacing:.04em;color:var(--muted)}
+.colophon b{color:var(--ink);font-weight:500}
+
+@media(max-width:1180px){.mast-grid{grid-template-columns:1fr;gap:32px}.control-panel{position:static!important}.readouts{grid-template-columns:repeat(3,minmax(0,1fr))}.ro:nth-child(3){border-right:0;margin-right:0}.ro:nth-child(n+4){border-top:1px solid var(--rule)}.methods{grid-template-columns:repeat(2,minmax(0,1fr))}.m-col:nth-child(2){border-right:0;margin-right:0}.status-meta{display:none}.status{grid-template-columns:1fr auto}}
+@media(max-width:720px){.gradio-container{padding:0 16px 16px!important}.readouts{grid-template-columns:repeat(2,minmax(0,1fr))}.ro:nth-child(3){border-right:1px solid var(--rule);margin-right:18px}.ro:nth-child(2n){border-right:0;margin-right:0}.ro:nth-child(n+3){border-top:1px solid var(--rule)}.findings{grid-template-columns:1fr;gap:16px}.methods{grid-template-columns:1fr}.m-col{border-right:0!important;margin-right:0!important;border-bottom:1px solid var(--rule)}.comp{grid-template-columns:1fr;gap:8px}.sec-sub{margin-left:0}.preset-card{border-right:0!important;border-bottom:1px solid var(--rule)!important}.f-regime{font-size:36px}}
+"""
+
+HEAD = """
+<meta name="theme-color" content="#FBF9F4">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,500;1,6..72,400&family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+<script>
+(function(){
+  function light(){document.documentElement.classList.remove('dark');if(document.body){document.body.classList.remove('dark');}}
+  light();
+  document.addEventListener('DOMContentLoaded',function(){
+    light();
+    var mo=new MutationObserver(light);
+    mo.observe(document.documentElement,{attributes:true,attributeFilter:['class']});
+    mo.observe(document.body,{attributes:true,attributeFilter:['class']});
+  });
+})();
+</script>
+"""
+
+MASTHEAD = f"""
+<header class="mast">
+  <div class="mast-rule"><span><b>SocialDynamics Lab</b> · Interactive research &amp; teaching simulator</span><span>Opinion dynamics · Network science</span><span>v{VERSION} · MIT</span></div>
+  <div class="mast-grid">
+    <div>
+      <div class="eyebrow">A laboratory for collective opinion</div>
+      <h1>How opinions <em>move</em> through a network.</h1>
+      <p class="lede">Configure a synthetic population, choose who talks to whom, add confirmation bias, committed minorities, or a persistent misinformation signal — then watch local interaction rules produce consensus, drift, or division.</p>
+      <div class="facts">
+        <div><b>100–1,000</b><span>Agents</span></div>
+        <div><b>3</b><span>Network families</span></div>
+        <div><b>5</b><span>Live views</span></div>
+        <div><b>Seeded</b><span>Fully reproducible</span></div>
+      </div>
+    </div>
+    <aside class="eq-card">
+      <div class="eq-label"><span>Update rule</span><span>per agent · per step</span></div>
+      <div class="eq">x<sub>i</sub>(t+1) <span class="n">=</span> clip [ x<sub>i</sub> <span class="n">+</span> α(S<sub>i</sub> <span class="n">−</span> x<sub>i</sub>) <span class="n">+</span> M<sub>i</sub> <span class="n">+</span> ε<sub>i</sub> ]</div>
+      <div class="eq-terms">
+        <i>S<sub>i</sub></i><span>neighbourhood target, weighted by e<sup>−β|x<sub>i</sub>−x<sub>j</sub>|</sup> — confirmation bias β</span>
+        <i>α</i><span>social-influence strength</span>
+        <i>M<sub>i</sub></i><span>directional external signal (exposed agents only)</span>
+        <i>ε<sub>i</sub></i><span>Gaussian noise · stubborn agents never update</span>
+      </div>
+      <div class="scale"><div class="scale-bar"></div><div class="scale-ticks"><span>−1 negative</span><span>0</span><span>positive +1</span></div></div>
+    </aside>
+  </div>
+</header>
+"""
+
+
+def _preset_card_html(name: str) -> str:
+    num, tag, copy = PRESET_META[name]
+    return (
+        f'<div class="pc-top"><b>Scenario {num}</b><span>{tag}</span></div>'
+        f'<div class="pc-title">{name}</div><div class="pc-copy">{copy}</div>'
+        f'<div class="pc-params">{_preset_params(PRESETS[name])}</div>'
+    )
+
+
+METHODS = """
+<section class="methods">
+  <div class="m-col">
+    <div class="m-num">§1 · Model</div>
+    <h3>Distance-weighted influence</h3>
+    <p>Each agent holds a bounded opinion in [−1, +1]. Neighbour influence decays with opinion distance:</p>
+    <div class="fx">w<sub>ij</sub> <span class="n">=</span> exp(<span class="n">−</span>β |x<sub>i</sub> <span class="n">−</span> x<sub>j</sub>|),&nbsp; β <span class="n">∈</span> [0, 6]</div>
+    <p>Updates are synchronous. A smooth model inspired by DeGroot and bounded-confidence traditions — not either verbatim.</p>
+  </div>
+  <div class="m-col">
+    <div class="m-num">§2 · Diagnostics</div>
+    <h3>What the readouts mean</h3>
+    <div class="m-list">
+      <div><b>Polarization</b><span>Population variance, Var(x) ∈ [0, 1].</span></div>
+      <div><b>Consensus</b><span>1 − Std(x), clipped to [0, 1].</span></div>
+      <div><b>Echo index</b><span>Drop in edge disagreement once confirmation-bias weights are applied. Near 0 = little selective filtering.</span></div>
+    </div>
+  </div>
+  <div class="m-col">
+    <div class="m-num">§3 · Topologies</div>
+    <h3>Three network families</h3>
+    <div class="m-list">
+      <div><b>Random</b><span>Erdős–Rényi, mean degree ≈ 8.</span></div>
+      <div><b>Small World</b><span>Watts–Strogatz, k = 8, rewiring p = 0.12.</span></div>
+      <div><b>Scale Free</b><span>Barabási–Albert, m = 4 — a few highly connected hubs.</span></div>
+    </div>
+    <p style="margin-top:12px">Large graphs use a hub-aware radial layout and sampled edges for display only; every tie is simulated.</p>
+  </div>
+  <div class="m-col">
+    <div class="m-num">§4 · References</div>
+    <h3>Scientific context</h3>
+    <ol class="refs">
+      <li>DeGroot (1974). Reaching a consensus. <i>JASA</i> 69.</li>
+      <li>Hegselmann &amp; Krause (2002). Opinion dynamics and bounded confidence. <i>JASSS</i> 5(3).</li>
+      <li>Watts &amp; Strogatz (1998). Small-world networks. <i>Nature</i> 393.</li>
+      <li>Barabási &amp; Albert (1999). Scaling in random networks. <i>Science</i> 286.</li>
+      <li>Erdős &amp; Rényi (1959). On random graphs I. <i>Publ. Math.</i> 6.</li>
+    </ol>
+  </div>
+</section>
+<div class="colophon">
+  <span><b>SocialDynamics Lab</b> · Open-source research &amp; teaching demo by Anouar Imel</span>
+  <span>A synthetic mechanistic model — not a forecast or measurement of any real population.</span>
+  <span>MIT License · v""" + VERSION + """</span>
+</div>
+"""
+
+
+# ── Interface ───────────────────────────────────────────────────────────────
+
+with gr.Blocks(title="SocialDynamics Lab — opinion dynamics simulator") as demo:
+    gr.HTML(MASTHEAD)
+
+    probe_btn = gr.Button("probe", visible=False)
+    probe_out = gr.Textbox(visible=False)
+    probe_btn.click(_zerogpu_startup_probe, outputs=probe_out, api_visibility="private", show_progress="hidden")
+
+    gr.HTML('<div class="sec-head"><span class="sec-num">01</span><span class="sec-title">Start from a scenario</span><span class="sec-sub">Each preset isolates one mechanism. Loading a scenario sets the parameters and runs it immediately.</span></div>')
+    preset_buttons = {}
+    with gr.Row(equal_height=True, elem_classes=["preset-row"]):
+        for _name in PRESETS:
+            with gr.Column(min_width=220, elem_classes=["preset-card"]):
+                gr.HTML(_preset_card_html(_name))
+                preset_buttons[_name] = gr.Button("Load & run  →", elem_classes=["preset-btn"], size="sm")
+    preset_banner = gr.HTML(_banner(None))
+
+    with gr.Row(equal_height=False, elem_classes=["lab-row"]):
+        with gr.Column(scale=3, min_width=320, elem_classes=["control-panel"]):
+            gr.HTML('<div class="ctl-head"><small>02 · Parameters</small><strong>Configure the experiment</strong><p>Every run is deterministic for a fixed seed.</p></div>')
+            with gr.Accordion("A · Population & network", open=True, elem_classes=["param-group"]):
+                n_agents = gr.Radio([100, 500, 1000], value=100, label="Population size")
+                network = gr.Dropdown(["Random", "Small World", "Scale Free"], value="Small World", label="Network structure")
+                initial_opinion = gr.Dropdown(["Random", "Neutral", "Polarized"], value="Random", label="Initial opinion state")
+            with gr.Accordion("B · Social dynamics", open=True, elem_classes=["param-group"]):
+                confirmation_bias = gr.Slider(0, 1, value=0.45, step=0.01, label="Confirmation bias (β)", info="Suppresses influence from dissimilar neighbours.")
+                social_influence = gr.Slider(0, 1, value=0.45, step=0.01, label="Social influence (α)", info="Speed of movement toward the neighbourhood target.")
+                stubborn_fraction = gr.Slider(0, 0.30, value=0.05, step=0.01, label="Stubborn agents", info="Share of agents that never update.")
+                stubborn_mode = gr.Dropdown(["Keep initial", "Positive (+1)", "Negative (-1)", "Split extremes"], value="Split extremes", label="Stubborn stance")
+            with gr.Accordion("C · External signal", open=False, elem_classes=["param-group"]):
+                misinformation_exposure = gr.Slider(0, 1, value=0.25, step=0.01, label="Misinformation exposure", info="Share of adaptive agents receiving the signal.")
+                misinformation_strength = gr.Slider(0, 1, value=0.35, step=0.01, label="Signal strength")
+                misinformation_direction = gr.Radio(["Positive (+1)", "Negative (-1)"], value="Positive (+1)", label="Signal direction")
+            with gr.Accordion("D · Run settings", open=False, elem_classes=["param-group"]):
+                noise = gr.Slider(0, 0.20, value=0.02, step=0.005, label="Random noise (σ)")
+                steps = gr.Slider(50, 300, value=120, step=10, label="Simulation horizon (steps)")
+                seed = gr.Number(value=42, precision=0, label="Random seed")
+            run_btn = gr.Button("▶  Run experiment", variant="primary", size="lg", elem_classes=["run-button"])
+            gr.HTML('<div class="ctl-foot">Large populations refresh charts less often; every step is still simulated.</div>')
+
+        with gr.Column(scale=10, min_width=620):
+            cards = gr.HTML()
+            gr.HTML(
+                '<div class="legend">'
+                f'<span><i class="lg-dot" style="background:{BLUE}"></i>negative opinion</span>'
+                '<span><i class="lg-dot" style="background:#DCD6C8"></i>neutral</span>'
+                f'<span><i class="lg-dot" style="background:{VERMILION}"></i>positive opinion</span>'
+                '<span><i class="lg-dia"></i>stubborn agent</span>'
+                '<span><i class="lg-ring"></i>exposed to misinformation</span>'
+                '</div>'
+            )
+            with gr.Tabs(elem_classes=["viz-tabs"]):
+                with gr.Tab("Network"):
+                    network_plot = gr.Plot(show_label=False)
+                with gr.Tab("Evolution"):
+                    evolution_plot = gr.Plot(show_label=False)
+                with gr.Tab("Diagnostics"):
+                    metric_plot = gr.Plot(show_label=False)
+                with gr.Tab("Distribution"):
+                    distribution_plot = gr.Plot(show_label=False)
+                with gr.Tab("Influence map"):
+                    influence_plot = gr.Plot(show_label=False)
+            summary = gr.HTML(_waiting("Ready", "Configure an experiment or load a scenario, then run it."))
+            download = gr.DownloadButton("↓  Download run data (CSV)", value=None, interactive=False, size="sm", elem_classes=["dl-btn"])
+
+    with gr.Column(elem_classes=["compare-sec"]):
+        gr.HTML('<div class="sec-head"><span class="sec-num">03</span><span class="sec-title">Does topology matter?</span><span class="sec-sub">Rerun the current configuration on all three network families, holding the seed and every other parameter fixed.</span></div>')
+        compare_btn = gr.Button("Compare the 3 network structures", elem_classes=["compare-button"])
+        compare_status = gr.HTML()
+        with gr.Row(equal_height=False):
+            with gr.Column(scale=5, min_width=320):
+                compare_table = gr.HTML('<div class="empty-note">No comparison yet — results appear here as a table and a grouped chart.</div>')
+            with gr.Column(scale=6, min_width=360):
+                compare_plot = gr.Plot(show_label=False)
+
+    gr.HTML(METHODS)
+
+    inputs = [n_agents, network, initial_opinion, stubborn_fraction, stubborn_mode, misinformation_exposure, misinformation_strength, misinformation_direction, confirmation_bias, social_influence, noise, steps, seed]
+    outputs = [cards, network_plot, evolution_plot, metric_plot, distribution_plot, influence_plot, summary, download]
+    run_kwargs = dict(inputs=inputs, outputs=outputs, api_visibility="undocumented", concurrency_limit=2, stream_every=0.75)
+
+    run_btn.click(run_simulation, show_progress="minimal", **run_kwargs)
+    demo.load(run_simulation, show_progress="hidden", **run_kwargs)
+    compare_btn.click(compare_networks, inputs=inputs, outputs=[compare_table, compare_plot, compare_status], show_progress="minimal", api_visibility="undocumented", concurrency_limit=1)
+
+    preset_outputs = [network, initial_opinion, stubborn_fraction, stubborn_mode, misinformation_exposure, misinformation_strength, misinformation_direction, confirmation_bias, social_influence, noise, steps, preset_banner]
+    for _name, _button in preset_buttons.items():
+        _button.click(
+            lambda name=_name: preset_values(name), outputs=preset_outputs, queue=False, api_visibility="undocumented"
+        ).then(run_simulation, show_progress="minimal", **run_kwargs)
+
+
+if __name__ == "__main__":
+    demo.queue(default_concurrency_limit=2, max_size=16, api_open=False).launch(
+        theme=_theme(),
+        css=CSS,
+        head=HEAD,
+        footer_links=[],
+        mcp_server=False,
+        show_error=True,
+    )

pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "socialdynamics-lab"
+version = "1.0.0"
+description = "Interactive multi-agent opinion dynamics and misinformation simulator."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+  { name = "Anouar Imel" }
+]
+dependencies = [
+  "gradio>=6.5,<7",
+  "numpy>=2.0,<3",
+  "networkx>=3.4,<4",
+  "plotly>=6.0,<7"
+]
+
+[project.urls]
+Space = "https://huggingface.co/spaces/imvirus/SocialDynamics_Lab"
+Source = "https://huggingface.co/spaces/imvirus/SocialDynamics_Lab/tree/main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

requirements.txt

@@ -0,0 +1,4 @@
+gradio>=6.5,<7
+numpy>=2.0,<3
+networkx>=3.4,<4
+plotly>=6.0,<7

src/socialdynamics/__init__.py

@@ -0,0 +1,6 @@
+"""Core package for SocialDynamics Lab."""
+
+from .simulation import OpinionSimulation, SimulationConfig
+
+__version__ = "1.1.0"
+__all__ = ["OpinionSimulation", "SimulationConfig"]

src/socialdynamics/metrics.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import networkx as nx
+import numpy as np
+
+
+def polarization(opinions: np.ndarray) -> float:
+    """Return bounded opinion variance."""
+    if opinions.size == 0:
+        return 0.0
+    value = float(np.var(opinions))
+    if abs(value) < 1e-15:
+        return 0.0
+    return float(np.clip(value, 0.0, 1.0))
+
+
+def consensus(opinions: np.ndarray) -> float:
+    """Return one minus population standard deviation."""
+    if opinions.size == 0:
+        return 0.0
+    std = float(np.std(opinions))
+    if abs(std) < 1e-15:
+        return 1.0
+    return float(np.clip(1.0 - std, 0.0, 1.0))
+
+
+def echo_chamber_index(
+    graph: nx.Graph, opinions: np.ndarray, confirmation_bias: float = 0.0
+) -> float:
+    """Measure selective interaction filtering induced by opinion-distance weighting."""
+    if graph.number_of_edges() == 0 or opinions.size < 2:
+        return 0.0
+
+    differences = np.fromiter(
+        (abs(float(opinions[u]) - float(opinions[v])) for u, v in graph.edges()),
+        dtype=float,
+        count=graph.number_of_edges(),
+    )
+    raw_disagreement = float(np.mean(differences))
+    if raw_disagreement < 1e-12:
+        return 0.0
+
+    beta = 6.0 * float(np.clip(confirmation_bias, 0.0, 1.0))
+    if beta <= 0.0:
+        return 0.0
+    weights = np.exp(-beta * differences)
+    denominator = float(np.sum(weights))
+    if denominator < 1e-12:
+        return 1.0
+    effective_disagreement = float(np.sum(weights * differences) / denominator)
+    score = 1.0 - (effective_disagreement / raw_disagreement)
+    return float(np.clip(score, 0.0, 1.0))
+
+
+def summarize_metrics(
+    graph: nx.Graph, opinions: np.ndarray, confirmation_bias: float = 0.0
+) -> dict[str, float]:
+    return {
+        "mean_opinion": float(np.mean(opinions)) if opinions.size else 0.0,
+        "polarization": polarization(opinions),
+        "consensus": consensus(opinions),
+        "echo_chamber": echo_chamber_index(graph, opinions, confirmation_bias),
+    }

src/socialdynamics/networks.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import random
+
+import networkx as nx
+
+
+NETWORK_ALIASES = {
+    "Random": "random",
+    "Small World": "small_world",
+    "Scale Free": "scale_free",
+}
+
+
+def build_network(kind: str, n_agents: int, seed: int, average_degree: int = 8) -> nx.Graph:
+    """Build a sparse undirected graph with comparable mean degree across families."""
+    if n_agents < 2:
+        raise ValueError("n_agents must be at least 2")
+
+    normalized = NETWORK_ALIASES.get(kind, kind).lower().replace("-", "_").replace(" ", "_")
+    degree = max(2, min(int(average_degree), n_agents - 1))
+
+    if normalized == "random":
+        probability = min(1.0, degree / max(1, n_agents - 1))
+        graph = nx.erdos_renyi_graph(n_agents, probability, seed=seed)
+    elif normalized == "small_world":
+        if degree % 2:
+            degree -= 1
+        degree = max(2, min(degree, n_agents - 1 - ((n_agents - 1) % 2)))
+        graph = nx.watts_strogatz_graph(n_agents, degree, 0.12, seed=seed)
+    elif normalized == "scale_free":
+        attachment = max(1, min(degree // 2, n_agents - 1))
+        graph = nx.barabasi_albert_graph(n_agents, attachment, seed=seed)
+    else:
+        raise ValueError(f"Unknown network kind: {kind}")
+
+    isolates = list(nx.isolates(graph))
+    if isolates:
+        rng = random.Random(seed + 991)
+        nodes = list(graph.nodes())
+        for node in isolates:
+            choices = [candidate for candidate in nodes if candidate != node]
+            graph.add_edge(node, rng.choice(choices))
+
+    return graph

src/socialdynamics/presets.py

@@ -0,0 +1,54 @@
+PRESETS = {
+    "Healthy Discussion": {
+        "network": "Random",
+        "initial_opinion": "Random",
+        "stubborn_fraction": 0.00,
+        "stubborn_mode": "Keep initial",
+        "misinformation_exposure": 0.00,
+        "misinformation_strength": 0.00,
+        "misinformation_direction": "Positive (+1)",
+        "confirmation_bias": 0.10,
+        "social_influence": 0.55,
+        "noise": 0.02,
+        "steps": 120,
+    },
+    "Echo Chamber": {
+        "network": "Small World",
+        "initial_opinion": "Polarized",
+        "stubborn_fraction": 0.04,
+        "stubborn_mode": "Split extremes",
+        "misinformation_exposure": 0.00,
+        "misinformation_strength": 0.00,
+        "misinformation_direction": "Positive (+1)",
+        "confirmation_bias": 0.85,
+        "social_influence": 0.42,
+        "noise": 0.01,
+        "steps": 160,
+    },
+    "Misinformation Cascade": {
+        "network": "Scale Free",
+        "initial_opinion": "Neutral",
+        "stubborn_fraction": 0.03,
+        "stubborn_mode": "Keep initial",
+        "misinformation_exposure": 0.45,
+        "misinformation_strength": 0.72,
+        "misinformation_direction": "Positive (+1)",
+        "confirmation_bias": 0.42,
+        "social_influence": 0.48,
+        "noise": 0.02,
+        "steps": 150,
+    },
+    "Stubborn Minority": {
+        "network": "Small World",
+        "initial_opinion": "Neutral",
+        "stubborn_fraction": 0.10,
+        "stubborn_mode": "Positive (+1)",
+        "misinformation_exposure": 0.00,
+        "misinformation_strength": 0.00,
+        "misinformation_direction": "Positive (+1)",
+        "confirmation_bias": 0.28,
+        "social_influence": 0.50,
+        "noise": 0.015,
+        "steps": 150,
+    },
+}

src/socialdynamics/simulation.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterator
+
+import networkx as nx
+import numpy as np
+
+from .metrics import summarize_metrics
+from .networks import build_network
+
+
+@dataclass(frozen=True)
+class SimulationConfig:
+    n_agents: int = 100
+    network: str = "Small World"
+    initial_opinion: str = "Random"
+    stubborn_fraction: float = 0.05
+    stubborn_mode: str = "Split extremes"
+    misinformation_exposure: float = 0.25
+    misinformation_strength: float = 0.35
+    misinformation_direction: float = 1.0
+    confirmation_bias: float = 0.45
+    social_influence: float = 0.45
+    noise: float = 0.02
+    steps: int = 120
+    seed: int = 42
+    average_degree: int = 8
+
+
+class OpinionSimulation:
+    """Synchronous continuous-opinion simulation on a fixed social graph."""
+
+    def __init__(self, config: SimulationConfig):
+        self.config = config
+        self._validate()
+        self.rng = np.random.default_rng(config.seed)
+        self.graph: nx.Graph = build_network(
+            config.network, config.n_agents, config.seed, config.average_degree
+        )
+        self.opinions = self._initialize_opinions()
+        self.initial_opinions = self.opinions.copy()
+        self.stubborn_mask = self._choose_mask(config.stubborn_fraction)
+        self._apply_stubborn_mode()
+        self.initial_opinions = self.opinions.copy()
+        self.misinformation_mask = self._choose_mask(config.misinformation_exposure, ~self.stubborn_mask)
+        self.history: list[np.ndarray] = [self.opinions.copy()]
+        self.metric_history: list[dict[str, float]] = [self.metrics(step=0)]
+
+    def _validate(self) -> None:
+        config = self.config
+        if config.n_agents not in (100, 500, 1000):
+            raise ValueError("n_agents must be one of 100, 500, or 1000")
+        for name in (
+            "stubborn_fraction",
+            "misinformation_exposure",
+            "misinformation_strength",
+            "confirmation_bias",
+            "social_influence",
+        ):
+            value = float(getattr(config, name))
+            if not 0.0 <= value <= 1.0:
+                raise ValueError(f"{name} must be in [0, 1]")
+        if not 0.0 <= config.noise <= 0.2:
+            raise ValueError("noise must be in [0, 0.2]")
+        if config.steps < 1:
+            raise ValueError("steps must be >= 1")
+        if config.misinformation_direction not in (-1.0, 1.0):
+            raise ValueError("misinformation_direction must be -1 or +1")
+
+    def _initialize_opinions(self) -> np.ndarray:
+        mode = self.config.initial_opinion.lower()
+        n_agents = self.config.n_agents
+        if mode == "random":
+            values = self.rng.uniform(-1.0, 1.0, size=n_agents)
+        elif mode == "neutral":
+            values = self.rng.normal(0.0, 0.16, size=n_agents)
+        elif mode == "polarized":
+            signs = self.rng.choice([-1.0, 1.0], size=n_agents)
+            values = signs * self.rng.normal(0.72, 0.13, size=n_agents)
+        else:
+            raise ValueError(f"Unknown initial opinion mode: {self.config.initial_opinion}")
+        return np.clip(values, -1.0, 1.0).astype(np.float64)
+
+    def _choose_mask(self, fraction: float, eligible: np.ndarray | None = None) -> np.ndarray:
+        n_agents = self.config.n_agents
+        mask = np.zeros(n_agents, dtype=bool)
+        if fraction <= 0:
+            return mask
+        candidates = np.arange(n_agents) if eligible is None else np.flatnonzero(eligible)
+        count = min(len(candidates), int(round(fraction * n_agents)))
+        if count > 0:
+            picked = self.rng.choice(candidates, size=count, replace=False)
+            mask[picked] = True
+        return mask
+
+    def _apply_stubborn_mode(self) -> None:
+        indices = np.flatnonzero(self.stubborn_mask)
+        if indices.size == 0:
+            return
+        mode = self.config.stubborn_mode.lower()
+        if mode == "keep initial":
+            return
+        if mode == "positive (+1)":
+            self.opinions[indices] = 1.0
+        elif mode == "negative (-1)":
+            self.opinions[indices] = -1.0
+        elif mode == "split extremes":
+            shuffled = self.rng.permutation(indices)
+            split = len(shuffled) // 2
+            self.opinions[shuffled[:split]] = -1.0
+            self.opinions[shuffled[split:]] = 1.0
+        else:
+            raise ValueError(f"Unknown stubborn mode: {self.config.stubborn_mode}")
+
+    def metrics(self, step: int | None = None) -> dict[str, float]:
+        values = summarize_metrics(self.graph, self.opinions, self.config.confirmation_bias)
+        values["step"] = float(len(self.history) - 1 if step is None else step)
+        return values
+
+    def step(self) -> np.ndarray:
+        old = self.opinions
+        new = old.copy()
+        beta = 6.0 * self.config.confirmation_bias
+        alpha = self.config.social_influence
+        misinformation_strength = self.config.misinformation_strength
+        misinformation_direction = self.config.misinformation_direction
+
+        for agent in range(self.config.n_agents):
+            if self.stubborn_mask[agent]:
+                continue
+            neighbors = list(self.graph.neighbors(agent))
+            if neighbors:
+                neighbor_opinions = old[neighbors]
+                distances = np.abs(old[agent] - neighbor_opinions)
+                weights = np.exp(-beta * distances)
+                total = float(np.sum(weights))
+                social_target = (
+                    float(np.sum(weights * neighbor_opinions) / total)
+                    if total > 1e-12
+                    else float(old[agent])
+                )
+            else:
+                social_target = float(old[agent])
+
+            delta = alpha * (social_target - old[agent])
+            if self.misinformation_mask[agent] and misinformation_strength > 0:
+                delta += 0.22 * misinformation_strength * (misinformation_direction - old[agent])
+            if self.config.noise > 0:
+                delta += float(self.rng.normal(0.0, self.config.noise))
+            new[agent] = float(np.clip(old[agent] + delta, -1.0, 1.0))
+
+        self.opinions = new
+        self.history.append(new.copy())
+        self.metric_history.append(self.metrics(step=len(self.history) - 1))
+        return new
+
+    def run(self, steps: int | None = None) -> np.ndarray:
+        for _ in range(self.config.steps if steps is None else steps):
+            self.step()
+        return self.opinions.copy()
+
+    def stream(self, update_every: int = 5) -> Iterator[int]:
+        update_every = max(1, int(update_every))
+        for step in range(1, self.config.steps + 1):
+            self.step()
+            if step % update_every == 0 or step == self.config.steps:
+                yield step
+
+    @property
+    def history_array(self) -> np.ndarray:
+        return np.vstack(self.history)

src/socialdynamics/visualization.py

@@ -0,0 +1,339 @@
+from __future__ import annotations
+
+import math
+
+import networkx as nx
+import numpy as np
+import plotly.graph_objects as go
+
+from .simulation import OpinionSimulation
+
+# ── Editorial "lab notebook" palette ────────────────────────────────────────
+PAPER = "#FBF9F4"
+PAPER_2 = "#F4F1E9"
+INK = "#1B1A17"
+INK_2 = "#3F3B34"
+MUTED = "#6B665C"
+RULE = "rgba(27,26,23,0.22)"
+GRID = "rgba(27,26,23,0.07)"
+BLUE = "#2B59C3"
+VERMILION = "#D2462C"
+OCHRE = "#B7811F"
+GREEN = "#2F7D5B"
+PLUM = "#6E4AA8"
+
+# Backwards-compatible aliases used by earlier versions of app.py
+TEXT = INK
+CYAN = BLUE
+ROSE = VERMILION
+EMERALD = GREEN
+VIOLET = PLUM
+AMBER = OCHRE
+
+SANS = "IBM Plex Sans, ui-sans-serif, system-ui, sans-serif"
+MONO = "IBM Plex Mono, ui-monospace, SFMono-Regular, Menlo, monospace"
+SERIF = "Newsreader, Georgia, 'Times New Roman', serif"
+
+OPINION_SCALE = [
+    [0.0, "#1F3F8F"],
+    [0.25, "#5B83D6"],
+    [0.5, "#DCD6C8"],
+    [0.75, "#E8876F"],
+    [1.0, "#B8321C"],
+]
+
+
+def _hex_to_rgb(value: str) -> tuple[int, int, int]:
+    value = value.lstrip("#")
+    return int(value[0:2], 16), int(value[2:4], 16), int(value[4:6], 16)
+
+
+def opinion_color(x: float) -> str:
+    """Map an opinion in [-1, 1] to the diverging opinion scale."""
+    t = (float(np.clip(x, -1.0, 1.0)) + 1.0) / 2.0
+    for (t0, c0), (t1, c1) in zip(OPINION_SCALE[:-1], OPINION_SCALE[1:]):
+        if t <= t1:
+            f = 0.0 if t1 == t0 else (t - t0) / (t1 - t0)
+            a, b = _hex_to_rgb(c0), _hex_to_rgb(c1)
+            r, g, bl = (round(a[k] + (b[k] - a[k]) * f) for k in range(3))
+            return f"#{r:02x}{g:02x}{bl:02x}"
+    return OPINION_SCALE[-1][1]
+
+
+def _hub_radial_layout(graph: nx.Graph, seed: int) -> dict[int, np.ndarray]:
+    nodes = list(graph.nodes())
+    if not nodes:
+        return {}
+    if len(nodes) == 1:
+        return {nodes[0]: np.array([0.0, 0.0], dtype=float)}
+
+    degrees = dict(graph.degree())
+    hub = max(nodes, key=lambda n: (degrees[n], -int(n) if isinstance(n, int) else 0))
+    distances = nx.single_source_shortest_path_length(graph, hub)
+    max_known = max(distances.values(), default=1)
+
+    rings: dict[int, list[int]] = {}
+    for node in nodes:
+        rings.setdefault(int(distances.get(node, max_known + 1)), []).append(node)
+
+    rng = np.random.default_rng(seed + 1701)
+    pos: dict[int, np.ndarray] = {}
+    max_ring = max(rings) if rings else 1
+
+    for ring, ring_nodes in sorted(rings.items()):
+        ring_nodes = sorted(ring_nodes, key=lambda n: (-degrees[n], n))
+        count = len(ring_nodes)
+        phase = float(rng.uniform(0.0, 2.0 * math.pi))
+        if ring == 0:
+            pos[ring_nodes[0]] = np.array([0.0, 0.0], dtype=float)
+            continue
+        radius = 0.18 + 0.82 * (ring / max(1, max_ring))
+        for idx, node in enumerate(ring_nodes):
+            angle = phase + (2.0 * math.pi * idx / max(1, count))
+            r = max(0.06, radius + float(rng.uniform(-0.025, 0.025)))
+            pos[node] = np.array([1.08 * r * math.cos(angle), r * math.sin(angle)], dtype=float)
+    return pos
+
+
+def _layout(graph: nx.Graph, seed: int) -> dict[int, np.ndarray]:
+    if graph.number_of_nodes() <= 250:
+        return nx.spring_layout(graph, seed=seed, iterations=42, threshold=1e-4)
+    return _hub_radial_layout(graph, seed)
+
+
+def base_layout(title: str, subtitle: str | None = None, height: int = 520) -> dict:
+    """Shared Plotly layout: paper ground, serif titles, mono ticks, hairline rules."""
+    title_text = title if not subtitle else (
+        f"{title}<br><span style='font-family:{MONO};font-size:10.5px;color:{MUTED};letter-spacing:.06em'>"
+        f"{subtitle.upper()}</span>"
+    )
+    return dict(
+        title=dict(text=title_text, x=0.012, xanchor="left", y=0.965, yanchor="top", font=dict(family=SERIF, size=21, color=INK)),
+        template="plotly_white",
+        paper_bgcolor="rgba(0,0,0,0)",
+        plot_bgcolor="rgba(0,0,0,0)",
+        font=dict(family=SANS, color=INK_2, size=12),
+        height=height,
+        margin=dict(l=60, r=28, t=92, b=56),
+        hoverlabel=dict(bgcolor=INK, bordercolor=INK, font=dict(family=MONO, size=11, color=PAPER)),
+        legend=dict(
+            orientation="h", yanchor="bottom", y=1.015, x=1, xanchor="right",
+            bgcolor="rgba(0,0,0,0)", font=dict(family=MONO, size=10.5, color=INK_2),
+        ),
+    )
+
+
+# Kept for compatibility with callers that imported the private name.
+_base_layout = base_layout
+
+
+def style_axes(fig: go.Figure, xtitle: str, ytitle: str, yrange=None, xrange=None, ytickformat=None) -> go.Figure:
+    common = dict(
+        gridcolor=GRID, zeroline=False, showline=True, linecolor=RULE, linewidth=1,
+        ticks="outside", tickcolor=RULE, ticklen=4, color=MUTED,
+        tickfont=dict(family=MONO, size=10, color=MUTED),
+    )
+    fig.update_xaxes(title=dict(text=xtitle, font=dict(size=11.5, color=INK_2)), range=xrange, **common)
+    fig.update_yaxes(title=dict(text=ytitle, font=dict(size=11.5, color=INK_2)), range=yrange, tickformat=ytickformat, **common)
+    return fig
+
+
+def network_figure(sim: OpinionSimulation, max_edges: int = 2600) -> go.Figure:
+    graph = sim.graph
+    if sim.config.n_agents >= 1000:
+        max_edges = min(max_edges, 900)
+    elif sim.config.n_agents >= 500:
+        max_edges = min(max_edges, 1400)
+
+    pos = getattr(sim, "_layout_cache", None)
+    if pos is None:
+        pos = _layout(graph, sim.config.seed)
+        sim._layout_cache = pos
+
+    edges = list(graph.edges())
+    if len(edges) > max_edges:
+        rng = np.random.default_rng(sim.config.seed + 73)
+        chosen = rng.choice(len(edges), size=max_edges, replace=False)
+        edges = [edges[int(i)] for i in chosen]
+
+    edge_x: list[float | None] = []
+    edge_y: list[float | None] = []
+    for u, v in edges:
+        x0, y0 = pos[u]
+        x1, y1 = pos[v]
+        edge_x.extend((float(x0), float(x1), None))
+        edge_y.extend((float(y0), float(y1), None))
+
+    edge_alpha = 0.16 if sim.config.n_agents <= 100 else 0.09
+    edge_trace = go.Scattergl(
+        x=edge_x, y=edge_y, mode="lines",
+        line=dict(width=0.6, color=f"rgba(27,26,23,{edge_alpha})"),
+        hoverinfo="skip", name="ties",
+    )
+
+    nodes = list(graph.nodes())
+    opinions = sim.opinions[nodes]
+    base_size = 9.0 if sim.config.n_agents <= 100 else 5.6 if sim.config.n_agents <= 500 else 4.6
+    stub = np.array([bool(sim.stubborn_mask[i]) for i in nodes])
+    exposed = np.array([bool(sim.misinformation_mask[i]) for i in nodes])
+    marker_sizes = np.where(stub, base_size + 4.5, base_size)
+    marker_symbols = np.where(stub, "diamond", "circle")
+    line_colors = np.where(exposed, OCHRE, np.where(stub, INK, "rgba(251,249,244,0.95)"))
+    line_widths = np.where(exposed, 1.8, np.where(stub, 1.1, 0.7))
+
+    hover = []
+    for i in nodes:
+        tags = []
+        if sim.stubborn_mask[i]:
+            tags.append("stubborn")
+        if sim.misinformation_mask[i]:
+            tags.append("exposed")
+        role = " · ".join(tags) if tags else "ordinary"
+        hover.append(f"<b>agent {i}</b><br>opinion  {sim.opinions[i]:+.3f}<br>degree   {graph.degree(i)}<br>role     {role}")
+
+    node_trace = go.Scattergl(
+        x=[float(pos[i][0]) for i in nodes],
+        y=[float(pos[i][1]) for i in nodes],
+        mode="markers", hovertext=hover, hoverinfo="text", name="agents",
+        marker=dict(
+            size=marker_sizes, symbol=marker_symbols, color=opinions,
+            colorscale=OPINION_SCALE, cmin=-1, cmax=1, showscale=True,
+            colorbar=dict(
+                title=dict(text="OPINION", font=dict(family=MONO, color=MUTED, size=10), side="top"),
+                thickness=8, len=0.46, y=0.5, x=1.0, xpad=6,
+                tickvals=[-1, -0.5, 0, 0.5, 1], ticktext=["−1", "−.5", "0", "+.5", "+1"],
+                tickfont=dict(family=MONO, color=MUTED, size=10), outlinewidth=0, ticks="",
+            ),
+            line=dict(width=line_widths, color=line_colors),
+        ),
+    )
+
+    total_edges = graph.number_of_edges()
+    shown_edges = len(edges)
+    caption = f"{sim.config.n_agents:,} AGENTS · {total_edges:,} TIES" + (f" · {shown_edges:,} DRAWN" if shown_edges < total_edges else "")
+    fig = go.Figure(data=[edge_trace, node_trace])
+    fig.update_layout(**base_layout("Network state", f"{sim.config.network} topology", height=620))
+    fig.update_layout(
+        margin=dict(l=14, r=18, t=92, b=18),
+        showlegend=False,
+        xaxis=dict(visible=False, fixedrange=True),
+        yaxis=dict(visible=False, fixedrange=True, scaleanchor="x", scaleratio=1),
+        uirevision="network",
+        annotations=[
+            dict(
+                text=caption, x=1.0, y=1.085, xref="paper", yref="paper", showarrow=False,
+                xanchor="right", yanchor="top", font=dict(family=MONO, size=10.5, color=INK_2),
+            )
+        ],
+    )
+    return fig
+
+
+def evolution_figure(sim: OpinionSimulation) -> go.Figure:
+    history = sim.history_array
+    steps = np.arange(history.shape[0])
+    mean = history.mean(axis=1)
+    p10 = np.quantile(history, 0.10, axis=1)
+    p25 = np.quantile(history, 0.25, axis=1)
+    p75 = np.quantile(history, 0.75, axis=1)
+    p90 = np.quantile(history, 0.90, axis=1)
+
+    # A deterministic sample of individual trajectories, coloured by current sign.
+    rng = np.random.default_rng(sim.config.seed + 5)
+    sample = rng.choice(history.shape[1], size=min(36, history.shape[1]), replace=False)
+    fig = go.Figure()
+    for sign, color, name in ((1, "rgba(210,70,44,0.26)", "agents ending +"), (-1, "rgba(43,89,195,0.26)", "agents ending −")):
+        xs: list[float | None] = []
+        ys: list[float | None] = []
+        for idx in sample:
+            if (history[-1, idx] >= 0) == (sign > 0):
+                xs.extend(steps.tolist() + [None])
+                ys.extend(history[:, idx].tolist() + [None])
+        fig.add_trace(go.Scatter(x=xs, y=ys, mode="lines", line=dict(width=0.8, color=color), name=name, hoverinfo="skip", showlegend=False))
+
+    fig.add_trace(go.Scatter(x=steps, y=p90, mode="lines", line=dict(width=0), showlegend=False, hoverinfo="skip"))
+    fig.add_trace(go.Scatter(x=steps, y=p10, mode="lines", fill="tonexty", fillcolor="rgba(27,26,23,0.06)", line=dict(width=0), name="10–90%", hovertemplate="10–90% band<extra></extra>"))
+    fig.add_trace(go.Scatter(x=steps, y=p75, mode="lines", line=dict(width=0), showlegend=False, hoverinfo="skip"))
+    fig.add_trace(go.Scatter(x=steps, y=p25, mode="lines", fill="tonexty", fillcolor="rgba(27,26,23,0.11)", line=dict(width=0), name="25–75%", hovertemplate="25–75% band<extra></extra>"))
+    fig.add_trace(go.Scatter(x=steps, y=mean, mode="lines", line=dict(width=2.4, color=INK), name="mean", hovertemplate="step %{x}<br>mean %{y:+.3f}<extra></extra>"))
+    fig.add_hline(y=0, line_width=1, line_dash="dot", line_color=RULE)
+    fig.update_layout(**base_layout("Opinion evolution", "Mean, quantile bands, and 36 sampled agents", height=540))
+    style_axes(fig, "Simulation step", "Opinion", yrange=[-1.05, 1.05])
+    return fig
+
+
+def metric_figure(sim: OpinionSimulation) -> go.Figure:
+    steps = [int(m["step"]) for m in sim.metric_history]
+    fig = go.Figure()
+    for key, label, color, dash in (
+        ("polarization", "polarization", VERMILION, "solid"),
+        ("consensus", "consensus", GREEN, "solid"),
+        ("echo_chamber", "echo-chamber index", PLUM, "solid"),
+    ):
+        fig.add_trace(go.Scatter(
+            x=steps, y=[m[key] for m in sim.metric_history], mode="lines", name=label,
+            line=dict(width=2.2, color=color, dash=dash),
+            hovertemplate=f"step %{{x}}<br>{label} %{{y:.3f}}<extra></extra>",
+        ))
+    fig.update_layout(**base_layout("Collective diagnostics", "Macro-level scores through time", height=540))
+    style_axes(fig, "Simulation step", "Score", yrange=[0, 1.02])
+    return fig
+
+
+def distribution_figure(sim: OpinionSimulation) -> go.Figure:
+    edges = np.linspace(-1, 1, 31)
+    centers = (edges[:-1] + edges[1:]) / 2.0
+    width = float(edges[1] - edges[0])
+    n = max(1, sim.opinions.size)
+    current, _ = np.histogram(sim.opinions, bins=edges)
+    initial, _ = np.histogram(sim.initial_opinions, bins=edges)
+    current = current / n
+    initial = initial / n
+
+    fig = go.Figure()
+    fig.add_vrect(x0=-0.2, x1=0.2, fillcolor="rgba(27,26,23,0.045)", line_width=0, layer="below")
+    fig.add_trace(go.Bar(
+        x=centers, y=current, width=width * 0.84, name="current",
+        marker=dict(color=[opinion_color(c) for c in centers], line=dict(width=0)),
+        hovertemplate="opinion %{x:+.2f}<br>share %{y:.1%}<extra>current</extra>",
+    ))
+    fig.add_trace(go.Scatter(
+        x=edges, y=np.r_[initial, initial[-1]], mode="lines", line=dict(shape="hv", width=1.4, color=INK),
+        name="initial", hoverinfo="skip",
+    ))
+    fig.update_layout(**base_layout("Opinion distribution", "Current shares (bars) against the initial state (line)", height=540))
+    fig.update_layout(bargap=0)
+    style_axes(fig, "Opinion", "Population share", xrange=[-1.02, 1.02], ytickformat=".0%")
+    return fig
+
+
+def influence_figure(sim: OpinionSimulation) -> go.Figure:
+    nodes = np.array(list(sim.graph.nodes()), dtype=int)
+    degrees = np.array([sim.graph.degree(int(i)) for i in nodes], dtype=float)
+    opinions = sim.opinions[nodes]
+    stub = sim.stubborn_mask[nodes]
+    exposure = sim.misinformation_mask[nodes]
+    sizes = np.where(stub, 12.0, 7.5)
+    symbols = np.where(stub, "diamond", "circle")
+    jitter = np.random.default_rng(sim.config.seed + 11).uniform(-0.22, 0.22, size=degrees.size)
+
+    hover = [
+        f"<b>agent {int(i)}</b><br>degree   {int(d)}<br>opinion  {o:+.3f}<br>stubborn {'yes' if s else 'no'}<br>exposed  {'yes' if e else 'no'}"
+        for i, d, o, s, e in zip(nodes, degrees, opinions, stub, exposure)
+    ]
+
+    fig = go.Figure(
+        go.Scattergl(
+            x=degrees + jitter, y=opinions, mode="markers", hovertext=hover, hoverinfo="text", name="agents",
+            marker=dict(
+                size=sizes, symbol=symbols, color=opinions, colorscale=OPINION_SCALE, cmin=-1, cmax=1,
+                opacity=np.where(exposure, 1.0, 0.78),
+                line=dict(width=np.where(exposure, 1.6, 0.5), color=np.where(exposure, OCHRE, np.where(stub, INK, "rgba(251,249,244,0.9)"))),
+                showscale=False,
+            ),
+        )
+    )
+    fig.add_hline(y=0, line_width=1, line_dash="dot", line_color=RULE)
+    fig.update_layout(**base_layout("Influence map", "Connectivity against current opinion · ochre ring = exposed", height=540))
+    style_axes(fig, "Node degree", "Opinion", yrange=[-1.05, 1.05])
+    return fig

tests/conftest.py

@@ -0,0 +1,6 @@
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src"
+sys.path.insert(0, str(SRC))

tests/test_large_visualization.py

@@ -0,0 +1,22 @@
+from unittest.mock import patch
+
+from socialdynamics.simulation import OpinionSimulation, SimulationConfig
+from socialdynamics.visualization import influence_figure, network_figure
+
+
+def test_large_network_visualization_avoids_spring_layout():
+    for n_agents in (500, 1000):
+        sim = OpinionSimulation(SimulationConfig(n_agents=n_agents, steps=1, seed=11))
+        with patch("networkx.spring_layout", side_effect=AssertionError("spring_layout called")):
+            fig = network_figure(sim)
+        assert len(fig.data) == 2
+        assert len(sim._layout_cache) == n_agents
+
+
+def test_influence_map_supports_all_population_sizes():
+    for n_agents in (100, 500, 1000):
+        sim = OpinionSimulation(SimulationConfig(n_agents=n_agents, steps=2, seed=7))
+        sim.run()
+        fig = influence_figure(sim)
+        assert len(fig.data) == 1
+        assert len(fig.data[0].x) == n_agents

tests/test_metrics.py

@@ -0,0 +1,24 @@
+import networkx as nx
+import numpy as np
+
+from socialdynamics.metrics import consensus, echo_chamber_index, polarization
+
+
+def test_consensus_population_scores_as_expected():
+    x = np.ones(100) * 0.4
+    assert polarization(x) == 0.0
+    assert consensus(x) == 1.0
+
+
+def test_split_extremes_are_highly_polarized():
+    x = np.array([-1.0] * 50 + [1.0] * 50)
+    assert polarization(x) == 1.0
+    assert consensus(x) == 0.0
+
+
+def test_echo_metric_detects_assortative_edges():
+    g = nx.Graph()
+    g.add_edges_from([(0, 1), (2, 3), (0, 2)])
+    x = np.array([-1.0, -0.9, 0.9, 1.0])
+    assert echo_chamber_index(g, x, 0.0) == 0.0
+    assert echo_chamber_index(g, x, 0.9) > 0.2

tests/test_networks.py

@@ -0,0 +1,18 @@
+import networkx as nx
+
+from socialdynamics.networks import build_network
+
+
+def test_all_networks_have_expected_nodes_and_edges():
+    for kind in ("Random", "Small World", "Scale Free"):
+        g = build_network(kind, 100, seed=7)
+        assert isinstance(g, nx.Graph)
+        assert g.number_of_nodes() == 100
+        assert g.number_of_edges() > 0
+        assert not list(nx.isolates(g))
+
+
+def test_network_generation_is_deterministic():
+    g1 = build_network("Small World", 100, seed=9)
+    g2 = build_network("Small World", 100, seed=9)
+    assert set(g1.edges()) == set(g2.edges())

tests/test_simulation.py

@@ -0,0 +1,64 @@
+import numpy as np
+
+from socialdynamics.simulation import OpinionSimulation, SimulationConfig
+
+
+def test_simulation_is_seed_deterministic():
+    cfg = SimulationConfig(n_agents=100, steps=20, seed=123)
+    a = OpinionSimulation(cfg)
+    b = OpinionSimulation(cfg)
+    a.run()
+    b.run()
+    assert np.array_equal(a.history_array, b.history_array)
+
+
+def test_opinions_stay_bounded():
+    cfg = SimulationConfig(
+        n_agents=100,
+        steps=50,
+        seed=3,
+        misinformation_exposure=1.0,
+        misinformation_strength=1.0,
+        social_influence=1.0,
+        noise=0.2,
+    )
+    sim = OpinionSimulation(cfg)
+    sim.run()
+    assert np.all(sim.history_array >= -1.0)
+    assert np.all(sim.history_array <= 1.0)
+
+
+def test_stubborn_agents_never_move():
+    cfg = SimulationConfig(
+        n_agents=100,
+        steps=30,
+        seed=4,
+        stubborn_fraction=0.20,
+        stubborn_mode="Split extremes",
+        misinformation_exposure=0.50,
+        misinformation_strength=0.8,
+    )
+    sim = OpinionSimulation(cfg)
+    initial = sim.opinions.copy()
+    mask = sim.stubborn_mask.copy()
+    sim.run()
+    assert np.array_equal(sim.opinions[mask], initial[mask])
+
+
+def test_misinformation_can_shift_mean_positive():
+    base = dict(
+        n_agents=100,
+        network="Random",
+        initial_opinion="Neutral",
+        stubborn_fraction=0.0,
+        confirmation_bias=0.2,
+        social_influence=0.4,
+        noise=0.0,
+        steps=30,
+        seed=11,
+    )
+    control = OpinionSimulation(SimulationConfig(**base, misinformation_exposure=0.0, misinformation_strength=0.0))
+    treatment = OpinionSimulation(SimulationConfig(**base, misinformation_exposure=1.0, misinformation_strength=0.8, misinformation_direction=1.0))
+    control.run()
+    treatment.run()
+    assert treatment.opinions.mean() > control.opinions.mean() + 0.1