# Atomizer Documentation Index

**Last Updated**: February 9, 2026  
**Project Version**: 0.5.0 (AtomizerSpec v2.0 + Atomizer-HQ Multi-Agent Team)

---

## Quick Start

### For AI Agents (Atomizer-HQ Team)
**Start here** if you're an AI agent working on client projects:

1. **[HQ Overview](hq/README.md)** — What Atomizer-HQ is and how agents work together
2. **[Project Structure](hq/PROJECT_STRUCTURE.md)** — Standard project organization  
3. **[Agent Workflows](hq/AGENT_WORKFLOWS.md)** — Who does what in the project lifecycle
4. **[Knowledge Base Conventions](hq/KB_CONVENTIONS.md)** — How to accumulate and share knowledge

### For Engineers (Core Optimization)
**Start here** if you're using Atomizer for FEA optimization:

1. **[README.md](../README.md)** - Project overview and philosophy  
2. **[Getting Started](GETTING_STARTED.md)** - Installation, first study, dashboard  
3. **[Protocol System](protocols/README.md)** - How Atomizer is organized  
4. **[Example Studies](../studies/)** - Working examples  

---

## Atomizer-HQ Agent Documentation

The multi-agent optimization team that runs client FEA projects.

### Essential HQ Docs

| Document | Purpose | Target Agents |
|----------|---------|---------------|
| **[HQ Overview](hq/README.md)** | What Atomizer-HQ is, how to use these docs | All agents |
| **[Project Structure](hq/PROJECT_STRUCTURE.md)** | Standard KB-integrated project layout | Manager, Technical Lead |  
| **[KB Conventions](hq/KB_CONVENTIONS.md)** | Knowledge Base accumulation principles | All agents |
| **[Agent Workflows](hq/AGENT_WORKFLOWS.md)** | Project lifecycle and agent handoffs | All agents |
| **[Study Conventions](hq/STUDY_CONVENTIONS.md)** | Technical study execution standards | Technical Lead, Optimizer |

### Agent Roles Quick Reference

| Agent | Role | Primary Phase | Key Responsibilities |
|-------|------|---------------|---------------------|
| 📋 **Secretary** | CEO interface | Intake | Client requirements, project initiation |
| 🏗️ **Manager** | Coordination | Breakdown | Project structure, team coordination |
| 🔧 **Technical Lead** | FEA expert | Introspection | Model setup, optimization planning |
| ⚡ **Optimizer** | Study execution | Study | FEA optimization execution |
| 📊 **Post-Processor** | Results analysis | Results | Performance analysis, insights |
| 📝 **Reporter** | Documentation | Deliverables | Client reports, final packages |

### Living Examples
- **Reference Project**: [projects/hydrotech-beam/](../projects/hydrotech-beam/) — Complete project structure
- **Project Structure**: Demonstrates KB-integrated organization and study flow
- **Knowledge Accumulation**: Shows generation-tracked knowledge evolution

---

## Core Documentation

Essential reference for understanding Atomizer's optimization framework.

### Foundation Documents

| Document | Purpose |
|----------|---------|
| **[GETTING_STARTED.md](GETTING_STARTED.md)** | Setup, first study, dashboard basics |
| **[ARCHITECTURE.md](ARCHITECTURE.md)** | System architecture, hooks, data flow |
| **[QUICK_REF.md](../QUICK_REF.md)** | Active reference guide |

### Protocol System

The Protocol Operating System (POS) provides structured workflows for optimization:

```
protocols/
├── README.md              # Protocol system overview
├── operations/            # How-to guides (OP_01-08)
│   ├── OP_01_CREATE_STUDY.md
│   ├── OP_02_RUN_OPTIMIZATION.md
│   ├── OP_03_MONITOR_PROGRESS.md
│   ├── OP_04_ANALYZE_RESULTS.md
│   ├── OP_05_EXPORT_TRAINING_DATA.md
│   ├── OP_06_TROUBLESHOOT.md
│   ├── OP_07_DISK_OPTIMIZATION.md
│   ├── OP_08_GENERATE_REPORT.md
│   └── OP_09_AGENT_COMMUNICATION.md
├── system/               # Technical specifications (SYS_10-18)
│   ├── SYS_10_IMSO.md           # Intelligent optimization
│   ├── SYS_11_MULTI_OBJECTIVE.md
│   ├── SYS_12_EXTRACTOR_LIBRARY.md
│   ├── SYS_13_DASHBOARD_TRACKING.md
│   ├── SYS_14_NEURAL_ACCELERATION.md
│   ├── SYS_15_METHOD_SELECTOR.md
│   ├── SYS_16_SELF_AWARE_TURBO.md
│   ├── SYS_17_STUDY_INSIGHTS.md
│   └── SYS_18_CONTEXT_ENGINEERING.md
└── extensions/           # Extensibility (EXT_01-04)
    ├── EXT_01_CREATE_EXTRACTOR.md
    ├── EXT_02_CREATE_HOOK.md
    ├── EXT_03_CREATE_PROTOCOL.md
    └── EXT_04_CREATE_SKILL.md
```

