# Atomizer Architecture Overview

**Version**: 1.0
**Last Updated**: 2025-12-11
**Purpose**: Comprehensive guide to understanding how Atomizer works - from session management to learning systems.

---

## Table of Contents

1. [What is Atomizer?](#1-what-is-atomizer)
2. [The Big Picture](#2-the-big-picture)
3. [Session Lifecycle](#3-session-lifecycle)
4. [Protocol Operating System (POS)](#4-protocol-operating-system-pos)
5. [Learning Atomizer Core (LAC)](#5-learning-atomizer-core-lac)
6. [Task Classification & Routing](#6-task-classification--routing)
7. [Execution Framework (AVERVS)](#7-execution-framework-avervs)
8. [Optimization Flow](#8-optimization-flow)
9. [Knowledge Accumulation](#9-knowledge-accumulation)
10. [File Structure Reference](#10-file-structure-reference)

---

## 1. What is Atomizer?

Atomizer is an **LLM-first FEA optimization framework**. Instead of clicking through complex GUI menus, engineers describe their optimization goals in natural language, and an AI assistant (Claude) configures, runs, and analyzes the optimization.

```mermaid
graph LR
    subgraph Traditional["Traditional Workflow"]
        A1[Engineer] -->|clicks| B1[NX GUI]
        B1 -->|manual setup| C1[Optuna Config]
        C1 -->|run| D1[Results]
    end

    subgraph Atomizer["Atomizer Workflow"]
        A2[Engineer] -->|"'Minimize mass while keeping stress < 250 MPa'"| B2[Atomizer Claude]
        B2 -->|auto-configures| C2[NX + Optuna]
        C2 -->|run| D2[Results + Insights]
        D2 -->|learns| B2
    end

    style Atomizer fill:#e1f5fe
```

**Core Philosophy**: LLM-driven FEA optimization.

---

## 2. The Big Picture

```mermaid
graph TB
    subgraph User["👤 Engineer"]
        U1[Natural Language Request]
    end

    subgraph Claude["🤖 Atomizer Claude"]
        C1[Session Manager]
        C2[Protocol Router]
        C3[Task Executor]
        C4[Learning System]
    end

    subgraph POS["📚 Protocol Operating System"]
        P1[Bootstrap Layer]
        P2[Operations Layer]
        P3[System Layer]
        P4[Extensions Layer]
    end

    subgraph LAC["🧠 Learning Atomizer Core"]
        L1[Optimization Memory]
        L2[Session Insights]
        L3[Skill Evolution]
    end

    subgraph Engine["⚙️ Optimization Engine"]
        E1[NX Open API]
        E2[Nastran Solver]
        E3[Optuna Optimizer]
        E4[Extractors]
    end

    U1 --> C1
    C1 --> C2
    C2 --> P1
    P1 --> P2
    P2 --> P3
    C2 --> C3
    C3 --> Engine
    C3 --> C4
    C4 --> LAC
    LAC -.->|prior knowledge| C2

    style Claude fill:#fff3e0
    style LAC fill:#e8f5e9
    style POS fill:#e3f2fd
```

---

## 3. Session Lifecycle

Every Claude session follows a structured lifecycle:

```mermaid
stateDiagram-v2
    [*] --> Startup: New Session

    state Startup {
        [*] --> EnvCheck: Check conda environment
        EnvCheck --> LoadContext: Load CLAUDE.md + Bootstrap
        LoadContext --> QueryLAC: Query prior knowledge
        QueryLAC --> DetectStudy: Check for active study
        DetectStudy --> [*]
    }

    Startup --> Active: Ready

    state Active {
        [*] --> Classify: Receive request
        Classify --> Route: Determine task type
        Route --> Execute: Load protocols & execute
        Execute --> Record: Record learnings
        Record --> [*]: Ready for next
    }

    Active --> Closing: Session ending

    state Closing {
        [*] --> SaveWork: Verify work saved
        SaveWork --> RecordLAC: Record insights to LAC
        RecordLAC --> RecordOutcome: Record optimization outcomes
        RecordOutcome --> Summarize: Summarize for user
        Summarize --> [*]
    }

    Closing --> [*]: Session complete
```

### Startup Checklist

| Step | Action | Purpose |
|------|--------|---------|
| 1 | Environment check | Ensure `atomizer` conda env active |
| 2 | Load context | Read CLAUDE.md, Bootstrap |
| 3 | Query LAC | Get relevant prior learnings |
| 4 | Detect study | Check for active study context |

### Closing Checklist

| Step | Action | Purpose |
|------|--------|---------|
| 1 | Save work | Commit files, validate configs |
| 2 | Record learnings | Store failures, successes, workarounds |
| 3 | Record outcomes | Store optimization results |
| 4 | Summarize | Provide next steps to user |

---

## 4. Protocol Operating System (POS)

The POS is Atomizer's documentation architecture - a layered system that provides the right context at the right time.

```mermaid
graph TB
    subgraph Layer1["Layer 1: Bootstrap (Always Loaded)"]
        B1[00_BOOTSTRAP.md<br/>Task classification & routing]
        B2[01_CHEATSHEET.md<br/>Quick reference]
        B3[02_CONTEXT_LOADER.md<br/>What to load when]
    end

    subgraph Layer2["Layer 2: Operations (Per Task)"]
        O1[OP_01 Create Study]
        O2[OP_02 Run Optimization]
        O3[OP_03 Monitor Progress]
        O4[OP_04 Analyze Results]
        O5[OP_05 Export Data]
        O6[OP_06 Troubleshoot]
    end

    subgraph Layer3["Layer 3: System (Technical Specs)"]
        S1[SYS_10 IMSO<br/>Adaptive sampling]
        S2[SYS_11 Multi-Objective<br/>Pareto optimization]
        S3[SYS_12 Extractors<br/>Physics extraction]
        S4[SYS_13 Dashboard<br/>Real-time monitoring]
        S5[SYS_14 Neural<br/>Surrogate acceleration]
        S6[SYS_15 Method Selector<br/>Algorithm selection]
    end

    subgraph Layer4["Layer 4: Extensions (Power Users)"]
        E1[EXT_01 Create Extractor]
        E2[EXT_02 Create Hook]
        E3[EXT_03 Create Protocol]
        E4[EXT_04 Create Skill]
    end

    Layer1 --> Layer2
    Layer2 --> Layer3
    Layer3 --> Layer4

    style Layer1 fill:#e3f2fd
    style Layer2 fill:#e8f5e9
    style Layer3 fill:#fff3e0
    style Layer4 fill:#fce4ec
```

### Loading Rules

```mermaid
flowchart TD
    A[User Request] --> B{Classify Task}

    B -->|Create| C1[Load: study-creation-core.md]
    B -->|Run| C2[Load: OP_02_RUN_OPTIMIZATION.md]
    B -->|Monitor| C3[Load: OP_03_MONITOR_PROGRESS.md]
    B -->|Analyze| C4[Load: OP_04_ANALYZE_RESULTS.md]
    B -->|Debug| C5[Load: OP_06_TROUBLESHOOT.md]
    B -->|Extend| C6{Check Privilege}

    C1 --> D1{Signals?}
    D1 -->|Mirror/Zernike| E1[+ zernike-optimization.md]
    D1 -->|Neural/50+ trials| E2[+ SYS_14_NEURAL.md]
    D1 -->|Multi-objective| E3[+ SYS_11_MULTI.md]

    C6 -->|power_user| F1[Load: EXT_01 or EXT_02]
    C6 -->|admin| F2[Load: Any EXT_*]
    C6 -->|user| F3[Deny - explain]
```

---

## 5. Learning Atomizer Core (LAC)

LAC is Atomizer's persistent memory - it learns from every session.

```mermaid
graph TB
    subgraph LAC["🧠 Learning Atomizer Core"]
        subgraph OM["Optimization Memory"]
            OM1[bracket.jsonl]
            OM2[beam.jsonl]
            OM3[mirror.jsonl]
        end

        subgraph SI["Session Insights"]
            SI1[failure.jsonl<br/>What went wrong & why]
            SI2[success_pattern.jsonl<br/>What worked well]
            SI3[workaround.jsonl<br/>Known fixes]
            SI4[user_preference.jsonl<br/>User preferences]
        end

        subgraph SE["Skill Evolution"]
            SE1[suggested_updates.jsonl<br/>Protocol improvements]
        end
    end

    subgraph Session["Current Session"]
        S1[Query prior knowledge]
        S2[Execute tasks]
        S3[Record learnings]
    end

    S1 -->|read| LAC
    S3 -->|write| LAC
    LAC -.->|informs| S2

    style LAC fill:#e8f5e9
```

### LAC Data Flow

```mermaid
sequenceDiagram
    participant U as User
    participant C as Claude
    participant LAC as LAC
    participant Opt as Optimizer

    Note over C,LAC: Session Start
    C->>LAC: query_similar_optimizations("bracket", ["mass"])
    LAC-->>C: Similar studies: TPE worked 85% of time
    C->>LAC: get_relevant_insights("bracket optimization")
    LAC-->>C: Insight: "20 startup trials improves convergence"

    Note over U,Opt: During Session
    U->>C: "Optimize my bracket for mass"
    C->>C: Apply prior knowledge
    C->>Opt: Configure with TPE, 20 startup trials
    Opt-->>C: Optimization complete

    Note over C,LAC: Discovery
    C->>C: Found: CMA-ES faster for this case
    C->>LAC: record_insight("success_pattern", "CMA-ES faster for simple brackets")

    Note over C,LAC: Session End
    C->>LAC: record_optimization_outcome(study="bracket_v4", converged=true, ...)
```

### What LAC Stores

| Category | Examples | Used For |
|----------|----------|----------|
| **Optimization Memory** | Method used, convergence, trials | Recommending methods for similar problems |
| **Failures** | "CMA-ES failed on discrete targets" | Avoiding repeat mistakes |
| **Success Patterns** | "TPE with 20 startup trials converges faster" | Applying proven techniques |
| **Workarounds** | "Load _i.prt before UpdateFemodel()" | Fixing known issues |
| **Protocol Updates** | "SYS_15 should mention CMA-ES limitation" | Improving documentation |

---

## 6. Task Classification & Routing

```mermaid
flowchart TD
    A[User Request] --> B{Contains keywords?}

    B -->|"new, create, set up, optimize"| C1[CREATE]
    B -->|"run, start, execute, begin"| C2[RUN]
    B -->|"status, progress, check, trials"| C3[MONITOR]
    B -->|"results, best, compare, pareto"| C4[ANALYZE]
    B -->|"error, failed, not working, help"| C5[DEBUG]
    B -->|"what is, how does, explain"| C6[EXPLAIN]
    B -->|"create extractor, add hook"| C7[EXTEND]

    C1 --> D1[OP_01 + study-creation-core]
    C2 --> D2[OP_02]
    C3 --> D3[OP_03]
    C4 --> D4[OP_04]
    C5 --> D5[OP_06]
    C6 --> D6[Relevant SYS_*]
    C7 --> D7{Privilege?}

    D7 -->|user| E1[Explain limitation]
    D7 -->|power_user+| E2[EXT_01 or EXT_02]

    style C1 fill:#c8e6c9
    style C2 fill:#bbdefb
    style C3 fill:#fff9c4
    style C4 fill:#d1c4e9
    style C5 fill:#ffccbc
    style C6 fill:#b2ebf2
    style C7 fill:#f8bbd9
```

---

## 7. Execution Framework (AVERVS)

Every task follows the AVERVS pattern:

```mermaid
graph LR
    A[Announce] --> V1[Validate]
    V1 --> E[Execute]
    E --> R[Report]
    R --> V2[Verify]
    V2 --> S[Suggest]

    style A fill:#e3f2fd
    style V1 fill:#fff3e0
    style E fill:#e8f5e9
    style R fill:#fce4ec
    style V2 fill:#f3e5f5
    style S fill:#e0f2f1
```

### AVERVS in Action

```mermaid
sequenceDiagram
    participant U as User
    participant C as Claude
    participant NX as NX/Solver

    U->>C: "Create a study for my bracket"

    Note over C: A - Announce
    C->>U: "I'm going to analyze your model to discover expressions and setup"

    Note over C: V - Validate
    C->>C: Check: .prt exists? .sim exists? _i.prt present?
    C->>U: "✓ All required files present"

    Note over C: E - Execute
    C->>NX: Run introspection script
    NX-->>C: Expressions, constraints, solutions

    Note over C: R - Report
    C->>U: "Found 12 expressions, 3 are design variable candidates"

    Note over C: V - Verify
    C->>C: Validate generated config
    C->>U: "✓ Config validation passed"

    Note over C: S - Suggest
    C->>U: "Ready to run. Want me to:<br/>1. Start optimization now?<br/>2. Adjust parameters first?"
```

---

## 8. Optimization Flow

```mermaid
flowchart TB
    subgraph Setup["1. Setup Phase"]
        A1[User describes goal] --> A2[Claude analyzes model]
        A2 --> A3[Query LAC for similar studies]
        A3 --> A4[Generate optimization_config.json]
        A4 --> A5[Create run_optimization.py]
    end

    subgraph Run["2. Optimization Loop"]
        B1[Optuna suggests parameters] --> B2[Update NX expressions]
        B2 --> B3[Update FEM mesh]
        B3 --> B4[Solve with Nastran]
        B4 --> B5[Extract results via Extractors]
        B5 --> B6[Report to Optuna]
        B6 --> B7{More trials?}
        B7 -->|Yes| B1
        B7 -->|No| C1
    end

    subgraph Analyze["3. Analysis Phase"]
        C1[Load study.db] --> C2[Find best trials]
        C2 --> C3[Generate visualizations]
        C3 --> C4[Create STUDY_REPORT.md]
    end

    subgraph Learn["4. Learning Phase"]
        D1[Record outcome to LAC]
        D2[Record insights discovered]
        D3[Suggest protocol updates]
    end

    Setup --> Run
    Run --> Analyze
    Analyze --> Learn

    style Setup fill:#e3f2fd
    style Run fill:#e8f5e9
    style Analyze fill:#fff3e0
    style Learn fill:#f3e5f5
```

### Extractors

Extractors bridge FEA results to optimization objectives:

```mermaid
graph LR
    subgraph FEA["FEA Output"]
        F1[OP2 File]
        F2[BDF File]
        F3[NX Part]
    end

    subgraph Extractors["Extractor Library"]
        E1[E1: Displacement]
        E2[E2: Frequency]
        E3[E3: Stress]
        E4[E4: Mass BDF]
        E5[E5: Mass CAD]
        E8[E8: Zernike WFE]
    end

    subgraph Output["Optimization Values"]
        O1[Objective Value]
        O2[Constraint Value]
    end

    F1 --> E1
    F1 --> E2
    F1 --> E3
    F2 --> E4
    F3 --> E5
    F1 --> E8

    E1 --> O1
    E2 --> O2
    E3 --> O2
    E4 --> O1
    E5 --> O1
    E8 --> O1
```

---

## 9. Knowledge Accumulation

Atomizer gets smarter over time:

```mermaid
graph TB
    subgraph Sessions["Claude Sessions Over Time"]
        S1[Session 1<br/>Bracket optimization]
        S2[Session 2<br/>Beam optimization]
        S3[Session 3<br/>Mirror optimization]
        S4[Session N<br/>New optimization]
    end

    subgraph LAC["LAC Knowledge Base"]
        K1[Optimization<br/>Patterns]
        K2[Failure<br/>Solutions]
        K3[Method<br/>Recommendations]
    end

    S1 -->|record| LAC
    S2 -->|record| LAC
    S3 -->|record| LAC
    LAC -->|inform| S4

    subgraph Improvement["Continuous Improvement"]
        I1[Better method selection]
        I2[Faster convergence]
        I3[Fewer failures]
    end

    LAC --> Improvement

    style LAC fill:#e8f5e9
    style Improvement fill:#fff3e0
```

### Example: Method Selection Improvement

```mermaid
graph LR
    subgraph Before["Without LAC"]
        B1[New bracket optimization]
        B2[Default: TPE]
        B3[Maybe suboptimal]
    end

    subgraph After["With LAC"]
        A1[New bracket optimization]
        A2[Query LAC:<br/>'bracket mass optimization']
        A3[LAC returns:<br/>'CMA-ES 30% faster for<br/>simple brackets']
        A4[Use CMA-ES]
        A5[Faster convergence]
    end

    B1 --> B2 --> B3
    A1 --> A2 --> A3 --> A4 --> A5

    style After fill:#e8f5e9
```

---

## 10. File Structure Reference

```
Atomizer/
├── CLAUDE.md                        # 🎯 Main instructions (read first)
│
├── .claude/
│   ├── skills/
│   │   ├── 00_BOOTSTRAP.md          # Task classification
│   │   ├── 01_CHEATSHEET.md         # Quick reference
│   │   ├── 02_CONTEXT_LOADER.md     # What to load when
│   │   ├── core/
│   │   │   └── study-creation-core.md
│   │   └── modules/
│   │       ├── learning-atomizer-core.md  # LAC documentation
│   │       ├── zernike-optimization.md
│   │       └── neural-acceleration.md
│   └── commands/                     # Slash commands
│
├── knowledge_base/
│   ├── lac.py                        # LAC implementation
│   └── lac/                          # LAC data storage
│       ├── optimization_memory/      # What worked for what
│       ├── session_insights/         # Learnings
│       └── skill_evolution/          # Protocol updates
│
├── docs/protocols/
│   ├── operations/                   # OP_01 - OP_06
│   ├── system/                       # SYS_10 - SYS_15
│   └── extensions/                   # EXT_01 - EXT_04
│
├── optimization_engine/
│   ├── extractors/                   # Physics extraction
│   ├── hooks/                        # NX automation
│   └── gnn/                          # Neural surrogates
│
└── studies/                          # User studies
    └── {study_name}/
        ├── 1_setup/
        │   ├── model/                # NX files
        │   └── optimization_config.json
        ├── 2_results/
        │   └── study.db              # Optuna database
        └── run_optimization.py
```

---

## Quick Reference: The Complete Flow

```mermaid
graph TB
    subgraph Start["🚀 Session Start"]
        A1[Load CLAUDE.md]
        A2[Load Bootstrap]
        A3[Query LAC]
    end

    subgraph Work["⚙️ During Session"]
        B1[Classify request]
        B2[Load protocols]
        B3[Execute AVERVS]
        B4[Record insights]
    end

    subgraph End["🏁 Session End"]
        C1[Save work]
        C2[Record to LAC]
        C3[Summarize]
    end

    Start --> Work --> End

    subgraph Legend["Legend"]
        L1[📚 POS: What to do]
        L2[🧠 LAC: What we learned]
        L3[⚡ AVERVS: How to do it]
    end
```

---

## Summary

| Component | Purpose | Key Files |
|-----------|---------|-----------|
| **CLAUDE.md** | Main instructions | `CLAUDE.md` |
| **Bootstrap** | Task routing | `00_BOOTSTRAP.md` |
| **POS** | Protocol system | `docs/protocols/` |
| **LAC** | Learning system | `knowledge_base/lac.py` |
| **AVERVS** | Execution pattern | Embedded in protocols |
| **Extractors** | Physics extraction | `optimization_engine/extractors/` |

**The key insight**: Atomizer is not just an optimization tool - it's a *learning* optimization tool that gets better with every session.

---

*Atomizer: Where engineers talk, AI optimizes, and every session makes the next one better.*