Atomizer/.claude/skills/modules/insights-catalog.md

# Insights Catalog Module

**Last Updated**: December 22, 2025
**Version**: 1.0
**Type**: Optional Module

This module documents all available Study Insights in the Atomizer framework. Load this when the user asks about visualization, physics insights, or wants to understand specific trial results beyond optimizer metrics.

---

## When to Load

- User asks "what insights are available?"
- User wants to visualize FEA results (stress, WFE, modes, etc.)
- User asks to understand a specific trial or design
- User wants to compare methods or generate physics reports
- User mentions "visualization", "3D plot", "surface plot"

---

## Insights vs Analysis

| Aspect | **Analysis** | **Insights** |
|--------|--------------|--------------|
| Focus | Optimization performance | Physics understanding |
| Questions | "Is the optimizer converging?" | "What does this design look like?" |
| Data Source | `study.db` (trials, objectives) | Simulation outputs (OP2, mesh) |
| Output | Convergence plots, Pareto fronts | 3D surfaces, stress contours |

---

## IN.1 Insight Catalog

| ID | Type ID | Name | Applicable To | Data Required | Output |
|----|---------|------|---------------|---------------|--------|
| I1 | `zernike_wfe` | Zernike WFE Analysis | Mirror, optics | OP2 with displacement subcases | 3D WFE surface + coefficient tables |
| I2 | `zernike_opd_comparison` | **Zernike OPD Comparison** | Mirror, optics, lateral | OP2 with displacement subcases | Method comparison + lateral disp. map |
| I3 | `msf_zernike` | MSF Zernike Analysis | Mirror, optics | OP2 with displacement subcases | LSF/MSF/HSF band decomposition |
| I4 | `stress_field` | Stress Distribution | Structural, bracket | OP2 with stress results | 3D stress contours |
| I5 | `modal` | Modal Analysis | Vibration, dynamic | OP2 with eigenvectors | Mode shape animations |
| I6 | `thermal` | Thermal Analysis | Thermo-structural | OP2 with temperature | Temperature distribution |
| I7 | `design_space` | Design Space Explorer | All studies | study.db with 5+ trials | Parameter-objective plots |

---

## IN.2 Insight Code Snippets (COPY-PASTE)

### I1: Zernike WFE Analysis

Standard 50-mode wavefront error visualization for mirror optimization.

```python
from optimization_engine.insights import get_insight, InsightConfig

# Get the insight for a study
insight = get_insight('zernike_wfe', study_path)

# Check if it can generate (data exists)
if insight.can_generate():
    result = insight.generate(InsightConfig())
    print(f"Generated: {result.html_path}")
```

**CLI Usage**:
```bash
python -m optimization_engine.insights generate studies/my_mirror --type zernike_wfe
```

**Output**: Interactive HTML with:
- 3D WFE surface plot
- Zernike coefficient bar chart
- RMS metrics table (global, filtered, J1-J3)
- Aberration magnitudes (astigmatism, coma, trefoil, spherical)

---

### I2: Zernike OPD Method Comparison (NEW - Critical for Lateral Supports)

Compares standard (Z-only) vs rigorous OPD method to reveal lateral displacement impact.

**When to Use**:
- Lateral support optimization
- Any case where supports may pinch the mirror
- Validating if your WFE objective is accurate

```python
from optimization_engine.insights import get_insight

insight = get_insight('zernike_opd_comparison', study_path)
result = insight.generate()
print(f"Generated: {result.html_path}")

# Check recommendation
print(result.summary['overall_recommendation'])
```

**CLI Usage**:
```bash
python -m optimization_engine.insights generate studies/my_mirror --type zernike_opd_comparison
```

**Output**: Interactive HTML with:
- **Lateral displacement magnitude map** (where pinching occurs)
- **WFE surface** using OPD method
- **Comparison table** (Standard vs OPD metrics)
- **Recommendation** (CRITICAL/RECOMMENDED/OPTIONAL/EQUIVALENT)

**Interpretation**:
| Max Lateral Disp. | Recommendation |
|-------------------|----------------|
| > 10 µm | **CRITICAL**: Use OPD method for optimization |
| 1-10 µm | **RECOMMENDED**: Use OPD method |
| < 1 µm | Both methods equivalent |

