templates/substudy_README_template.md

# Substudy NN: [Descriptive Name]

**Date**: YYYY-MM-DD
**Status**: [planned | running | completed | failed]
**Trials**: N

## Purpose

[Why was this substudy created? What hypothesis is being tested?]

Example:
- Validate parameter update mechanism
- Explore promising design region identified in previous run
- Test relaxed constraint settings
- Sensitivity analysis for specific parameter

## Configuration Changes

**From Previous Substudy** (or baseline):

[List what changed compared to previous substudy or baseline config]

Examples:
- Increased beam thickness bounds from 40mm to 60mm
- Changed displacement constraint from 10mm to 12.5mm
- Adjusted objective weights: displacement 50% (was 33%), stress 25% (was 33%), mass 25% (was 34%)
- Narrowed hole_count range to 9-13 (was 5-15)
- Increased trial count from 10 to 50

**Design Variables**:
- `var1`: min-max units [if changed, note it]
- `var2`: min-max units

**Objectives**:
- objective1: weight [if changed, note it]
- objective2: weight

**Sampler**: [TPE | Random | Grid | etc.]

## Expected Outcome

[What do you hope to learn or achieve?]

Examples:
- Find feasible designs meeting relaxed constraint
- Identify which parameter has most impact on displacement
- Validate that hole_count updates correctly
- Achieve 10% improvement over best result from substudy 03

## Actual Results

[Fill in after completion]

**Status**: [✅ SUCCESS | ⚠️ PARTIAL | ❌ FAILED]

**Best Trial**: #XX
- Objective: XXX
- Key metrics: [e.g., displacement: X.X mm, mass: XXXX kg]
- Feasible: [Yes/No]

**Key Findings**:
- Finding 1
- Finding 2
- Finding 3

**Statistics**:
- Total trials: XX
- Feasible designs: N / N_total (XX%)
- Best objective: XXX
- Improvement over previous: XX%

## Validation

[If this was a validation run, document what was validated]

Examples:
- ✅ All design variables updated correctly
- ✅ FEA results reflect parameter changes
- ✅ Mesh regenerated properly
- ✅ Expression import via .exp method works

## Lessons Learned

