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 - Project overview, philosophy, and quick start guide
2. Getting Started Tutorial - Create your first optimization study
3. Neural Features Guide - Neural network acceleration (NEW!)
4. Example Studies - Working examples (UAV arm with neural, bracket)

---

Documentation Structure

🧠 Neural Network Acceleration (NEW!)

Core Neural Documentation:

• NEURAL_FEATURES_COMPLETE.md - Complete guide to all neural features
• NEURAL_WORKFLOW_TUTORIAL.md - Step-by-step: data → training → optimization
• GNN_ARCHITECTURE.md - Technical deep-dive into GNN models
• PHYSICS_LOSS_GUIDE.md - Loss function selection guide

Integration Documentation:

• ATOMIZER_FIELD_INTEGRATION_PLAN.md - Integration roadmap (COMPLETE)
• ATOMIZER_FIELD_NEURAL_OPTIMIZATION_GUIDE.md - API reference

Quick Commands:

# 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 - 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 - Adaptive characterization, landscape analysis
• PROTOCOL_10_V2_IMPLEMENTATION.md - Implementation summary
• PROTOCOL_10_V2_FIXES.md - Bug fixes and improvements
• PROTOCOL_11_MULTI_OBJECTIVE_SUPPORT.md - Multi-objective requirements
• FIX_SUMMARY_PROTOCOL_11.md - Protocol 11 bug fixes
• PROTOCOL_13_DASHBOARD.md - Dashboard implementation complete spec

🏗️ 02. Architecture & Design

Visual Architecture (🆕 Comprehensive Diagrams):

• Architecture Overview - Complete system architecture with Mermaid diagrams
  • High-level system architecture
  • Component interactions
  • Data flow diagrams
  • Philosophy and design principles
  • Technology stack
• Protocol Workflows - 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 - Plugin system and lifecycle hooks
• NX_SESSION_MANAGEMENT.md - NX Nastran integration details
• SYSTEM_CONFIGURATION.md - Configuration format and options

Extractors & Data Flow:

• HOW_TO_EXTEND_OPTIMIZATION.md - Unified extractor library (Protocol 12)

📊 03. Dashboard

Dashboard Documentation:

• DASHBOARD_MASTER_PLAN.md - Complete 3-page architecture blueprint
• DASHBOARD_REACT_IMPLEMENTATION.md - React frontend implementation guide
• DASHBOARD_IMPLEMENTATION_STATUS.md - Current progress and testing
• DASHBOARD_SESSION_SUMMARY.md - Features and usage summary

Quick Commands:

# 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 guide, workflow, testing
• TODAY_PLAN_NOV18.md - Daily development planning example
• LESSONS_LEARNED.md - Lessons from development sessions

Phase Planning:

• PHASE_3_1_COMPLETION_SUMMARY.md - Phase 3.1 completion
• PHASE_3_2_INTEGRATION_PLAN.md - Current phase plan

📖 05. User Guides

Creating & Running Studies:

• 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
• See DASHBOARD_MASTER_PLAN.md for full capabilities

Multi-Objective Optimization:

• Read PROTOCOL_11_MULTI_OBJECTIVE_SUPPORT.md
• Check example: studies/bracket_stiffness_optimization_V3/

🔬 06. Advanced Topics

Intelligent Optimization (Protocol 10):

• PROTOCOL_10_IMSO.md - How it works
• PROTOCOL_10_V2_IMPLEMENTATION.md - Implementation details
• PROTOCOL_10_V2_FIXES.md - Bug fixes and improvements

LLM Integration (Hybrid Mode):

• HYBRID_MODE_GUIDE.md - Using LLM-assisted workflows

NX Integration:

• NX_SESSION_MANAGEMENT.md - Session handling, solving, extraction
• NASTRAN_VISUALIZATION_RESEARCH.md - Visualizing OP2/BDF results with pyNastran + PyVista

📚 07. Session Summaries & Historical

Recent Sessions (Nov 2025):

• GOOD_MORNING_NOV18.md - Morning summary Nov 18
• DASHBOARD_SESSION_SUMMARY.md - Dashboard completion
• 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 - All visual documentation hub
• Architecture Overview - System architecture diagrams
• Protocol Workflows - 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 - Understand the project
2. Review PROTOCOLS.md - Learn about the architecture
3. Try HOW_TO_EXTEND_OPTIMIZATION.md - Build your first study
4. Explore dashboard with DASHBOARD_SESSION_SUMMARY.md

For Developers

Contributing to Atomizer:

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

For Researchers

Using Atomizer for research:

1. PROTOCOL_10_IMSO.md - Intelligent optimization algorithms
2. PROTOCOL_11_MULTI_OBJECTIVE_SUPPORT.md - Multi-objective capabilities
3. 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 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 for details.

---

Common Tasks

Running an Optimization

# 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

# 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

# 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 for comprehensive specs
• Protocol questions? See individual protocol docs (PROTOCOL_XX_*.md)
• Dashboard issues? Check DASHBOARD_IMPLEMENTATION_STATUS.md

Technical Issues

• NX integration problems? See NX_SESSION_MANAGEMENT.md
• Multi-objective errors? Check PROTOCOL_11_MULTI_OBJECTIVE_SUPPORT.md
• Protocol 10 not working? See 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 (this file) up to date with new docs
2. Update PROTOCOLS.md when adding/modifying protocols
3. Maintain ../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.