Antoine/Atomizer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Major update with validators, skills, dashboard, and docs reorganization

Browse Source 
- Add validation framework (config, model, results, study validators)
- Add Claude Code skills (create-study, run-optimization, generate-report,
  troubleshoot, analyze-model)
- Add Atomizer Dashboard (React frontend + FastAPI backend)
- Reorganize docs into structured directories (00-09)
- Add neural surrogate modules and training infrastructure
- Add multi-objective optimization support

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Anto01
2025-11-25 19:23:58 -05:00
parent 74a92803b7
commit e3bdb08a22
155 changed files with 52729 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

371
docs/00_INDEX.md Normal file
View File

@@ -0,0 +1,371 @@
# 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.