REPLICATION_KIT.md

# Replication kit — second rig (Windows OK)

Goal: an INDEPENDENT machine + scene + operator reproduces (or kills) the
learnability law AND its mechanism. No cameras required for the core replication.

## TURNKEY (one command) — do this first
```
pip install torch numpy opencv-python scipy
# copy from this repo: paper2/replicate.py, simreal/train_composite.py, triclock/
python replicate.py --bank <folder-of-~1000-photos-of-any-room | scene.npy> --full --seeds 3
```
It builds a 64px bank from your photos, computes R + feat-R, trains a size grid
blind, and prints a PASS/FAIL scorecard for P1 (R<->feat-R), P2 (the LAW), and
P3 (ignition). Compare to EXPECTED_RESULTS.md; send back results_replicate.json.
CPU works (slower: use default 8k-step quick mode first to sanity-check, then
--full). CUDA auto-detected. Everything below is the manual/long-form protocol.

**Read EXPECTED_RESULTS.md for the PASS bars and the caveats that will bite you**
(the wall is seed-bimodal and slow — always multi-seed and train long; collapse =
loss==log 4; compare ORDERING across scenes, never absolute thresholds).


## Setup (Windows or Linux, ~30 min)
1. Python 3.10+, then: pip install torch numpy opencv-python
   (CUDA build of torch if the PC has a GPU: pytorch.org selector.
    CPU-only works: one condition ≈ 2-4h instead of 35 min.)
2. Copy from this tree: simreal/train_composite.py, triclock/ (model.py,
   __init__.py). Nothing else needed for the core test.
3. Background bank: DO NOT copy ours (independence!). Either:
   (a) film ~2h of any static-camera scene at 1fps (script below), or
   (b) any folder of ~5000 varied photos of one room.
   Build: python make_bank.py <folder>  -> frames64.npy/ts64.npy
   (make_bank.py = 15 lines: resize each to 64x64, stack, save; included.)

## Protocol (the part that makes it science)
1. CALIBRATE: train exactly TWO conditions on the new scene:
   static-bg 6px and static-bg 14px (20K steps, seed 0).
2. PREDICT: compute R for 8 fresh conditions (sizes 5,8,10,12 x static/moving)
   with compute_R.py (included); WRITE PREDICTIONS TO A FILE + note the time.
3. TRAIN the 8 blind. 4. Score Spearman(R, outcome).
   Law survives if rho > 0.9 on the new scene. Kill-criteria welcome.
5. Optional round 2: the low-contrast falsification (contrast 0.4 at a size
   that learned) and the gate (NOISE_BLUR sweep).

## Windows notes
- Paths: the scripts use relative paths; run from the repo root.
- No bash needed: each run is one python command; a .bat loop is fine.
- If filming: python jetson/capture.py --out bank_scene --fps 1 works with
  any webcam via OpenCV on Windows (device 0).

## What to send back
The predictions file (pre-training), the results JSONs, and the scene bank
hash. Disagreement with our numbers is a RESULT, not a failure.