# OID Analysis Notes

## Document role

Execution plan, task tracking, and current priority for the OID analysis line.
Does NOT repeat confirmed facts or hard rules (see OID_knowledge.md).

---

## Overall Status: COMPLETE (Phase 2 delivered 2026-06-28)

All planned work is done. Repository is ready for handover.

### What was built

```
src/OID_analysis/
  configs.py                    # Unified scene config (10+ scenes, mirroring SR/CCD)
  OID_knowledge.md              # Confirmed facts, rules, results
  OID_notes.md                  # This file -- task tracking
  Final_Conclusions.md          # Six-question conclusions
  Sch12.md                      # OID reference paper
  utils/
    cfd_interface.py            # Re-exports CCD's proven CFD interface
    analysis.py                 # CPU-only: POD, OID, PCD, zone statistics, comparison
  scripts/ (11 scripts)
    collect_empty_channel.py    # q_in for steady/illusion
    collect_pinball_baseline.py # q_blk for steady/illusion (cloak positions)
    collect_disturbance_only.py # q_in for Karman
    collect_karman_blk.py       # q_blk for Karman
    collect_controlled.py       # q_ctl for PPO scenes (Karman + Illusion)
    collect_steady_cloak.py     # q_ctl for steady cloak (open-loop)
    collect_target_cylinder.py  # q_tar for illusion
    collect_illusion_qblk.py    # q_blk for illusion-specific geometry
    collect_fields_replay.py    # Replay PPO with field extraction from CCD
    collect_baseline_forces.py  # Quick force collection (auxiliary)
    collect_all_data.py         # Batch data collection runner
    compute_delta_fields.py     # Phase 0: Delta_q + zone stats (draft)
    replay_full_fields.py       # Full-field replay (no cropping)
    replay_verify.py            # Verify replay fidelity
  analysis/ (13 scripts)
    phase1_correction_pod.py    # Correction-field POD + rank sensitivity
    phase2_build_observables.py # Scene-specific Y matrices
    phase3_force_oid.py         # Force-OID
    phase4a_signature_oid.py    # Signature-OID minimal
    phase4b_signature_pcd.py    # Signature-PCD whitened
    phase5_steady_oid.py        # Steady cloak suppression-OID
    phase6_comparison.py        # POD vs OID vs PCD
    phase7_whitebox.py          # White-box control chain
    run_full_analysis.py        # Batch pipeline runner
    robustness_analysis.py      # Rank/window/tau_c/zone robustness
    save_robustness.py          # Save robustness data
    steady_reanalysis.py        # Steady cloak suppression metrics
    compile_master_table.py     # Cross-scene comparison table
    make_figures.py             # Generate all 7 figures
  data/
    configs/legacy/             # Legacy CFD config JSONs (symlinked)
    steady_cloak/               # empty_channel, pinball_baseline, steady_cloak, pinball_baseline_illusion
    karman_cloak/               # disturbance_only, karman_blk, karman_re100
    illusion/                   # illusion_0.75L, illusion_1.0L, illusion_1.5L
    target_cylinder/            # target_cylinder_0.75L, 1.0L, 1.5L
    derived/                    # POD, OID, comparison, observables, robustness, figures, whitebox
docs/
  OID_analysis_results.md       # Full project report (292 lines, 7 figures)
```

### Data collected (all complete)

| Dataset | Snapshots | GPU | Source |
|---------|-----------|-----|--------|
| empty_channel (q_in) | 100 | 3 | collected |
| pinball_baseline (cloak q_blk) | 200 | 3 | collected |
| steady_cloak (q_ctl, open-loop) | 500 | 3 | collected |
| disturbance_only (Karman q_in) | 500 | 1 | collected |
| karman_blk (Karman q_blk) | 500 | 1 | collected |
| karman_re100 (Karman q_ctl PPO) | 500 | 1 | CCD replay |
| illusion_0.75L (q_ctl PPO) | 500 | 3 | CCD replay |
| illusion_1.0L (q_ctl PPO) | 500 | 3 | CCD replay |
| illusion_1.5L (q_ctl PPO) | 500 | 3 | CCD replay |
| illusion q_blk (separate geometry) | 500 | 3 | collected |
| target_cylinder 0.75/1.0/1.5L | 96 each | via CCD | symlinked |

### Key results

1. **Force-vs-Signature systematic separation** (flagship): steady(+0.763) -> Karman(-0.034) -> ill0.75(-0.082) -> ill1.0(-0.495) -> ill1.5(-0.932)
2. **OID beats POD** for both force and signature prediction in ALL scenes
3. **Robust**: Karman and illusion 1.0/1.5L rank-stable; Karman tau_c sweep confirms separation is not an artifact
4. **OID != control state**: force-OID captures only 22.5% of action variance (expected)

### Phase-by-phase completion

| Phase | Description | Status |
|-------|-------------|--------|
| 0 | Three-field decomposition + data collection | COMPLETE |
| 1 | Correction-field POD + rank sensitivity | COMPLETE (all 5 scenes) |
| 2 | Scene-specific observable construction | COMPLETE (all 5 scenes) |
| 3 | Force-OID | COMPLETE (all 5 scenes) |
| 4a | Signature-OID (minimal) | COMPLETE (Karman + Illusion 3x) |
| 4b | Signature-PCD (whitened) | COMPLETE (Karman + Illusion 3x) |
| 5 | Steady cloak suppression-OID | COMPLETE |
| 6 | POD vs OID vs PCD comparison | COMPLETE (all scenes with R2 tables) |
| 7 | White-box control chain | COMPLETE (Karman, partial) |
| Robustness | Rank/tau_c/window/zone | COMPLETE |
| Figures | 7 figures generated | COMPLETE |
| Report | docs/OID_analysis_results.md | COMPLETE (292 lines) |

### Open items (for next agent)

1. **Illusion 0.75L rank instability** (std=0.26) -- needs investigation with longer time series
2. **Karman future-signal R2~0** -- may need phase-error formulation instead of direct delay
3. **OID mode-to-field mapping** -- OID spatial modes are computed but not visualized as flow fields
4. **causal-PCD for action coordinates** -- needed for obs->z->act whitebox chain
5. **Cross-validation** over multiple independent rollouts

### Environment

- CFD/collection: `conda run -n pycuda_3_10` (requires GPU)
- Analysis: `conda run -n sr_env python3` (CPU only, has sklearn)
- GPUs: device 1 (Karman), device 3 (steady/illusion)

### References to read before starting

1. `docs/OID_analysis_results.md` -- full project report
2. `src/OID_analysis/OID_knowledge.md` -- rules, results, bugs
3. `src/OID_analysis/configs.py` -- scene definitions
4. `docs/ccd_correction_field_report.md` -- sibling project for cross-reference
5. `docs/SR_analysis_results.md` -- sibling project for cross-reference
