Antoine/Atomizer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
74a92803b7dd4b9908b306a7f2c0c329bda0920e
Atomizer/README.md
Anto01 dd7f0c0f82 Phase 3.3: Multi-objective optimization fix, updated docs & Claude skill 
- Fixed drone gimbal optimization to use proper semantic directions
- Changed from ['minimize', 'minimize'] to ['minimize', 'maximize']
- Updated Claude skill (v2.0) with Phase 3.3 integration
- Added centralized extractor library documentation
- Added multi-objective optimization (Protocol 11) section
- Added NX multi-solution protocol documentation
- Added dashboard integration documentation
- Fixed Pareto front degenerate issue with proper NSGA-II configuration

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

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-24 07:49:48 -05:00

446 lines
20 KiB
Markdown
Raw Blame History

# 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
---
## Documentation
📚 **[Complete Documentation Index](docs/00_INDEX.md)** - Start here for all documentation
### Quick Links
- **[Visual Architecture Diagrams](docs/09_DIAGRAMS/)** - 🆕 Comprehensive Mermaid diagrams showing system architecture and workflows
- **[Protocol Specifications](docs/PROTOCOLS.md)** - All active protocols (10, 11, 13) consolidated
- **[Development Guide](DEVELOPMENT.md)** - Development workflow, testing, contributing
- **[Dashboard Guide](docs/DASHBOARD.md)** - 🆕 Comprehensive React dashboard with multi-objective visualization
- **[NX Multi-Solution Protocol](docs/NX_MULTI_SOLUTION_PROTOCOL.md)** - 🆕 Critical fix for multi-solution workflows
- **[Getting Started](docs/HOW_TO_EXTEND_OPTIMIZATION.md)** - Create your first optimization study
### By Topic
- **Protocols**: [PROTOCOLS.md](docs/PROTOCOLS.md) - Protocol 10 (Intelligent Optimization), 11 (Multi-Objective), 13 (Dashboard)
- **Architecture**: [HOOK_ARCHITECTURE.md](docs/HOOK_ARCHITECTURE.md), [NX_SESSION_MANAGEMENT.md](docs/NX_SESSION_MANAGEMENT.md)
- **Dashboard**: [DASHBOARD_MASTER_PLAN.md](docs/DASHBOARD_MASTER_PLAN.md), [DASHBOARD_REACT_IMPLEMENTATION.md](docs/DASHBOARD_REACT_IMPLEMENTATION.md)
- **Advanced**: [HYBRID_MODE_GUIDE.md](docs/HYBRID_MODE_GUIDE.md) - LLM-assisted workflows
---
## 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\NX2412\NXBIN\run_journal.exe`
- Update in `optimization_engine/nx_solver.py` if different
### Basic Usage
#### Example 1: Natural Language Optimization (LLM Mode - Available Now!)
**New in Phase 3.2**: Describe your optimization in natural language - no JSON config needed!
```bash
python optimization_engine/run_optimization.py \
--llm "Minimize displacement and mass while keeping stress below 200 MPa. \
Design variables: beam_half_core_thickness (15-30 mm), \
beam_face_thickness (15-30 mm). Run 10 trials using TPE." \
--prt studies/simple_beam_optimization/1_setup/model/Beam.prt \
--sim studies/simple_beam_optimization/1_setup/model/Beam_sim1.sim \
--trials 10
```
**What happens automatically:**
- ✅ LLM parses your natural language request
- ✅ Auto-generates result extractors (displacement, stress, mass)
- ✅ Auto-generates inline calculations (safety factor, RSS objectives)
- ✅ Auto-generates post-processing hooks (plotting, reporting)
- ✅ Runs optimization with Optuna
- ✅ Saves results, plots, and best design
**Example**: See [examples/llm_mode_simple_example.py](examples/llm_mode_simple_example.py) for a complete walkthrough.
**Requirements**: Claude Code integration (no API key needed) or provide `--api-key` for Anthropic API.
#### Example 2: Current JSON Configuration
Create `studies/my_study/config.json`:
```json
{
"sim_file": "studies/bracket_stress_minimization/model/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 tests/test_journal_optimization.py
# Or use the quick 5-trial test:
python run_5trial_test.py
```
## Features
- **Intelligent Multi-Objective Optimization**: NSGA-II algorithm for Pareto-optimal solutions
- **Advanced Dashboard**: React-based real-time monitoring with parallel coordinates visualization
- **NX Integration**: Seamless journal-based control of Siemens NX Simcenter
- **Multi-Solution Support**: Automatic handling of combined analysis types (static + modal, thermal + structural)
- **Smart Logging**: Detailed per-trial logs + high-level optimization progress tracking
- **Plugin System**: Extensible hooks at pre-solve, post-solve, and post-extraction points
- **Study Management**: Isolated study folders with automatic result organization
- **Substudy System**: NX-like hierarchical studies with shared models and independent configurations
- **Live History Tracking**: Real-time incremental JSON updates for monitoring progress
- **Resume Capability**: Interrupt and resume optimizations without data loss
- **Pareto Front Analysis**: Automatic extraction and visualization of non-dominated solutions
- **Parallel Coordinates Plot**: Research-grade multi-dimensional visualization with interactive selection
## Current Status
**Development Phase**: Alpha - 80-90% Complete
- ✅ **Phase 1 (Plugin System)**: 100% Complete & Production Ready
- ✅ **Phases 2.5-3.1 (LLM Intelligence)**: 100% Complete - Components built and tested
- ✅ **Phase 3.2 Week 1 (LLM Mode)**: **COMPLETE** - Natural language optimization now available!
- 🎯 **Phase 3.2 Week 2-4 (Robustness)**: **IN PROGRESS** - Validation, safety, learning system
- 🔬 **Phase 3.4 (NXOpen Docs)**: Research & investigation phase
**What's Working**:
- ✅ Complete optimization engine with Optuna + NX Simcenter
- ✅ Substudy system with live history tracking
- ✅ **LLM Mode**: Natural language → Auto-generated code → Optimization → Results
- ✅ LLM components (workflow analyzer, code generators, research agent) - production integrated
- ✅ 50-trial optimization validated with real results
- ✅ End-to-end workflow: `--llm "your request"` → results
**Current Focus**: Adding robustness, safety checks, and learning capabilities to LLM mode.
See [DEVELOPMENT_GUIDANCE.md](DEVELOPMENT_GUIDANCE.md) for comprehensive status and priorities.
## Project Structure
```
Atomizer/
├── optimization_engine/ # Core optimization logic
│ ├── runner.py # Main optimization runner
│ ├── nx_solver.py # NX journal execution
│ ├── nx_updater.py # NX model parameter updates
│ ├── pynastran_research_agent.py # Phase 3: Auto OP2 code gen ✅
│ ├── hook_generator.py # Phase 2.9: Auto hook generation ✅
│ ├── result_extractors/ # OP2/F06 parsers
│ │ └── extractors.py # Stress, displacement extractors
│ └── plugins/ # Plugin system (Phase 1 ✅)
│ ├── hook_manager.py # Hook registration & execution
│ ├── hooks.py # HookPoint enum, Hook dataclass
│ ├── pre_solve/ # Pre-solve lifecycle hooks
│ │ ├── detailed_logger.py
│ │ └── optimization_logger.py
│ ├── post_solve/ # Post-solve lifecycle hooks
│ │ └── log_solve_complete.py
│ ├── post_extraction/ # Post-extraction lifecycle hooks
│ │ ├── log_results.py
│ │ └── optimization_logger_results.py
│ └── post_calculation/ # Post-calculation hooks (Phase 2.9 ✅)
│ ├── weighted_objective_test.py
│ ├── safety_factor_hook.py
│ └── min_to_avg_ratio_hook.py
├── dashboard/ # Web UI
│ ├── api/ # Flask backend
│ ├── frontend/ # HTML/CSS/JS
│ └── scripts/ # NX expression extraction
├── studies/ # Optimization studies
│ ├── README.md # Comprehensive studies guide
│ └── bracket_displacement_maximizing/ # Example study with substudies
│ ├── README.md # Study documentation
│ ├── SUBSTUDIES_README.md # Substudy system guide
│ ├── model/ # Shared FEA model files (.prt, .sim, .fem)
│ ├── config/ # Substudy configuration templates
│ ├── substudies/ # Independent substudy results
│ │ ├── coarse_exploration/ # Fast 20-trial coarse search
│ │ │ ├── config.json
│ │ │ ├── optimization_history_incremental.json # Live updates
│ │ │ └── best_design.json
│ │ └── fine_tuning/ # Refined 50-trial optimization
│ ├── run_substudy.py # Substudy runner with continuation support
│ └── run_optimization.py # Standalone optimization runner
├── tests/ # Unit and integration tests
│ ├── test_hooks_with_bracket.py
│ ├── run_5trial_test.py
│ └── test_journal_optimization.py
├── docs/ # Documentation
├── atomizer_paths.py # Intelligent path resolution
├── DEVELOPMENT_ROADMAP.md # Future vision and phases
└── README.md # This file
```
## Example: Bracket Displacement Maximization with Substudies
A complete working example is in `studies/bracket_displacement_maximizing/`:
```bash
# Run standalone optimization (20 trials)
cd studies/bracket_displacement_maximizing
python run_optimization.py
# Or run a substudy (hierarchical organization)
python run_substudy.py coarse_exploration # 20-trial coarse search
python run_substudy.py fine_tuning # 50-trial refinement with continuation
# View live progress
cat substudies/coarse_exploration/optimization_history_incremental.json
```
**What it does**:
1. Loads `Bracket_sim1.sim` with parametric geometry
2. Varies `tip_thickness` (15-25mm) and `support_angle` (20-40°)
3. Runs FEA solve for each trial using NX journal mode
4. Extracts displacement and stress from OP2 files
5. Maximizes displacement while maintaining safety factor >= 4.0
**Substudy System**:
- **Shared Models**: All substudies use the same model files
- **Independent Configs**: Each substudy has its own parameter bounds and settings
- **Continuation Support**: Fine-tuning substudy continues from coarse exploration results
- **Live History**: Real-time JSON updates for monitoring progress
**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."
```
## Development Status
### Completed Phases
- [x] **Phase 1**: Core optimization engine & Plugin system ✅
- NX journal integration
- Web dashboard
- Lifecycle hooks (pre-solve, post-solve, post-extraction)
- [x] **Phase 2.5**: Intelligent Codebase-Aware Gap Detection ✅
- Scans existing capabilities before requesting examples
- Matches workflow steps to implemented features
- 80-90% accuracy on complex optimization requests
- [x] **Phase 2.6**: Intelligent Step Classification ✅
- Distinguishes engineering features from inline calculations
- Identifies post-processing hooks vs FEA operations
- Foundation for smart code generation
- [x] **Phase 2.7**: LLM-Powered Workflow Intelligence ✅
- Replaces static regex with Claude AI analysis
- Detects ALL intermediate calculation steps
- Understands engineering context (PCOMP, CBAR, element forces, etc.)
- 95%+ expected accuracy with full nuance detection
- [x] **Phase 2.8**: Inline Code Generation ✅
- LLM-generates Python code for simple math operations
- Handles avg/min/max, normalization, percentage calculations
- Direct integration with Phase 2.7 LLM output
- Optional automated code generation for calculations
- [x] **Phase 2.9**: Post-Processing Hook Generation ✅
- LLM-generates standalone Python middleware scripts
- Integrated with Phase 1 lifecycle hook system
- Handles weighted objectives, custom formulas, constraints, comparisons
- Complete JSON-based I/O for optimization loops
- Optional automated scripting for post-processing operations
- [x] **Phase 3**: pyNastran Documentation Integration ✅
- LLM-enhanced OP2 extraction code generation
- Documentation research via WebFetch
- 3 core extraction patterns (displacement, stress, force)
- Knowledge base for learned patterns
- Successfully tested on real OP2 files
- Optional automated code generation for result extraction!
- [x] **Phase 3.1**: LLM-Enhanced Automation Pipeline ✅
- Extractor orchestrator integrates Phase 2.7 + Phase 3.0
- Optional automatic extractor generation from LLM output
- Dynamic loading and execution on real OP2 files
- End-to-end test passed: Request → Code → Execution → Objective
- LLM-enhanced workflow with user flexibility achieved!
### Next Priorities
- [ ] **Phase 3.2**: Optimization runner integration with orchestrator
- [ ] **Phase 3.5**: NXOpen introspection & pattern curation
- [ ] **Phase 4**: Code generation for complex FEA features
- [ ] **Phase 5**: Analysis & decision support
- [ ] **Phase 6**: Automated reporting
**For Developers**:
- [DEVELOPMENT.md](DEVELOPMENT.md) - Current status, todos, and active development
- [DEVELOPMENT_ROADMAP.md](DEVELOPMENT_ROADMAP.md) - Strategic vision and long-term plan
- [CHANGELOG.md](CHANGELOG.md) - Version history and changes
## License
Proprietary - Atomaste © 2025
## Support
- **Documentation**: [docs/](docs/)
- **Studies**: [studies/](studies/) - Optimization study templates and 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
Reference in New Issue View Git Blame Copy Permalink