Atomizer/.claude/ATOMIZER_CONTEXT.md

# Atomizer Session Context

<!--
ATOMIZER CONTEXT LOADER v1.0
This file is the SINGLE SOURCE OF TRUTH for new Claude sessions.
Load this FIRST on every new session, then route to specific protocols.
-->

## What is Atomizer?

**Atomizer** is an LLM-first FEA (Finite Element Analysis) optimization framework. Users describe optimization problems in natural language, and Claude orchestrates the entire workflow: model introspection, config generation, optimization execution, and results analysis.

**Philosophy**: Talk, don't click. Engineers describe what they want; AI handles the rest.

---

## Session Initialization Checklist

On EVERY new session, perform these steps:

### Step 1: Identify Working Directory
```
If in: c:\Users\Antoine\Atomizer\           → Project root (full capabilities)
If in: c:\Users\Antoine\Atomizer\studies\*  → Inside a study (load study context)
If elsewhere:                               → Limited context (warn user)
```

### Step 2: Detect Study Context
If working directory contains `optimization_config.json`:
1. Read the config to understand the study
2. Check `2_results/study.db` for optimization status
3. Summarize study state to user

**Python utility for study detection**:
```bash
# Get study state for current directory
python -m optimization_engine.study_state .

# Get all studies in Atomizer
python -c "from optimization_engine.study_state import get_all_studies; from pathlib import Path; [print(f'{s[\"study_name\"]}: {s[\"status\"]}') for s in get_all_studies(Path('.'))]"
```

### Step 3: Route to Task Protocol
Use keyword matching to load appropriate context:

| User Intent | Keywords | Load Protocol | Action |
|-------------|----------|---------------|--------|
| Create study | "create", "new", "set up", "optimize" | OP_01 + SYS_12 | Launch study builder |
| Run optimization | "run", "start", "execute", "trials" | OP_02 + SYS_15 | Execute optimization |
| Check progress | "status", "progress", "how many" | OP_03 | Query study.db |
| Analyze results | "results", "best", "Pareto", "analyze" | OP_04 | Generate analysis |
| Neural acceleration | "neural", "surrogate", "turbo", "NN" | SYS_14 + SYS_15 | Method selection |
| NX/CAD help | "NX", "model", "mesh", "expression" | MCP + nx-docs | Use Siemens MCP |
| Troubleshoot | "error", "failed", "fix", "debug" | OP_06 | Diagnose issues |

---

## Quick Reference

### Core Commands

```bash
# Optimization workflow
python run_optimization.py --discover    # 1 trial - model introspection
python run_optimization.py --validate    # 1 trial - verify pipeline
python run_optimization.py --test        # 3 trials - quick sanity check
python run_optimization.py --run --trials 50  # Full optimization
python run_optimization.py --resume      # Continue existing study

# Neural acceleration
python run_nn_optimization.py --turbo --nn-trials 5000  # Fast NN exploration
python -m optimization_engine.method_selector config.json study.db  # Get recommendation

# Dashboard
cd atomizer-dashboard && npm run dev     # Start at http://localhost:3003
```

### Study Structure (100% standardized)

```
study_name/
├── optimization_config.json    # Problem definition
├── run_optimization.py         # FEA optimization script
├── run_nn_optimization.py      # Neural acceleration (optional)
├── 1_setup/
│   └── model/
│       ├── Model.prt           # NX part file
│       ├── Model_sim1.sim      # NX simulation
│       └── Model_fem1.fem      # FEM definition
└── 2_results/
    ├── study.db                # Optuna database
    ├── optimization.log        # Logs
    └── turbo_report.json       # NN results (if run)
```

### Available Extractors (SYS_12)

| ID | Physics | Function | Notes |
|----|---------|----------|-------|
| E1 | Displacement | `extract_displacement()` | mm |
| E2 | Frequency | `extract_frequency()` | Hz |
| E3 | Von Mises Stress | `extract_solid_stress()` | **Specify element_type!** |
| E4 | BDF Mass | `extract_mass_from_bdf()` | kg |
| E5 | CAD Mass | `extract_mass_from_expression()` | kg |
| E8-10 | Zernike WFE | `extract_zernike_*()` | nm (mirrors) |
| E12-14 | Phase 2 | Principal stress, strain energy, SPC forces |
| E15-18 | Phase 3 | Temperature, heat flux, modal mass |

