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.

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:

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

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:

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

---

I3: MSF Zernike Analysis

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

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.

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.

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.

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.

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

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:

# 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

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