README.md

metadata

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

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
# source .venv/bin/activate

pip install -r requirements.txt
python app.py

Tests

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

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.

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.

License

MIT License. Copyright © 2026 Anouar Imel.