**Critical**: For stress extraction, specify element type:
- Shell (CQUAD4): `element_type='cquad4'`
- Solid (CTETRA): `element_type='ctetra'`

---

## Protocol System Overview

```
┌─────────────────────────────────────────────────────────────────┐
│ Layer 0: BOOTSTRAP (.claude/skills/00_BOOTSTRAP.md)            │
│ Purpose: Task routing, quick reference                          │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ Layer 1: OPERATIONS (docs/protocols/operations/OP_*.md)        │
│ OP_01: Create Study    OP_02: Run Optimization                  │
│ OP_03: Monitor         OP_04: Analyze Results                   │
│ OP_05: Export Data     OP_06: Troubleshoot                      │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ Layer 2: SYSTEM (docs/protocols/system/SYS_*.md)               │
│ SYS_10: IMSO (single-obj)    SYS_11: Multi-objective           │
│ SYS_12: Extractors           SYS_13: Dashboard                  │
│ SYS_14: Neural Accel         SYS_15: Method Selector            │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ Layer 3: EXTENSIONS (docs/protocols/extensions/EXT_*.md)       │
│ EXT_01: Create Extractor  EXT_02: Create Hook                   │
│ EXT_03: Create Protocol   EXT_04: Create Skill                  │
└─────────────────────────────────────────────────────────────────┘
```

---

## Subagent Routing

For complex tasks, Claude should spawn specialized subagents:

| Task | Subagent Type | Context to Load |
|------|---------------|-----------------|
| Create study from description | `general-purpose` | core/study-creation-core.md, SYS_12 |
| Explore codebase | `Explore` | (built-in) |
| Plan architecture | `Plan` | (built-in) |
| NX API lookup | `general-purpose` | Use MCP siemens-docs tools |

---

## Environment Setup

**CRITICAL**: Always use the `atomizer` conda environment:

```bash
conda activate atomizer
python run_optimization.py
```

**DO NOT**:
- Install packages with pip/conda (everything is installed)
- Create new virtual environments
- Use system Python

**NX Open Requirements**:
- NX 2506 installed at `C:\Program Files\Siemens\NX2506\`
- Use `run_journal.exe` for NX automation

---

## Template Registry

Available study templates for quick creation:

| Template | Objectives | Extractors | Example Study |
|----------|------------|------------|---------------|
| `multi_objective_structural` | mass, stress, stiffness | E1, E3, E4 | bracket_pareto_3obj |
| `frequency_optimization` | frequency, mass | E2, E4 | uav_arm_optimization |
| `mirror_wavefront` | Zernike RMS | E8-E10 | m1_mirror_zernike |
| `shell_structural` | mass, stress | E1, E3, E4 | beam_pareto_4var |
| `thermal_structural` | temperature, stress | E3, E15 | (template only) |

**Python utility for templates**:
```bash
# List all templates
python -m optimization_engine.templates

# Get template details in code
from optimization_engine.templates import get_template, suggest_template
template = suggest_template(n_objectives=2, physics_type="structural")
```

---

## Auto-Documentation Protocol

When Claude creates/modifies extractors or protocols:

1. **Code change** → Update `optimization_engine/extractors/__init__.py`
2. **Doc update** → Update `SYS_12_EXTRACTOR_LIBRARY.md`
3. **Quick ref** → Update `.claude/skills/01_CHEATSHEET.md`
4. **Commit** → Use structured message: `feat: Add E{N} {name} extractor`

---

## Key Principles

1. **Conversation first** - Don't ask user to edit JSON manually
2. **Validate everything** - Catch errors before FEA runs
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
6. **Proactive documentation** - Update docs after code changes

---

## Base Classes (Phase 2 - Code Deduplication)

New studies should use these base classes instead of duplicating code:

### ConfigDrivenRunner (FEA Optimization)
```python
# run_optimization.py - Now just ~30 lines instead of ~300
from optimization_engine.base_runner import ConfigDrivenRunner

runner = ConfigDrivenRunner(__file__)
runner.run()  # Handles --discover, --validate, --test, --run
```

### ConfigDrivenSurrogate (Neural Acceleration)
```python
# run_nn_optimization.py - Now just ~30 lines instead of ~600
from optimization_engine.generic_surrogate import ConfigDrivenSurrogate

