Atomizer/docs/hq/STUDY_CONVENTIONS.md

# Study Conventions

**Version**: 1.0  
**Created**: February 2026  
**Target Audience**: Technical Lead, Optimizer, Study Builder  
**References**: `studies/README.md`, `templates/HOW_TO_CREATE_A_STUDY.md`

---

## Overview

Studies are the technical execution units of Atomizer-HQ. They represent specific FEA optimization runs that generate data, insights, and optimized designs. This document defines how studies are structured, executed, and integrated with the broader project workflow.

### Study vs. Project Distinction
- **Project** = Business/client organizing unit (`projects/[name]/`)
- **Study** = Technical execution unit (`studies/[name]/`)
- **Relationship**: Studies contribute results back to project KB and deliverables

---

## Study Directory Structure

Every study follows a standardized structure for consistency and tool compatibility.

### Standard Study Layout
```
studies/[study-name]/
│
├── README.md                      # Study purpose, configuration, results
├── atomizer_spec.json             # Study configuration (AtomizerSpec v2.0)
├── run_optimization.py            # Study execution script
│
├── model/                         # Study-specific model files
│   ├── [component].prt            # NX CAD model (copied from project reference)
│   ├── [component].sim            # NX simulation setup
│   ├── [component].fem            # FEM file
│   └── baseline_results/          # Initial validation results
│
├── introspection/                 # Pre-study analysis
│   ├── model_analysis.md          # Model validation and setup notes
│   ├── parameter_sensitivity.md   # Initial parameter studies
│   └── optimization_plan.md       # Study-specific optimization strategy
│
├── results/                       # Generated by Atomizer (DO NOT COMMIT)
│   ├── optimization.log           # High-level progress log
│   ├── trial_logs/                # Detailed per-trial logs
│   ├── history.json               # Complete trial history
│   ├── history.csv                # CSV format for analysis
│   ├── best_trial.json            # Best design summary
│   ├── plots/                     # Auto-generated visualizations
│   └── study_*.db                 # Optuna database files
│
└── project_link                   # Link to parent project (optional)
```

---

## Study Naming Conventions

Studies use a consistent naming pattern for organization and traceability.

### Naming Pattern: `[project]_[number]_[descriptive_name]`

**Examples**:
- `hydrotech_01_baseline_validation`
- `hydrotech_02_stress_optimization`  
- `bracket_03_mass_reduction`
- `mount_04_fatigue_analysis`

### Naming Rules
1. **Project prefix** — Links study to project context
2. **Sequential numbering** — `01`, `02`, `03`, etc. (always two digits)
3. **Descriptive name** — Clear purpose in underscore format
4. **No spaces** — Use underscores throughout
5. **Lowercase** — Consistent case convention

---

## atomizer_spec.json Format

Studies use AtomizerSpec v2.0 as the single source of truth for configuration.