**Related Documentation**: [ZERNIKE_OPD_METHOD.md](../../../docs/06_PHYSICS/ZERNIKE_OPD_METHOD.md)

---

### I3: MSF Zernike Analysis

100-mode analysis with LSF/MSF/HSF band decomposition for mid-spatial frequency analysis.

```python
from optimization_engine.insights import get_insight

insight = get_insight('msf_zernike', study_path)
result = insight.generate()
```

**Output**: Band breakdown showing:
- LSF (Low Spatial Frequency) - Modes 1-21 (correctable by polishing)
- MSF (Mid Spatial Frequency) - Modes 22-50 (problematic for optical performance)
- HSF (High Spatial Frequency) - Modes 51-100 (typically noise/mesh effects)

---

### I4: Stress Field Visualization

3D stress contour visualization for structural optimization.

```python
from optimization_engine.insights import get_insight

insight = get_insight('stress_field', study_path)
if insight.can_generate():
    result = insight.generate()
```

**Output**: Interactive 3D mesh with:
- Von Mises stress colormap
- Peak stress location indicators
- Statistics table (max, mean, P99)

---

### I5: Modal Analysis

Mode shape visualization for frequency optimization.

```python
from optimization_engine.insights import get_insight

insight = get_insight('modal', study_path)
result = insight.generate()
```

**Output**:
- First N mode shapes (deformed mesh)
- Frequency table
- Modal effective mass (if available)

---

### I6: Thermal Analysis

Temperature distribution visualization.

```python
from optimization_engine.insights import get_insight

insight = get_insight('thermal', study_path)
result = insight.generate()
```

**Output**:
- Temperature contour plot
- Gradient magnitude map
- Heat flux vectors (if available)

---

### I7: Design Space Explorer

Parameter-objective relationship visualization.

```python
from optimization_engine.insights import get_insight

insight = get_insight('design_space', study_path)
result = insight.generate()
```

**Requirements**: At least 5 completed trials in study.db

**Output**:
- Parallel coordinates plot
- Parameter importance
- Objective correlations

---

## IN.3 Generating All Insights for a Study

```python
from optimization_engine.insights import InsightReport

# Create report from all configured insights
report = InsightReport(study_path)

# Generate all enabled insights
results = report.generate_all()

# Create HTML report with all insights
report_path = report.generate_report_html()
print(f"Full report: {report_path}")
```

**CLI**:
```bash
# Generate report from config
python -m optimization_engine.insights report studies/my_study

# List available insights
python -m optimization_engine.insights list

# Get recommendations for a study
python -m optimization_engine.insights recommend studies/my_study
```

---

## IN.4 Configuring Insights in optimization_config.json

```json
{
  "insights": [
    {
      "type": "zernike_wfe",
      "name": "WFE at 40 vs 20 deg",
      "enabled": true,
      "linked_objective": "rel_filtered_rms_40_vs_20",
      "config": {
        "target_subcase": "3",
        "reference_subcase": "2"
      },
      "include_in_report": true
    },
    {
      "type": "zernike_opd_comparison",
      "name": "Lateral Displacement Check",
      "enabled": true,
      "config": {}
    }
  ]
}
```

---

## IN.5 Decision Guide

| You want to... | Use Insight |
|----------------|-------------|
| See wavefront error surface | `zernike_wfe` |
| Check if lateral displacement matters | `zernike_opd_comparison` |
| Analyze mid-spatial frequencies | `msf_zernike` |
| Visualize stress hotspots | `stress_field` |
| See mode shapes | `modal` |
| Check thermal distribution | `thermal` |
| Understand parameter effects | `design_space` |

---

## Related Documentation

- **Protocol Specification**: `docs/protocols/system/SYS_17_STUDY_INSIGHTS.md`
- **OPD Method Physics**: `docs/06_PHYSICS/ZERNIKE_OPD_METHOD.md`
- **Zernike Integration**: `docs/ZERNIKE_INTEGRATION.md`
- **Extractor Catalog**: `.claude/skills/modules/extractors-catalog.md`