Atomizer/docs/00_INDEX.md

# Atomizer Documentation Index

**Welcome to the Atomizer documentation!** This index provides a structured navigation hub for all documentation resources.

**Last Updated**: 2025-11-25
**Project Version**: 0.95.0 (95% complete - Neural Integration Complete!)

---

## Quick Start

New to Atomizer? Start here:

1. **[README.md](../README.md)** - Project overview, philosophy, and quick start guide
2. **[Getting Started Tutorial](HOW_TO_EXTEND_OPTIMIZATION.md)** - Create your first optimization study
3. **[Neural Features Guide](NEURAL_FEATURES_COMPLETE.md)** - Neural network acceleration (NEW!)
4. **[Example Studies](../studies/)** - Working examples (UAV arm with neural, bracket)

---

## Documentation Structure

### 🧠 Neural Network Acceleration (NEW!)

**Core Neural Documentation**:
- **[NEURAL_FEATURES_COMPLETE.md](NEURAL_FEATURES_COMPLETE.md)** - Complete guide to all neural features
- **[NEURAL_WORKFLOW_TUTORIAL.md](NEURAL_WORKFLOW_TUTORIAL.md)** - Step-by-step: data → training → optimization
- **[GNN_ARCHITECTURE.md](GNN_ARCHITECTURE.md)** - Technical deep-dive into GNN models
- **[PHYSICS_LOSS_GUIDE.md](PHYSICS_LOSS_GUIDE.md)** - Loss function selection guide

**Integration Documentation**:
- **[ATOMIZER_FIELD_INTEGRATION_PLAN.md](ATOMIZER_FIELD_INTEGRATION_PLAN.md)** - Integration roadmap (COMPLETE)
- **[ATOMIZER_FIELD_NEURAL_OPTIMIZATION_GUIDE.md](ATOMIZER_FIELD_NEURAL_OPTIMIZATION_GUIDE.md)** - API reference

**Quick Commands**:
```bash
# Run neural-accelerated optimization
python run_optimization.py --trials 5000 --use-neural

# Train new model
cd atomizer-field && python train_parametric.py --epochs 200
```

### 📋 01. Core Specifications

**[PROTOCOLS.md](PROTOCOLS.md)** - Master protocol specifications (ALL PROTOCOLS IN ONE PLACE)
- Protocol 10: Intelligent Multi-Strategy Optimization (IMSO)
- Protocol 11: Multi-Objective Support (MANDATORY for all components)
- Protocol 13: Real-Time Dashboard Tracking

**Individual Protocol Documents** (detailed specifications):
- [PROTOCOL_10_IMSO.md](PROTOCOL_10_IMSO.md) - Adaptive characterization, landscape analysis
- [PROTOCOL_10_V2_IMPLEMENTATION.md](PROTOCOL_10_V2_IMPLEMENTATION.md) - Implementation summary
- [PROTOCOL_10_V2_FIXES.md](PROTOCOL_10_V2_FIXES.md) - Bug fixes and improvements
- [PROTOCOL_11_MULTI_OBJECTIVE_SUPPORT.md](PROTOCOL_11_MULTI_OBJECTIVE_SUPPORT.md) - Multi-objective requirements
- [FIX_SUMMARY_PROTOCOL_11.md](FIX_SUMMARY_PROTOCOL_11.md) - Protocol 11 bug fixes
- [PROTOCOL_13_DASHBOARD.md](PROTOCOL_13_DASHBOARD.md) - Dashboard implementation complete spec

### 🏗️ 02. Architecture & Design

**Visual Architecture** (🆕 Comprehensive Diagrams):
- [**Architecture Overview**](09_DIAGRAMS/architecture_overview.md) - Complete system architecture with Mermaid diagrams
  - High-level system architecture
  - Component interactions
  - Data flow diagrams
  - Philosophy and design principles
  - Technology stack
- [**Protocol Workflows**](09_DIAGRAMS/protocol_workflows.md) - Detailed protocol execution flows
  - Protocol 10: IMSO workflow
  - Protocol 11: Multi-objective decision trees
  - Protocol 13: Real-time tracking
  - LLM-assisted workflow (Hybrid Mode)
  - All protocols integrated

