CreativeEngineer commited on
Commit
011c17d
·
1 Parent(s): 3cb52d4

docs: tighten p1 contract notes

Browse files
docs/P1_ENV_CONTRACT_V1.md CHANGED
@@ -1,6 +1,6 @@
1
  # P1 Environment Contract V1
2
 
3
- **Status:** Technical implementation plan
4
  **Role:** Supporting spec for the `P1` environment contract
5
  **SSOT relationship:** This file refines [FUSION_DESIGN_LAB_PLAN_V2.md](FUSION_DESIGN_LAB_PLAN_V2.md). If this file conflicts with the planning SSOT, update both in the same task.
6
 
@@ -17,6 +17,7 @@ The central change is now explicit:
17
 
18
  - the current upstream 3-knob rotating-ellipse family is blocked on P1 triangularity under the real verifier path
19
  - the next environment contract must repair parameterization before more reward iteration or heuristic work
 
20
 
21
  ## Verified Blocker
22
 
@@ -59,6 +60,12 @@ Keep three layers separate:
59
 
60
  `server/physics.py` should expose a boundary-based verifier surface.
61
 
 
 
 
 
 
 
62
  Target functions:
63
 
64
  - `build_initial_boundary(...) -> SurfaceRZFourier`
@@ -120,6 +127,14 @@ For `run`, the controllable parameter should be one of:
120
 
121
  This keeps the environment human-playable and aligned with the historical low-dimensional P1 path.
122
 
 
 
 
 
 
 
 
 
123
  ## Observation Contract
124
 
125
  The observation should stay metric-centered and human-readable.
@@ -150,6 +165,11 @@ This can be done either by:
150
 
151
  The minimum requirement is that a reader can tell whether a metric came from low-fi `run` or high-fi `submit`.
152
 
 
 
 
 
 
153
  ## Reward V0
154
 
155
  Keep reward mostly scalar and verifier-driven.
@@ -217,7 +237,7 @@ before tuning reward further
217
  2. Split boundary construction from official boundary evaluation in [server/physics.py](../server/physics.py).
218
  3. Update the action and state schema in [fusion_lab/models.py](../fusion_lab/models.py).
219
  4. Update the episode loop and observation labeling in [server/environment.py](../server/environment.py).
220
- 5. Update the task summary in [server/app.py](../server/app.py).
221
  6. Add explicit VMEC failure semantics in [server/environment.py](../server/environment.py).
222
  7. Run a small measured sweep to choose ranges, deltas, and reset seeds.
223
  8. Freeze 1-2 repaired low-dimensional fixtures.
 
1
  # P1 Environment Contract V1
2
 
3
+ **Status:** Technical revision plan over a partial implementation
4
  **Role:** Supporting spec for the `P1` environment contract
5
  **SSOT relationship:** This file refines [FUSION_DESIGN_LAB_PLAN_V2.md](FUSION_DESIGN_LAB_PLAN_V2.md). If this file conflicts with the planning SSOT, update both in the same task.
6
 
 
17
 
18
  - the current upstream 3-knob rotating-ellipse family is blocked on P1 triangularity under the real verifier path
19
  - the next environment contract must repair parameterization before more reward iteration or heuristic work
20
+ - the current repo still exposes the old 3-knob surface and needs to be revised to this 4-knob target
21
 
22
  ## Verified Blocker
23
 
 
60
 
61
  `server/physics.py` should expose a boundary-based verifier surface.
62
 
63
+ Current repo state:
64
+
65
+ - the live code still exposes `evaluate_params(...)`
66
+ - boundary construction and evaluation are not yet split cleanly
67
+ - the verifier rewrite in this file is still pending
68
+
69
  Target functions:
70
 
71
  - `build_initial_boundary(...) -> SurfaceRZFourier`
 
127
 
128
  This keeps the environment human-playable and aligned with the historical low-dimensional P1 path.
129
 
130
+ Current repo state:
131
+
132
+ - the live action schema still exposes only:
133
+ - `aspect_ratio`
134
+ - `elongation`
135
+ - `rotational_transform`
136
+ - the fourth low-dimensional control is still pending
137
+
138
  ## Observation Contract
139
 
140
  The observation should stay metric-centered and human-readable.
 
165
 
166
  The minimum requirement is that a reader can tell whether a metric came from low-fi `run` or high-fi `submit`.
167
 
168
+ Current repo state:
169
+
170
+ - the live observation surface still presents a single `p1_score` / `p1_feasibility` view
171
+ - the environment and `/task` surface still need an explicit low-fi vs high-fi distinction
172
+
173
  ## Reward V0
174
 
175
  Keep reward mostly scalar and verifier-driven.
 
237
  2. Split boundary construction from official boundary evaluation in [server/physics.py](../server/physics.py).
238
  3. Update the action and state schema in [fusion_lab/models.py](../fusion_lab/models.py).
