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)

• Project structure created
• Git repository initialized
• GitHub remote configured (Anto01/Atomizer)
• Documentation framework
• NXOpen resources documented
• 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)

git clone https://github.com/Anto01/Atomizer.git
cd Atomizer

Set Up Python Environment

# 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

# 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

# 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 🤖