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:

# 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:

{
  "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

cd studies/bracket_displacement_maximizing
python run_substudy.py my_substudy_name

4. Monitor Progress

Watch the live history file update in real-time:

# 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:

{
  "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