Atomizer/studies/bracket_displacement_maximizing/SUBSTUDIES_README.md

# Substudy System

The substudy system allows you to organize multiple optimization runs that share the same model files but have different configurations, like NX Solutions with subcases.

## Directory Structure

```
bracket_displacement_maximizing/
├── model/                          # Shared model files
│   ├── Bracket.prt                # Part file (shared)
│   ├── Bracket_fem1.fem           # FEM file (shared)
│   └── Bracket_sim1.sim           # Simulation file (shared)
├── config/
│   └── substudy_template.json    # Template for new substudies
├── substudies/                    # Independent substudy results
│   ├── coarse_exploration/       # Example: fast exploration
│   │   ├── config.json
│   │   ├── optimization_history.json
│   │   ├── optimization_history_incremental.json  # Live updates!
│   │   ├── best_design.json
│   │   └── report.md
│   └── fine_tuning/              # Example: refined optimization
│       ├── config.json
│       └── ...
├── run_substudy.py               # Substudy runner
└── run_optimization.py           # Original standalone runner
```

## Key Concepts

### Shared Model Files
All substudies use the **same** model files from `model/` directory:
- `Bracket.prt` - Updated with design variables during optimization
- `Bracket_fem1.fem` - Automatically updated when geometry changes
- `Bracket_sim1.sim` - Simulation definition

This is like NX where different Subcases share the same model.

### Independent Substudy Configurations
Each substudy has its own:
- Parameter bounds (coarse vs. fine)
- Number of trials
- Algorithm settings
- Results directory

### Continuation Support
Substudies can continue from previous runs:
- Start from best design of previous substudy
- Refine search in narrower bounds
- Build on previous work incrementally

### Live History Tracking
Each substudy automatically saves incremental history:
- `optimization_history_incremental.json` updates after each trial
- Monitor progress in real-time
- No need to query Optuna database

## Usage

### 1. Create a New Substudy

Copy the template and customize:

```bash
# Create new substudy directory
mkdir substudies/my_substudy_name

# Copy template
cp config/substudy_template.json substudies/my_substudy_name/config.json

# Edit config.json with your parameters
```

### 2. Configure the Substudy

Edit `substudies/my_substudy_name/config.json`:

```json
{
  "substudy_name": "my_substudy_name",
  "description": "What this substudy investigates",
  "parent_study": "bracket_displacement_maximizing",

  "optimization": {
    "algorithm": "TPE",
    "direction": "minimize",
    "n_trials": 20,
    "design_variables": [
      {
        "parameter": "tip_thickness",
        "min": 15.0,
        "max": 25.0,
        "units": "mm"
      },
      {
        "parameter": "support_angle",
        "min": 20.0,
        "max": 40.0,
        "units": "degrees"
      }
    ]
  },

  "continuation": {
    "enabled": false
  }
}
```

**IMPORTANT**: Use `"parameter"` not `"name"` for design variables!

### 3. Run the Substudy

```bash
cd studies/bracket_displacement_maximizing
python run_substudy.py my_substudy_name
```

### 4. Monitor Progress

Watch the live history file update in real-time:

```bash
# In another terminal
watch -n 5 cat substudies/my_substudy_name/optimization_history_incremental.json
```

### 5. Continuing from Previous Substudy

To refine results from a previous substudy:

```json
{
  "substudy_name": "refined_search",
  "optimization": {
    "design_variables": [
      {
        "parameter": "tip_thickness",
        "min": 18.0,  // Narrower bounds
        "max": 22.0,
        "units": "mm"
      }
    ]
  },

  "continuation": {
    "enabled": true,
    "from_substudy": "my_substudy_name",
    "inherit_best_params": true  // Start from best design
  }
}
```

## Example Workflows

### Workflow 1: Coarse-to-Fine Optimization

1. **Coarse Exploration** (20 trials, wide bounds)
   - Fast exploration of entire design space
   - Identify promising regions

2. **Fine Tuning** (50 trials, narrow bounds)
   - Continue from best coarse design
   - Refine solution in narrow bounds

### Workflow 2: Algorithm Comparison

1. **TPE Optimization** (substudy with TPE algorithm)
2. **NSGAII Optimization** (substudy with genetic algorithm)
3. Compare results across different algorithms

### Workflow 3: Incremental Study Extension

1. Run initial 20-trial substudy
2. Analyze results
3. Create continuation substudy for 30 more trials
4. Keep building on previous work

## Files Generated per Substudy

After running a substudy, you'll find:

- `optimization_history.json` - Complete trial history
- `optimization_history_incremental.json` - Live-updating history
- `best_design.json` - Best parameters and performance
- `report.md` - Human-readable markdown report
- `optuna_study.db` - Optuna database (in output_dir)

## Tips

1. **Name substudies descriptively**: `coarse_20trials`, `fine_50trials_narrow_bounds`
2. **Use continuation wisely**: Continue from coarse to fine, not vice versa
3. **Monitor live history**: Use it to catch issues early
4. **Keep model files clean**: The shared model in `model/` is modified during optimization
5. **Back up good results**: Copy substudy directories before running new ones

## Comparison with NX

| NX Concept | Substudy Equivalent |
|------------|-------------------|
| Solution | Study (bracket_displacement_maximizing) |
| Subcase | Substudy (coarse_exploration) |
| Shared model | model/ directory |
| Subcase parameters | config.json |
| Subcase results | substudy directory |