Atomizer/PROJECT_SUMMARY.md

# Atomizer - Project Summary

**Last Updated**: 2025-11-15
**Repository**: https://github.com/Anto01/Atomizer (Private)
**Branch**: main (5 commits)

---

## 🎯 Project Vision

Atomizer is an advanced optimization platform for Siemens NX Simcenter that combines:
- **LLM-driven configuration** via conversational interface (MCP)
- **Superior optimization** using Optuna (TPE, Gaussian Process surrogates)
- **Real-time monitoring** with interactive dashboards
- **Flexible architecture** with pluggable result extractors
- **NXOpen integration** for seamless NX automation

**Goal**: Create a general-purpose FEA optimization tool more powerful and flexible than NX's built-in optimizer.

---

## 📂 Repository Structure

```
C:\Users\antoi\Documents\Atomaste\Atomizer\
├── .git/                           # Git repository
├── .gitignore                      # Python, NX, optimization files
├── LICENSE                         # Proprietary license
├── README.md                       # Main documentation
├── GITHUB_SETUP.md                 # GitHub push instructions
├── DEVELOPMENT.md                  # Development workflow guide
├── PROJECT_SUMMARY.md              # This file
├── pyproject.toml                  # Python package config
├── requirements.txt                # Pip dependencies
│
├── config/                         # Configuration templates
│   ├── nx_config.json.template     # NX paths (NX 2412)
│   └── optimization_config_template.json  # Optimization setup
│
├── mcp_server/                     # MCP Server (LLM interface)
│   ├── __init__.py
│   ├── tools/                      # MCP tool implementations
│   │   └── __init__.py             # Tool registry
│   ├── schemas/                    # JSON validation schemas
│   └── prompts/
│       ├── system_prompt.md        # LLM instructions (complete)
│       └── examples/               # Few-shot examples
│
├── optimization_engine/            # Core optimization logic
│   ├── __init__.py
│   └── result_extractors/          # Pluggable metric extractors
│       └── __init__.py             # Base class + registry
│
├── nx_journals/                    # NXOpen scripts
│   ├── __init__.py
│   └── utils/                      # Helper functions
│
├── dashboard/                      # Web UI (planned)
│   ├── frontend/                   # React app
│   └── backend/                    # FastAPI server
│
├── docs/
│   ├── NXOPEN_RESOURCES.md         # NXOpen reference guide
│   └── configuration.md            # (planned)
│
├── tests/                          # Unit tests
└── examples/                       # Example projects
```

---

## 🔑 Key Technologies

### Core Stack
- **Python 3.10** (conda environment: `atomizer`)
- **Siemens NX 2412** with NX Nastran solver
- **Optuna 3.5+** for optimization
- **pyNastran 1.4+** for OP2/F06 parsing
- **Pandas 2.0+** for data management

### MCP & Dashboard
- **MCP Protocol** for LLM integration
- **FastAPI** for backend server
- **WebSockets** for real-time updates
- **React + TypeScript** for frontend (planned)
- **Plotly.js** for 3D visualizations

### Development Tools
- **pytest** for testing
- **black** for code formatting
- **ruff** for linting
- **Git** for version control

---

## 🏗️ Architecture Overview

### Three-Tier Design

```
┌─────────────────────────────────────────────────────────┐
│                 TIER 1: UI Layer                        │
│  ┌─────────────────────┐  ┌──────────────────────────┐ │
│  │  Web Dashboard      │  │  LLM Chat Interface      │ │
│  │  (React + Plotly)   │  │  (MCP Client)            │ │
│  └─────────────────────┘  └──────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
                          ↕ HTTP/WebSocket
┌─────────────────────────────────────────────────────────┐
│                 TIER 2: MCP Server                      │
│  ┌──────────────────────────────────────────────────┐  │
│  │  • Model Discovery (parse .sim files)           │  │
│  │  • Config Builder (generate optimization.json)  │  │
│  │  • Optimizer Control (start/stop/monitor)       │  │
│  │  • Result Analyzer (extract metrics)            │  │
│  │  • NXOpen API Wrapper (file-based bridge)       │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                          ↕ File I/O + Subprocess
┌─────────────────────────────────────────────────────────┐
│           TIER 3: Execution Layer                       │
│  ┌──────────┐  ┌──────────┐  ┌────────────────────┐   │
│  │ NX Core  │  │ Optuna   │  │ Custom Scripts     │   │
│  │ (NXOpen) │  │ Engine   │  │ (Parsing/Analysis) │   │
│  └──────────┘  └──────────┘  └────────────────────┘   │
└─────────────────────────────────────────────────────────┘
```

