VCMS — Visibility, Cost, Memory, Strain-Budget

Behavioral prediction engine for experimental game theory. Given round-by-round observations of a human subject in a cooperation game, predict their future contributions and punishment decisions using a library of previously-fitted behavioral profiles and a cognitive dynamics model.

Current engine: v5 (22 parameters, 17 free during fitting). Library: ~548 profiles (212 N-experiment + 196 P-experiment + 140 Fischbacher). Evaluation standard: next-round predictive accuracy (MAE 2.10, 74% hit rate within ±2).

v5 documentation: ENGINE_SPEC.md (engine), GUESS_WHO_ARCHITECTURE.md (prediction), TESTING_AND_FITTING.md (evaluation protocol and fitting workflow).

Note: The file map and architecture sections below are from the v4 era and have not been fully updated. The v5 codebase is described in the documents above.

---

Architecture

Guess Who Elimination Protocol — three steps per round:

1. Observe — Record the subject's actual contribution/punishment at round t.
2. Eliminate — Score every library candidate by behavioral distance to the subject's trajectory so far. Hard-eliminate beyond an adaptive threshold (3x best distance, 0.5 floor).
3. Predict — Run the v4 engine with each surviving candidate's fitted parameters on the current subject's actual environment. Ensemble prediction = inverse-distance-weighted average of survivor outputs.

Forward shadow: the elimination curve E(t) and its second derivative E''(t) predict behavioral transitions 1 round ahead.

---

Current Files (actively used)

Engine

File	What it does
vcms_engine_v4.py	The engine. 22-parameter state machine with GameConfig adapter pattern. Supports PGG (with/without punishment) and IPD. Normalized game time, latent strain accumulator, self-exploitation strain. Exports DEFAULTS (all 22 params), make_vcms_params(x, free_names, fixed), and vcms_objective(x, rounds, free_names, game_config) for fitting pipelines. Punishment normalizer uses gc.max_punish / 2 (generalizes across game types). Pure Python, no numpy.
pgg_p_loader.py	Loads Herrmann et al. PGG CSV data. Returns {subject_id: [PRoundData]}. Used by all PGG scripts.
ipd_loader.py	Loads IPD CSV data, adapts binary C/D actions to VCMS interface (contribution=0/1, others_mean=0/1).

Prediction System

File	What it does
guess_who.py	Main predictor. Guess Who elimination protocol with precomputed response matrix. LOO cross-validation over 140 Fischbacher subjects. Traj-only and drift prediction modes.
fischbacher_adapter.py	Builds the 140-profile Fischbacher board. Validates engine against conditional cooperation schedules (Fischbacher & Gachter 2010).
nottingham_ood_test.py	OOD test harness. Accepts any city CSV via argv[1]. Runs traj-only + drift predictions against the full 576-profile board. Reports per-horizon MAE, correlation, coverage.

Fitting & Library Construction

File	What it does
refit_oscillators.py	Targeted re-fit for subjects with multi-round cycling. Adds s_latent_rate/s_latent_thresh as free parameters. Only updates if RMSE improves.
normalized_fit.py	Shared fitting infrastructure for normalized-time scripts. Provides fit_subject_de() (Differential Evolution + Nelder-Mead polish), predict_fast_normalized(), params_array_to_dict(), FIT_PARAM_NAMES (15 free), FIXED_PARAMS (5 fixed). Used by all refit/fit scripts below.
refit_p_normalized.py	Re-fit 196 P-experiment subjects with v4 normalized-time engine. Uses vcms_report for run output.
refit_n_normalized.py	Re-fit 212 N-experiment subjects (7 cities) with v4 normalized-time engine. Per-city breakdown via vcms_report.
refit_ipd_normalized.py	Re-fit 188 IPD subjects (SP + FP) with v4 normalized-time engine. Per-treatment and per-type breakdown via vcms_report.
fit_nottingham.py	Fit 16 Nottingham N-experiment subjects. Uses vcms_report for run output, keeps custom per-subject detail table.
fit_minsk.py	Fit 32 Minsk N-experiment subjects. Same structure as fit_nottingham.py.
n_experiment_fit.py	Initial N-experiment fitting pipeline (all Herrmann cities).
ipd_fit.py	IPD fitting pipeline (15 free params, 5 fixed).

Reporting

File

What it does

vcms_report.py

