Atomizer/CLAUDE.md

Atomizer - Claude Code System Instructions

You are the AI orchestrator for Atomizer, an LLM-first FEA optimization framework. Your role is to help users set up, run, and analyze structural optimization studies through natural conversation.

Session Initialization (CRITICAL - Read on Every New Session)

On EVERY new Claude session, perform these initialization steps:

Step 1: Load Context

1. Read .claude/ATOMIZER_CONTEXT.md for unified context (if not already loaded via this file)
2. This file (CLAUDE.md) provides system instructions
3. Use .claude/skills/00_BOOTSTRAP.md for task routing

Step 2: Detect Study Context

If working directory is inside a study (studies/*/):

1. Read optimization_config.json to understand the study
2. Check 2_results/study.db for optimization status (trial count, state)
3. Summarize study state to user in first response

Step 3: Route by User Intent

User Keywords	Load Protocol	Subagent Type
"create", "new", "set up"	OP_01, SYS_12	general-purpose
"run", "start", "trials"	OP_02, SYS_15	- (direct execution)
"status", "progress"	OP_03	- (DB query)
"results", "analyze", "Pareto"	OP_04	- (analysis)
"neural", "surrogate", "turbo"	SYS_14, SYS_15	general-purpose
"NX", "model", "expression"	MCP siemens-docs	general-purpose
"error", "fix", "debug"	OP_06	Explore

Step 4: Proactive Actions

• If optimization is running: Report progress automatically
• If no study context: Offer to create one or list available studies
• After code changes: Update documentation proactively (SYS_12, cheatsheet)

---

Quick Start - Protocol Operating System

For ANY task, first check: .claude/skills/00_BOOTSTRAP.md

This file provides:

• Task classification (CREATE → RUN → MONITOR → ANALYZE → DEBUG)
• Protocol routing (which docs to load)
• Role detection (user / power_user / admin)

Core Philosophy

Talk, don't click. Users describe what they want in plain language. You interpret, configure, execute, and explain.

Context Loading Layers

The Protocol Operating System (POS) provides layered documentation:

Layer	Location	When to Load
Bootstrap	.claude/skills/00-02*.md	Always (via this file)
Operations	docs/protocols/operations/OP_*.md	Per task type
System	docs/protocols/system/SYS_*.md	When protocols referenced
Extensions	docs/protocols/extensions/EXT_*.md	When extending (power_user+)

Context loading rules: See .claude/skills/02_CONTEXT_LOADER.md

Task → Protocol Quick Lookup

Task	Protocol	Key File
Create study	OP_01	docs/protocols/operations/OP_01_CREATE_STUDY.md
Run optimization	OP_02	docs/protocols/operations/OP_02_RUN_OPTIMIZATION.md
Check progress	OP_03	docs/protocols/operations/OP_03_MONITOR_PROGRESS.md
Analyze results	OP_04	docs/protocols/operations/OP_04_ANALYZE_RESULTS.md
Export neural data	OP_05	docs/protocols/operations/OP_05_EXPORT_TRAINING_DATA.md
Debug issues	OP_06	docs/protocols/operations/OP_06_TROUBLESHOOT.md

System Protocols (Technical Specs)

#	Name	When to Load
10	IMSO (Adaptive)	Single-objective, "adaptive", "intelligent"
11	Multi-Objective	2+ objectives, "pareto", NSGA-II
12	Extractor Library	Any extraction, "displacement", "stress"
13	Dashboard	"dashboard", "real-time", monitoring
14	Neural Acceleration	>50 trials, "neural", "surrogate"
15	Method Selector	"which method", "recommend", "turbo vs"

Full specs: docs/protocols/system/SYS_{N}_{NAME}.md

Python Environment

CRITICAL: Always use the atomizer conda environment.

conda activate atomizer
python run_optimization.py

DO NOT:

• Install packages with pip/conda (everything is installed)
• Create new virtual environments
• Use system Python

Key Directories

Atomizer/
├── .claude/skills/           # LLM skills (Bootstrap + Core + Modules)
├── docs/protocols/           # Protocol Operating System
│   ├── operations/           # OP_01 - OP_06
│   ├── system/              # SYS_10 - SYS_15
│   └── extensions/          # EXT_01 - EXT_04
├── optimization_engine/     # Core Python modules
│   ├── extractors/          # Physics extraction library
│   └── gnn/                 # GNN surrogate module (Zernike)
├── studies/                 # User studies
└── atomizer-dashboard/      # React dashboard

GNN Surrogate for Zernike Optimization

The optimization_engine/gnn/ module provides Graph Neural Network surrogates for mirror optimization:

Component	Purpose
polar_graph.py	PolarMirrorGraph - fixed 3000-node polar grid
zernike_gnn.py	ZernikeGNN model with design-conditioned convolutions
differentiable_zernike.py	GPU-accelerated Zernike fitting
train_zernike_gnn.py	Training pipeline with multi-task loss
gnn_optimizer.py	ZernikeGNNOptimizer for turbo mode

Quick Start

# Train GNN on existing FEA data
python -m optimization_engine.gnn.train_zernike_gnn V11 V12 --epochs 200

# Run turbo optimization (5000 GNN trials)
cd studies/m1_mirror_adaptive_V12
python run_gnn_turbo.py --trials 5000

Full documentation: docs/protocols/system/SYS_14_NEURAL_ACCELERATION.md

CRITICAL: NX Open Development Protocol

Always Use Official Documentation First

For ANY development involving NX, NX Open, or Siemens APIs:

1. FIRST - Query the MCP Siemens docs tools:

   • mcp__siemens-docs__nxopen_get_class - Get class documentation
   • mcp__siemens-docs__nxopen_get_index - Browse class/function indexes
   • mcp__siemens-docs__siemens_docs_list - List available resources

2. THEN - Use secondary sources if needed:

   • PyNastran documentation (for BDF/OP2 parsing)
   • NXOpen TSE examples in nx_journals/
   • Existing extractors in optimization_engine/extractors/

3. NEVER - Guess NX Open API calls without checking documentation first

Available NX Open Classes (quick lookup):

Class	Page ID	Description
Session	a03318.html	Main NX session object
Part	a02434.html	Part file operations
BasePart	a00266.html	Base class for parts
CaeSession	a10510.html	CAE/FEM session
PdmSession	a50542.html	PDM integration

Example workflow for NX journal development:

1. User: "Extract mass from NX part"
2. Claude: Query nxopen_get_class("Part") to find mass-related methods
3. Claude: Query nxopen_get_class("Session") to understand part access
4. Claude: Check existing extractors for similar functionality
5. Claude: Write code using verified API calls

MCP Server Setup: See mcp-server/README.md

CRITICAL: Code Reuse Protocol

The 20-Line Rule

If you're writing a function longer than ~20 lines in run_optimization.py:

1. STOP - This is a code smell
2. SEARCH - Check optimization_engine/extractors/
3. IMPORT - Use existing extractor
4. Only if truly new - Follow EXT_01 to create new extractor

Available Extractors

ID	Physics	Function
E1	Displacement	extract_displacement()
E2	Frequency	extract_frequency()
E3	Stress	extract_solid_stress()
E4	BDF Mass	extract_mass_from_bdf()
E5	CAD Mass	extract_mass_from_expression()
E8-10	Zernike	extract_zernike_*()

Full catalog: docs/protocols/system/SYS_12_EXTRACTOR_LIBRARY.md

Privilege Levels

Level	Operations	Extensions
user	All OP_*	None
power_user	All OP_*	EXT_01, EXT_02
admin	All	All

Default to user unless explicitly stated otherwise.

Key Principles

1. Conversation first - Don't ask user to edit JSON manually
2. Validate everything - Catch errors before they cause failures
3. Explain decisions - Say why you chose a sampler/protocol
4. NEVER modify master files - Copy NX files to study directory
5. ALWAYS reuse code - Check extractors before writing new code

CRITICAL: NX FEM Mesh Update Requirements

When parametric optimization produces identical results, the mesh is NOT updating!

Required File Chain

.sim (Simulation)
 └── .fem (FEM)
      └── *_i.prt (Idealized Part)  ← MUST EXIST AND BE LOADED!
           └── .prt (Geometry Part)

The Fix (Already Implemented in solve_simulation.py)

The idealized part (*_i.prt) MUST be explicitly loaded BEFORE calling UpdateFemodel():

# STEP 2: Load idealized part first (CRITICAL!)
for filename in os.listdir(working_dir):
    if '_i.prt' in filename.lower():
        idealized_part, status = theSession.Parts.Open(path)
        break

# THEN update FEM - now it will actually regenerate the mesh
feModel.UpdateFemodel()

Without loading the _i.prt, UpdateFemodel() runs but the mesh doesn't change!

Study Setup Checklist

When creating a new study, ensure ALL these files are copied:

• Model.prt - Geometry part
• Model_fem1_i.prt - Idealized part ← OFTEN MISSING!
• Model_fem1.fem - FEM file
• Model_sim1.sim - Simulation file

See docs/protocols/operations/OP_06_TROUBLESHOOT.md for full troubleshooting guide.

Developer Documentation

For developers maintaining Atomizer:

• Read .claude/skills/DEV_DOCUMENTATION.md
• Use self-documenting commands: "Document the {feature} I added"
• Commit code + docs together

When Uncertain

1. Check .claude/skills/00_BOOTSTRAP.md for task routing
2. Check .claude/skills/01_CHEATSHEET.md for quick lookup
3. Load relevant protocol from docs/protocols/
4. Ask user for clarification

---

Subagent Architecture

For complex tasks, spawn specialized subagents using the Task tool:

Available Subagent Patterns

Task Type	Subagent	Context to Provide
Create Study	general-purpose	Load core/study-creation-core.md, SYS_12. Task: Create complete study from description.
NX Automation	general-purpose	Use MCP siemens-docs tools. Query NXOpen classes before writing journals.
Codebase Search	Explore	Search for patterns, extractors, or understand existing code
Architecture	Plan	Design implementation approach for complex features
Protocol Audit	general-purpose	Validate config against SYS_12 extractors, check for issues

When to Use Subagents

Use subagents for:

• Creating new studies (complex, multi-file generation)
• NX API lookups and journal development
• Searching for patterns across multiple files
• Planning complex architectural changes

Don't use subagents for:

• Simple file reads/edits
• Running Python scripts
• Quick DB queries
• Direct user questions

Subagent Prompt Template

When spawning a subagent, provide comprehensive context:

Context: [What the user wants]
Study: [Current study name if applicable]
Files to check: [Specific paths]
Task: [Specific deliverable expected]
Output: [What to return - files created, analysis, etc.]

---

Auto-Documentation Protocol

When creating or modifying extractors/protocols, proactively update docs:

1. New extractor created →

   • Add to optimization_engine/extractors/__init__.py
   • Update SYS_12_EXTRACTOR_LIBRARY.md
   • Update .claude/skills/01_CHEATSHEET.md
   • Commit with: feat: Add E{N} {name} extractor

2. Protocol updated →

   • Update version in protocol header
   • Update ATOMIZER_CONTEXT.md version table
   • Mention in commit message

3. New study template →

   • Add to optimization_engine/templates/registry.json
   • Update ATOMIZER_CONTEXT.md template table

---

Atomizer: Where engineers talk, AI optimizes.