Atomizer/docs/QUICK_REF.md

Atomizer QUICK_REF

2-page maximum intent: fastest lookup for humans + Claude Code. If it grows, split into WORKFLOWS/* and PROTOCOLS/*.

Last updated: 2026-01-29 (Mario)

---

0) Non-negotiables (Safety / Correctness)

NX process safety

• NEVER kill ugraf.exe / user NX sessions directly.
• Only close NX using NXSessionManager.close_nx_if_allowed() (sessions we started).

Study derivation

• When creating a new study version: COPY the working run_optimization.py first. Never rewrite from scratch.

Relative WFE

• NEVER compute relative WFE as abs(RMS_a - RMS_b).
• Always use extract_relative() (node-by-node difference → Zernike fit → RMS).

CMA-ES baseline

• CmaEsSampler(x0=...) does not evaluate baseline first.
• Always study.enqueue_trial(x0) when baseline must be trial 0.

---

1) Canonical workflow order (UI + docs)

Create → Validate → Run → Analyze → Report → Deliver

Canvas is a visual validation layer. Spec is the source of truth.

---

2) Single source of truth: AtomizerSpec v2.0

• Published spec: studies/<topic>/<study>/atomizer_spec.json
• Canvas edges are for visual validation; truth is in:
  • objective.source.*
  • constraint.source.*

---

3) Save strategy (S2)

• Draft: autosaved locally (browser storage)
• Publish: explicit action that writes to atomizer_spec.json

---

4) Key folders

• optimization_engine/ core logic
• atomizer-dashboard/ UI + backend
• knowledge_base/lac/ learnings (failures/workarounds/patterns)
• studies/ studies

---

5) Session start (Claude Code)

1. Read PROJECT_STATUS.md
2. Read knowledge_base/lac/session_insights/failure.jsonl
3. Read this file (docs/QUICK_REF.md)

---

6) References

• Deep protocols: docs/protocols/
• System instructions: CLAUDE.md
• Project coordination: PROJECT_STATUS.md