**System Architecture**:
- [HOOK_ARCHITECTURE.md](HOOK_ARCHITECTURE.md) - Plugin system and lifecycle hooks
- [NX_SESSION_MANAGEMENT.md](NX_SESSION_MANAGEMENT.md) - NX Nastran integration details
- [SYSTEM_CONFIGURATION.md](SYSTEM_CONFIGURATION.md) - Configuration format and options

**Extractors & Data Flow**:
- [HOW_TO_EXTEND_OPTIMIZATION.md](HOW_TO_EXTEND_OPTIMIZATION.md) - Unified extractor library (Protocol 12)

### 📊 03. Dashboard

**Dashboard Documentation**:
- [DASHBOARD_MASTER_PLAN.md](DASHBOARD_MASTER_PLAN.md) - Complete 3-page architecture blueprint
- [DASHBOARD_REACT_IMPLEMENTATION.md](DASHBOARD_REACT_IMPLEMENTATION.md) - React frontend implementation guide
- [DASHBOARD_IMPLEMENTATION_STATUS.md](DASHBOARD_IMPLEMENTATION_STATUS.md) - Current progress and testing
- [DASHBOARD_SESSION_SUMMARY.md](DASHBOARD_SESSION_SUMMARY.md) - Features and usage summary

**Quick Commands**:
```bash
# Start backend (port 8000)
cd atomizer-dashboard/backend && python -m uvicorn api.main:app --reload --port 8000

# Start frontend (port 3001)
cd atomizer-dashboard/frontend && npm run dev
```

### 🔧 04. Development

**For Contributors**:
- [../DEVELOPMENT.md](../DEVELOPMENT.md) - Development guide, workflow, testing
- [TODAY_PLAN_NOV18.md](TODAY_PLAN_NOV18.md) - Daily development planning example
- [LESSONS_LEARNED.md](LESSONS_LEARNED.md) - Lessons from development sessions

**Phase Planning**:
- [PHASE_3_1_COMPLETION_SUMMARY.md](PHASE_3_1_COMPLETION_SUMMARY.md) - Phase 3.1 completion
- [PHASE_3_2_INTEGRATION_PLAN.md](PHASE_3_2_INTEGRATION_PLAN.md) - Current phase plan

### 📖 05. User Guides

**Creating & Running Studies**:
- [HOW_TO_EXTEND_OPTIMIZATION.md](HOW_TO_EXTEND_OPTIMIZATION.md) - Complete guide
  - Creating custom extractors
  - Defining objectives
  - Setting up design variables
  - Configuring constraints

**Using the Dashboard**:
- Start with [DASHBOARD_SESSION_SUMMARY.md](DASHBOARD_SESSION_SUMMARY.md)
- See [DASHBOARD_MASTER_PLAN.md](DASHBOARD_MASTER_PLAN.md) for full capabilities

**Multi-Objective Optimization**:
- Read [PROTOCOL_11_MULTI_OBJECTIVE_SUPPORT.md](PROTOCOL_11_MULTI_OBJECTIVE_SUPPORT.md)
- Check example: `studies/bracket_stiffness_optimization_V3/`

### 🔬 06. Advanced Topics

**Intelligent Optimization (Protocol 10)**:
- [PROTOCOL_10_IMSO.md](PROTOCOL_10_IMSO.md) - How it works
- [PROTOCOL_10_V2_IMPLEMENTATION.md](PROTOCOL_10_V2_IMPLEMENTATION.md) - Implementation details
- [PROTOCOL_10_V2_FIXES.md](PROTOCOL_10_V2_FIXES.md) - Bug fixes and improvements

**LLM Integration** (Hybrid Mode):
- [HYBRID_MODE_GUIDE.md](HYBRID_MODE_GUIDE.md) - Using LLM-assisted workflows

**NX Integration**:
- [NX_SESSION_MANAGEMENT.md](NX_SESSION_MANAGEMENT.md) - Session handling, solving, extraction
- [NASTRAN_VISUALIZATION_RESEARCH.md](NASTRAN_VISUALIZATION_RESEARCH.md) - Visualizing OP2/BDF results with pyNastran + PyVista

### 📚 07. Session Summaries & Historical

