Atomizer/README.md

# Atomizer

> Advanced LLM-native optimization platform for Siemens NX Simcenter

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Proprietary-red.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-alpha-yellow.svg)](https://github.com)

## Overview

Atomizer is an **LLM-native optimization framework** for Siemens NX Simcenter that transforms how engineers interact with optimization workflows. Instead of manual JSON configuration and scripting, Atomizer uses AI as a collaborative engineering assistant.

### Core Philosophy

Atomizer enables engineers to:
- **Describe optimizations in natural language** instead of writing configuration files
- **Generate custom analysis functions on-the-fly** (RSS metrics, weighted objectives, constraints)
- **Get intelligent recommendations** based on optimization results and surrogate models
- **Generate comprehensive reports** with AI-written insights and visualizations
- **Extend the framework autonomously** through LLM-driven code generation

### Key Features

- **LLM-Driven Workflow**: Natural language study creation, configuration, and analysis
- **Advanced Optimization**: Optuna-powered TPE, Gaussian Process surrogates, multi-objective Pareto fronts
- **Dynamic Code Generation**: AI writes custom Python functions and NX journal scripts during optimization
- **Intelligent Decision Support**: Surrogate quality assessment, sensitivity analysis, engineering recommendations
- **Real-Time Monitoring**: Interactive web dashboard with live progress tracking
- **Extensible Architecture**: Plugin system with hooks for pre/post mesh, solve, and extraction phases
- **Self-Improving**: Feature registry that learns from user workflows and expands capabilities

📘 See [DEVELOPMENT_ROADMAP.md](DEVELOPMENT_ROADMAP.md) for the complete vision and implementation plan.

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                 LLM Interface Layer                     │
│  Claude Skill + Natural Language Parser + Workflow Mgr  │
└─────────────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────────────────────────────────────┐
│              Optimization Engine Core                   │
│  Plugin System + Feature Registry + Code Generator      │
└─────────────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────────────────────────────────────┐
│           Execution Layer                               │
│  NX Solver (via Journals) + Optuna + Result Extractors  │
└─────────────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────────────────────────────────────┐
│              Analysis & Reporting                       │
│  Surrogate Quality + Sensitivity + Report Generator     │
└─────────────────────────────────────────────────────────┘
```

## Quick Start

### Prerequisites

- **Siemens NX 2412** with NX Nastran solver
- **Python 3.10+** (recommend Anaconda)
- **Git** for version control

### Installation

1. **Clone the repository**:
   ```bash
   git clone https://github.com/yourusername/Atomizer.git
   cd Atomizer
   ```

2. **Create Python environment**:
   ```bash
   conda create -n atomizer python=3.10
   conda activate atomizer
   ```

3. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

4. **Configure NX path** (edit if needed):
   - Default NX path: `C:\Program Files\Siemens\Simcenter3D_2412\NXBIN\run_journal.exe`
   - Update in `optimization_engine/nx_solver.py` if different

### Basic Usage

#### Example 1: Natural Language Optimization (Future - Phase 2)

```
User: "Let's create a new study to minimize stress on my bracket"

LLM: "Study created! Please drop your .sim file into the study folder,
     then I'll explore it to find available design parameters."

User: "Done. I want to vary wall_thickness between 3-8mm"

LLM: "Perfect! I've configured:
     - Objective: Minimize max von Mises stress
     - Design variable: wall_thickness (3.0 - 8.0 mm)
     - Sampler: TPE with 50 trials

     Ready to start?"

User: "Yes, go!"

LLM: "Optimization running! View progress at http://localhost:8080"
```

#### Example 2: Current JSON Configuration

Create `examples/my_study/config.json`:

```json
{
  "sim_file": "examples/bracket/Bracket_sim1.sim",
  "design_variables": [
    {
      "name": "wall_thickness",
      "expression_name": "wall_thickness",
      "min": 3.0,
      "max": 8.0,
      "units": "mm"
    }
  ],
  "objectives": [
    {
      "name": "max_stress",
      "extractor": "stress_extractor",
      "metric": "max_von_mises",
      "direction": "minimize",
      "weight": 1.0,
      "units": "MPa"
    }
  ],
  "optimization_settings": {
    "n_trials": 50,
    "sampler": "TPE",
    "n_startup_trials": 20
  }
}
```

Run optimization:
```bash
python examples/run_optimization.py --config examples/my_study/config.json
```

## Current Features

### ✅ Implemented

- **Core Optimization Engine**: Optuna integration with TPE sampler
- **NX Journal Integration**: Update expressions and run simulations via NXOpen
- **Result Extraction**: Stress (OP2), displacement (OP2), mass properties
- **Study Management**: Folder-based isolation, metadata tracking
- **Web Dashboard**: Real-time monitoring, study configuration UI
- **Precision Control**: 4-decimal rounding for mm/degrees/MPa
- **Crash Recovery**: Resume interrupted optimizations

### 🚧 In Progress (see [DEVELOPMENT_ROADMAP.md](DEVELOPMENT_ROADMAP.md))

- **Phase 1**: Plugin system with optimization lifecycle hooks (2 weeks)
- **Phase 2**: LLM interface with natural language configuration (2 weeks)
- **Phase 3**: Dynamic code generation for custom objectives (3 weeks)
- **Phase 4**: Intelligent analysis and surrogate quality assessment (3 weeks)
- **Phase 5**: Automated HTML/PDF report generation (2 weeks)
- **Phase 6**: NX MCP server with full API documentation (4 weeks)
- **Phase 7**: Self-improving feature registry (4 weeks)

## Project Structure

```
Atomizer/
├── optimization_engine/        # Core optimization logic
│   ├── nx_solver.py           # NX journal execution
│   ├── multi_optimizer.py     # Optuna integration
│   ├── result_extractors/     # OP2/F06 parsers
│   └── expression_updater.py  # CAD parameter modification
├── dashboard/                  # Web UI
│   ├── api/                   # Flask backend
│   ├── frontend/              # HTML/CSS/JS
│   └── scripts/               # NX expression extraction
├── examples/                   # Example optimizations
│   └── bracket/               # Bracket stress minimization
├── tests/                      # Unit and integration tests
├── docs/                       # Documentation
├── DEVELOPMENT_ROADMAP.md      # Future vision and phases
└── README.md                  # This file
```

## Example: Bracket Stress Minimization

A complete working example is in `examples/bracket/`:

```bash
# Run the bracket optimization (50 trials, TPE sampler)
python examples/test_journal_optimization.py

# View results
python dashboard/start_dashboard.py
# Open http://localhost:8080 in browser
```

**What it does**:
1. Loads `Bracket_sim1.sim` with wall thickness = 5mm
2. Varies thickness from 3-8mm over 50 trials
3. Runs FEA solve for each trial
4. Extracts max stress and displacement from OP2
5. Finds optimal thickness that minimizes stress

**Results** (typical):
- Best thickness: ~4.2mm
- Stress reduction: 15-20% vs. baseline
- Convergence: ~30 trials to plateau

## Dashboard Usage

Start the dashboard:
```bash
python dashboard/start_dashboard.py
```

Features:
- **Create studies** with folder structure (sim/, results/, config.json)
- **Drop .sim/.prt files** into study folders
- **Explore .sim files** to extract expressions via NX
- **Configure optimization** with 5-step wizard:
  1. Simulation files
  2. Design variables
  3. Objectives
  4. Constraints
  5. Optimization settings
- **Monitor progress** with real-time charts
- **View results** with trial history and best parameters

## Vision: LLM-Native Engineering Assistant

Atomizer is evolving into a comprehensive AI-powered engineering platform. See [DEVELOPMENT_ROADMAP.md](DEVELOPMENT_ROADMAP.md) for details on:

- **Phase 1-7 development plan** with timelines and deliverables
- **Example use cases** demonstrating natural language workflows
- **Architecture diagrams** showing plugin system and LLM integration
- **Success metrics** for each phase

### Future Capabilities

```
User: "Add RSS function combining stress and displacement"
→ LLM: Writes Python function, validates, registers as custom objective

User: "Use surrogate to predict these 10 parameter sets"
→ LLM: Checks surrogate R² > 0.9, runs predictions with confidence intervals

User: "Make an optimization report"
→ LLM: Generates HTML with plots, insights, recommendations (30 seconds)

User: "Why did trial #34 perform best?"
→ LLM: "Trial #34 had optimal stress distribution due to thickness 4.2mm
       creating uniform load paths. Fillet radius 3.1mm reduced stress
       concentration by 18%. This combination is Pareto-optimal."
```

## Roadmap

- [x] Core optimization engine with Optuna
- [x] NX journal integration
- [x] Web dashboard with study management
- [x] OP2 result extraction
- [ ] **Phase 1**: Plugin system (2 weeks)
- [ ] **Phase 2**: LLM interface (2 weeks)
- [ ] **Phase 3**: Code generation (3 weeks)
- [ ] **Phase 4**: Analysis & decision support (3 weeks)
- [ ] **Phase 5**: Automated reporting (2 weeks)
- [ ] **Phase 6**: NX MCP enhancement (4 weeks)
- [ ] **Phase 7**: Self-improving system (4 weeks)

See [DEVELOPMENT_ROADMAP.md](DEVELOPMENT_ROADMAP.md) for complete timeline.

## License

Proprietary - Atomaste © 2025

## Support

- **Documentation**: [docs/](docs/)
- **Examples**: [examples/](examples/)
- **Development Roadmap**: [DEVELOPMENT_ROADMAP.md](DEVELOPMENT_ROADMAP.md)
- **Email**: antoine@atomaste.com

## Resources

### NXOpen References
- **Official API Docs**: [Siemens NXOpen Documentation](https://docs.sw.siemens.com/en-US/doc/209349590/)
- **NXOpenTSE**: [The Scripting Engineer's Guide](https://nxopentsedocumentation.thescriptingengineer.com/)
- **Our Guide**: [NXOpen Resources](docs/NXOPEN_RESOURCES.md)

### Optimization
- **Optuna Documentation**: [optuna.readthedocs.io](https://optuna.readthedocs.io/)
- **pyNastran**: [github.com/SteveDoyle2/pyNastran](https://github.com/SteveDoyle2/pyNastran)

---

**Built with ❤️ by Atomaste** | Powered by Optuna, NXOpen, and Claude