feat: Add Study Insights module (SYS_16) for physics visualizations

Introduces a new plugin architecture for study-specific physics visualizations, separating "optimizer perspective" (Analysis) from "engineer perspective" (Insights). New module: optimization_engine/insights/ - base.py: StudyInsight base class, InsightConfig, InsightResult, registry - zernike_wfe.py: Mirror WFE with 3D surface and Zernike decomposition - stress_field.py: Von Mises stress contours with safety factors - modal_analysis.py: Natural frequencies and mode shapes - thermal_field.py: Temperature distribution visualization - design_space.py: Parameter-objective landscape exploration Features: - 5 insight types: zernike_wfe, stress_field, modal, thermal, design_space - CLI: python -m optimization_engine.insights generate <study> - Standalone HTML generation with Plotly - Enhanced Zernike viz: Turbo colorscale, smooth shading, 0.5x AMP - Dashboard API fix: Added include_coefficients param to extract_relative() Documentation: - docs/protocols/system/SYS_16_STUDY_INSIGHTS.md - Updated ATOMIZER_CONTEXT.md (v1.7) - Updated 01_CHEATSHEET.md with insights section Tools: - tools/zernike_html_generator.py: Standalone WFE HTML generator - tools/analyze_wfe.bat: Double-click to analyze OP2 files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-20 13:46:28 -05:00
parent 01a7d7d121
commit 1612991d0d
15 changed files with 4450 additions and 173 deletions
--- a/.claude/ATOMIZER_CONTEXT.md
+++ b/.claude/ATOMIZER_CONTEXT.md
@@ -51,6 +51,7 @@ Use keyword matching to load appropriate context:
 | Analyze results | "results", "best", "Pareto", "analyze" | OP_04 | Generate analysis |
 | Neural acceleration | "neural", "surrogate", "turbo", "NN" | SYS_14 + SYS_15 | Method selection |
 | NX/CAD help | "NX", "model", "mesh", "expression" | MCP + nx-docs | Use Siemens MCP |
+| Physics insights | "zernike", "stress view", "insight" | SYS_16 | Generate insights |
 | Troubleshoot | "error", "failed", "fix", "debug" | OP_06 | Diagnose issues |

 ---
@@ -86,22 +87,46 @@ cd atomizer-dashboard && npm run dev     # Start at http://localhost:3003

 ### Study Structure (100% standardized)

+**Studies are organized by geometry type**:
 ```
-study_name/
+studies/
+├── M1_Mirror/                    # Mirror optimization studies
+│   ├── m1_mirror_adaptive_V14/
+│   ├── m1_mirror_cost_reduction_V3/
+│   └── m1_mirror_cost_reduction_V4/
+├── Simple_Bracket/               # Bracket studies
+├── UAV_Arm/                      # UAV arm studies
+├── Drone_Gimbal/                 # Gimbal studies
+├── Simple_Beam/                  # Beam studies
+└── _Other/                       # Test/experimental studies
+```
+
+**Individual study structure**:
+```
+studies/{geometry_type}/{study_name}/
 ├── optimization_config.json    # Problem definition
 ├── run_optimization.py         # FEA optimization script
 ├── run_nn_optimization.py      # Neural acceleration (optional)
+├── README.md                   # MANDATORY documentation
+├── STUDY_REPORT.md             # Results template
 ├── 1_setup/
 │   └── model/
 │       ├── Model.prt           # NX part file
 │       ├── Model_sim1.sim      # NX simulation
 │       └── Model_fem1.fem      # FEM definition
-└── 2_results/
-    ├── study.db                # Optuna database
-    ├── optimization.log        # Logs
-    └── turbo_report.json       # NN results (if run)
+├── 2_iterations/               # FEA trial folders (iter1, iter2, ...)
+├── 3_results/
+│   ├── study.db                # Optuna database
+│   ├── optimization.log        # Logs
+│   └── turbo_report.json       # NN results (if run)
+└── 3_insights/                 # Study Insights (SYS_16)
+    ├── zernike_*.html          # Zernike WFE visualizations
+    ├── stress_*.html           # Stress field visualizations
+    └── design_space_*.html     # Parameter exploration
 ```

+**IMPORTANT**: When creating a new study, always place it under the appropriate geometry type folder!
+
 ### Available Extractors (SYS_12)

 | ID | Physics | Function | Notes |
