Atomizer/docs/GETTING_STARTED.md

Getting Started with Atomizer

Last Updated: 2026-01-20

This guide walks you through setting up Atomizer and running your first optimization study.

---

Table of Contents

1. Prerequisites
2. Quick Setup
3. Project Structure
4. Your First Optimization Study
5. Using the Dashboard
6. Neural Acceleration (Optional)
7. Next Steps

---

Prerequisites

Required Software

Software	Version	Purpose
Siemens NX	2506+	CAD/FEA modeling
NX Nastran	Included with NX	FEA solver
Python	3.10+	Core engine
Anaconda	Latest	Environment management
Git	Latest	Version control

Hardware Recommendations

• RAM: 16GB minimum, 32GB recommended
• Storage: SSD with 50GB+ free space (FEA files are large)
• CPU: Multi-core for parallel FEA runs

---

Quick Setup

1. Clone the Repository

git clone http://192.168.86.50:3000/Antoine/Atomizer.git
cd Atomizer

2. Activate the Conda Environment

The atomizer environment is pre-configured with all dependencies.

conda activate atomizer

Important: Always use this environment. Do not install additional packages.

3. Verify Installation

# Check Python path
python --version  # Should show Python 3.10+

# Verify core imports
python -c "from optimization_engine.core.runner import OptimizationRunner; print('OK')"

4. Configure NX Path (if needed)

The default NX installation path is C:\Program Files\Siemens\NX2506\. If yours differs, update it in your study's optimization_config.json:

{
  "nx_settings": {
    "nx_install_path": "C:\\Program Files\\Siemens\\NX2506"
  }
}

---

Project Structure

Atomizer/
├── CLAUDE.md                    # AI assistant instructions
├── README.md                    # Project overview
├── .claude/                     # LLM configuration
│   ├── ATOMIZER_CONTEXT.md      # Session context
│   └── skills/                  # Claude skill modules
├── optimization_engine/         # Core Python package
│   ├── core/                    # Optimization runners
│   ├── extractors/              # Physics extraction (20+)
│   ├── nx/                      # NX/Nastran integration
│   ├── gnn/                     # Neural network surrogates
│   └── study/                   # Study management
├── atomizer-dashboard/          # Web dashboard
│   ├── backend/                 # FastAPI server
│   └── frontend/                # React UI
├── studies/                     # Your optimization studies
│   ├── M1_Mirror/               # Mirror studies
│   ├── Simple_Bracket/          # Bracket studies
│   └── ...
├── docs/                        # Documentation
│   ├── protocols/               # Protocol Operating System
│   ├── guides/                  # User guides
│   └── physics/                 # Physics documentation
└── knowledge_base/              # Learning system (LAC)

---

Your First Optimization Study

Option A: Using Claude (Recommended)

The easiest way to create a study is through natural language:

You: "Create a new study to optimize my bracket for minimum mass 
      with stress under 200 MPa. The model is at C:\Models\bracket.prt"

Claude: [Analyzes model, creates study, generates configuration]

Option B: Manual Creation

Step 1: Create Study Directory

# Create study under appropriate geometry type
mkdir -p studies/Simple_Bracket/my_first_study/1_setup/model
mkdir -p studies/Simple_Bracket/my_first_study/2_iterations
mkdir -p studies/Simple_Bracket/my_first_study/3_results

Step 2: Copy NX Files

Copy your NX model files to the study:

• Model.prt - Geometry part
• Model_fem1.fem - FEM file
• Model_sim1.sim - Simulation file
• Model_fem1_i.prt - Idealized part (IMPORTANT!)

