# M3b — Sociological & population dynamics sims

## 1. Component
Sociological simulation: **evolutionary game theory, bounded rationality, opinion dynamics,
complex contagion, adaptive learning populations, and Mean-Field Game equilibria** among market
participants. Pops here are **behavioral archetypes** — retail herd followers, contrarian whales,
MEV searchers, passive LPs, pump-and-dump manipulators — whose strategies evolve under selection
pressure across **six concurrent time horizons**. Grounded in evolutionary consensus game models
[8,9], Hegselmann-Krause opinion dynamics (2002), complex contagion theory (Centola & Macy 2007),
MFG theory (Lasry & Lions 2007), and crypto manipulation ABMs.

## 2. Status / certainty
DESIGN-FIRST · ABSENT. Evolutionary game theory C4 (Cornell [8]). Hegselmann-Krause bounded
confidence C5 (established 2002). Complex contagion C4 (Centola & Macy 2007; crypto applications
C3). Bandit-replicator hybrid C3 (emerging). Mean-Field Games C4 (Lasry & Lions 2007; tensor-train
solvers C3). Crypto pump-and-dump ABM C3 (3-agent protocol validated on historical data).
Pop behavioral models C1.

## 3. Language & location
ECLiPSe Prolog · `src/economy/sims/sociological/`. **Prolog** — game-theoretic equilibria, replicator
dynamics, and strategy evolution are naturally expressed as logical relations over population
states; Nash equilibrium search is constraint satisfaction. Needs efficient population iteration,
strategy mutation, PDE solvers for MFG (HJB + Fokker-Planck), and bandit algorithms
(UCB/Thompson).

## 4. Does / does-not
- **Does:** simulate populations of behavioral archetypes competing in a market; apply
  **replicator dynamics** $dx_i/dt = x_i(\pi_i(x) - \bar{\pi}(x))$ to strategy distributions;
  model **opinion clustering** via Hegselmann-Krause bounded confidence:
  $x_i(t+1) = x_i(t) + \mu(x_j(t) - x_i(t))$ for $|x_i - x_j| \leq d$ — agents only update
  toward neighbors within confidence bound $d$, creating natural clustering and trend-reversal
  thresholds; model **complex contagion** with heterogeneous thresholds: adoption probability
  $P_i = f(n_i / k_i)$ where multiple exposures amplify adoption non-linearly (captures meme-coin
  rallies and narrative-driven pumps); implement **bandit-replicator hybrid** where pops use
  UCB or Thompson Sampling to estimate strategy payoffs:
  $x_i'(t) = x_i(t)[\lambda_i(t) - \bar{\lambda}(t)]$ with $\lambda_i = \text{UCB}(\theta_i)$
  — bridges replicator dynamics with multi-armed bandit learning; solve **Mean-Field Game
  equilibria** via coupled HJB + Fokker-Planck PDEs for large-population limits:
  $-\partial_t u + H(x, \nabla u) = F(x, m)$ (HJB, individual optimization),
  $\partial_t m - \nabla \cdot (m \nabla_p H) = 0$ (Fokker-Planck, population density) — Newton
  iteration with tensor-train decomposition reduces $O(N^d)$ to $O(dNr^2)$ for high-dimensional
  state spaces; simulate **crypto pump-and-dump protocol** with 3 pop types: Normal traders,
  Market Analysts (MA, information-advantaged), Market Players (MP, manipulators) in a 4-phase
  cycle (accumulation → promotion → distribution → collapse); model sentiment cascades
  (fear/greed contagion across pop clusters); model bounded rationality (pops satisfice, not
  optimize — heuristics, not perfect strategies); produce bounded predictions across all six
  time horizons.
- **Does-not:** model protocol mechanics (M3c–M3f); compute statistical forecasts (M3a);
  represent real individuals (pops are archetypes, not profiles).

## 5. Interface contract
- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub.
- **Output bounds:** population-fraction ranges, sentiment scales, MFG equilibrium stability.
- **Time-horizon mapping** (all run concurrently):
  | Horizon | Primary models | Update cadence |
  |---------|---------------|----------------|
  | Hourly | Hegselmann-Krause opinion clusters, bandit-replicator | Every data tick |
  | Daily | Complex contagion cascades, pump-and-dump phase detection | Hourly roll |
  | Weekly | Replicator dynamics strategy evolution, MFG equilibrium | Daily roll |
  | Monthly | Population archetype composition, narrative regime shifts | Weekly roll |
  | Annual | Long-run evolutionary stable strategies (ESS) | Monthly roll |
  | 5-year | MFG stationary equilibria, structural population shifts | Quarterly roll |
