# SR analysis

## Five-minute navigation

This directory is the symbolic-regression (SR) evidence package for the LegacyCelerisLab fluidic pinball. The **current scientific scope is Kármán/cloaking only**: a compact, symmetry-constrained surrogate of the frozen PPO policy, tested in closed-loop Legacy CFD. The disturbance-free `steady` scene is contextual calibration for the Kármán rear-rotation magnitude; it is not a fitting objective or an independent mechanism result.

Read in this order:

1. This file for scope, claims, and the package map.
2. `results/README.md` for the evidence index and claim-status ledger. Until that index is rewritten as an active/archive ledger, treat any older Illusion “accepted” or “generalization” wording there as historical rather than current authority.
3. `PIPELINE.md` for executable contracts and reproduction rules.
4. `HISTORY_AND_LESSONS.md` for chronology, failed routes, and lessons.
5. `HANDOFF.md` before resuming experiments or manuscript work.

The executable July route remains:

```text
stage_1_infer.py -> stage_2_fit.py -> stage_3_validate.py
```

The August standardized role-acquisition route is separate in purpose: `src/drl_pinball/legacy_test/acquire.py` reruns frozen roles under a common long-window collection contract. It audits deployment behavior and produces comparable role artifacts; it does not replace Stage 1 discovery data, refit formulas, or silently promote a new scientific claim.

## Current scientific position

### Kármán/cloaking — active

The canonical mapped-shared law is retained under the immutable `article-*` evidence chain. The evidence supports a bounded statement: persistent rear counter-rotation is the dominant tested element, rear-lift feedback is secondary, and the tested front feedback is weak over the deletion window. The steady sweep is consistent with the magnitude of the rear constant, but does not establish momentum balance, a causal wake mechanism, universal Reynolds-number behavior, or a unique symbolic law.

Formula output is dimensionless `alpha = omega/U0`. The current architecture is

```text
alpha_F = (h_F(x) - h_F(Gx))/2
alpha_U = h_R(x)
alpha_L = -h_R(Gx)
```

This imposes exact reflection symmetry at deployment. It does not show that PPO training was equivariant.

### Illusion SR — retained historical/negative route

Illusion runtime support remains shared capability because Stage 1–3, target/harmonics handling, formula loading, provenance checks, and standardized acquisition still depend on it. Its immutable data, formulas, manifests, rejected runs, and standardized outputs must remain at their existing paths.

Illusion is **not** an active SR scientific result. The runtime and fitting pool supplied target information, but the selected formulas omitted target/error terms. In the long standardized Legacy acquisition, the retained SR action decayed near physical zero and showed no meaningful benefit over the physical-zero role. Older finite 200/400-step target-similarity values therefore do not establish efficacy against zero. Do not claim Illusion target tracking, cross-size generalization, term necessity, or mechanism from this route. The Illusion PPO/DRL capability and the failed SR explanation are different claims.

## Evidence and claim rules

`results/README.md` is expected to provide, or link to, a claim-status ledger with at least these states:

- **active/supported:** Kármán surrogate deployment and explicitly bounded term-ranking evidence;
- **contextual:** steady magnitude calibration;
- **historical:** July Illusion discovery/refit and finite short/medium closed-loop records;
- **negative/diagnostic:** standardized Illusion decay toward physical zero, failed crossings, rejected topology, and incomplete campaign roles;
- **unsupported:** target tracking, universal/general distribution claims, unique/global symbolic optimality, causal mechanism, momentum equality, and physical delay inferred from DTW lag.

A numerical statement is not authoritative unless it resolves to an immutable artifact, manifest/hash chain, metric definition, duration/window, scene, role, and evidence status. Preserve rejected and failed telemetry.

## Package map

- `configs.py`, `stage_1_infer.py`, `stage_2_fit.py`, `stage_3_validate.py`: active July Stage 1→2→3 implementation.
- `checks/`: native order and policy-replay gates.
- `utils/`: data/alignment, feature, symmetry, formula, metric, CFD, and provenance contracts.
- `tools/`: derived export and plotting tools; these do not create acceptance evidence by themselves.
- `tests/`: CPU contract tests.
- `data/`: frozen inputs and accepted run-scoped acquisition artifacts. Existing paths are provenance dependencies.
- `results/`: immutable run families and their evidence index. Semantic status must be layered over run IDs; do not rename hash/parent-bound runs for readability.
- `archive/`: non-active experiments, superseded implementations, diagnostics, and historical material. Archived paths may not execute.
- `HISTORY_AND_LESSONS.md`: project chronology and mistakes not to repeat.
- `HANDOFF.md`: restart checklist, claim boundaries, and writing handoff.

The standardized collector lives outside this directory at `src/drl_pinball/legacy_test/acquire.py`. Its role outputs normally resolve through the reproduction storage mapping; the resolved output root and source hashes belong in each artifact's metadata.

## Non-negotiable contracts

- Native body/action order: `front, upper, lower`.
- Force order: front, upper, lower, each `(x,y)`; sensors: upper, centre, lower, each `(u_x,u_y)`.
- Causal fitting alignment: recorded post-state `i` predicts action `i+1`; no warm-up, lag, split, or derivative state crosses a trajectory boundary.
- Runtime PPO uses the frozen scene norm; PyCUDA owns the CFD GPU and PPO inference remains on CPU.
- `re_code` uses reference length `2D`, so `Re_D = re_code/2`.
- Historical Illusion size labels are not to be silently reinterpreted: the stored `target_diameter` value is passed to the Legacy builder as a radius.
- The exact July acceptance metric is `legacy_dtw_v1_abs_n_unclipped` / `legacy_reference_cycle_vs_last_recorded_cycle`; fitted circular lag is alignment metadata, not physical delay.
- Runs are immutable and no-clobber. Never overwrite a successful, failed, or partial evidence directory; use a new run/role ID and retain the old record.

## Verification and review

Documentation-only checks require no CFD:

```bash
git diff --check -- src/SR_analysis/README.md src/SR_analysis/PIPELINE.md src/SR_analysis/HISTORY_AND_LESSONS.md src/SR_analysis/HANDOFF.md
git diff -- src/SR_analysis/README.md src/SR_analysis/PIPELINE.md src/SR_analysis/HISTORY_AND_LESSONS.md src/SR_analysis/HANDOFF.md
```

For later code changes, run focused CPU tests before the full SR suite. GPU CFD is never part of a routine documentation verification. Each phase must end with a contract, evidence, claim, provenance, and scope self-review; details are in `HANDOFF.md`.