--- title: SocialDynamics Lab emoji: 🌍 colorFrom: pink colorTo: indigo sdk: gradio sdk_version: 6.28.0 python_version: '3.12' app_file: app.py pinned: true license: mit short_description: Interactive multi-agent opinion dynamics simulator thumbnail: >- https://cdn-uploads.huggingface.co/production/uploads/656a180aadba74cd5ef69893/HcfF09F5S4rgtuI1GjYSe.png --- # SocialDynamics Lab **Interactive opinion dynamics across network structure, confirmation bias, committed minorities, and directional misinformation.** SocialDynamics Lab is a reproducible multi-agent simulator for exploring how simple local interaction rules can generate different population-level outcomes. It is designed for research prototyping, classroom demonstrations, and portfolio use rather than as a calibrated model of any real community. **Live Space:** https://huggingface.co/spaces/imvirus/SocialDynamics_Lab ## What you can explore Choose **100, 500, or 1,000 agents**, select a **Random**, **Small World**, or **Scale Free** graph, then vary: - initial opinion distribution - confirmation bias - social-influence strength - stubborn-agent fraction and stance - misinformation exposure and direction - stochastic noise - simulation horizon - random seed The dashboard includes: - interactive network state - opinion trajectories with population quantile bands - polarization, consensus, and echo-chamber diagnostics - initial-versus-current opinion distributions - degree-versus-opinion influence map - population composition summary - deterministic end-state interpretation - one-click mechanism presets - controlled comparison across network families ## Scenario presets | Preset | Purpose | |---|---| | **Healthy Discussion** | Low confirmation bias and no misinformation | | **Echo Chamber** | Polarized initialization with strong cross-opinion attenuation | | **Misinformation Cascade** | Directional exposure on a scale-free network | | **Stubborn Minority** | A committed minority remains fixed while other agents adapt | Presets are illustrative experimental configurations. They are not empirical claims about real populations. ## Model Each agent has a scalar opinion \[ x_i(t) \in [-1,1]. \] For a non-stubborn agent, neighbor influence is weighted by opinion distance: \[ w_{ij}(t)=\exp\{-\beta |x_i(t)-x_j(t)|\}, \] where the interface maps the confirmation-bias control to \(\beta \in [0,6]\). The weighted neighborhood target is \[ S_i(t)=\frac{\sum_{j\in N(i)} w_{ij}(t)x_j(t)}{\sum_{j\in N(i)} w_{ij}(t)}. \] The synchronous update is \[ x_i(t+1)=\operatorname{clip}_{[-1,1]}\left[x_i(t)+\alpha(S_i(t)-x_i(t))+M_i(t)+\epsilon_i(t)\right]. \] Here, \(\alpha\) is the social-influence strength, \(M_i(t)\) is the optional external directional signal, and \(\epsilon_i(t)\) is Gaussian noise. Stubborn agents retain their assigned opinions exactly. This is a custom smooth distance-weighted model inspired by classical consensus and bounded-confidence traditions; it is not an implementation of DeGroot or Hegselmann–Krause verbatim. ## Diagnostics **Polarization** \[ P(t)=\operatorname{Var}(x(t)). \] Because opinions are bounded in \([-1,1]\), the variance lies in \([0,1]\). **Consensus** \[ C(t)=1-\operatorname{Std}(x(t)), \] clipped to \([0,1]\). **Echo-chamber index** The simulator compares mean opinion disagreement on graph edges before and after applying the same confirmation-bias weights used in the update rule. A score near zero indicates little selective filtering; larger values indicate that effective influence is increasingly concentrated among opinion-similar neighbors. These are transparent simulator diagnostics, not universal definitions of the corresponding social phenomena. ## Network models - **Random:** Erdős–Rényi graph with expected average degree near 8 - **Small World:** Watts–Strogatz graph with degree 8 and rewiring probability 0.12 - **Scale Free:** Barabási–Albert graph with `m=4` The configurations keep sparsity in a similar range while changing topology. ## Large-population rendering All configured agents and graph edges participate in the simulation and metric calculations. For browser rendering only: - 100-agent runs use a force-directed layout - 500- and 1,000-agent runs use a deterministic hub-aware radial layout - displayed edges are sampled for large graphs - visual refresh frequency is reduced as population size grows This keeps the hosted Space responsive without changing the underlying simulation. ## Reproducibility A fixed configuration and random seed reproduce: - graph construction - opinion initialization - stubborn-agent assignment - misinformation exposure assignment - stochastic noise - full opinion trajectory ## Run locally ```bash python -m venv .venv # Windows .venv\Scripts\activate # macOS / Linux # source .venv/bin/activate pip install -r requirements.txt python app.py ``` ## Tests ```bash pip install pytest pytest -q ``` The test suite covers graph generation, deterministic replay, metric sanity, opinion bounds, stubborn-agent invariance, misinformation direction, and large-population visualization without SciPy. ## Repository structure ```text socialdynamics-lab/ ├── app.py ├── README.md ├── requirements.txt ├── CITATION.cff ├── REFERENCES.bib ├── LICENSE ├── src/socialdynamics/ │ ├── metrics.py │ ├── networks.py │ ├── presets.py │ ├── simulation.py │ └── visualization.py └── tests/ ``` ## Scientific context The simulator draws on established ideas from opinion dynamics and network science while using its own update rule and diagnostics. 1. DeGroot, M. H. (1974). Reaching a Consensus. *Journal of the American Statistical Association*, 69(345), 118–121. https://doi.org/10.1080/01621459.1974.10480137 2. Hegselmann, R., & Krause, U. (2002). Opinion Dynamics and Bounded Confidence: Models, Analysis and Simulation. *Journal of Artificial Societies and Social Simulation*, 5(3), 2. https://www.jasss.org/5/3/2.html 3. Watts, D. J., & Strogatz, S. H. (1998). Collective dynamics of ‘small-world’ networks. *Nature*, 393, 440–442. https://doi.org/10.1038/30918 4. Barabási, A.-L., & Albert, R. (1999). Emergence of Scaling in Random Networks. *Science*, 286(5439), 509–512. https://doi.org/10.1126/science.286.5439.509 5. Erdős, P., & Rényi, A. (1959). On Random Graphs I. *Publicationes Mathematicae*, 6, 290–297. BibTeX entries are available in [`REFERENCES.bib`](REFERENCES.bib). ## Responsible interpretation SocialDynamics Lab is a synthetic mechanistic simulator. Parameter values and outputs should not be interpreted as measurements, forecasts, or validated estimates of real platforms, communities, demographic groups, or political populations. ## Citation If you use the software in teaching, a report, or a research prototype, cite the project using the metadata in [`CITATION.cff`](CITATION.cff). ## License MIT License. Copyright © 2026 Anouar Imel.