Atomizer/studies/README.md

# Atomizer Studies Directory

This directory contains optimization studies for the Atomizer framework. Each study is a self-contained workspace for running NX optimization campaigns.

## Directory Structure

```
studies/
├── README.md                    # This file
├── _templates/                  # Study templates for quick setup
│   ├── basic_stress_optimization/
│   ├── multi_objective/
│   └── constrained_optimization/
├── _archive/                    # Completed/old studies
│   └── YYYY-MM-DD_study_name/
└── [active_studies]/            # Your active optimization studies
    └── bracket_stress_minimization/  # Example study
```

## Study Folder Structure

Each study should follow this standardized structure:

```
study_name/
├── README.md                    # Study description, objectives, notes
├── optimization_config.json     # Atomizer configuration file
│
├── model/                       # FEA model files (NX or other solvers)
│   ├── model.prt               # NX part file
│   ├── model.sim               # NX Simcenter simulation file
│   ├── model.fem               # FEM file
│   └── assembly.asm            # NX assembly (if applicable)
│
├── optimization_results/        # Generated by Atomizer (DO NOT COMMIT)
│   ├── optimization.log        # High-level optimization progress log
│   ├── trial_logs/             # Detailed iteration logs (one per trial)
│   │   ├── trial_000_YYYYMMDD_HHMMSS.log
│   │   ├── trial_001_YYYYMMDD_HHMMSS.log
│   │   └── ...
│   ├── history.json            # Complete optimization history
│   ├── history.csv             # CSV format for analysis
│   ├── optimization_summary.json # Best results summary
│   ├── study_*.db              # Optuna database files
│   └── study_*_metadata.json   # Study metadata for resumption
│
├── analysis/                    # Post-optimization analysis
│   ├── plots/                  # Generated visualizations
│   ├── reports/                # Generated PDF/HTML reports
│   └── sensitivity_analysis.md # Analysis notes
│
└── notes.md                     # Engineering notes, decisions, insights
```

## Creating a New Study

### Option 1: From Template

```bash
# Copy a template
cp -r studies/_templates/basic_stress_optimization studies/my_new_study
cd studies/my_new_study

# Edit the configuration
# - Update optimization_config.json
# - Place your .sim, .prt, .fem files in model/
# - Update README.md with study objectives
```

### Option 2: Manual Setup

```bash
# Create study directory
mkdir -p studies/my_study/{model,analysis/plots,analysis/reports}

# Create config file
# (see _templates/ for examples)

# Add your files
# - Place all FEA files (.prt, .sim, .fem) in model/
# - Edit optimization_config.json
```

## Running an Optimization

```bash
# Navigate to project root
cd /path/to/Atomizer

# Run optimization for a study
python run_study.py --study studies/my_study

# Or use the full path to config
python -c "from optimization_engine.runner import OptimizationRunner; ..."
```

## Configuration File Format

The `optimization_config.json` file defines the optimization setup:

```json
{
  "design_variables": [
    {
      "name": "thickness",
      "type": "continuous",
      "bounds": [3.0, 8.0],
      "units": "mm",
      "initial_value": 5.0
    }
  ],
  "objectives": [
    {
      "name": "minimize_stress",
      "description": "Minimize maximum von Mises stress",
      "extractor": "stress_extractor",
      "metric": "max_von_mises",
      "direction": "minimize",
      "weight": 1.0,
      "units": "MPa"
    }
  ],
  "constraints": [
    {
      "name": "displacement_limit",
      "description": "Maximum allowable displacement",
      "extractor": "displacement_extractor",
      "metric": "max_displacement",
      "type": "upper_bound",
      "limit": 1.0,
      "units": "mm"
    }
  ],
  "optimization_settings": {
    "n_trials": 50,
    "sampler": "TPE",
    "n_startup_trials": 20,
    "tpe_n_ei_candidates": 24,
    "tpe_multivariate": true
  },
  "model_info": {
    "sim_file": "model/model.sim",
    "note": "Brief description"
  }
}
```

## Results Organization

All optimization results are stored in `optimization_results/` within each study folder.

### Optimization Log (optimization.log)

