Atomizer/hq/skills/atomizer-company/LAC_CRITICAL.md

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