- Examples:
  `{ value: 7.3, lower_bound: 5.0, upper_bound: 9.1, confidence: 6.80,
  time_horizon: "12h", sim_type: "sociological" }` — herd-panic index (0–10).
  `{ value: 0.42, lower_bound: 0.31, upper_bound: 0.55, confidence: 7.20,
  time_horizon: "1w", sim_type: "sociological" }` — fraction of pops in "contrarian" strategy.
  `{ value: "promotion", lower_bound: null, upper_bound: null, confidence: 6.10,
  time_horizon: "current", sim_type: "sociological" }` — pump-and-dump phase detection.
  `{ value: 0.78, lower_bound: 0.65, upper_bound: 0.88, confidence: 7.00,
  time_horizon: "30d", sim_type: "sociological" }` — MFG equilibrium stability index.
  Models span multiple horizons — e.g. replicator dynamics runs hourly through annual; MFG
  produces weekly equilibria and 5-year stationary states. The table shows primary assignments.
- **Prediction types:** `sentiment_index`, `herd_threshold`, `strategy_distribution`,
  `cascade_probability`, `coordination_stability`, `opinion_cluster_count`,
  `pump_dump_phase`, `mfg_equilibrium_stability`, `narrative_regime`.
- Calibration: ingests `rss_news` (sentiment signal) and `price_tick` (realized behavior) from M2.

## 6. Dependencies & stubs
- M2 Data Feeds — sentiment and price data for calibration; *stub:* canned sentiment series.
- M3 Sims hub — lifecycle management; *stub:* manual init.

## 7. Invariants / laws
- **L1 (C5):** pops are **archetypal individuals, not literal living persons** — no attempt to model or track real
  market participants. The sim models emergent behavior from abstracted populations.
- **L2 (C5):** strategies **evolve** — the population distribution shifts over time via
  replicator dynamics. No fixed strategy ratios.
- **L3 (C4):** rationality is ***NOT*** the **default** — pops satisfice with heuristics, not
  optimize with perfect information. Rational-agent models are an **abnormal** case, not the baseline.
- **L4 (C4):** **complex contagion requires multiple exposures** — adoption is non-linear in
  neighbor count, not simple diffusion. Single-exposure models undercount threshold effects.
- **L5 (C4):** the MFG limit is **valid only for large populations** — below ~100 pops, use
  discrete replicator dynamics; above, the continuum HJB+FP approximation applies.
- **L6 (C3):** pump-and-dump detection is **phase-based** — the 4-phase cycle (accumulate →
  promote → distribute → collapse) has distinct statistical signatures in volume and price.

## 8. Build steps
0. Get ECLiPSe tool chain installed and operational.
1. Define pop archetypes and their various strategies.
2. Implement replicator dynamics (strategy evolution over generations).
3. Implement Hegselmann-Krause bounded confidence opinion model.
4. Implement complex contagion with heterogeneous thresholds.
5. Implement bandit-replicator hybrid (UCB payoff estimation + replicator selection).
6. Implement MFG solver (HJB + Fokker-Planck with Newton iteration).
7. Implement pump-and-dump 3-type ABM (Normal, MA, MP) with 4-phase protocol.
8. Wire M2 news/price data → calibration of pop parameters.
9. Implement multi-horizon `BoundedPrediction` outputs.

## 9. Tests
Evolution: dominant strategy shifts when payoff landscape changes. Cascade: sentiment shock
propagates through pop network above threshold, not below. Bounded confidence: opinion clusters
form at predicted cluster count for given $d$. Complex contagion: multiple-exposure requirement
produces slower but more robust adoption than simple contagion. Bandit: explore-exploit tradeoff
produces adapting populations. MFG: equilibrium converges for large N; matches discrete sim for
small N. Pump-dump: 4-phase cycle detected on synthetic manipulation data. Bounds: all outputs
include upper/lower.

## 10. Open items
- Pop archetype catalog (which behavioral types? how many?).
- Network topology for sentiment contagion (small-world? scale-free?).
- Calibration from real market data — how to infer pop distribution from observable price action. >>>We actually use blogs, reddit, and social networks to infer pops<<<
- MFG tensor-train rank $r$ (>>>accuracy<<< vs. compute tradeoff).
- Hegselmann-Krause confidence bound $d$ — fixed or >>>adaptive<<<?
- Cross-sim interaction: do sociological predictions feed into M3c (AMM) or M3d (MEV)? [conditional on prediction accuracy over time]