### Complete atomizer_spec.json Example
```json
{
  "study_name": "hydrotech_02_stress_optimization",
  "description": "Minimize maximum stress in hydraulic cylinder mount",
  "created": "2026-02-05T14:30:00Z",
  "version": "2.0",
  
  "model": {
    "sim_file": "model/cylinder_mount.sim",
    "prt_file": "model/cylinder_mount.prt",
    "fem_file": "model/cylinder_mount.fem",
    "description": "Hydraulic cylinder mounting bracket with 4-bolt pattern"
  },
  
  "design_variables": {
    "bracket_thickness": {
      "type": "continuous",
      "min": 8.0,
      "max": 20.0,
      "initial": 12.0,
      "units": "mm",
      "description": "Main bracket plate thickness"
    },
    "fillet_radius": {
      "type": "continuous", 
      "min": 3.0,
      "max": 12.0,
      "initial": 5.0,
      "units": "mm",
      "description": "Fillet radius at gusset-bracket intersection"
    },
    "gusset_thickness": {
      "type": "continuous",
      "min": 6.0,
      "max": 15.0,
      "initial": 10.0,
      "units": "mm",
      "description": "Gusset plate thickness"
    }
  },
  
  "extractors": [
    {
      "name": "max_stress",
      "function": "extract_stress",
      "parameters": {
        "result_type": "von_mises",
        "metric": "max",
        "units": "MPa"
      },
      "description": "Maximum von Mises stress in structure"
    },
    {
      "name": "max_displacement", 
      "function": "extract_displacement",
      "parameters": {
        "metric": "max",
        "units": "mm"
      },
      "description": "Maximum displacement magnitude"
    },
    {
      "name": "total_mass",
      "function": "extract_mass",
      "parameters": {
        "units": "kg"
      },
      "description": "Total structural mass"
    }
  ],
  
  "objectives": [
    {
      "name": "minimize_stress",
      "extractor": "max_stress",
      "direction": "minimize",
      "weight": 1.0,
      "target": 150.0,
      "units": "MPa"
    }
  ],
  
  "constraints": [
    {
      "name": "displacement_limit",
      "extractor": "max_displacement", 
      "type": "upper_bound",
      "limit": 2.0,
      "units": "mm",
      "description": "Maximum allowable displacement"
    },
    {
      "name": "mass_limit",
      "extractor": "total_mass",
      "type": "upper_bound", 
      "limit": 5.0,
      "units": "kg",
      "description": "Maximum allowable mass"
    }
  ],
  
  "optimization_settings": {
    "n_trials": 50,
    "sampler": "TPE",
    "n_startup_trials": 10,
    "timeout": 7200,
    "pruning": {
      "enabled": true,
      "patience": 5
    }
  },
  
  "post_processing": {
    "generate_plots": true,
    "plot_formats": ["png", "pdf"],
    "cleanup_models": false,
    "keep_top_n_models": 10
  },
  
  "project": {
    "name": "hydrotech-beam",
    "phase": "stress_optimization", 
    "kb_path": "../projects/hydrotech-beam/kb",
    "deliverable_path": "../projects/hydrotech-beam/deliverables"
  }
}
```

---

## Study Setup Process

### 1. Technical Lead: Study Planning
Before creating the study, the Technical Lead defines the optimization strategy.

**Planning Tasks**:
- Define study objectives and success criteria
- Select design variables and ranges
- Choose optimization strategy and settings
- Plan model setup and validation approach

**Planning Documentation** (`introspection/optimization_plan.md`):
```markdown
# Study Optimization Plan

## Objective
Minimize maximum stress while maintaining displacement and mass constraints

## Design Variables
- bracket_thickness: Primary structural parameter (8-20mm)
- fillet_radius: Local stress concentrator (3-12mm)  
- gusset_thickness: Secondary support (6-15mm)

## Strategy
1. Initial exploration: 20 trials to map design space
2. Focused optimization: 30 additional trials on promising regions
3. Validation: Verify best designs with mesh convergence

## Expected Outcomes
- Target: Reduce max stress from 185 MPa to <150 MPa
- Maintain: Displacement <2mm, mass <5kg
- Timeline: 2-3 days execution
```

### 2. Optimizer: Study Creation
The Optimizer creates the study structure and configuration.

**Creation Steps**:
```bash
# Create study directory
mkdir -p studies/hydrotech_02_stress_optimization/{model,introspection,results}

# Copy reference models from project
cp projects/hydrotech-beam/models/reference/* \
   studies/hydrotech_02_stress_optimization/model/

# Create atomizer_spec.json from template
# (Use existing study as template or create from scratch)

# Create study README.md
cp templates/study_README_template.md \
   studies/hydrotech_02_stress_optimization/README.md
```

### 3. Optimizer: Model Validation  
Validate the model setup before optimization begins.

**Validation Checklist**:
- [ ] Model loads and runs successfully in NX
- [ ] Design variables update model geometry correctly
- [ ] Extractors return valid results
- [ ] Baseline results match expectations
- [ ] Convergence criteria are met

**Validation Documentation** (`introspection/model_analysis.md`):
```markdown
# Model Validation Results

## Baseline Analysis
- Max stress: 185.3 MPa at upper bolt interface
- Max displacement: 1.42 mm at bracket tip
- Total mass: 3.8 kg

## Parameter Sensitivity
- Thickness: 10% increase → 8% stress reduction
- Fillet radius: 2mm increase → 12% stress reduction
- Gusset thickness: Minimal effect on global stress

## Model Quality
- Mesh convergence: <5% change with 50% refinement
- Solver convergence: 6 iterations typical
- Extractor validation: Results consistent with NX postprocessor
```