Auditing & reporting module. Section A: per-subject trace interpretation (interpret_trace, format_audit_report, format_audit_summary) — decodes engine decisions (dominant strain channel, budget trajectory shape, routing). Section B: run summary reporting (format_run_header, format_progress_line, collect_run_stats, format_run_summary, format_comparison_table, format_group_breakdown, format_param_scale_comparison, format_run_footer). Used by all 5 fitting scripts for consistent output. Stdlib-only (no numpy).

Analysis & Diagnostics

File	What it does
knockout_v4.py	Channel knockout analysis. Disables each of 10 behavioral channels, measures RMSE impact. Populates active_channels/null_channels on all library entries.
oscillation_diagnostic.py	Grid-samples 20k+ v4 parameter sets to measure engine oscillation capacity (round-to-round variance, cycle length).
phenotype_geometry.py	Cross-game phenotype convergence: do cooperator/defector archetypes occupy the same parameter-space regions in PGG-P, PGG-N, and IPD?
diagnose_errors.py	Error decomposition: engine accuracy vs weighting accuracy vs board coverage.
diagnose_response_matrix.py	Response matrix validation and horizon-by-horizon accuracy checks.
sweep_sigma.py	Parameter sensitivity grid-search for s_rate and b_depletion_rate.

Simulation

File	What it does
federation_sim.py	4-agent self-play PGG, 50-100 rounds. Tests phenotype sustainability (CC, EC, CD, DL) and time-to-rupture.
enforcement_sim.py	40-agent populations with 5 enforcement mechanisms (none, punishment, threshold exclusion, sustainability exclusion, voluntary exit).
enforcement_phase2.py	Phase 2: baseline punishment mechanism validation.
enforcement_phase3.py	Phase 3: larger populations (100+ agents), multiple phenotype draws.
enforcement_phase3d.py	Divisive enforcement variant (expel worst offenders).
hierarchy_sim.py	Multi-level: 4 agents/group, 5 groups/federation, 2 federations.
theory_instance_tests.py	Tests specific Book 1 theorems via simulation: combined library transfer, prosocial strain fitting, budget resilience.

Validation Tests

File	What it does
v4_validation.py	Quick RMSE checks across multiple v4 libraries.
ipd_transfer_test_v4.py	Cross-game transfer: v4 PGG library predicts IPD subjects.
ipd_refinement_test.py	IPD refinement: strain decay, horizon scaling, tighter elimination.
ipd_characterize.py	Per-subject IPD characterization (cooperation rate, TFT-ness, transitions).
verify_dynamics.py	Mechanism verification: proves engine does real work (state-dependent dynamics, not pattern-matching).

---

Current Libraries (v4, normalized time)

File	Subjects	Experiment	Engine	Notes
v4_library_fitted.json	176	PGG-P (6 cities)	v4 normalized	Has knockout channel annotations
v4_n_library_fitted.json	212	PGG-N (7 cities)	v4/v4.1	Some subjects have latent strain
v4_nottingham_library_fitted.json	16	PGG-N (Nottingham)	v4/v4.1	OOD holdout city
v4_minsk_library_fitted.json	32	PGG-N (Minsk)	v4/v4.1	OOD holdout city
v4_ipd_library_fitted.json	188	IPD (FP + SP)	v4 normalized	92 fixed-pairing + 96 stranger-pairing
fischbacher_library.json	140	Fischbacher PGG	Fischbacher adapter	Conditional cooperation schedules, types
p_experiment_canonical_library.json	176	PGG-P	v3	Demographic + behavioral classification

---

Deprecated Files

These remain in the repo for reference but are superseded by v4 equivalents.

Deprecated Engine / Fitting

File	Superseded by	Notes
pgg_vcms_agent_v3.py	vcms_engine_v4.py	16-param v3 engine. Still imported by v3_cross_validation.py.
pgg_vcms_fit_v3.py	refit_p_normalized.py	v3 fitting pipeline (DE + NM). Knockout infrastructure here was basis for knockout_v4.py.
vcms_v3_combined.py	guess_who.py	v3 combined predictor.
build_v3_library.py	refit_p_normalized.py	Batch v3 library builder.
incremental_library_expand.py	Direct library JSON edits	Library expansion utility (v3).
refit_library.py	refit_*_normalized.py	v3 re-fit utility.

Deprecated Tests

