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

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

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

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

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

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

# Navigate to Atomizer root
cd /path/to/Atomizer

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

3. Monitor Progress:

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

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

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

# 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

# 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