sica-fondt/core/docs/plans/M3b-sociological-sims.md

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

TBD · src/economy/sims/sociological/. Agent-based modeling frameworks (Mesa/Python, NetLogo, or custom). 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: 0.68, time_horizon: "12h", sim_type: "sociological" } — herd-panic index (0–10). { value: 0.42, lower_bound: 0.31, upper_bound: 0.55, confidence: 0.72, time_horizon: "1w", sim_type: "sociological" } — fraction of pops in "contrarian" strategy. { value: "promotion", lower_bound: null, upper_bound: null, confidence: 0.61, time_horizon: "current", sim_type: "sociological" } — pump-and-dump phase detection. { value: 0.78, lower_bound: 0.65, upper_bound: 0.88, confidence: 0.70, time_horizon: "30d", sim_type: "sociological" } — MFG equilibrium stability index.
• 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 archetypes, not individuals — no attempt to model or track real market participants. The sim models emergent behavior from strategy populations.
• L2 (C5): strategies evolve — the population distribution shifts over time via replicator dynamics. No fixed strategy ratios.
• L3 (C4): bounded rationality is the default — pops satisfice with heuristics, not optimize with perfect information. Rational-agent models are a special 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

1. Define pop archetypes and their heuristic 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 output.

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.
• 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)?