---

## User Guides

Practical guides for using Atomizer features (engineers + Claude Code era).

### Current User Guides

| Guide | Purpose | Status |
|-------|---------|--------|
| **[CANVAS.md](guides/CANVAS.md)** | Visual study builder (AtomizerSpec v2.0) | Active |
| **[DASHBOARD.md](guides/DASHBOARD.md)** | Dashboard overview and features | Active |
| **[NEURAL_FEATURES_COMPLETE.md](guides/NEURAL_FEATURES_COMPLETE.md)** | Neural acceleration guide | Active |
| **[NEURAL_WORKFLOW_TUTORIAL.md](guides/NEURAL_WORKFLOW_TUTORIAL.md)** | Data → Training → Optimization | Active |
| **[hybrid_mode.md](guides/hybrid_mode.md)** | Hybrid FEA/NN optimization | Active |
| **[TRAINING_DATA_EXPORT_GUIDE.md](guides/TRAINING_DATA_EXPORT_GUIDE.md)** | Exporting data for neural training | Active |

---

## API Reference

Technical integration documentation for developers and advanced users.

| Document | Purpose |
|----------|---------|
| **[system_configuration.md](api/system_configuration.md)** | Configuration format reference |
| **[nx_integration.md](api/nx_integration.md)** | NX Open API integration |
| **[GNN_ARCHITECTURE.md](api/GNN_ARCHITECTURE.md)** | Graph Neural Network details |
| **[NXOPEN_RESOURCES.md](api/NXOPEN_RESOURCES.md)** | NX Open documentation resources |

---

## Domain Knowledge

Physics and engineering domain documentation.

### Physics Documentation

| Document | Purpose |
|----------|---------|
| **[ZERNIKE_FUNDAMENTALS.md](physics/ZERNIKE_FUNDAMENTALS.md)** | Zernike polynomial basics |
| **[ZERNIKE_OPD_METHOD.md](physics/ZERNIKE_OPD_METHOD.md)** | OPD method for mirror optimization |

---

## Workflows and Operations

Operational workflows for common tasks.

### Standard Workflows

| Document | Purpose |
|----------|---------|
| **[CREATE.md](WORKFLOWS/CREATE.md)** | Study creation workflow |
| **[RUN.md](WORKFLOWS/RUN.md)** | Optimization execution workflow |
| **[ANALYZE.md](WORKFLOWS/ANALYZE.md)** | Results analysis workflow |
| **[DELIVER.md](WORKFLOWS/DELIVER.md)** | Deliverable creation workflow |
| **[VALIDATE.md](WORKFLOWS/VALIDATE.md)** | Validation and verification workflow |
| **[REPORT.md](WORKFLOWS/REPORT.md)** | Report generation workflow |

---

## Development and Architecture

Technical development documentation.

### Development Guides

| Document | Purpose |
|----------|---------|
| **[DEVELOPMENT_GUIDANCE.md](development/DEVELOPMENT_GUIDANCE.md)** | Development guidelines |
| **[DEVELOPMENT_ROADMAP.md](development/DEVELOPMENT_ROADMAP.md)** | Future plans |
| **[Philosophy.md](development/Philosophy.md)** | Design philosophy |

### Architecture Documentation

| Document | Purpose |
|----------|---------|
| **[architecture_overview.md](diagrams/architecture_overview.md)** | System architecture diagrams |
| **[protocol_workflows.md](diagrams/protocol_workflows.md)** | Protocol execution flows |

---

## Archive

Historical and review documents preserved for context and CEO review.

### Archive Structure
- **[archive/review/](archive/review/)** — Documents flagged for CEO review
  - RALPH_LOOP implementation plans
  - Dashboard implementation iterations  
  - Superseded development plans
  - Session summaries and old development notes
- **[archive/historical/](archive/historical/)** — Historical but valuable documents
  - Original protocol v1 monolithic document
  - Foundational design documents
  - Completed restructuring plans

### Key Historical Documents
- **[PROTOCOL_V1_MONOLITHIC.md](archive/historical/PROTOCOL_V1_MONOLITHIC.md)** — Original monolithic protocol (Nov 2025)
- Various implementation plans and session summaries in review directories

---

## Documentation by Task

