docs: Archive stale docs and create Atomizer-HQ agent documentation
Archive Management: - Moved RALPH_LOOP, CANVAS, and dashboard implementation plans to archive/review/ for CEO review - Moved completed restructuring plan and protocol v1 to archive/historical/ - Moved old session summaries to archive/review/ New HQ Documentation (docs/hq/): - README.md: Overview of Atomizer-HQ multi-agent optimization team - PROJECT_STRUCTURE.md: Standard KB-integrated project layout with Hydrotech reference - KB_CONVENTIONS.md: Knowledge Base accumulation principles with generation tracking - AGENT_WORKFLOWS.md: Project lifecycle phases and agent handoffs (OP_09 integration) - STUDY_CONVENTIONS.md: Technical study execution standards and atomizer_spec.json format Index Update: - Reorganized docs/00_INDEX.md with HQ docs prominent - Updated structure to reflect new agent-focused organization - Maintained core documentation access for engineers No files deleted, only moved to appropriate archive locations.
This commit is contained in:
549
docs/hq/STUDY_CONVENTIONS.md
Normal file
549
docs/hq/STUDY_CONVENTIONS.md
Normal file
@@ -0,0 +1,549 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user