### File-Based Communication Pattern
- **MCP Server** ↔ **NX Journals**: JSON request/response files
- **Optimization Engine** ↔ **NX**: Expression files (.exp)
- **Results**: CSV (history.csv) + SQLite (optuna_study.db)

---

## 🧩 Reusable Components from P04/Atomizer

The following modules from your existing Atomizer project can be adapted:

| P04 Module | New Location | Adaptation Needed |
|-----------|--------------|-------------------|
| `code/multi_optimizer.py` | `optimization_engine/multi_optimizer.py` | Minimal - Optuna logic is general |
| `code/config_loader.py` | `optimization_engine/config_loader.py` | Extend for extractor plugins |
| `code/surrogate_optimizer.py` | `optimization_engine/surrogate_optimizer.py` | Direct copy |
| `code/journal_NX_Update_and_Solve.py` | `nx_journals/update_and_solve.py` | Generalize for any .sim file |
| `code/zernike_Post_Script_NX.py` | `optimization_engine/result_extractors/zernike.py` | Convert to plugin class |
| `code/nx_post_each_iter.py` | `nx_journals/post_process.py` | Use extractor registry |

**Key Insight**: The optimization engine core (Optuna, history management, CSV/DB) works as-is. Main changes are in result extraction (pluggable) and NX interaction (generalized).

---

## 🛠️ MCP Tools (Planned)

### Model Discovery
- **`discover_fea_model`**: Parse .sim files → extract solutions, expressions, FEM info
- **`search_nxopen_docs`**: Fetch Siemens NXOpen API documentation

### Optimization Control
- **`build_optimization_config`**: Natural language → optimization_config.json
- **`start_optimization`**: Launch optimization run
- **`query_optimization_status`**: Get current iteration metrics

### Result Analysis
- **`extract_results`**: Parse OP2/F06/XDB → stress, displacement, mass, etc.
- **`run_nx_journal`**: Execute custom NXOpen scripts

---

## 📚 NXOpen Development Strategy

### Resource Hierarchy
1. **Official Siemens NXOpen API** - Authoritative reference
2. **NXOpenTSE** - Patterns & best practices (reference only, not dependency)
3. **Atomizer-specific conventions** - Our implementation

### NXOpenTSE Integration
- **GitHub**: https://github.com/theScriptingEngineer/nxopentse
- **Docs**: https://nxopentsedocumentation.thescriptingengineer.com/
- **Usage**: Reference for learning, NOT for copying code
- **Benefits**:
  - See proven design patterns
  - Learn error handling approaches
  - Understand NX-specific gotchas
  - Discover lesser-known APIs

### Code Generation Workflow (via MCP)
1. Check official API for method signatures
2. Reference NXOpenTSE for usage patterns
3. Adapt to Atomizer's architecture
4. Add error handling and attribution comments

**See**: `docs/NXOPEN_RESOURCES.md` for complete guide

---

## 🔄 Development Phases (Recommended Order)

### ✅ Phase 0: Foundation (COMPLETE)
- [x] Project structure created
- [x] Git repository initialized
- [x] GitHub remote configured (Anto01/Atomizer)
- [x] Documentation framework
- [x] NXOpen resources documented
- [x] MCP system prompt complete

