Atomizer/projects/isogrid-dev-plate/playbooks/01_FIRST_RUN.md

# Playbook 01 — First Run: Campaign 01 (TPE v1)

**Study:** `studies/01_v1_tpe`
**Algorithm:** Optuna TPE, 200 trials
**Constraint:** Stress only — σ_max ≤ 100.6 MPa (no displacement constraint)
**Expected runtime:** ~8–10 hours

---

## Pre-conditions

Before starting, verify:
- [ ] NX DesigncenterNX2512 is installed
- [ ] `atomizer` conda environment is active
- [ ] You are running from the `Atomizer/` root directory
- [ ] NX files in `studies/01_v1_tpe/1_setup/model/` (check with step 1)

---

## Step 1 — Pre-flight Check

Run the pre-flight script to verify all files, imports, and NX are ready:

```bash
C:\Users\antoi\anaconda3\envs\atomizer\python.exe \
  projects/isogrid-dev-plate/studies/01_v1_tpe/check_preflight.py
```

Expected output:
```
Pre-flight checks
============================================================

Model files:
  [OK]      Geometry part (X.X MB)
  [OK]      Idealized part (CRITICAL) (X.X MB)
  [OK]      FEM file (X.X MB)
  [OK]      Simulation file (X.X MB)
  [OK]      Sandbox 1 geometry (X.X MB)
  [OK]      Sandbox 2 geometry (X.X MB)

NX:
  [OK]      run_journal.exe: C:/Program Files/Siemens/DesigncenterNX2512/NXBIN/run_journal.exe

Python Brain:
  [OK]      optimization_engine.isogrid
            Material: AL7075-T6  sigma_allow=100.6 MPa

Extractors:
  [OK]      extract_part_mass_material + extract_solid_stress

============================================================
All checks PASSED — ready to run run_optimization.py
```

If anything is `[MISSING]`, resolve before continuing.

---

## Step 2 — Launch Campaign 01

```bash
C:\Users\antoi\anaconda3\envs\atomizer\python.exe \
  projects/isogrid-dev-plate/studies/01_v1_tpe/run_optimization.py
```

The script will print a header:
```
======================================================================
  Isogrid Dev Plate — Mass Minimization Study 01 (TPE v1)
======================================================================
  Material:    AL7075-T6
  σ_yield:     503.0 MPa
  σ_allow:     100.6 MPa  (SF = 5)
  Trials:      200
  DB:          ...3_results/study.db
```

Then iterate:
```
--- Trial 0 ---
  η₀=0.123  α=0.875  β=0.412  γ_s=0.234  R₀=45.2  R_e=18.7  s_min=12.3  s_max=41.5
  [Brain] sandbox_1: 104 pockets  valid=True  mass_est≈2420g
  [Brain] sandbox_2: 31 pockets   valid=True  mass_est≈310g
  [Brain] Total pockets: 135
  [NX] Running journal: import_profile.py
  [NX] OK in 18.3s
  [NX] Running journal: solve_simulation.py
  [NX] OK in 74.2s
  [Extract] Mass: 2.731 kg  (2731.0 g)
  [Extract] Max stress: 83.47 MPa  (allow=100.6  SF=6.02)
  [Obj] mass=2.7310 kg  penalty=0.00  obj=2.7310  feasible=True
```

---

## Step 3 — Monitor Progress

### Option A: Console output
Watch the terminal. Each trial prints mass, stress, and objective.

### Option B: Optuna dashboard
```bash
C:\Users\antoi\anaconda3\envs\atomizer\python.exe -m optuna-dashboard \
  sqlite:///projects/isogrid-dev-plate/studies/01_v1_tpe/3_results/study.db
```
Then open http://localhost:8080 in a browser.

### Option C: Trial folders
Each completed trial creates:
```
studies/01_v1_tpe/2_iterations/trial_NNNN/
├── params.json          ← sampled design variables
├── results.json         ← mass, stress, SF, objective
├── rib_profile_sandbox_1.json   ← rib geometry for this trial
└── rib_profile_sandbox_2.json
```

---

## Step 4 — If a Trial Fails

Failures return a large penalty (`1e6`) and are logged in Optuna with `error` user attribute.
The study will **continue automatically** to the next trial.

To see which trials failed after the run:
```python
import optuna
study = optuna.load_study(
    study_name="isogrid_01_v1_tpe",
    storage="sqlite:///studies/01_v1_tpe/3_results/study.db"
)
failed = [t for t in study.trials if t.user_attrs.get("error")]
for t in failed:
    print(f"Trial {t.number}: {t.user_attrs['error']}")
```

---

## Step 5 — Resume After Interruption

The optimizer uses `load_if_exists=True` — it resumes from where it stopped.
Simply re-run the same command:

```bash
C:\Users\antoi\anaconda3\envs\atomizer\python.exe \
  projects/isogrid-dev-plate/studies/01_v1_tpe/run_optimization.py
```

It will print:
```
Resuming study: N trials already complete.
Current best: trial X  obj=2.XXXX kg  mass=2.XXXX kg  SF=X.XX
```

---

## Step 6 — After the Run

1. **Fill in `STUDY_REPORT.md`** with actual results:
   - Best trial number, mass, stress, SF
   - Convergence trial (when best was found)
   - Feasibility rate

2. **Update `CONTEXT.md` baseline mass** (Gap G-02):
   - Run `extract_part_mass_material` on the unmodified model to get solid plate baseline

3. **Record improvement:**
   - `mass_reduction = (baseline_mass - best_mass) / baseline_mass * 100`

4. **Archive if campaign is complete:**
   ```bash
   python tools/archive_study.bat  # or zip 3_results/ manually
   ```

---

## Troubleshooting

| Symptom | Likely Cause | Fix |
|---------|-------------|-----|
| `[NX] FAILED` on import journal | NX can't find model files | Check `1_setup/model/` has all 4 NX files |
| Identical stress every trial | `_i.prt` not loading | Verify `ACS_Stack_Main_Plate_Iso_project_fem2_i.prt` exists in model dir |
| `Brain ERROR` | Geometry JSON malformed | Check `geometry_sandbox_1.json` / `_2.json` in `adaptive_isogrid_data/` |
| `run_journal.exe not found` | Wrong NX version path | Confirm DesigncenterNX2512 is installed; check `check_preflight.py` |
| Very high stress (>500 MPa) | Mesh not updating | `_i.prt` must be in same directory as `.fem` |
| Trial folders not appearing | `2_iterations/` not created | Should auto-create; check for TrialManager error in console |

See also: `docs/protocols/operations/OP_06_TROUBLESHOOT.md`