Frank14f/DynamisLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(SR): consolidate Karman closeout evidence

Browse Source 
Narrow active SR claims to Karman cloaking, preserve Illusion as an indexed historical route, and add readable provenance catalogs and acquisition documentation.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Frank14f
2026-08-09 08:23:33 +08:00
co-authored by Cursor
parent 08ee312ef7
commit 3a12e29571
30 changed files with 2562 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/SR_analysis/README.md
+83 -45
View File
@@ -1,54 +1,92 @@
# SR analysis
## Authority and scope
## Five-minute navigation
This directory is the frozen symbolic-regression evidence package for the LegacyCelerisLab fluidic pinball. The active scientific scope is Kármán-cloak and Illusion PPO data collection, symbolic discovery/refit, closed-loop CFD validation, sampled duration/generalization extensions, term deletion/scaling, and canonical publication export. The disturbance-free `steady` scene remains only as the calibration used to interpret the Kármán rear constant.
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.
The authoritative evidence index is `results/README.md`; execution details are in `PIPELINE.md`. Material under `archive/` is historical, excluded, or non-authoritative.
Read in this order:
## Three-stage workflow
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.
1. `stage_1_infer.py`: collect immutable, run-scoped Legacy PPO trajectories for trained Kármán and Illusion scenes.
2. `stage_2_fit.py`: perform broad per-case discovery, within-objective joint discovery, and fixed-topology all-data coefficient refit.
3. `stage_3_validate.py`: deploy PPO, symbolic, uncontrolled, or constant policies in serial Legacy CFD and evaluate the exact legacy DTW contract.
The executable July route remains:
The acceptance chain is data and wiring checks → offline discovery/Pareto diagnostics → frozen topology and coefficient refit → finite closed-loop CFD → 200-step acceptance → 400-step duration and sampled unseen-condition checks → term deletion/scaling. Offline R² helps discover structure; it does not accept a controller. Averages never override a non-finite or prematurely terminated case.
## Scientific contracts
- **Solver/model/norm:** Stage 1 and Stage 3 use LegacyCelerisLab and the frozen legacy PPO models. Runtime PPO observations use the scene's frozen `data/karman/**/norm.json` or `data/illusion/**/norm.json`; PPO inference defaults to CPU while PyCUDA owns the CFD GPU.
- **Native order:** bodies/actions are `front, upper, lower`; forces are front, upper, lower with `(x,y)` components; sensors are upper, centre, lower with `(u_x,u_y)` components. `checks/order_contract.py` is the runtime gate.
- **Causal alignment:** Stage 2 uses `causal_post_state_to_next_action`: recorded post-state `i` predicts action `i+1`. Warm-up and lag construction are trajectory-local and splits do not cross trajectories.
- **Action units:** formulas output `alpha = omega/U0`. PPO normalized actions are decoded with the scene scale and bias before fitting; Stage 3 converts formula outputs back to `omega` for CFD.
- **Mapped-shared deployment:** the canonical architecture is `alpha_F=(h_F(x)-h_F(Gx))/2`, `alpha_U=h_R(x)`, `alpha_L=-h_R(Gx)`. This imposes exact reflection symmetry; it is not a claim that PPO training was equivariant. Three independent heads are diagnostic only.
- **Metric:** `legacy_dtw_v1_abs_n_unclipped`, reported as `legacy_reference_cycle_vs_last_recorded_cycle`, is the exact acceptance metric. Its fitted circular lag is part of the historical comparison algorithm, not a physical delay.
- **Names:** Kármán scene `re_code` uses reference length `2D`, so `Re_D=re_code/2`. Illusion labels such as `1L` are historical: the stored `target_diameter` value is passed to `add_cylinder` as a radius and must not be silently relabelled as a physical diameter.
## Current claim and evidence chain
Accepted training data are `data/runs/article-joint-data-karman-20260718` (Re-code 50/100/200/400) and `data/runs/article-joint-data-illusion-20260718` (0.75L/1L/1.5L). Formula discovery, refits, accepted and rejected CFD, 400-step duration, sampled unseen points, deletion/scaling, steady calibration, and plotting are retained under `results/runs/article-*` and `results/runs/article2-*` because their manifests and parent paths are provenance dependencies.
The Kármán evidence supports a controller dominated by persistent rear counter-rotation, with secondary rear-lift feedback and weak tested front feedback. The steady sweep calibrates the rear constant's magnitude; it is not a third fitting objective. The Illusion result is a finite symmetric numerical family, but its terms are partly replaceable and it does not establish explicit target tracking. Neither result proves global symbolic optimality, causal flow mechanism, universal high-Re behavior, or distribution-wide generalization; Article2 supports only the explicitly sampled conditions.
## Active package map
- Root: `configs.py`, the three stages, this README, and `PIPELINE.md`.
- `checks/`: order and policy-replay gates.
- `utils/`: active data, feature, symmetry, metric, formula, CFD, and provenance contracts.
- `tools/`: canonical plotting/export tools (`prepare_plotting_data.py`, `telemetry_to_csv.py`, both SR plotting modules, and `export_flow_comparison.py`).
- `tests/`: CPU contract tests.
- `data/`: frozen Kármán/Illusion norms, steady calibration data, and the two accepted article data runs.
- `results/`: the evidence index and provenance-dependent `article-*`/`article2-*` families.
- `archive/`: excluded experiments, diagnostics, old run families, superseded flat surfaces, and historical code/docs. Archive paths may be non-executable.
## Verification
From the repository root:
```bash
PYTHONPATH=src conda run -n sr_env python -m pytest src/SR_analysis/tests -q
python3 -m compileall -q src/SR_analysis/configs.py src/SR_analysis/stage_1_infer.py src/SR_analysis/stage_2_fit.py src/SR_analysis/stage_3_validate.py src/SR_analysis/utils src/SR_analysis/checks src/SR_analysis/tools
git diff --check -- src/SR_analysis
```text
stage_1_infer.py -> stage_2_fit.py -> stage_3_validate.py
```
No GPU CFD is part of this verification.
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`.