239
  4. Update the episode loop and observation labeling in [server/environment.py](../server/environment.py).
240
+ 5. Update the task summary and public action description in [server/app.py](../server/app.py).
241
  6. Add explicit VMEC failure semantics in [server/environment.py](../server/environment.py).
242
  7. Run a small measured sweep to choose ranges, deltas, and reset seeds.
243
  8. Freeze 1-2 repaired low-dimensional fixtures.
docs/P1_PARAMETERIZATION_DEEPDIVE.md CHANGED
@@ -1,7 +1,7 @@
1
  # P1 Parameterization Deep-Dive
2
 
3
  **Date:** 2026-03-07
4
- **Status:** Findings complete. Implementation pending.
5
 
6
  This document records the investigation into why the current 3-knob rotating-ellipse
7
  environment cannot produce P1-feasible designs, what the original winning session
@@ -136,7 +136,7 @@ n_field_periods = 3
136
  mpol = 3, ntor = 3
137
  ```
138
 
139
- **Result (reproduced twice):**
140
 
141
  ```
142
  Total configs: 256
@@ -305,7 +305,8 @@ constraint-satisfaction and basic optimization, not a path to the leaderboard.
305
 
306
  ### Agreed anti-overfitting levers
307
 
308
- 1. **Multiple reset seeds** (3-10 starting configurations with bounded jitter)
 
309
  2. **Held-out evaluation seeds** (test generalization, not memorization)
310
  3. **Reward based on official scalars only** (feasibility + objective, not per-constraint)
311
  4. **Domain knowledge in initial state, not reward** (good baseline params in `reset()`,
@@ -357,7 +358,7 @@ This plan was cross-validated with an independent agent that:
357
 
358
  | Pushback | Verdict | Resolution |
359
  |----------|---------|------------|
360
- | "10/228 feasible is unverified" | **Refuted.** Reproduced exactly twice in live execution. | 256 total, 228 evaluated, 10 feasible. |
361
  | "rt=1.8 comfortably feasible is too strong" | **Partially valid.** 44% crash rate at 1.8. | rt=1.6 is the true sweet spot: 0% crashes, 6 feasible. |
362
  | "Delta values are design proposals, not facts" | **Valid.** | Defer to post-build playtesting. |
363
  | "Seed pool not empirically validated" | **Valid.** | Methodology sound, execution pending. |
@@ -396,6 +397,7 @@ The 4-knob boundary construction, as implemented in the original
396
  ```python
397
  from constellaration.initial_guess import generate_rotating_ellipse
398
  from constellaration.geometry import surface_rz_fourier
 
399
  import numpy as np
400
 
401
  def build_boundary(aspect_ratio, elongation, rotational_transform, tri_scale, nfp=3):
 
1
  # P1 Parameterization Deep-Dive
2
 
3
  **Date:** 2026-03-07
4
+ **Status:** Findings complete. Partial implementation exists; parameterization repair pending.
5
 
6
  This document records the investigation into why the current 3-knob rotating-ellipse
7
  environment cannot produce P1-feasible designs, what the original winning session
 
136
  mpol = 3, ntor = 3
137
  ```
138
 
139
+ **Result from the recorded sweep:**
140
 
141
  ```
142
  Total configs: 256
 
305
 
306
  ### Agreed anti-overfitting levers
307
 
308
+ 1. **Multiple frozen reset seeds first** (start with exact seeds; add bounded jitter only
309
+ if memorization becomes a real problem)
310
  2. **Held-out evaluation seeds** (test generalization, not memorization)
311
  3. **Reward based on official scalars only** (feasibility + objective, not per-constraint)
312
  4. **Domain knowledge in initial state, not reward** (good baseline params in `reset()`,
 
358
 
359
  | Pushback | Verdict | Resolution |
360
  |----------|---------|------------|
361
+ | "10/228 feasible is unverified" | **Partially addressed.** The recorded sweep found feasible points in the repaired 4-knob family, but this exact count should be treated as an artifact-backed result, not a free-floating fact. | Keep the sweep note, and link or preserve the underlying artifact if this exact count will be cited elsewhere. |
362
  | "rt=1.8 comfortably feasible is too strong" | **Partially valid.** 44% crash rate at 1.8. | rt=1.6 is the true sweet spot: 0% crashes, 6 feasible. |
363
  | "Delta values are design proposals, not facts" | **Valid.** | Defer to post-build playtesting. |
364
  | "Seed pool not empirically validated" | **Valid.** | Methodology sound, execution pending. |
 
397
  ```python
398
  from constellaration.initial_guess import generate_rotating_ellipse
399
  from constellaration.geometry import surface_rz_fourier
400
+ from constellaration.geometry.surface_rz_fourier import SurfaceRZFourier
401
  import numpy as np
402
 
403
  def build_boundary(aspect_ratio, elongation, rotational_transform, tri_scale, nfp=3):