### 🎯 Phase 1: MCP Server Foundation (NEXT)
- [ ] Implement `discover_fea_model` tool
- [ ] Create .sim file parser
- [ ] Build expression extractor
- [ ] Test with real .sim files
- [ ] Validate JSON schema

### 🔧 Phase 2: Optimization Engine Port
- [ ] Copy Atomizer's `multi_optimizer.py`
- [ ] Adapt `config_loader.py` for extractors
- [ ] Create pluggable result extractor system
- [ ] Implement Nastran OP2 extractor
- [ ] Implement NX mass properties extractor

### 🔌 Phase 3: NXOpen Bridge
- [ ] Build file-based NXOpen API wrapper
- [ ] Create generic journal dispatcher
- [ ] Implement expression update journal
- [ ] Implement solve simulation journal
- [ ] Test with NX 2412

### 🎨 Phase 4: Dashboard UI
- [ ] React frontend skeleton
- [ ] FastAPI backend with WebSocket
- [ ] Real-time iteration monitoring
- [ ] Plotly visualizations
- [ ] Config editor UI

### 🚀 Phase 5: Integration & Testing
- [ ] End-to-end workflow testing
- [ ] LLM prompt refinement
- [ ] Error handling improvements
- [ ] Performance optimization
- [ ] User documentation

---

## 📝 Current Git Status

**Repository**: https://github.com/Anto01/Atomizer
**Visibility**: Private
**Branch**: main
**Commits**: 5

### Commit History
```
f359d4e - chore: Update NX version to 2412
14d2b67 - docs: Add NXOpen resources guide and MCP system prompt
d1cbeb7 - Rebrand project from nx-optimaster to Atomizer
2201aee - docs: Add GitHub setup and development guides
aa3dafb - Initial commit: NX OptiMaster project structure
```

### Files Tracked (15)
- `.gitignore`
- `LICENSE`
- `README.md`
- `GITHUB_SETUP.md`
- `DEVELOPMENT.md`
- `PROJECT_SUMMARY.md` (this file)
- `pyproject.toml`
- `requirements.txt`
- `config/nx_config.json.template`
- `config/optimization_config_template.json`
- `mcp_server/__init__.py`
- `mcp_server/tools/__init__.py`
- `optimization_engine/__init__.py`
- `optimization_engine/result_extractors/__init__.py`
- `nx_journals/__init__.py`
- `mcp_server/prompts/system_prompt.md`
- `docs/NXOPEN_RESOURCES.md`

---

## 🚀 Quick Start Commands

### Clone Repository (Different Machine)
```bash
git clone https://github.com/Anto01/Atomizer.git
cd Atomizer
```

### Set Up Python Environment
```bash
# Create conda environment
conda create -n atomizer python=3.10
conda activate atomizer

# Install dependencies
pip install -e .

# Install dev tools (optional)
pip install -e ".[dev]"

# Install MCP (when ready)
pip install -e ".[mcp]"
```

### Configure NX Path
```bash
# Copy template
cp config/nx_config.json.template config/nx_config.json

# Edit config/nx_config.json:
# - Set nx_executable to your NX 2412 path
# - Set python_env to your atomizer conda environment
```

### Git Workflow
```bash
# Create feature branch
git checkout -b feature/model-discovery

# Make changes, commit
git add .
git commit -m "feat: implement FEA model discovery tool"

# Push to GitHub
git push -u origin feature/model-discovery

# Merge to main (after review)
git checkout main
git merge feature/model-discovery
git push origin main
```

---

## 🎯 Next Immediate Steps

**When you're ready to start coding**, choose one of these entry points:

### Option A: MCP Model Discovery (Recommended First)
**Goal**: Get LLM to parse .sim files and extract expressions

**Tasks**:
1. Create `mcp_server/tools/model_discovery.py`
2. Implement .sim file parsing logic
3. Extract expression names and values
4. Return structured JSON for LLM
5. Test with your P04 .sim files

**Benefit**: Establishes MCP pattern, immediately useful

