Mathematical Architecture for Scalable Social Interaction & Virtual Engine
A hybrid social-dynamics simulation platform that predicts opinion formation, polarization, and intervention outcomes over complex social systems — with optional Rust acceleration, real-world Factbook data, and scientifically validated numerics.
- Opinion & polarization simulation — backward-compatible legacy API (
simular,run_with_schedule) plus energy-based Langevin dynamics. - Real-world data integration — initialize agents with CIA World Factbook demographics for 260+ countries.
- Rust acceleration — optional compiled numerical kernels (
massive_rust_core) with Python fallbacks. - Scientific opt-in layer — adaptive steppers, stability analysis, EnKF assimilation, bifurcation diagnostics.
- API-first design — FastAPI backend with auth-gated endpoints (
/api/v1/forecast,/api/v1/architect,/api/v1/energy).
| Category | Technology | Why |
|---|---|---|
| Core | Python 3.11, numpy, scipy, networkx, pydantic | Numerical + graph + typed contract |
| Acceleration | Rust (maturin, pyo3) |
Hot-path numerical kernels |
| API | FastAPI, uvicorn | Low-latency, auto-documented HTTP API |
| Scientific | numba, statsmodels, pgmpy, nashpy, dask | Optional engines behind config flags |
| Frontend | React 18, Vite, TypeScript, Tailwind | Modern SPA with auto-generated DTOs |
| ML/AI | OpenAI, LangChain, PyTorch (Mamba, CfC) | LLM-based architect + SNN baselines |
| Deployment | Docker multi-stage, nginx, supervisord | Single gateway, non-root runtime |
git clone https://github.com/Adlgr87/MASSIVE.git
cd MASSIVE
python -m pip install --upgrade pip
pip install -r requirements.txt
cp .env.example .env # add your API key if needed
python app.py # opens Streamlit UINo Streamlit? Run the API server instead:
uvicorn api:app --host 0.0.0.0 --port 8000Minimum requirement: Python 3.11, 500 MB free RAM. Rust/CUDA/torch are optional.
from simulator import simular, resumen_historial
estado = {
"opinion": 0.5, "propaganda": 0.7, "confianza": 0.4,
"opinion_grupo_a": 0.72, "opinion_grupo_b": 0.28,
"pertenencia_grupo": 0.65,
}
historial = simular(estado, pasos=30, cada_n_pasos=5)
print(resumen_historial(historial))| Engine | 1K Agents | 100K Agents | 1M Agents | 100M Agents |
|---|---|---|---|---|
| MassiveEngine (aggregated) | 0.39s • 0.87 GB | 2.3s • 0.87 GB | 21s • 0.88 GB | 44s • 8.3 GB |
| EnergyEngine | 0.06s • 0.89 GB | 3.1s • 0.89 GB | 35s • 0.9 GB | 16.8 GB required |
| SparseMultilayerEngine | 0.03s • 0.88 GB | 6.3s • 0.88 GB | 43s • 1.1 GB | N/A |
| MultilayerEngine | 0.26s • 0.84 GB | — (7GB+) | — | N/A |
MassiveSimEngine uses cluster-aggregated super-agents (build_aggregated_super_agents): agents with identical features are collapsed into representative clusters. This means 1K and 100M agents materialize the same number of compute nodes (~5K clusters), giving near-constant RAM (0.87 GB baseline + aggregation table overhead).
Current hardware: 31 GB RAM available. With MassiveEngine you can run up to 100 million agents on 8.3 GB of RAM.
Pro tip: Use
lod_mode="aggregated"for population-scale runs >100K agents to avoid memory explosion.
| Repository | Contents |
|---|---|
datasets/real_cases/ |
Real-world case studies with country-level Factbook data |
datasets/pvu_cases/ |
PVU-MASSIVE offline validation cases |
reports/validation/ |
Validation reports and scientific benchmarks |
reports/sota_baselines/ |
State-of-the-art baseline comparisons |
reports/factbook_validation_US_*.json |
Factbook-to-simulation alignment metrics |
models/cfc_calibrated/ |
Trained Closed-form Continuous-time (CfC) neural network residual corrector |
| Model | Type | Purpose | Performance |
|---|---|---|---|
models/cfc_calibrated/cfc_residual.pt |
CfC (Liquid NN) | Brexit referendum bias correction | 50% error reduction (54.5%→53.2% Leave%) |
| R² = -18.7 (direction-only); 10/10 seeds improved |
CFC model detects systematic simulation bias and applies adaptive correction proportional to each run's baseline error.
cp .env.example .env
docker compose up --build
# → frontend: http://localhost
# → API docs: http://localhost/api (FastAPI /docs)from massive_core import run_scientific_simulation
result = run_scientific_simulation(
estado, pasos=30,
scientific_config={"enable_scientific_report": True},
)
print(result.scientific_report.to_dict())| Engine | Purpose | Activate via |
|---|---|---|
social_architect |
Inverse intervention strategy | from social_architect import buscar_estrategia_inversa |
forecast/engine.py |
Temporal risk forecast | /api/v1/forecast |
energy_runner |
Social-energy landscape | /api/v1/energy, SocialEnergyEngine(solver="euler_maruyama") |
SparseMultilayerEngine |
Scalable super-agent sim | from massive_core.numerics import SparseMultilayerEngine |
SparseEnsembleKalmanFilter |
Data assimilation | from massive_core.data_assimilation import SparseEnsembleKalmanFilter |
| Endpoint | Method | Description |
|---|---|---|
/api/v1/architect |
POST | Inverse-strategy search to reach a user goal |
/api/v1/forecast |
POST | Analytical + Monte Carlo temporal forecast |
/api/v1/energy |
POST | Social-energy landscape simulation |
/api/extract |
POST | File → MASSIVE config (PDF/JSON/CSV) |
/api/wizard |
POST | LLM-powered simulation wizard |
/health |
GET | Liveness probe |
/ready |
GET | Readiness probe |
/docs |
GET | OpenAPI UI (FastAPI) |
Auth: X-API-Key header or MASSIVE_API_KEY env var. Dev fallback: dev-secret-key.
# Install dev extras
pip install -e ".[dev,api,ml,scientific]"
# Test suite
python -m pytest tests/ -x -q
# PVU-MASSIVE offline validation
python -m benchmarks.runner --cases datasets/pvu_cases --offline --out reports/validation/local --seed 42
# Type checking
python scripts/typecheck_slice.py
# Regenerate frontend types
python scripts/gen_ts_types.py
# Build Rust core (optional)
maturin develop --release| Topic | Link |
|---|---|
| Full API reference | docs/api.md |
| Scientific roadmap (ES) | docs/math_physics_extension_plan_ES.md |
| PVU-MASSIVE validation | docs/validation/ |
| CIA Factbook integration | docs/FACTBOOK_INTEGRATION_COMPLETE.md |
| MkDocs site | python -m mkdocs serve |
| Spanish README | README_ES.md |
Apache License 2.0. See LICENSE.
MASSIVE was previously developed as BeyondSight (archived in git history). Codebase renamed 2026-06-29.