Atomizer/docs/development/ATOMIZER_USER_GUIDE.md

# Atomizer User Guide

**How to Use Atomizer So It Evolves the Right Way**

**Version**: 1.0
**Last Updated**: 2025-12-11

---

## Introduction

Atomizer is not just an optimization tool - it's a **learning system**. Every session you have with Claude contributes to making future sessions better. This guide teaches you how to use Atomizer properly so that:

1. You get the best results from your optimizations
2. The system learns and improves over time
3. Knowledge is preserved and shared

---

## Table of Contents

1. [The Right Mindset](#1-the-right-mindset)
2. [Starting a Session](#2-starting-a-session)
3. [Communicating with Atomizer Claude](#3-communicating-with-atomizer-claude)
4. [Creating Optimization Studies](#4-creating-optimization-studies)
5. [Running Optimizations](#5-running-optimizations)
6. [Analyzing Results](#6-analyzing-results)
7. [When Things Go Wrong](#7-when-things-go-wrong)
8. [Contributing to Learning](#8-contributing-to-learning)
9. [Ending a Session](#9-ending-a-session)
10. [Best Practices Summary](#10-best-practices-summary)

---

## 1. The Right Mindset

### Think of Atomizer as a Knowledgeable Colleague

```
❌ Wrong: "Atomizer is a tool I use"
✅ Right: "Atomizer is a colleague who learns from our conversations"
```

When you work with Atomizer:
- **Explain your goals** - not just what you want, but *why*
- **Share context** - what constraints matter? what tradeoffs are acceptable?
- **Report outcomes** - did it work? what surprised you?
- **Mention discoveries** - found something unexpected? Say so!

### The Learning Loop

```mermaid
graph LR
    A[You describe problem] --> B[Claude suggests approach]
    B --> C[Optimization runs]
    C --> D[Results analyzed]
    D --> E[Learnings recorded]
    E --> F[Next session is smarter]
    F --> A
```

**Your job**: Keep Claude informed so the loop works.

---

## 2. Starting a Session

### What Happens Behind the Scenes

When you start a new Claude Code session in the Atomizer project:

1. Claude reads `CLAUDE.md` (system instructions)
2. Claude checks for active studies
3. Claude queries LAC for relevant prior knowledge
4. Claude is ready to help

### Good Session Starters

```
✅ "I need to optimize my bracket for minimum mass while keeping
   stress below 250 MPa. The model is in studies/bracket_v4/"

✅ "Continue working on the mirror optimization from yesterday.
   I think we were at 50 trials."

✅ "I'm having trouble with the beam study - the solver keeps
   timing out."
```

### Bad Session Starters

```
❌ "Optimize this" (no context)

❌ "Run the thing" (what thing?)

❌ "It's not working" (what isn't working?)
```

### Providing Context Helps Learning

When you provide good context, Claude can:
- Find similar past optimizations in LAC
- Apply learnings from previous sessions
- Make better method recommendations

```mermaid
sequenceDiagram
    participant You
    participant Claude
    participant LAC

    You->>Claude: "Optimize bracket for mass, stress < 250 MPa"
    Claude->>LAC: Query similar: "bracket mass stress"
    LAC-->>Claude: Found: TPE worked 85% for brackets
    LAC-->>Claude: Insight: "20 startup trials helps"
    Claude->>You: "Based on 5 similar studies, I recommend TPE with 20 startup trials..."
```

---

## 3. Communicating with Atomizer Claude

### Be Specific About Goals

```
❌ Vague: "Make it lighter"

✅ Specific: "Minimize mass while keeping maximum displacement < 2mm
   and first natural frequency > 100 Hz"
```

### Mention Constraints and Preferences

```
✅ "I need results by Friday, so limit to 50 trials"

✅ "This is a preliminary study - rough results are fine"

✅ "This is for production - I need high confidence in the optimum"

✅ "I prefer TPE over CMA-ES based on past experience"
```

### Ask Questions

Atomizer Claude is an expert. Use that expertise:

```
✅ "What method do you recommend for this problem?"

✅ "How many trials should I run?"

✅ "Is this the right extractor for von Mises stress?"

✅ "Why did convergence slow down after trial 30?"
```

### Report What You Observe

This is **critical for learning**:

```
✅ "The optimization converged faster than expected - maybe because
   the design space is simple?"

✅ "I noticed the solver is slow when thickness < 2mm"

✅ "The Pareto front has a sharp knee around mass = 3kg"

✅ "This result doesn't make physical sense - stress should increase
   with thinner walls"
```

---

## 4. Creating Optimization Studies

### The Creation Flow

```mermaid
flowchart TD
    A[Describe your optimization goal] --> B{Claude analyzes model}
    B --> C[Claude suggests config]
    C --> D{You approve?}
    D -->|Yes| E[Files generated]
    D -->|Adjust| F[Discuss changes]
    F --> C
    E --> G[Ready to run]
```

### What to Provide

| Information | Why It Matters |
|-------------|----------------|
| **Model files** (.prt, .sim, .fem) | Claude needs to analyze them |
| **Optimization goal** | "Minimize mass", "Maximize stiffness" |
| **Constraints** | "Stress < 250 MPa", "Frequency > 100 Hz" |
| **Design variables** | Which parameters to vary (or let Claude discover) |
| **Trial budget** | How many evaluations you can afford |

### Example: Good Study Creation Request

```
"Create an optimization study for my UAV arm:

Goal: Minimize mass while maximizing stiffness (multi-objective)

Constraints:
- Maximum stress < 200 MPa
- First frequency > 50 Hz

Design variables:
- Wall thickness (1-5 mm)
- Rib spacing (10-50 mm)
- Material (Al6061 or Al7075)

Budget: About 100 trials, I have time for a thorough study.

The model is in studies/uav_arm_v2/1_setup/model/"
```

### Review the Generated Config

Claude will generate `optimization_config.json`. **Review it**:

```
✅ Check that objectives match your goals
✅ Verify constraints are correct
✅ Confirm design variable bounds make sense
✅ Ensure extractors are appropriate
```

If something's wrong, say so! This helps Claude learn what works.

---

## 5. Running Optimizations

### Before Running

Ask Claude to validate:

```
"Please validate the config before we run"
```

This catches errors early.

### During Running

You can:
- **Check progress**: "How many trials completed?"
- **See best so far**: "What's the current best design?"
- **Monitor convergence**: "Is it converging?"

### If You Need to Stop

```
"Pause the optimization - I need to check something"
```

Claude will help you resume later.

### Long-Running Optimizations

For studies with many trials:

```
"Start the optimization and let it run overnight.
I'll check results tomorrow."
```

---

## 6. Analyzing Results

### What to Ask For

```
✅ "Show me the best design"

✅ "Plot the convergence history"

✅ "Show the Pareto front" (for multi-objective)

✅ "Compare the top 5 designs"

✅ "What parameters are most important?"

✅ "Generate a study report"
```

### Validate Results Physically

**This is important for learning!** Tell Claude if results make sense:

```
✅ "This looks right - thinner walls do reduce mass"

✅ "This is surprising - I expected more sensitivity to rib spacing"

❌ "This can't be right - stress should be higher with this geometry"
```

When results don't make sense, investigate together:
- Check extractor configuration
- Verify solver completed correctly
- Look for constraint violations

### Record Insights

If you discover something interesting:

```
"Record this insight: For UAV arms with thin walls (<2mm),
the frequency constraint becomes dominant before stress."
```

---

## 7. When Things Go Wrong

### How to Report Errors

**Good error report:**
```
"The optimization failed at trial 23.
Error message: 'OP2 file not found'
The NX log shows 'Singular stiffness matrix'"
```

**Bad error report:**
```
"It's broken"
```

### Common Issues and What to Say

| Issue | How to Report |
|-------|---------------|
| Solver timeout | "Solver timed out after X minutes on trial Y" |
| Missing file | "Can't find [filename] - should it be in [location]?" |
| Unexpected results | "Results don't match physics - [explain why]" |
| Slow convergence | "Still not converged after X trials - should I continue?" |

### Help Claude Help You

When troubleshooting:

```
✅ "Here's what I already tried: [list attempts]"

✅ "This worked for a similar study last week"

✅ "The model works fine when I run it manually in NX"
```

### Workarounds Should Be Recorded

If you find a workaround:

```
"We found that loading the _i.prt file first fixes the mesh update issue.
Please record this as a workaround."
```

This helps future sessions avoid the same problem.

---

## 8. Contributing to Learning

### The Learning Atomizer Core (LAC)

LAC stores three types of knowledge:

```mermaid
graph TB
    subgraph LAC["What LAC Learns"]
        A[Optimization Memory<br/>What methods work for what]
        B[Session Insights<br/>Failures, successes, workarounds]
        C[Skill Evolution<br/>Protocol improvements]
    end
```

### How You Contribute

#### 1. Report Outcomes

At the end of a successful optimization:

```
"The optimization completed successfully. TPE worked well for this
bracket problem - converged at trial 67 out of 100."
```

Claude records this to LAC automatically.

#### 2. Share Discoveries

When you learn something:

```
"I discovered that CMA-ES struggles with this type of problem
because of the discrete frequency target. TPE handled it better."
```

Claude will record this insight.

#### 3. Report Preferences

Your preferences help personalize future sessions:

```
"I prefer seeing actual values in plots rather than normalized values"

"I like concise summaries - you don't need to explain basic FEA to me"
```

#### 4. Suggest Improvements

If documentation was unclear:

```
"The protocol didn't explain how to handle assemblies -
you should add that."
```

Claude will suggest a protocol update.

### What Gets Recorded

| Type | Example | Used For |
|------|---------|----------|
| **Success** | "TPE converged in 67 trials for bracket" | Method recommendations |
| **Failure** | "CMA-ES failed on discrete targets" | Avoiding bad choices |
| **Workaround** | "Load _i.prt before UpdateFemodel()" | Fixing known issues |
| **Preference** | "User prefers concise output" | Personalization |

---

## 9. Ending a Session

### Before You Go

Take 30 seconds to wrap up properly:

```
"Let's wrap up this session."
```

Claude will:
1. Summarize what was accomplished
2. Record any learnings to LAC
3. Note the current state of any studies
4. Suggest next steps

### Good Session Endings

```
✅ "We're done for today. The optimization is at trial 50,
   continuing overnight. I'll check results tomorrow."

✅ "Session complete. Please record that TPE worked well
   for this beam optimization."

✅ "Ending session. Next time I want to analyze the Pareto
   front in more detail."
```

### Bad Session Endings

```
❌ [Just closing the window without wrapping up]

❌ [Stopping mid-task without noting the state]
```

### Session Summary

Ask for a summary:

```
"Summarize this session"
```

You'll get:
- What was accomplished
- Current state of studies
- Learnings recorded
- Recommended next steps

---

## 10. Best Practices Summary

### Do These Things

| Practice | Why |
|----------|-----|
| **Provide context** | Enables LAC queries and better recommendations |
| **Explain your goals** | Claude can suggest better approaches |
| **Report outcomes** | Builds optimization memory |
| **Share discoveries** | Prevents repeat mistakes |
| **Validate results** | Catches errors, improves extractors |
| **Wrap up sessions** | Records learnings properly |

### Avoid These Things

| Anti-Pattern | Why It's Bad |
|--------------|--------------|
| Vague requests | Claude can't help effectively |
| Ignoring results | Missed learning opportunities |
| Not reporting errors | Same errors repeat |
| Abandoning sessions | Learnings not recorded |
| Skipping validation | Errors propagate |

### The Golden Rules

```
┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│  1. CONTEXT IS KING                                                 │
│     The more context you provide, the better Claude can help.       │
│                                                                     │
│  2. OUTCOMES MATTER                                                 │
│     Always report whether things worked or didn't.                  │
│                                                                     │
│  3. SHARE DISCOVERIES                                               │
│     If you learn something, say it. It helps everyone.              │
│                                                                     │
│  4. CLOSE THE LOOP                                                  │
│     End sessions properly so learnings are captured.                │
│                                                                     │
│  5. TRUST BUT VERIFY                                                │
│     Review generated configs. Validate results physically.          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

---

## Quick Reference Card

### Session Start
```
"I need to [goal] for my [geometry type].
The model is in [location].
Constraints: [list].
Budget: [trials]."
```

### During Session
```
"What do you recommend for [decision]?"
"The results show [observation] - does this make sense?"
"I discovered that [insight]."
```

### Session End
```
"Let's wrap up. Please record that [outcome/learning]."
"Summarize this session."
```

### Reporting Issues
```
"[Action] failed with error: [message]
I already tried: [attempts]
The expected behavior was: [expectation]"
```

---

## Example: A Complete Session

Here's what a good session looks like:

```
YOU: I need to optimize my bracket for minimum mass.
     Stress must stay below 250 MPa. The model is in
     studies/bracket_v5/1_setup/model/. I have time
     for about 100 trials.

CLAUDE: I'll analyze your model and check LAC for similar studies.
        [Analyzes model, queries LAC]

        Based on 3 similar bracket optimizations, I recommend TPE
        with 20 startup trials. This converged in ~70 trials for
        similar problems.

        Found 4 expressions: thickness_1, thickness_2, fillet_r, width
        I suggest varying all of them.

        Here's the proposed config: [shows config]

        Want me to proceed?

YOU: Looks good, but I want to fix fillet_r at 5mm -
     it's a manufacturing constraint.

CLAUDE: Updated config with fillet_r fixed at 5mm.
        Validated - ready to run.

        Start the optimization?

YOU: Yes, run it.

[Optimization runs...]

YOU: How's progress?

CLAUDE: Trial 45/100 complete.
        Current best: 2.34 kg at trial 32
        Convergence: Good - variance dropping steadily

        On track to complete in ~30 minutes.

[Optimization completes]

CLAUDE: Optimization complete.
        Best design: mass = 2.18 kg (trial 78)
        - thickness_1: 3.2 mm
        - thickness_2: 2.8 mm
        - width: 45 mm

        Stress constraint satisfied: max stress = 237 MPa

        Want me to generate a detailed report?

YOU: Yes. Also, I noticed convergence was faster than the similar
     studies you mentioned. Maybe because I fixed the fillet radius?

CLAUDE: Good observation. That reduces the design space from 4 to 3
        variables, which typically speeds convergence.

        I'll record this insight: "Fixing fillet radius in bracket
        optimization reduced design space and improved convergence
        by ~20%."

        [Generates report]

        Report saved. Anything else?

YOU: No, let's wrap up.

CLAUDE: Session Summary:

        ## Accomplished
        - Created and ran bracket_v5 optimization
        - Found optimum: 2.18 kg at trial 78
        - Generated study report

        ## Learnings Recorded
        - TPE effective for 3-variable bracket optimization
        - Fixing fillet radius improved convergence ~20%

        ## Next Steps
        1. Review detailed report
        2. Validate design in NX
        3. Consider manufacturing feasibility
```

---

## Getting Help

If you're stuck:

```
"I'm not sure how to [task]. Can you help?"
```

If something seems wrong:

```
"This doesn't seem right because [reason]. Can we investigate?"
```

If you want to learn:

```
"Explain how [concept] works in Atomizer"
```

---

*Remember: Every session makes Atomizer smarter. Your contributions matter.*

*Atomizer: Where engineers talk, AI optimizes, and learning never stops.*