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](#prerequisites)
2. [Quick Setup](#quick-setup)
3. [Project Structure](#project-structure)
4. [Your First Optimization Study](#your-first-optimization-study)
5. [Using the Dashboard](#using-the-dashboard)
6. [Neural Acceleration (Optional)](#neural-acceleration-optional)
7. [Next Steps](#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

```bash
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.

```bash
conda activate atomizer
```

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

### 3. Verify Installation

```bash
# 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`:

```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

```bash
# 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!)

```bash
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:

```json
{
  "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

```bash
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

```bash
# 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

```bash
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

```bash
# 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

```bash
# 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.*