# Guided Study Creation Wizard

**Version**: 1.0
**Purpose**: Interactive conversational wizard for creating new optimization studies from scratch.

---

## Overview

This skill provides a step-by-step guided experience for users who want to create a new optimization study. It asks focused questions to gather requirements, then generates the complete study configuration.

---

## Wizard Flow

### Phase 1: Understanding the Problem (Discovery)

Start with open-ended questions to understand what the user wants to optimize:

**Opening Prompt:**
```
I'll help you set up a new optimization study. Let's start with the basics:

1. **What are you trying to optimize?**
   - Describe the physical system (e.g., "a telescope mirror", "a UAV arm", "a bracket")

2. **What's your goal?**
   - Minimize weight? Maximize stiffness? Minimize stress? Multiple objectives?

3. **Do you have an NX model ready?**
   - If yes, where is it located?
   - If no, we can discuss what's needed
```

### Phase 2: Model Analysis (If NX model provided)

If user provides a model path:

1. **Check the model exists**
   ```python
   # Verify path
   model_path = Path(user_provided_path)
   if model_path.exists():
       # Proceed with analysis
   else:
       # Ask for correct path
   ```

2. **Extract expressions (design parameters)**
   - List all NX expressions that could be design variables
   - Ask user to confirm which ones to optimize

3. **Identify simulation setup**
   - What solution types are present? (static, modal, buckling)
   - What results are available?

### Phase 3: Define Objectives & Constraints

Ask focused questions:

```
Based on your model, I can see these results are available:
- Displacement (from static solution)
- Von Mises stress (from static solution)
- Natural frequency (from modal solution)
- Mass (from geometry)

**Questions:**

1. **Primary Objective** - What do you want to minimize/maximize?
   Examples: "minimize tip displacement", "minimize mass"

2. **Secondary Objectives** (optional) - Any other goals?
   Examples: "also minimize stress", "maximize first frequency"

3. **Constraints** - What limits must be respected?
   Examples: "stress < 200 MPa", "frequency > 50 Hz", "mass < 2 kg"
```

### Phase 4: Define Design Space

For each design variable identified:

```
For parameter `{param_name}` (current value: {current_value}):
- **Minimum value**: (default: -20% of current)
- **Maximum value**: (default: +20% of current)
- **Type**: continuous or discrete?
```

### Phase 5: Optimization Settings

```
**Optimization Configuration:**

1. **Number of trials**: How thorough should the search be?
   - Quick exploration: 50-100 trials
   - Standard: 100-200 trials
   - Thorough: 200-500 trials
   - With neural acceleration: 500+ trials

2. **Protocol Selection** (I'll recommend based on your setup):
   - Single objective → Protocol 10 (IMSO)
   - Multi-objective (2-3 goals) → Protocol 11 (NSGA-II)
   - Large-scale with NN → Protocol 12 (Hybrid)

3. **Neural Network Acceleration**:
   - Enable if n_trials > 100 and you want faster iterations
```

### Phase 6: Summary & Confirmation

Present the complete configuration for user approval:

```
## Study Configuration Summary

**Study Name**: {study_name}
**Location**: studies/{study_name}/

**Model**: {model_path}

**Design Variables** ({n_vars} parameters):
| Parameter | Min | Max | Type |
|-----------|-----|-----|------|
| {name1} | {min1} | {max1} | continuous |
| ... | ... | ... | ... |

**Objectives**:
- {objective1}: {direction1}
- {objective2}: {direction2} (if multi-objective)

**Constraints**:
- {constraint1}
- {constraint2}

**Settings**:
- Protocol: {protocol}
- Trials: {n_trials}
- Sampler: {sampler}
- Neural Acceleration: {enabled/disabled}

---

Does this look correct?
- Type "yes" to generate the study files
- Type "change X" to modify a specific setting
- Type "start over" to begin again
```

### Phase 7: Generation

Once confirmed, generate:

1. Create study directory structure
2. Copy model files to working directory
3. Generate `optimization_config.json`
4. Generate `run_optimization.py`
5. Validate everything works