**Recent Sessions** (Nov 2025):
- [GOOD_MORNING_NOV18.md](GOOD_MORNING_NOV18.md) - Morning summary Nov 18
- [DASHBOARD_SESSION_SUMMARY.md](DASHBOARD_SESSION_SUMMARY.md) - Dashboard completion
- [PROTOCOL_13_DASHBOARD.md](PROTOCOL_13_DASHBOARD.md) - Protocol 13 summary

**Historical Documents** (archived for reference):
- Various session summaries in docs/ folder
- Phase completion documents

### 🎨 09. Visual Diagrams

**Comprehensive Visual Documentation**:
- [**Diagram Index**](09_DIAGRAMS/00_INDEX.md) - All visual documentation hub
- [**Architecture Overview**](09_DIAGRAMS/architecture_overview.md) - System architecture diagrams
- [**Protocol Workflows**](09_DIAGRAMS/protocol_workflows.md) - Protocol execution flows

**Viewing Diagrams**:
- Render automatically in GitHub and VS Code (with Markdown Preview Mermaid extension)
- Copy to https://mermaid.live/ for online viewing
- Supported by MkDocs, Docusaurus, and most documentation generators

---

## Documentation by Role

### For New Users

Start here for a guided learning path:

1. Read [../README.md](../README.md) - Understand the project
2. Review [PROTOCOLS.md](PROTOCOLS.md) - Learn about the architecture
3. Try [HOW_TO_EXTEND_OPTIMIZATION.md](HOW_TO_EXTEND_OPTIMIZATION.md) - Build your first study
4. Explore dashboard with [DASHBOARD_SESSION_SUMMARY.md](DASHBOARD_SESSION_SUMMARY.md)

### For Developers

Contributing to Atomizer:

1. [../DEVELOPMENT.md](../DEVELOPMENT.md) - Development workflow and guidelines
2. [PROTOCOLS.md](PROTOCOLS.md) - Understand protocol-based architecture
3. [HOOK_ARCHITECTURE.md](HOOK_ARCHITECTURE.md) - Plugin system internals
4. [HOW_TO_EXTEND_OPTIMIZATION.md](HOW_TO_EXTEND_OPTIMIZATION.md) - Extractor library details

### For Researchers

Using Atomizer for research:

1. [PROTOCOL_10_IMSO.md](PROTOCOL_10_IMSO.md) - Intelligent optimization algorithms
2. [PROTOCOL_11_MULTI_OBJECTIVE_SUPPORT.md](PROTOCOL_11_MULTI_OBJECTIVE_SUPPORT.md) - Multi-objective capabilities
3. [DASHBOARD_MASTER_PLAN.md](DASHBOARD_MASTER_PLAN.md) - Visualization and analysis tools
4. Example studies in `studies/` folder

---

## Protocol Quick Reference

| Protocol | Name | Status | Priority | Version |
|----------|------|--------|----------|---------|
| **10** | Intelligent Multi-Strategy Optimization | ✅ Complete | P0 | v2.1 |
| **11** | Multi-Objective Support | ✅ Complete | P0 (MANDATORY) | v1.0 |
| **13** | Real-Time Dashboard Tracking | ✅ Complete | P1 | v1.0 |
| **Neural** | GNN Acceleration (AtomizerField) | ✅ Complete | P0 | v1.0 |

**See [PROTOCOLS.md](PROTOCOLS.md) for complete specifications.**

## Neural Features Quick Reference

| Feature | Status | Performance |
|---------|--------|-------------|
| **Parametric GNN** | ✅ Production | 4.5ms inference, 2,200x speedup |
| **Field Predictor GNN** | ✅ Production | 50ms inference, full field output |
| **Physics-Informed Loss** | ✅ Production | <5% prediction error |
| **Hybrid Optimization** | ✅ Production | 97% NN usage rate |
| **Uncertainty Quantification** | ✅ Production | Ensemble-based confidence |
| **Training Pipeline** | ✅ Production | BDF/OP2 → GNN → Deploy |

**See [NEURAL_FEATURES_COMPLETE.md](NEURAL_FEATURES_COMPLETE.md) for details.**

---

## Common Tasks

### Running an Optimization

```bash
# Navigate to study
cd studies/my_study

# Run optimization
python run_optimization.py --trials 50

# View in dashboard
# Open http://localhost:3001 and select study
```

### Creating a New Study

