Atomizer/templates/README.md

# Atomizer Study Templates

Quick-start templates for common structural optimization problems.

## Available Templates

| Template | Analysis | Objectives | Use Case |
|----------|----------|------------|----------|
| `beam_stiffness_optimization` | Static | Maximize stiffness | Cantilever beams, support arms |
| `bracket_stress_minimization` | Static | Minimize stress | Mounting brackets, L-brackets |
| `frequency_tuning` | Modal | Minimize mass + Maximize frequency | Motor mounts, drone arms |

## Usage

### Option 1: Create Study from Template (Recommended)

```bash
python -m atomizer create-study --template beam_stiffness --name my_beam_study
```

This creates a new study folder with:
- `1_setup/optimization_config.json` - Configuration (editable)
- `1_setup/model/` - Empty folder for your NX files
- `2_results/` - Empty folder for results
- `run_optimization.py` - Runner script
- `README.md` - Study-specific instructions

### Option 2: Copy and Customize

1. Copy template JSON to your study folder:
   ```bash
   copy templates\beam_stiffness_optimization.json studies\my_study\1_setup\optimization_config.json
   ```

2. Edit the config:
   - Update `study_name`
   - Adjust `design_variables` bounds for your model
   - Modify `constraints` thresholds
   - Update `simulation` file names

3. Add your NX model files to `1_setup/model/`

4. Run optimization:
   ```bash
   python studies\my_study\run_optimization.py --trials 50
   ```

## Template Details

### Beam Stiffness Optimization

**Goal**: Maximize bending stiffness (minimize tip displacement) while staying under mass budget.

**Design Variables**:
- `beam_width` - Cross-section width (mm)
- `beam_height` - Cross-section height (mm)
- `beam_length` - Overall length (mm)

**Constraints**:
- Maximum mass limit
- Maximum stress limit

**Required NX Expressions**: `beam_width`, `beam_height`, `beam_length`

---

### Bracket Stress Minimization

**Goal**: Minimize peak von Mises stress to increase fatigue life and safety factor.

**Design Variables**:
- `wall_thickness` - Main wall thickness (mm)
- `fillet_radius` - Corner radius (mm) - key for stress relief
- `web_thickness` - Stiffening web thickness (mm)
- `rib_count` - Number of stiffening ribs (integer)

**Constraints**:
- Maximum displacement limit (stiffness)
- Maximum mass limit (weight budget)

**Required NX Expressions**: `wall_thickness`, `fillet_radius`, `web_thickness`, `rib_count`

---

### Frequency Tuning

**Goal**: Multi-objective - minimize mass while maximizing first natural frequency to avoid resonance.

**Design Variables**:
- `section_width` - Cross-section width (mm)
- `section_height` - Cross-section height (mm)
- `arm_length` - Cantilever length (mm)
- `wall_thickness` - Wall thickness for hollow sections (mm)

**Constraints**:
- Minimum frequency limit (above excitation)
- Maximum stress limit (static strength)

**Required NX Expressions**: `section_width`, `section_height`, `arm_length`, `wall_thickness`

**Note**: Requires modal analysis solution (SOL 103) in NX simulation.

## Customizing Templates

Templates are JSON files with placeholders. Key sections to customize:

```json
{
  "study_name": "your_study_name",
  "design_variables": [
    {
      "parameter": "your_nx_expression_name",
      "bounds": [min_value, max_value],
      "description": "What this parameter controls"
    }
  ],
  "constraints": [
    {
      "name": "your_constraint",
      "type": "less_than",
      "threshold": your_limit
    }
  ],
  "simulation": {
    "model_file": "YourModel.prt",
    "sim_file": "YourModel_sim1.sim"
  }
}
```

## Creating Custom Templates

1. Copy an existing template closest to your problem
2. Modify for your specific use case
3. Save as `templates/your_template_name.json`
4. The template will be available via `--template your_template_name`

## Neural Network Training

All templates include `training_data_export` enabled by default:

```json
"training_data_export": {
  "enabled": true,
  "export_dir": "atomizer_field_training_data/${study_name}"
}
```

This automatically exports training data for AtomizerField neural surrogate training.