```
✓ Study created successfully!

**Next Steps:**
1. Review the generated files in studies/{study_name}/
2. Run a quick validation: `python run_optimization.py --validate`
3. Start optimization: `python run_optimization.py --start`

Or just tell me "start the optimization" and I'll handle it!
```

---

## Question Templates

### For Understanding Goals

- "What problem are you trying to solve?"
- "What makes a 'good' design for your application?"
- "Are there any hard limits that must not be exceeded?"
- "Is this a weight reduction study, a performance study, or both?"

### For Design Variables

- "Which dimensions or parameters should I vary?"
- "Are there any parameters that must stay fixed?"
- "What are reasonable bounds for {parameter}?"
- "Should {parameter} be continuous or discrete (specific values only)?"

### For Constraints

- "What's the maximum stress this component can handle?"
- "Is there a minimum stiffness requirement?"
- "Are there weight limits?"
- "What frequency should the structure avoid (resonance concerns)?"

### For Optimization Settings

- "How much time can you allocate to this study?"
- "Do you need a quick exploration or thorough optimization?"
- "Is this a preliminary study or final optimization?"

---

## Default Configurations by Use Case

### Structural Weight Minimization
```json
{
  "objectives": [
    {"name": "mass", "direction": "minimize", "target": null}
  ],
  "constraints": [
    {"name": "max_stress", "type": "<=", "value": 200e6, "unit": "Pa"},
    {"name": "max_displacement", "type": "<=", "value": 0.001, "unit": "m"}
  ],
  "n_trials": 150,
  "sampler": "TPE"
}
```

### Multi-Objective (Weight vs Performance)
```json
{
  "objectives": [
    {"name": "mass", "direction": "minimize"},
    {"name": "max_displacement", "direction": "minimize"}
  ],
  "n_trials": 200,
  "sampler": "NSGA-II"
}
```

### Modal Optimization (Frequency Tuning)
```json
{
  "objectives": [
    {"name": "first_frequency", "direction": "maximize"}
  ],
  "constraints": [
    {"name": "mass", "type": "<=", "value": 5.0, "unit": "kg"}
  ],
  "n_trials": 150,
  "sampler": "TPE"
}
```

### Telescope Mirror (Zernike WFE)
```json
{
  "objectives": [
    {"name": "filtered_rms", "direction": "minimize", "unit": "nm"}
  ],
  "constraints": [
    {"name": "mass", "type": "<=", "value": null}
  ],
  "extractor": "ZernikeExtractor",
  "n_trials": 200,
  "sampler": "NSGA-II"
}
```

---

## Error Handling

### Model Not Found
```
I couldn't find a model at that path. Let's verify:
- Current directory: {cwd}
- You specified: {user_path}

Could you check the path and try again?
Tip: Use an absolute path like "C:/Users/.../model.prt"
```

### No Expressions Found
```
I couldn't find any parametric expressions in this model.

For optimization, we need parameters defined as NX expressions.
Would you like me to explain how to add expressions to your model?
```

### Invalid Constraint
```
That constraint doesn't match any available results.

Available results from your model:
- {result1}
- {result2}

Which of these would you like to constrain?
```

---

## Integration with Dashboard

When running from the Atomizer dashboard with a connected Claude terminal:

1. **No study selected** → Offer to create a new study
2. **Study selected** → Use that study's context, offer to modify or run

The dashboard will display the study once created, showing real-time progress.

---

## Quick Commands

For users who know what they want:

- `create study {name} from {model_path}` - Skip to model analysis
- `quick setup` - Use all defaults, just confirm
- `copy study {existing} as {new}` - Clone an existing study as starting point

---

## Remember

- **Be conversational** - This is a wizard, not a form
- **Offer sensible defaults** - Don't make users specify everything
- **Validate as you go** - Catch issues early
- **Explain decisions** - Say why you recommend certain settings
- **Keep it focused** - One question at a time, don't overwhelm