CAD-Documenter/docs/ATOMIZER_INTEGRATION.md

# Atomizer Integration Guide

CAD-Documenter generates FEA optimization hints that integrate with Atomizer, the Atomaste optimization framework.

## Overview

When you explain your CAD model in a video walkthrough, CAD-Documenter extracts:

1. **Optimization objectives** - What you want to minimize/maximize
2. **Design constraints** - Limits and requirements
3. **Design parameters** - Variables that could be optimized
4. **Critical regions** - Areas requiring careful FEA attention

## Verbal Cues → Atomizer Hints

### Objectives

| What You Say | Generated Objective |
|--------------|---------------------|
| "minimize the weight" | `{"name": "mass", "direction": "minimize"}` |
| "maximize stiffness" | `{"name": "stiffness", "direction": "maximize"}` |
| "reduce stress" | `{"name": "stress", "direction": "minimize"}` |
| "keep the frequency high" | `{"name": "frequency", "direction": "maximize"}` |
| "minimize deflection" | `{"name": "displacement", "direction": "minimize"}` |

### Constraints

| What You Say | Generated Constraint |
|--------------|---------------------|
| "must fit in 200mm" | `{"type": "envelope", "value": "200mm"}` |
| "under 500 grams" | `{"type": "limit", "value": "500g"}` |
| "frequency above 100 Hz" | `{"type": "minimum", "value": "100 Hz"}` |
| "stress cannot exceed 150 MPa" | `{"type": "maximum", "value": "150 MPa"}` |

### Parameters

Mentioning these terms adds them to potential design parameters:

- thickness, wall thickness
- radius, fillet radius
- diameter, hole size
- length, width, height
- angle, spacing, count
- rib dimensions

### Critical Regions

| What You Mention | FEA Concern |
|-----------------|-------------|
| "this fillet is important" | Stress concentration |
| "corner stress" | Stress concentration |
| "bearing load here" | Contact stress |
| "weld joint" | Fatigue concern |
| "interface between parts" | Contact analysis |

## Output Format

### atomizer_hints.json

```json
{
  "assembly_name": "Motor Bracket Assembly",
  "generated": "2026-01-27T20:15:00",
  
  "model_understanding": {
    "components": [
      {
        "name": "Main Bracket",
        "material": "Aluminum 6061-T6",
        "function": "Motor mounting",
        "features": ["M6 holes", "fillet radii"]
      }
    ],
    "materials_mentioned": ["Aluminum 6061-T6", "Steel"]
  },
  
  "optimization_hints": {
    "objectives": [
      {"name": "mass", "direction": "minimize", "source": "Mentioned 'lightweight' in transcript"},
      {"name": "stiffness", "direction": "maximize", "source": "Mentioned 'stiff' in transcript"}
    ],
    "constraints": [
      {"type": "envelope", "value": "200mm", "raw_match": "must fit in (\\d+)"},
      {"type": "minimum", "value": "100 Hz", "raw_match": "greater than (\\d+)"}
    ],
    "parameters": ["thickness", "fillet_radius", "rib_count"]
  },
  
  "fea_hints": {
    "critical_regions": [
      {"feature": "fillet", "concern": "stress_concentration"},
      {"feature": "interface", "concern": "contact_analysis"}
    ],
    "study_suggestions": [
      "Modal analysis recommended - frequency/vibration mentioned",
      "Topology optimization could reduce mass while maintaining performance"
    ]
  },
  
  "transcript_summary": "This assembly provides structural support for a NEMA 23 motor..."
}
```

## Using with Atomizer

### 1. Generate Hints

```bash
cad-doc walkthrough.mp4 --atomizer-hints
```

### 2. Load in Atomizer

```python
# In Atomizer study setup
from atomizer import Study
import json

with open("walkthrough_docs/atomizer_hints.json") as f:
    hints = json.load(f)

study = Study.from_hints(hints)

# Hints pre-populate:
# - Objective functions
# - Constraints
# - Suggested parameters
# - Critical regions for mesh refinement
```

### 3. Review and Refine

The hints are suggestions, not final configurations:

- Verify objectives match your actual goals
- Add specific constraint values
- Map parameters to CAD model variables
- Adjust mesh refinement regions

## Best Practices

### During Recording

1. **State objectives clearly**
   - "The goal is to minimize weight while maintaining stiffness"
   - "We need to keep the first natural frequency above 100 Hz"

2. **Quantify constraints**
   - "Maximum envelope is 200mm by 150mm by 100mm"
   - "Weight budget is 500 grams"
   - "Stress must stay below 150 MPa"

3. **Point out critical features**
   - "This fillet is critical for stress concentration"
   - "The bearing surface here sees high contact stress"

4. **Mention what could be optimized**
   - "The wall thickness could potentially be reduced"
   - "These rib dimensions are candidates for optimization"

### After Generation

1. Review `atomizer_hints.json` for accuracy
2. Add missing numerical values
3. Map parameters to your CAD model
4. Use critical regions to guide mesh refinement
5. Run initial FEA to validate hints

## Example Workflow

1. **Record walkthrough** explaining bracket design
2. **Run CAD-Documenter** with `--atomizer-hints`
3. **Review hints** in generated JSON
4. **Import into Atomizer** for optimization study
5. **Iterate** based on FEA results

## Limitations

- Hints are extracted from verbal/visual cues only
- Numerical values may need refinement
- Complex multi-objective problems need manual setup
- Material properties should be verified against database