cp /path/to/your/model/* studies/Simple_Bracket/my_first_study/1_setup/model/

Step 3: Create Configuration

Create optimization_config.json in your study root:

{
  "study_name": "my_first_study",
  "description": "Bracket mass optimization with stress constraint",
  
  "design_variables": [
    {
      "name": "thickness",
      "expression_name": "web_thickness",
      "min": 2.0,
      "max": 10.0,
      "initial": 5.0
    }
  ],
  
  "objectives": [
    {
      "name": "mass",
      "type": "minimize",
      "extractor": "extract_mass_from_bdf"
    }
  ],
  
  "constraints": [
    {
      "name": "max_stress",
      "type": "less_than",
      "value": 200.0,
      "extractor": "extract_solid_stress",
      "extractor_args": {"element_type": "ctetra"}
    }
  ],
  
  "optimization": {
    "method": "TPE",
    "n_trials": 50
  },
  
  "nx_settings": {
    "nx_install_path": "C:\\Program Files\\Siemens\\NX2506",
    "simulation_timeout_s": 600
  }
}

Step 4: Run the Optimization

cd studies/Simple_Bracket/my_first_study
python run_optimization.py --start --trials 50

Understanding the Output

During optimization:

• Trial folders are created in 2_iterations/ (trial_0001, trial_0002, ...)
• Results are logged to 3_results/study.db (Optuna database)
• Progress is printed to console and logged to optimization.log

Trial 15/50: mass=2.34 kg, stress=185.2 MPa [FEASIBLE]
  Best so far: mass=2.12 kg (trial #12)

---

Using the Dashboard

Starting the Dashboard

# From project root
python launch_dashboard.py

This starts:

• Backend: FastAPI at http://localhost:8000
• Frontend: React at http://localhost:3003

Dashboard Features

Tab	Purpose
Home	Study selection, creation
Canvas	Visual study builder (AtomizerSpec v2.0)
Dashboard	Real-time monitoring, convergence plots
Analysis	Pareto fronts, parallel coordinates
Insights	Physics visualizations (Zernike, stress fields)

Canvas Builder

The Canvas provides a visual, node-based interface:

1. Add Model Node - Select your .sim file
2. Add Design Variables - Link to NX expressions
3. Add Extractors - Choose physics to extract
4. Add Objectives - Define what to optimize
5. Connect Nodes - Create the optimization flow
6. Execute - Generate and run the study

---

Neural Acceleration (Optional)

For studies with 50+ completed FEA trials, you can train a neural surrogate for 2000x+ speedup.

When to Use Neural Acceleration

Scenario	Use Neural?
< 30 trials needed	No - FEA is fine
30-100 trials	Maybe - depends on FEA time
> 100 trials	Yes - significant time savings
Exploratory optimization	Yes - explore more designs

Training a Surrogate

cd studies/M1_Mirror/m1_mirror_adaptive_V15

# Train on existing FEA data
python -m optimization_engine.gnn.train_zernike_gnn V15 --epochs 200

Running Turbo Mode

# Run 5000 GNN predictions, validate top candidates with FEA
python run_nn_optimization.py --turbo --nn-trials 5000

Performance Comparison

Method	Time per Evaluation	100 Trials
FEA only	10-30 minutes	17-50 hours
GNN Turbo	4.5 milliseconds	~30 seconds

---

Next Steps

Learn the Protocol System

Atomizer uses a layered protocol system:

Layer	Location	Purpose
Operations	docs/protocols/operations/	How to create, run, analyze
System	docs/protocols/system/	Technical specifications
Extensions	docs/protocols/extensions/	How to extend Atomizer

Key protocols to read:

• OP_01: Creating studies
• OP_02: Running optimizations
• SYS_12: Available extractors
• SYS_14: Neural acceleration

Explore Available Extractors

Atomizer includes 20+ physics extractors:

Category	Examples
Mechanical	Displacement, stress, strain energy
Modal	Frequency, mode shapes
Thermal	Temperature, heat flux
Mass	BDF mass, CAD mass
Optical	Zernike wavefront error

Full catalog: docs/protocols/system/SYS_12_EXTRACTOR_LIBRARY.md

Use Claude for Complex Tasks

For complex optimizations, describe your goals naturally:

"Set up a multi-objective optimization for my UAV arm:
 - Minimize mass
 - Maximize first natural frequency  
 - Keep stress under 150 MPa
 Use NSGA-II with 100 trials"

Claude will:

1. Analyze your model
2. Suggest appropriate extractors
3. Configure the optimization
4. Generate all necessary files

---

Troubleshooting

Common Issues

Issue	Solution
"NX not found"	Check nx_install_path in config
"Mesh not updating"	Ensure *_i.prt (idealized part) is copied
"Solver timeout"	Increase simulation_timeout_s
"Import error"	Verify conda activate atomizer

Getting Help

1. Check docs/protocols/operations/OP_06_TROUBLESHOOT.md
2. Ask Claude: "Why is my optimization failing?"
3. Review 3_results/optimization.log

---

Quick Reference

Essential Commands

# Activate environment
conda activate atomizer

# Run optimization
python run_optimization.py --start --trials 50

# Resume interrupted run
python run_optimization.py --start --resume

# Test single trial
python run_optimization.py --test

# Start dashboard
python launch_dashboard.py

# Check study status
python -c "from optimization_engine.study.state import get_study_status; print(get_study_status('.'))"

Key Files

File	Purpose
optimization_config.json	Study configuration
atomizer_spec.json	AtomizerSpec v2.0 (Canvas)
run_optimization.py	FEA optimization script
3_results/study.db	Optuna database

---

Ready to optimize? Start with a simple study, then explore advanced features like neural acceleration and multi-objective optimization.