surrogate = ConfigDrivenSurrogate(__file__)
surrogate.run()  # Handles --train, --turbo, --all
```

**Templates**: `optimization_engine/templates/run_*_template.py`

---

## Skill Registry (Phase 3 - Consolidated Skills)

All skills now have YAML frontmatter with metadata for versioning and dependency tracking.

| Skill ID | Name | Type | Version | Location |
|----------|------|------|---------|----------|
| SKILL_000 | Bootstrap | bootstrap | 2.0 | `.claude/skills/00_BOOTSTRAP.md` |
| SKILL_001 | Cheatsheet | reference | 2.0 | `.claude/skills/01_CHEATSHEET.md` |
| SKILL_002 | Context Loader | loader | 2.0 | `.claude/skills/02_CONTEXT_LOADER.md` |
| SKILL_CORE_001 | Study Creation Core | core | 2.4 | `.claude/skills/core/study-creation-core.md` |

### Deprecated Skills

| Old File | Reason | Replacement |
|----------|--------|-------------|
| `create-study.md` | Duplicate of core skill | `core/study-creation-core.md` |

### Skill Metadata Format

All skills use YAML frontmatter:
```yaml
---
skill_id: SKILL_XXX
version: X.X
last_updated: YYYY-MM-DD
type: bootstrap|reference|loader|core|module
code_dependencies:
  - path/to/code.py
requires_skills:
  - SKILL_YYY
replaces: old-skill.md  # if applicable
---
```

---

## Subagent Commands (Phase 5 - Specialized Agents)

Atomizer provides specialized subagent commands for complex tasks:

| Command | Purpose | When to Use |
|---------|---------|-------------|
| `/study-builder` | Create new optimization studies | "create study", "set up optimization" |
| `/nx-expert` | NX Open API help, model automation | "how to in NX", "update mesh" |
| `/protocol-auditor` | Validate configs and code quality | "validate config", "check study" |
| `/results-analyzer` | Analyze optimization results | "analyze results", "best solution" |

### Command Files
```
.claude/commands/
├── study-builder.md      # Create studies from descriptions
├── nx-expert.md          # NX Open / Simcenter expertise
├── protocol-auditor.md   # Config and code validation
├── results-analyzer.md   # Results analysis and reporting
└── dashboard.md          # Dashboard control
```

### Subagent Invocation Pattern
```python
# Master agent delegates to specialized subagent
Task(
    subagent_type='general-purpose',
    prompt='''
    Load context from .claude/commands/study-builder.md

    User request: "{user's request}"

    Follow the workflow in the command file.
    ''',
    description='Study builder task'
)
```

---

## Auto-Documentation (Phase 4 - Self-Expanding Knowledge)

Atomizer can auto-generate documentation from code:

```bash
# Generate all documentation
python -m optimization_engine.auto_doc all

# Generate only extractor docs
python -m optimization_engine.auto_doc extractors

# Generate only template docs
python -m optimization_engine.auto_doc templates
```

**Generated Files**:
- `docs/generated/EXTRACTORS.md` - Full extractor reference (auto-generated)
- `docs/generated/EXTRACTOR_CHEATSHEET.md` - Quick reference table
- `docs/generated/TEMPLATES.md` - Study templates reference

**When to Run Auto-Doc**:
1. After adding a new extractor
2. After modifying template registry
3. Before major releases

---

## Version Info

| Component | Version | Last Updated |
|-----------|---------|--------------|
| ATOMIZER_CONTEXT | 1.5 | 2025-12-07 |
| BaseOptimizationRunner | 1.0 | 2025-12-07 |
| GenericSurrogate | 1.0 | 2025-12-07 |
| Study State Detector | 1.0 | 2025-12-07 |
| Template Registry | 1.0 | 2025-12-07 |
| Extractor Library | 1.3 | 2025-12-07 |
| Method Selector | 2.1 | 2025-12-07 |
| Protocol System | 2.0 | 2025-12-06 |
| Skill System | 2.0 | 2025-12-07 |
| Auto-Doc Generator | 1.0 | 2025-12-07 |
| Subagent Commands | 1.0 | 2025-12-07 |

---

*Atomizer: Where engineers talk, AI optimizes.*