**High-level overview** of the entire optimization run:
- Optimization configuration (design variables, objectives, constraints)
- One compact line per trial showing design variables and results
- Easy to scan and monitor optimization progress
- Perfect for quick reviews and debugging

**Example format**:
```
[08:15:35] Trial   0 START | tip_thickness=20.450, support_angle=32.100
[08:15:42] Trial   0 COMPLETE | max_von_mises=245.320, max_displacement=0.856
[08:15:45] Trial   1 START | tip_thickness=18.230, support_angle=28.900
[08:15:51] Trial   1 COMPLETE | max_von_mises=268.450, max_displacement=0.923
```

### Trial Logs (trial_logs/)

**Detailed per-trial logs** showing complete iteration trace:
- Design variable values for the trial
- Complete optimization configuration
- Execution timeline (pre_solve, solve, post_solve, extraction)
- Extracted results (stress, displacement, etc.)
- Constraint evaluations
- Hook execution trace
- Solver output and warnings

**Example**: `trial_005_20251116_143022.log`

These logs are invaluable for:
- Debugging failed trials
- Understanding what happened in specific iterations
- Verifying solver behavior
- Tracking hook execution

### History Files

**Structured data** for analysis and visualization:
- **history.json**: Complete trial-by-trial results in JSON format
- **history.csv**: Same data in CSV for Excel/plotting
- **optimization_summary.json**: Best parameters and final results

### Optuna Database

**Study persistence** for resuming optimizations:
- **study_NAME.db**: SQLite database storing all trial data
- **study_NAME_metadata.json**: Study metadata and configuration hash

The database allows you to:
- Resume interrupted optimizations
- Add more trials to a completed study
- Query optimization history programmatically

## Best Practices

### Study Naming

- Use descriptive names: `bracket_stress_minimization` not `test1`
- Include objective: `wing_mass_displacement_tradeoff`
- Version if iterating: `bracket_v2_reduced_mesh`

### Documentation

- Always fill out README.md in each study folder
- Document design decisions in notes.md
- Keep analysis/ folder updated with plots and reports

### Version Control

Add to `.gitignore`:
```
studies/*/optimization_results/
studies/*/analysis/plots/
studies/*/__pycache__/
```

Commit to git:
```
studies/*/README.md
studies/*/optimization_config.json
studies/*/notes.md
studies/*/model/*.sim
studies/*/model/*.prt  (optional - large CAD files)
studies/*/model/*.fem
```

### Archiving Completed Studies

When a study is complete:

```bash
# Archive the study
mv studies/completed_study studies/_archive/2025-11-16_completed_study

# Update _archive/README.md with study summary
```

## Study Templates

### Basic Stress Optimization
- Single objective: minimize stress
- Single design variable
- Simple mesh
- Good for learning/testing

### Multi-Objective Optimization
- Multiple competing objectives (stress, mass, displacement)
- Pareto front analysis
- Weighted sum approach

### Constrained Optimization
- Objectives with hard constraints
- Demonstrates constraint handling
- Pruned trials when constraints violated

## Troubleshooting

### Study won't resume

Check that `optimization_config.json` hasn't changed. The config hash is stored in metadata and verified on resume.

### Missing trial logs or optimization.log

Ensure logging plugins are enabled:
- `optimization_engine/plugins/pre_solve/detailed_logger.py` - Creates detailed trial logs
- `optimization_engine/plugins/pre_solve/optimization_logger.py` - Creates high-level optimization.log
- `optimization_engine/plugins/post_extraction/log_results.py` - Appends results to trial logs
- `optimization_engine/plugins/post_extraction/optimization_logger_results.py` - Appends results to optimization.log

### Results directory missing

The directory is created automatically on first run. Check file permissions.

## Advanced: Custom Hooks

Studies can include custom hooks in a `hooks/` folder:

```
my_study/
├── hooks/
│   ├── pre_solve/
│   │   └── custom_parameterization.py
│   └── post_extraction/
│       └── custom_objective.py
└── ...
```

These hooks are automatically loaded if present.

## Questions?

- See main README.md for Atomizer documentation
- See DEVELOPMENT_ROADMAP.md for planned features
- Check docs/ for detailed guides