# LAC Critical Lessons — NEVER FORGET

These are hard-won insights from past optimization sessions. Violating any of these will cause failures.

## NX Safety (CRITICAL)
- **NEVER kill ugraf.exe directly** → use `NXSessionManager.close_nx_if_allowed()`
- **PowerShell for NX journals** → NEVER use `cmd /c`
- **Always load `*_i.prt` before `UpdateFemodel()`** → mesh won't update without the idealized part
- **File chain must be intact:** `.sim → .fem → *_i.prt → .prt` (ALL must be present)

## Optimization (CRITICAL)
- **CMA-ES doesn't evaluate x0 first** → always call `enqueue_trial(x0)` to evaluate baseline
- **Surrogate + L-BFGS = DANGEROUS** → gradient descent finds fake optima on surrogate surface
- **NEVER rewrite `run_optimization.py` from scratch** → ALWAYS copy a working template (V15 NSGA-II is gold standard)
- **Relative WFE math:** use `extract_relative()` (node-by-node subtraction) → NOT `abs(RMS_a - RMS_b)` (wrong math!)

## File Management (IMPORTANT)
- **Trial folders:** `trial_NNNN/` — zero-padded, never reused, never overwritten
- **Always copy working studies** — never modify originals
- **Output paths must be relative** — no absolute Windows/Linux paths (Syncthing-compatible)
- **Never delete trial data mid-run** — archive after study is complete

## Algorithm Selection (REFERENCE)
| Variables | Landscape | Recommended | Notes |
|-----------|-----------|-------------|-------|
| < 5 | Smooth | Nelder-Mead or COBYLA | Simple, fast convergence |
| 5-20 | Noisy | CMA-ES | Robust, population-based |
| > 20 | Any | Bayesian (Optuna TPE) | Efficient with many variables |
| Multi-obj | Any | NSGA-II or MOEA/D | Pareto front generation |
| With surrogate | Expensive eval | GNN surrogate + CMA-ES | Reduce simulation count |

## Common Failures
| Symptom | Cause | Fix |
|---------|-------|-----|
| Mesh not updating | Missing `*_i.prt` load | Load idealized part first |
| NX crashes on journal | Using `cmd /c` | Switch to PowerShell |
| Baseline trial missing | CMA-ES skips x0 | Explicitly enqueue baseline |
| Optimization finds unphysical optimum | Surrogate + gradient | Switch to CMA-ES or add validation |
| Study can't resume | Absolute paths in script | Use relative paths |