---

## Study Execution

### Optimization Execution Workflow

**1. Pre-Execution Check**:
```bash
# Validate configuration
python optimization_engine/validate_spec.py studies/hydrotech_02_stress_optimization/atomizer_spec.json

# Test model functionality  
python optimization_engine/test_model.py studies/hydrotech_02_stress_optimization/
```

**2. Execute Study**:
```bash
# Navigate to Atomizer root
cd /path/to/Atomizer

# Run optimization
python run_study.py --study studies/hydrotech_02_stress_optimization
```

**3. Monitor Progress**:
```bash
# Follow optimization log
tail -f studies/hydrotech_02_stress_optimization/results/optimization.log

# Check current status
python optimization_engine/check_status.py studies/hydrotech_02_stress_optimization
```

### Progress Monitoring

**Optimization Log Format**:
```
[14:35:22] Study START | Design variables: 3, Objectives: 1, Constraints: 2
[14:35:22] Trial   0 START | bracket_thickness=12.0, fillet_radius=5.0, gusset_thickness=10.0
[14:35:48] Trial   0 COMPLETE | max_stress=185.3, max_displacement=1.42, total_mass=3.8
[14:35:51] Trial   1 START | bracket_thickness=15.2, fillet_radius=7.8, gusset_thickness=11.5
[14:36:15] Trial   1 COMPLETE | max_stress=158.7, max_displacement=1.18, total_mass=4.2
```

---

## Results Processing

### Automatic Results Generation
The optimization engine automatically generates:

**Core Results**:
- `history.json` — Complete trial data
- `history.csv` — Analysis-friendly format  
- `best_trial.json` — Optimal design summary
- `optimization.log` — Human-readable progress

**Visualizations** (if enabled):
- Parameter correlation plots
- Objective history plots
- Constraint violation plots  
- Pareto front plots (multi-objective)

### Manual Results Analysis
The Optimizer should create additional analysis as needed:

**Custom Analysis** (`results/custom_analysis.md`):
```markdown
# Study Results Analysis

## Best Design Summary
- Optimal parameters: bracket_thickness=16.5mm, fillet_radius=9.2mm, gusset_thickness=12.1mm
- Performance: max_stress=142.8 MPa (23% reduction from baseline)
- Constraints: displacement=1.58mm (OK), mass=4.3kg (OK)

## Key Insights
- Fillet radius most influential parameter (40% of improvement)
- Diminishing returns above 17mm bracket thickness
- Gusset thickness has minimal effect within tested range

## Validation Required
- Mesh convergence check on optimal design
- Fatigue analysis at reduced stress levels
- Manufacturing feasibility of 9.2mm fillet radius
```

---

## Results Integration with Projects

### Knowledge Base Updates
Study results flow back to the project KB immediately after completion.

**KB Update Process**:
1. **Component Knowledge** — Update component behavior insights
2. **FEA Knowledge** — Document modeling insights and lessons
3. **Optimization Knowledge** — Record algorithm performance and sensitivities
4. **Lessons Learned** — Process improvements and unexpected findings

**Example KB Update** (`projects/hydrotech-beam/kb/components/cylinder-mount.md`):
```markdown
## Generation 3: Stress Optimization Study (2026-02-05)
**Context**: hydrotech_02_stress_optimization results  
**Agent**: Optimizer  
**Confidence**: High

### Optimization Results
- Achieved 23% stress reduction (185.3 → 142.8 MPa)
- Optimal design: 16.5mm thickness, 9.2mm fillet, 12.1mm gusset
- All constraints satisfied with margin

### Key Sensitivities
- Fillet radius: Most critical parameter (40% of improvement)
- Bracket thickness: Diminishing returns >17mm  
- Gusset thickness: Minimal effect in tested range (6-15mm)

### Design Insights
- Local geometry (fillet) more important than global (thickness)
- Current constraint limits not binding (could push further)
- Manufacturing implications: 9.2mm fillet requires machining

### Implications
- Focus future optimization on fillet and local geometry
- Consider tighter mass constraints to drive efficiency
- Investigate manufacturing cost of optimal fillet radius
```