### For Agents: Project Execution
1. **[Agent Workflows](hq/AGENT_WORKFLOWS.md)** — Project lifecycle and handoffs
2. **[Project Structure](hq/PROJECT_STRUCTURE.md)** — How to organize projects  
3. **[Study Conventions](hq/STUDY_CONVENTIONS.md)** — Technical execution standards
4. **[KB Conventions](hq/KB_CONVENTIONS.md)** — Knowledge accumulation

### For Engineers: Creating Studies
1. **[GETTING_STARTED.md](GETTING_STARTED.md)** — First study tutorial
2. **[OP_01_CREATE_STUDY.md](protocols/operations/OP_01_CREATE_STUDY.md)** — Detailed creation protocol
3. **[guides/CANVAS.md](guides/CANVAS.md)** — Visual study builder

### For Engineers: Running Optimizations
1. **[OP_02_RUN_OPTIMIZATION.md](protocols/operations/OP_02_RUN_OPTIMIZATION.md)** — Run protocol
2. **[SYS_10_IMSO.md](protocols/system/SYS_10_IMSO.md)** — Intelligent optimization
3. **[SYS_15_METHOD_SELECTOR.md](protocols/system/SYS_15_METHOD_SELECTOR.md)** — Method selection

### For Engineers: Neural Acceleration
1. **[guides/NEURAL_FEATURES_COMPLETE.md](guides/NEURAL_FEATURES_COMPLETE.md)** — Overview
2. **[SYS_14_NEURAL_ACCELERATION.md](protocols/system/SYS_14_NEURAL_ACCELERATION.md)** — Technical spec
3. **[guides/NEURAL_WORKFLOW_TUTORIAL.md](guides/NEURAL_WORKFLOW_TUTORIAL.md)** — Step-by-step

### For Engineers: Analyzing Results
1. **[OP_04_ANALYZE_RESULTS.md](protocols/operations/OP_04_ANALYZE_RESULTS.md)** — Analysis protocol
2. **[SYS_17_STUDY_INSIGHTS.md](protocols/system/SYS_17_STUDY_INSIGHTS.md)** — Physics visualizations

### For Everyone: Troubleshooting
1. **[OP_06_TROUBLESHOOT.md](protocols/operations/OP_06_TROUBLESHOOT.md)** — Troubleshooting guide
2. **[GETTING_STARTED.md#troubleshooting](GETTING_STARTED.md#troubleshooting)** — Common issues

---

## Quick Reference

### Protocol Summary

| Protocol | Name | Purpose |
|----------|------|---------|
| **OP_01** | Create Study | Study creation workflow |
| **OP_02** | Run Optimization | Execution workflow |
| **OP_03** | Monitor Progress | Real-time monitoring |
| **OP_04** | Analyze Results | Results analysis |
| **OP_06** | Troubleshoot | Debugging issues |
| **OP_09** | Agent Communication | HQ communication standards |
| **SYS_10** | IMSO | Intelligent optimization |
| **SYS_12** | Extractors | Physics extraction library |
| **SYS_14** | Neural | Neural network acceleration |

### Essential Commands

```bash
# Activate environment
conda activate atomizer

# Run optimization (engineers)
python run_optimization.py --start --trials 50

# Resume interrupted run  
python run_optimization.py --start --resume

# Start dashboard
python launch_dashboard.py

# Neural turbo mode
python run_nn_optimization.py --turbo --nn-trials 5000

# KB status check (agents)
cad_kb.py status projects/[project]/kb
```

### Key Extractors

| ID | Physics | Function |
|----|---------|----------|
| E1 | Displacement | `extract_displacement()` |
| E2 | Frequency | `extract_frequency()` |
| E3 | Stress | `extract_solid_stress()` |
| E4 | Mass (BDF) | `extract_mass_from_bdf()` |
| E5 | Mass (CAD) | `extract_mass_from_expression()` |
| E22 | Zernike OPD | `extract_zernike_opd()` |

Full catalog: [SYS_12_EXTRACTOR_LIBRARY.md](protocols/system/SYS_12_EXTRACTOR_LIBRARY.md)

---

## LLM Resources

For Claude/AI integration:

| Resource | Purpose |
|----------|---------|
| **[../CLAUDE.md](../CLAUDE.md)** | System instructions |
| **[../.claude/ATOMIZER_CONTEXT.md](../.claude/ATOMIZER_CONTEXT.md)** | Session context |
| **[../.claude/skills/](../.claude/skills/)** | Skill modules |

---

**Last Updated**: February 9, 2026  
**Maintained By**: Atomizer-HQ Team (Manager, Technical Lead, Secretary) + Antoine