### Option B: Port Optimization Engine
**Goal**: Get core optimization working independently

**Tasks**:
1. Copy `multi_optimizer.py`, `config_loader.py` from P04
2. Adapt for general use (remove Zernike-specific code)
3. Update import paths
4. Create simple test case
5. Verify Optuna integration works

**Benefit**: Core functionality ready, can test optimization without MCP

### Option C: NXOpen Bridge
**Goal**: Get NX automation working via file-based communication

**Tasks**:
1. Create `nx_journals/api_dispatcher.py`
2. Implement JSON request/response pattern
3. Test expression updates
4. Test .sim file loading
5. Document NXOpen patterns

**Benefit**: NX integration ready for optimization loop

---

## 📊 Key Design Decisions

### 1. **Why File-Based Communication?**
- NXOpen requires NX GUI process
- MCP server runs in separate Python environment
- Files are robust, inspectable, version-controllable
- Proven pattern from P04 Atomizer

### 2. **Why Pluggable Result Extractors?**
- Different FEA problems need different metrics
- Zernike analysis is specific to optical surfaces
- General tool needs stress, thermal, modal, etc.
- Easy to add new extractors without changing core

### 3. **Why MCP vs. Direct UI?**
- Natural language is faster than JSON editing
- LLM can suggest reasonable parameter bounds
- Conversational debugging ("why did this fail?")
- Future: voice commands, multi-modal input

### 4. **Why Dual Persistence (CSV + SQLite)?**
- CSV: Human-readable, Excel-compatible, git-friendly
- SQLite: Fast queries, Optuna requirement
- Sync on each iteration for crash recovery

---

## 🔗 Important Links

### GitHub
- **Repository**: https://github.com/Anto01/Atomizer
- **Issues**: GitHub Issues (private repository)

### Documentation
- **Official NXOpen API**: https://docs.sw.siemens.com/en-US/doc/209349590/
- **NXOpenTSE**: https://nxopentsedocumentation.thescriptingengineer.com/
- **Optuna**: https://optuna.readthedocs.io/
- **pyNastran**: https://github.com/SteveDoyle2/pyNastran

### Local Documentation
- **NXOpen Resources**: `docs/NXOPEN_RESOURCES.md`
- **MCP System Prompt**: `mcp_server/prompts/system_prompt.md`
- **Development Guide**: `DEVELOPMENT.md`
- **GitHub Setup**: `GITHUB_SETUP.md`

---

## 💡 Key Insights for Success

1. **Start Small**: Implement one MCP tool at a time, test thoroughly
2. **Reference P04**: Your existing Atomizer is 80% of the solution
3. **Use NXOpenTSE**: Learn patterns, don't copy code
4. **Test Early**: Use real .sim files from day one
5. **Document as You Go**: Future you will thank present you
6. **Commit Often**: Small, focused commits are easier to debug

---

## 🏁 Success Criteria

**Phase 1 Complete When**:
- LLM can parse a .sim file and list expressions
- User can ask "what parameters can I optimize?"
- System responds with structured list

**Phase 2 Complete When**:
- Can run optimization without LLM (manual config.json)
- Optuna suggests parameters
- Results saved to history.csv

**Phase 3 Complete When**:
- NX journals can update expressions via file commands
- Solver runs automatically
- Results extracted to CSV

**Phase 4 Complete When**:
- Dashboard shows real-time iteration updates
- User can monitor without opening NX
- Plots update automatically

**Full System Complete When**:
- User says: "Optimize bracket.sim to reduce stress"
- LLM configures optimization
- NX runs iterations automatically
- Dashboard shows progress
- User gets optimized design

---

**Project Status**: Foundation complete, ready for development
**Next Action**: Choose entry point (A, B, or C above) and start coding
**Estimated Timeline**: 12-16 weeks for full system (part-time)

---

**Last Updated**: 2025-11-15
**Maintained By**: Antoine (Anto01)
**Built With**: Claude Code 🤖