File	Superseded by	Notes
v3_cross_validation.py	guess_who.py + nottingham_ood_test.py	v3 LOO/LOCO CV. Uses v3 engine + library.
v3_n_experiment_test.py	nottingham_ood_test.py	v3 P-library -> N-experiment transfer.
v3_n_experiment_diagnostics.py	diagnose_errors.py	v3 N-experiment error analysis.
v3_n_experiment_validation.py	v4_validation.py	v3 N-experiment convergence curves.
ipd_transfer_test.py	ipd_transfer_test_v4.py	v3 IPD transfer (superseded by v4 version).

Deprecated Libraries

File	Superseded by	Notes
v3_library_fitted.json (196 subjects)	v4_library_fitted.json	v3 P-experiment fits, 18 params.
v3_library_fitted_pre_experience_fix.json	v3_library_fitted.json	Historical: before facilitation_rate bug fix.
n_library_fitted.json (212 subjects)	v4_n_library_fitted.json	v3 N-experiment fits, pre-normalized-time.
ipd_library_fitted.json (188 subjects)	v4_ipd_library_fitted.json	v3 IPD fits, pre-normalized-time.

Deprecated Analysis

File	Superseded by	Notes
v3_constrainedness.py	phenotype_geometry.py	v3 parameter identifiability.
ablation_drift.py	knockout_v4.py	v3 parameter ablation study.

---

Documentation

File	Content
CLAUDE_CODE_HANDOFF.md	Architecture walkthrough from initial handoff. Describes v3; still accurate for core concepts.
executive_summary_for_theory.txt	Normalized-time implementation report. Cross-game transfer results.
cross_instance_briefing.txt	Technical briefing on v4 design decisions.
phase3_guess_who_writeup.md	Guess Who protocol validation results.
phase2_warm_start_writeup.md	Warm-start initialization for enforcement sims.
phase2_confidence_shadow_writeup.md	Confidence metrics + forward shadow analysis.
enforcement_sim_results.md	Enforcement mechanism comparison results.
enforcement_phase2_results.md	Phase 2 enforcement results.
enforcement_phase3_results.md	Phase 3 enforcement results.
enforcement_phase3d_results.md	Divisive enforcement results.
hierarchy_sim_results.md	Multi-level federation results.

---

Running Key Scripts

# OOD prediction on any city
python nottingham_ood_test.py HerrmannThoeniGaechterDATA_ISTANBUL_N-EXPERIMENT_TRUNCATED_SESSION1.csv

# Channel knockout analysis
python knockout_v4.py

# Guess Who LOO cross-validation
python guess_who.py

# Oscillation diagnostic
python oscillation_diagnostic.py

# Cross-game phenotype convergence
python phenotype_geometry.py

# Federation self-play simulation
python federation_sim.py

# Enforcement mechanism comparison
python enforcement_sim.py

---

Engine Parameters (v4.1, 22 total)

Channel	Parameters	What they control
V (Visibility)	alpha, v_rep, v_ref	How the agent perceives and tracks group behavior
C (Cost)	c_base, p_scale	Baseline cooperation propensity, punishment scaling
M (Memory)	inertia	Behavioral persistence / striation
S (Strain)	s_dir, s_rate, s_initial	Motive force from norm-violation gap
R (Resolution)	s_frac, s_thresh	Discharge gate mechanics
B (Budget)	b_initial, b_depletion_rate, b_replenish_rate, acute_threshold	Psychological resource pool
M_eval (Facilitation)	facilitation_rate	Experience-driven cost modification
H (Horizon)	h_strength, h_start	End-game discounting
Exploitation (v4)	v_self_weight, s_exploitation_rate	Self-awareness of over-contribution
Latent (v4.1)	s_latent_rate, s_latent_thresh	Silent strain accumulator for charge-hold-crash cycling

Rupture (budget collapse -> cooperation crash) is emergent, not parameterized.

---

Data Sources

• Fischbacher & Gachter (2010) — 140 subjects, PGG with conditional cooperation elicitation
• Herrmann, Thoni & Gachter (2008) — PGG-P and PGG-N across 16 cities worldwide
• Collucci, Franco & Valori (2023) — Iterated Prisoner's Dilemma, fixed + stranger pairing

CSV files follow the naming pattern: HerrmannThoeniGaechterDATA_{CITY}_{P|N}-EXPERIMENT_TRUNCATED_SESSION{N}.csv