### Model Archival  
Best study models are promoted to project optimized models.

**Model Promotion Process**:
```bash
# Copy optimal model to project
cp studies/hydrotech_02_stress_optimization/results/best_trial/cylinder_mount_optimal.prt \
   projects/hydrotech-beam/models/optimized/cylinder_mount_stress_optimized_v1.0.prt

# Update model registry
# (Document in project metadata and KB)
```

---

## Study Quality Standards

### Technical Quality Criteria
1. **Model Validation** — Baseline results verified
2. **Convergence** — Optimization converged appropriately  
3. **Constraint Satisfaction** — All constraints respected
4. **Result Validation** — Best designs verified for engineering reasonableness
5. **Documentation** — Complete introspection and results documentation

### Process Quality Criteria  
1. **Planning** — Clear optimization strategy documented
2. **Execution** — Followed standard execution workflow
3. **Monitoring** — Progress tracked and issues documented
4. **Integration** — Results properly integrated with project KB
5. **Handoff** — Clear communication to Post-Processor

### Documentation Standards
Every study must include:

**Required Documentation**:
- [ ] `README.md` with study purpose and summary
- [ ] `introspection/optimization_plan.md` with strategy
- [ ] `introspection/model_analysis.md` with validation
- [ ] `results/custom_analysis.md` with insights (if applicable)
- [ ] KB updates with generation-tracked knowledge

---

## Common Study Patterns

### 1. Baseline Validation Studies
**Purpose**: Validate model setup and establish baseline performance  
**Trials**: 3-5 (minimal optimization, focus on validation)  
**Documentation**: Extensive model validation, minimal optimization insights

### 2. Exploration Studies  
**Purpose**: Map design space and identify promising regions  
**Trials**: 20-50 (broad parameter ranges)  
**Documentation**: Parameter sensitivities, design space characteristics

### 3. Optimization Studies
**Purpose**: Find optimal designs within known promising regions  
**Trials**: 30-100 (focused parameter ranges)  
**Documentation**: Convergence analysis, optimal design validation

### 4. Validation Studies
**Purpose**: Verify optimal designs and perform additional analysis  
**Trials**: 5-10 (focused around optimal points)  
**Documentation**: Mesh convergence, robustness analysis, manufacturing assessment

---

## Integration with Templates

### Reference Documents
- **`studies/README.md`** — Complete study directory overview
- **`templates/HOW_TO_CREATE_A_STUDY.md`** — Detailed study creation guide
- **`templates/study_template/`** — Template directory structure

### Template Usage
```bash
# Create study from template
cp -r templates/study_template studies/new_study_name

# Customize for specific project
# - Update atomizer_spec.json
# - Copy reference models  
# - Update README.md
# - Create optimization plan
```

---

## Troubleshooting Common Issues

### Model Execution Problems
**Symptoms**: Trials fail with model errors  
**Solutions**:
- Verify NX installation and licensing
- Check model file paths in atomizer_spec.json
- Validate design variable expressions exist in model
- Test model manually in NX with parameter changes

### Optimization Not Converging  
**Symptoms**: No improvement over many trials  
**Solutions**:
- Check parameter ranges (too narrow/too wide?)
- Verify objective scaling (similar magnitudes?)
- Try different sampler (Random for exploration)
- Increase trial count or adjust convergence criteria

### Constraint Violations
**Symptoms**: All or most trials violate constraints  
**Solutions**:
- Relax constraint limits (may be too tight)
- Expand design variable bounds  
- Adjust objective weights (prioritize feasibility)
- Consider multi-stage optimization (feasibility first)

### Results Don't Make Sense
**Symptoms**: Optimal designs seem wrong or unrealistic  
**Solutions**:
- Verify extractor functions return correct values
- Check units consistency across specification
- Validate optimal design manually in NX
- Review optimization log for anomalies

---

Last updated: February 2026