@@ -141,6 +166,7 @@ study_name/
 │ SYS_10: IMSO (single-obj)    SYS_11: Multi-objective           │
 │ SYS_12: Extractors           SYS_13: Dashboard                  │
 │ SYS_14: Neural Accel         SYS_15: Method Selector            │
+│ SYS_16: Study Insights                                          │
 └─────────────────────────────────────────────────────────────────┘
                              ▼
 ┌─────────────────────────────────────────────────────────────────┐
@@ -411,7 +437,7 @@ python -m optimization_engine.auto_doc templates

 | Component | Version | Last Updated |
 |-----------|---------|--------------|
-| ATOMIZER_CONTEXT | 1.6 | 2025-12-12 |
+| ATOMIZER_CONTEXT | 1.7 | 2025-12-20 |
 | BaseOptimizationRunner | 1.0 | 2025-12-07 |
 | GenericSurrogate | 1.0 | 2025-12-07 |
 | Study State Detector | 1.0 | 2025-12-07 |
@@ -423,6 +449,7 @@ python -m optimization_engine.auto_doc templates
 | Auto-Doc Generator | 1.0 | 2025-12-07 |
 | Subagent Commands | 1.0 | 2025-12-07 |
 | FEARunner Pattern | 1.0 | 2025-12-12 |
+| Study Insights | 1.0 | 2025-12-20 |

 ---

--- a/.claude/skills/01_CHEATSHEET.md
+++ b/.claude/skills/01_CHEATSHEET.md
@@ -22,7 +22,7 @@ requires_skills:

 | I want to... | Use Protocol | Key Command/Action |
 |--------------|--------------|-------------------|
-| Create a new optimization study | OP_01 | Generate `optimization_config.json` + `run_optimization.py` |
+| Create a new optimization study | OP_01 | Place in `studies/{geometry_type}/`, generate config + runner + **README.md** |
 | Run an optimization | OP_02 | `conda activate atomizer && python run_optimization.py` |
 | Check optimization progress | OP_03 | Query `study.db` or check dashboard at `localhost:3000` |
 | See best results | OP_04 | `optuna-dashboard sqlite:///study.db` or dashboard |
@@ -30,6 +30,7 @@ requires_skills:
 | Fix an error | OP_06 | Read error log → follow diagnostic tree |
 | Add custom physics extractor | EXT_01 | Create in `optimization_engine/extractors/` |
 | Add lifecycle hook | EXT_02 | Create in `optimization_engine/plugins/` |
+| Generate physics insight | SYS_16 | `python -m optimization_engine.insights generate <study>` |

 ---

@@ -291,6 +292,53 @@ Without it, `UpdateFemodel()` runs but the mesh doesn't change!
 | 13 | Dashboard | Real-time tracking and visualization |
 | 14 | Neural | Surrogate model acceleration |
 | 15 | Method Selector | Recommends optimization strategy |
+| 16 | Study Insights | Physics visualizations (Zernike, stress, modal) |
+
+---
+
+## Study Insights Quick Reference (SYS_16)
+
+Generate physics-focused visualizations from FEA results.
+
+### Available Insight Types
+| Type | Purpose | Data Required |
+|------|---------|---------------|
+| `zernike_wfe` | Mirror wavefront error | OP2 with displacements |
+| `stress_field` | Von Mises stress contours | OP2 with stresses |
+| `modal` | Mode shapes + frequencies | OP2 with eigenvectors |
+| `thermal` | Temperature distribution | OP2 with temperatures |
+| `design_space` | Parameter-objective landscape | study.db with 5+ trials |
+
+### Commands
+```bash
+# List available insights for a study
+python -m optimization_engine.insights list
+
+# Generate all insights
+python -m optimization_engine.insights generate studies/my_study
+
+# Generate specific insight
+python -m optimization_engine.insights generate studies/my_study --type zernike_wfe
+```
+
+### Python API
+```python
+from optimization_engine.insights import get_insight, list_available_insights
+from pathlib import Path
+
+study_path = Path("studies/my_study")
+
+# Check what's available
+available = list_available_insights(study_path)
+
+# Generate Zernike WFE insight
+insight = get_insight('zernike_wfe', study_path)
+result = insight.generate()
+print(result.html_path)  # Path to generated HTML
+print(result.summary)    # Key metrics dict
+```
+
+**Output**: HTMLs saved to `{study}/3_insights/`

 ---