[What did we learn that wasn't expected?]

Examples:
- Optimizer consistently pushes beam thickness to maximum bounds
- hole_count has minimal impact on displacement (< 5% variation)
- Constraint appears infeasible with current design variable ranges
- TPE sampler converges after ~30 trials

## Visualization

[Link to generated plots if available]

- [convergence.pdf](plots/convergence.pdf)
- [design_space_evolution.pdf](plots/design_space_evolution.pdf)
- [parallel_coordinates.pdf](plots/parallel_coordinates.pdf)

## Next Steps

[What should be done next based on these results?]

Examples:
- → Substudy 05: Run refined search with narrowed parameter bounds
- → Increase beam thickness limit to 80mm to meet constraint
- → Perform sensitivity analysis to identify most important parameters
- → Study complete - recommend design #43 for detailed validation

---

**Files**:
- Configuration: `config.json`
- Results: `history.json`, `best_trial.json`
- Detailed Analysis: `OPTIMIZATION_RESULTS.md` (if significant findings)
feat: Implement Study Organization System (Organization v2.0) Reorganized simple_beam_optimization study and created templates for future studies following best practices for clarity, chronology, and self-documentation. ## Study Reorganization (simple_beam_optimization) New Directory Structure: ``` studies/simple_beam_optimization/ ├── 1_setup/ # Pre-optimization setup │ ├── model/ # Reference CAD/FEM model │ └── benchmarking/ # Baseline validation results ├── 2_substudies/ # Optimization runs (numbered chronologically) │ ├── 01_initial_exploration/ │ ├── 02_validation_3d_3trials/ │ ├── 03_validation_4d_3trials/ │ └── 04_full_optimization_50trials/ └── 3_reports/ # Study-level analysis └── COMPREHENSIVE_BENCHMARK_RESULTS.md ``` Key Changes: 1. Numbered Substudies: 01_, 02_, 03_, 04_ indicate chronological order 2. Reorganized Setup: model/ and benchmarking/ moved to 1_setup/ 3. Centralized Reports: Study-level docs moved to 3_reports/ 4. Substudy Documentation: Each substudy has README.md explaining purpose/results ## Updated Metadata study_metadata.json (v2.0): - Tracks all 4 substudies with creation date, status, purpose - Includes result summaries (best objective, feasible count) - Documents new organization version Substudies Documented: - 01_initial_exploration - Initial design space exploration - 02_validation_3d_3trials - Validate 3D parameter updates - 03_validation_4d_3trials - Validate 4D updates including hole_count - 04_full_optimization_50trials - Full 50-trial optimization ## Templates for Future Studies templates/study_template/ - Complete study structure: - README.md template with study overview format - study_metadata.json template with v2.0 schema - Pre-created 1_setup/, 2_substudies/, 3_reports/ directories templates/substudy_README_template.md - Standardized substudy documentation: - Purpose and hypothesis - Configuration changes from previous run - Expected vs actual results - Validation checklist - Lessons learned - Next steps templates/HOW_TO_CREATE_A_STUDY.md - Complete guide: - Quick start (9 steps from template to first run) - Substudy workflow - Directory structure reference - Naming conventions - Best practices - Troubleshooting guide - Examples ## Benefits Clarity: - Numbered substudies show chronological progression (01 → 02 → 03 → 04) - Clear separation: setup vs. optimization runs vs. analysis - Self-documenting via substudy READMEs Discoverability: - study_metadata.json provides complete substudy registry - Each substudy README explains what was tested and why - Easy to find results for specific runs Scalability: - Works for small studies (3 substudies) or large studies (50+) - Chronological numbering scales to 99 substudies - Template system makes new studies quick to set up Reproducibility: - Each substudy documents configuration changes - Purpose and results clearly stated - Lessons learned captured for future reference ## Implementation Details reorganize_study.py - Migration script: - Handles locked files gracefully - Moves files to new structure - Provides clear progress reporting - Safe to run multiple times Organization Version: 2.0 - Tracked in study_metadata.json - Future studies will use this structure by default - Existing studies can migrate or keep current structure ## Files Added - templates/study_template/ - Complete study template - templates/substudy_README_template.md - Substudy documentation template - templates/HOW_TO_CREATE_A_STUDY.md - Comprehensive creation guide - reorganize_study.py - Migration script for existing studies ## Files Reorganized (simple_beam_optimization) Moved to 1_setup/: - model/ → 1_setup/model/ (CAD/FEM reference files) - substudies/benchmarking/ → 1_setup/benchmarking/ - baseline_validation.json → 1_setup/ Renamed and Moved to 2_substudies/: - substudies/initial_exploration/ → 2_substudies/01_initial_exploration/ - substudies/validation_3trials/ → 2_substudies/02_validation_3d_3trials/ - substudies/validation_4d_3trials/ → 2_substudies/03_validation_4d_3trials/ - substudies/full_optimization_50trials/ → 2_substudies/04_full_optimization_50trials/ Moved to 3_reports/: - COMPREHENSIVE_BENCHMARK_RESULTS.md → 3_reports/ Substudy-Specific Docs (moved to substudy directories): - OPTIMIZATION_RESULTS_50TRIALS.md → 2_substudies/04_full_optimization_50trials/OPTIMIZATION_RESULTS.md ## Documentation Created Each substudy now has README.md documenting: - 01_initial_exploration: Initial exploration purpose - 02_validation_3d_3trials: 3D parameter update validation - 03_validation_4d_3trials: hole_count validation success - 04_full_optimization_50trials: Full results, no feasible designs found ## Next Steps For Future Studies: 1. Copy templates/study_template/ 2. Follow templates/HOW_TO_CREATE_A_STUDY.md 3. Use numbered substudies (01_, 02_, ...) 4. Document each substudy with README.md For Existing Studies: - Can migrate using reorganize_study.py - Or apply organization v2.0 to new substudies only - See docs/STUDY_ORGANIZATION.md for migration guide 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> 2025-11-17 19:20:45 -05:00			`# Substudy NN: [Descriptive Name]`

			`Date: YYYY-MM-DD`
			`Status: [planned \| running \| completed \| failed]`
			`Trials: N`

			`## Purpose`

			`[Why was this substudy created? What hypothesis is being tested?]`

			`Example:`
			`- Validate parameter update mechanism`
			`- Explore promising design region identified in previous run`
			`- Test relaxed constraint settings`
			`- Sensitivity analysis for specific parameter`

			`## Configuration Changes`

			`From Previous Substudy (or baseline):`

			`[List what changed compared to previous substudy or baseline config]`

			`Examples:`
			`- Increased beam thickness bounds from 40mm to 60mm`
			`- Changed displacement constraint from 10mm to 12.5mm`
			`- Adjusted objective weights: displacement 50% (was 33%), stress 25% (was 33%), mass 25% (was 34%)`
			`- Narrowed hole_count range to 9-13 (was 5-15)`
			`- Increased trial count from 10 to 50`

			`Design Variables:`
			- `var1`: min-max units [if changed, note it]
			- `var2`: min-max units

			`Objectives:`
			`- objective1: weight [if changed, note it]`
			`- objective2: weight`

			`Sampler: [TPE \| Random \| Grid \| etc.]`

			`## Expected Outcome`

			`[What do you hope to learn or achieve?]`

			`Examples:`
			`- Find feasible designs meeting relaxed constraint`
			`- Identify which parameter has most impact on displacement`
			`- Validate that hole_count updates correctly`
			`- Achieve 10% improvement over best result from substudy 03`

			`## Actual Results`

			`[Fill in after completion]`

			`Status: [✅ SUCCESS \| ⚠️ PARTIAL \| ❌ FAILED]`

			`Best Trial: #XX`
			`- Objective: XXX`
			`- Key metrics: [e.g., displacement: X.X mm, mass: XXXX kg]`
			`- Feasible: [Yes/No]`

			`Key Findings:`
			`- Finding 1`
			`- Finding 2`
			`- Finding 3`

			`Statistics:`
			`- Total trials: XX`
			`- Feasible designs: N / N_total (XX%)`
			`- Best objective: XXX`
			`- Improvement over previous: XX%`

			`## Validation`

			`[If this was a validation run, document what was validated]`

			`Examples:`
			`- ✅ All design variables updated correctly`
			`- ✅ FEA results reflect parameter changes`
			`- ✅ Mesh regenerated properly`
			`- ✅ Expression import via .exp method works`

			`## Lessons Learned`

			`[What did we learn that wasn't expected?]`

			`Examples:`
			`- Optimizer consistently pushes beam thickness to maximum bounds`
			`- hole_count has minimal impact on displacement (< 5% variation)`
			`- Constraint appears infeasible with current design variable ranges`
			`- TPE sampler converges after ~30 trials`

			`## Visualization`

			`[Link to generated plots if available]`

			`- [convergence.pdf](plots/convergence.pdf)`
			`- [design_space_evolution.pdf](plots/design_space_evolution.pdf)`
			`- [parallel_coordinates.pdf](plots/parallel_coordinates.pdf)`

			`## Next Steps`

			`[What should be done next based on these results?]`

			`Examples:`
			`- → Substudy 05: Run refined search with narrowed parameter bounds`
			`- → Increase beam thickness limit to 80mm to meet constraint`
			`- → Perform sensitivity analysis to identify most important parameters`
			`- → Study complete - recommend design #43 for detailed validation`

			`---`

			`Files:`
			- Configuration: `config.json`
			- Results: `history.json`, `best_trial.json`
			- Detailed Analysis: `OPTIMIZATION_RESULTS.md` (if significant findings)