```bash
# Use template (recommended)
python create_study.py --name my_study --model path/to/model.prt

# Or manually
mkdir -p studies/my_study/1_setup/model
# Copy model files
# Edit optimization_config.json
# Create run_optimization.py
```

### Checking Protocol 10 Intelligence Reports

```bash
# View characterization progress
cat studies/my_study/2_results/intelligent_optimizer/characterization_progress.json

# View final intelligence report
cat studies/my_study/2_results/intelligent_optimizer/intelligence_report.json

# View strategy transitions
cat studies/my_study/2_results/intelligent_optimizer/strategy_transitions.json
```

---

## File Organization

```
Atomizer/
├── README.md                          # Project overview
├── DEVELOPMENT.md                     # Development guide
├── docs/
│   ├── 00_INDEX.md                   # THIS FILE - Documentation hub
│   ├── PROTOCOLS.md                  # Master protocol specifications
│   ├── PROTOCOL_10_*.md              # Protocol 10 detailed docs
│   ├── PROTOCOL_11_*.md              # Protocol 11 detailed docs
│   ├── PROTOCOL_13_*.md              # Protocol 13 detailed docs
│   ├── DASHBOARD_*.md                # Dashboard documentation
│   ├── HOOK_ARCHITECTURE.md          # Plugin system
│   ├── NX_SESSION_MANAGEMENT.md      # NX integration
│   ├── HOW_TO_EXTEND_OPTIMIZATION.md # User guide
│   └── [session summaries]           # Historical documents
├── optimization_engine/              # Core optimization code
├── atomizer-dashboard/               # Dashboard frontend & backend
├── studies/                          # Optimization studies
└── examples/                         # Example models
```

---

## Getting Help

### Documentation Issues

- **Missing information?** Check [PROTOCOLS.md](PROTOCOLS.md) for comprehensive specs
- **Protocol questions?** See individual protocol docs (PROTOCOL_XX_*.md)
- **Dashboard issues?** Check [DASHBOARD_IMPLEMENTATION_STATUS.md](DASHBOARD_IMPLEMENTATION_STATUS.md)

### Technical Issues

- **NX integration problems?** See [NX_SESSION_MANAGEMENT.md](NX_SESSION_MANAGEMENT.md)
- **Multi-objective errors?** Check [PROTOCOL_11_MULTI_OBJECTIVE_SUPPORT.md](PROTOCOL_11_MULTI_OBJECTIVE_SUPPORT.md)
- **Protocol 10 not working?** See [PROTOCOL_10_V2_FIXES.md](PROTOCOL_10_V2_FIXES.md)

### Community

- **GitHub Issues**: https://github.com/yourusername/Atomizer/issues
- **Discussions**: https://github.com/yourusername/Atomizer/discussions
- **Email**: your.email@example.com

---

## Document Conventions

### Naming System

Documentation files use numbered prefixes for organization:
- `00_*` - Index and navigation files
- `01_*` - Core specifications (protocols)
- `02_*` - Architecture documentation
- `03_*` - User guides
- Individual protocol docs use descriptive names (PROTOCOL_XX_NAME.md)

### Status Indicators

- ✅ Complete - Fully implemented and tested
- 🔨 In Progress - Active development
- 📋 Planned - Design phase
- ⏳ Pending - Not yet started

### Version Format

- **Major.Minor.Patch** (e.g., v2.1.0)
- **Major**: Breaking changes or architectural redesign
- **Minor**: New features, backward compatible
- **Patch**: Bug fixes

---

## Contributing to Documentation

### Updating Documentation

1. Keep [00_INDEX.md](00_INDEX.md) (this file) up to date with new docs
2. Update [PROTOCOLS.md](PROTOCOLS.md) when adding/modifying protocols
3. Maintain [../DEVELOPMENT.md](../DEVELOPMENT.md) with current status
4. Add session summaries for major development sessions

### Documentation Style

- Use clear, concise language
- Include code examples
- Add diagrams for complex concepts
- Follow Markdown best practices
- Keep table of contents updated

### Review Process

1. Create pull request with documentation changes
2. Ensure cross-references are valid
3. Update index files (this file, PROTOCOLS.md)
4. Check for broken links

---

**Last Updated**: 2025-11-21
**Maintained By**: Atomizer Development Team
**Next Review**: When new protocols or major features are added

For questions about this documentation structure, open an issue on GitHub.