Spaces:
Running on Zero
Running on Zero
| 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. |