Atomizer/studies/M1_Mirror/README.md

# M1 Mirror - Telescope Primary Mirror Optimization

**Project Type**: Telescope Primary Mirror Support Structure Optimization
**Material**: Zerodur Class 2 Glass Ceramic
**Analysis**: NX Nastran SOL 101 (Linear Static, 4 Subcases)
**Status**: Active Optimization Campaign

---

## 1. Project Overview

The M1 Mirror project optimizes the **support structure** of a telescope primary mirror to minimize wavefront error (WFE) across operational elevation angles while managing mass and manufacturing constraints.

### 1.1 What We're Optimizing

The mirror itself is a fixed optical prescription. We optimize **how it's supported**:

- **Whiffle-tree axial support** (18 contact points) - distributes gravity load evenly
- **Lateral support** (3 contact points) - prevents sideways motion at different elevations
- **Mirror blank geometry** - backface angle, rib structure affecting mass

### 1.2 Why This Matters

At different telescope elevation angles, gravity acts on the mirror differently:
- **90° (zenith)**: Gravity purely axial - whiffle-tree handles load
- **20-60° (operational)**: Mixed axial + lateral gravity component
- **Polishing (horizontal)**: Different deformation than operational use

Poor support design causes:
- Tracking errors (WFE change between elevations)
- Manufacturing difficulty (optician must polish out gravity sag)
- Excessive mass (over-designed structure)

---

## 2. Optical Prescription

> **Source**: Validated optical design specification (2025-12-22)

| Parameter | Value | Tolerance | Units |
|-----------|-------|-----------|-------|
| **Radius of Curvature (R)** | 2890 | ± 3 | mm |
| **Conic Constant (K)** | -0.987 | ± 0.001 | - |
| **Clear Aperture (Ø)** | 1202.00 | - | mm |
| **Central Bore (Ø)** | 271.56 | - | mm |
| **Focal Length** | 1445 | - | mm |
| **f-number (f/D)** | f/1.20 | - | - |
| **Surface Type** | Near-Parabolic | - | - |

**Notes**:
- Surface is concave (front surface)
- Conic constant K = -0.987 indicates near-parabolic (K = -1 is pure parabola)
- Focal length derived: f = R/2 = 1445 mm
- FEA mesh (1300 mm) includes lateral support nodes beyond the 1202 mm optical clear aperture

### 2.1 Usage in OPD Extractor

For rigorous WFE analysis (especially lateral support optimization), use explicit focal length:

```python
from optimization_engine.extractors import ZernikeOPDExtractor

extractor = ZernikeOPDExtractor(
    op2_file,
    focal_length=1445.0,  # mm - from optical prescription R/2
    concave=True
)
```

### 2.2 Mesh vs Optical Aperture

| Geometry | Mesh Value | Optical Value | Reason |
|----------|------------|---------------|--------|
| Diameter | 1300 mm | 1202 mm | Mesh includes lateral support structure |
| Central hole | 135 mm | 271.56 mm | Mesh underestimates bore size |

When analyzing WFE, filter nodes to clear aperture (r < 601 mm) or use the optical aperture radius in post-processing.

---

## 3. Physical System

### 3.1 Mirror Blank

| Property | Value | Notes |
|----------|-------|-------|
| Material | Zerodur Class 2 | E=91 GPa, ρ=2.53 g/cm³, CTE≈0 |
| Mass Target | < 105 kg | Hard constraint |
| Current Best | ~94-95 kg | Achieved in V8/V9 |

### 3.2 Support Structure

| System | Points | Purpose |
|--------|--------|---------|
| Whiffle-tree (axial) | 18 | Distribute gravity load uniformly |
| Lateral supports | 3 | Prevent lateral motion at elevation |
| Vertical support skeleton | - | Structural frame |

### 3.3 Loading

| Subcase | Elevation | Gravity Direction | Purpose |
|---------|-----------|-------------------|---------|
| 1 | 90° | Pure -Z (axial) | Manufacturing/polishing reference |
| 2 | 20° | Mixed | **Reference** for tracking |
| 3 | 40° | Mixed | Operational tracking |
| 4 | 60° | Mixed | Operational tracking |

---

## 4. Optimization Objectives

### 4.1 WFE Metrics (Zernike-based)

| Objective | Formula | Weight | Target | Description |
|-----------|---------|--------|--------|-------------|
| 40-20 Tracking | RMS_filt(Z₄₀ - Z₂₀) | 5.0 | 4 nm | WFE change from 20° to 40° |
| 60-20 Tracking | RMS_filt(Z₆₀ - Z₂₀) | 5.0 | 10 nm | WFE change from 20° to 60° |
| Manufacturing | RMS_J1-J3(Z₉₀ - Z₂₀) | 3.0 | 20 nm | Optician workload |

Where:
- `RMS_filt` = RMS after removing J1-J4 (piston, tip, tilt, defocus)
- `RMS_J1-J3` = RMS after removing only J1-J3 (keeps defocus for optician)

### 4.2 Mass

| Objective | Weight | Target |
|-----------|--------|--------|
| M1_Blank mass | 1.0 | Minimize (< 105 kg hard limit) |

### 4.3 Weighted Sum Formula

```
WS = 5×(40-20 nm) + 5×(60-20 nm) + 3×(MFG nm) + 1×(mass kg)
```

---

## 5. Design Variables

### 5.1 Whiffle Tree Parameters

| Variable | Range | Units | Description |
|----------|-------|-------|-------------|
| `whiffle_min` | 30-72 | mm | Minimum whiffle extent |
| `whiffle_outer_to_vertical` | 70-85 | deg | Outer arm to vertical angle |
| `whiffle_triangle_closeness` | 65-120 | mm | Triangle spacing |
| `blank_backface_angle` | 4.2-4.5 | deg | Mirror blank taper (affects mass) |

### 5.2 Lateral Support Parameters

| Variable | Range | Units | Description |
|----------|-------|-------|-------------|
| `lateral_inner_angle` | 25-32 | deg | Inner lateral angle |
| `lateral_outer_angle` | 9-17 | deg | Outer lateral angle |
| `lateral_outer_pivot` | 9-12 | deg | Outer pivot position |
| `lateral_inner_pivot` | 5-12 | deg | Inner pivot position |
| `lateral_middle_pivot` | 15-27 | deg | Middle pivot position |
| `lateral_closeness` | 7-12 | deg | Lateral support closeness |

### 5.3 Structural Parameters

| Variable | Range | Units | Description |
|----------|-------|-------|-------------|
| `inner_circular_rib_dia` | 480-620 | mm | Inner rib diameter |
| `Pocket_Radius` | Fixed 10.05 | mm | Lightweighting pocket size |

---

## 6. Optimization Campaign History

### 6.1 Campaign Phases

```
Phase 1: Initial Exploration (V11-V15)
─────────────────────────────────────
V11 (GNN + TuRBO)  →  V12 (GNN extended)  →  V13 (TPE validation)
    107 trials          ~5000 surrogate        291 trials
    WS = 129.33         WS = 129.33            WS = 129.33
                              ↓
V14 (TPE intensive)  →  V15 (NSGA-II)
    785 trials             126 trials
    WS = 121.72 ✓          WS = 121.72 (confirmed)

Phase 2: Cost Reduction (V6-V9)
─────────────────────────────────
V6 (TPE)  →  V7 (CMA-ES whiffle)  →  V8 (CMA-ES lateral)  →  V9 (CMA-ES combined)
281.82        268.75 (-4.6%)          266.02 (-5.6%)          In progress
```

### 6.2 Best Results Summary

| Campaign | Best WS | 40-20 nm | 60-20 nm | MFG nm | Mass kg |
|----------|---------|----------|----------|--------|---------|
| V11-V15 (adaptive) | 121.72 | 5.99 | 13.10 | 26.28 | 91.02 |
| V6-V9 (cost reduction) | 266.02* | 6.03 | 12.81 | 25.73 | 94.66 |

*Different weighting scheme - not directly comparable

---

## 7. Sub-Studies Index

| Study | Focus | Algorithm | Trials | Best WS | Status |
|-------|-------|-----------|--------|---------|--------|
| [m1_mirror_adaptive_V11](m1_mirror_adaptive_V11/) | Initial GNN + TuRBO | GNN+TuRBO | 107 | 129.33 | Complete |
| [m1_mirror_adaptive_V12](m1_mirror_adaptive_V12/) | Extended surrogate | GNN+TuRBO | ~5000 | 129.33 | Complete |
| [m1_mirror_adaptive_V13](m1_mirror_adaptive_V13/) | TPE validation | TPE | 291 | 129.33 | Complete |
| [m1_mirror_adaptive_V14](m1_mirror_adaptive_V14/) | Intensive TPE | TPE | 785 | **121.72** | Complete |
| [m1_mirror_adaptive_V15](m1_mirror_adaptive_V15/) | NSGA-II Pareto | NSGA-II | 126 | 121.72 | Complete |
| [m1_mirror_cost_reduction](m1_mirror_cost_reduction/) | Mass reduction baseline | TPE | 150 | - | Complete |
| [m1_mirror_cost_reduction_V7](m1_mirror_cost_reduction_V7/) | Whiffle refinement | CMA-ES | 200 | 268.75 | Complete |
| [m1_mirror_cost_reduction_V8](m1_mirror_cost_reduction_V8/) | Lateral optimization (Z-only) | CMA-ES | 200 | 266.02 | Complete |
| [m1_mirror_cost_reduction_V9](m1_mirror_cost_reduction_V9/) | Combined fine-tuning | CMA-ES | 200 | - | Complete |
| [m1_mirror_cost_reduction_V10](m1_mirror_cost_reduction_V10/) | Lateral + OPD (corrupted) | CMA-ES | - | - | Abandoned |
| [m1_mirror_cost_reduction_V11](m1_mirror_cost_reduction_V11/) | Lateral + OPD + extract_relative | CMA-ES | 200 | 284.19 | Complete |
| [m1_mirror_cost_reduction_V12](m1_mirror_cost_reduction_V12/) | Combined Whiffle + Lateral (10 vars) | CMA-ES | 200 | TBD | **Active** |
| [m1_mirror_surrogate_turbo](m1_mirror_surrogate_turbo/) | GNN surrogate + turbo optimization | GNN+FEA | ~1000 | TBD | Setup Complete |

### Flat Back Studies (Cost Reduction Option C)

| Study | Focus | Algorithm | Trials | Best WS | Status |
|-------|-------|-----------|--------|---------|--------|
| [m1_mirror_cost_reduction_flat_back_V3](m1_mirror_cost_reduction_flat_back_V3/) | Initial exploration | TPE | ~297 | - | Complete |
| [m1_mirror_cost_reduction_flat_back_V4](m1_mirror_cost_reduction_flat_back_V4/) | Continued exploration | TPE | ~19 | - | Complete |
| [m1_mirror_cost_reduction_flat_back_V5](m1_mirror_cost_reduction_flat_back_V5/) | MLP Surrogate + L-BFGS | Surrogate | 45 | 290.18 | Complete (Failed) |
| [m1_mirror_cost_reduction_flat_back_V6](m1_mirror_cost_reduction_flat_back_V6/) | Pure TPE baseline | TPE | 196 | **225.41** | Complete |
| [m1_mirror_cost_reduction_flat_back_V7](m1_mirror_cost_reduction_flat_back_V7/) | Self-Aware Turbo | SAT | 200 | TBD | **Ready** |

**Flat Back Notes**:
- `blank_backface_angle = 0` (flat backface eliminates custom jig during machining)
- Mass constraint: ≤ 120 kg
- Weighted sum: `6*wfe_40_20 + 5*wfe_60_20 + 3*mfg_90`
- V5 failure: MLP surrogate led L-BFGS to "fake optima" (OOD extrapolation)
- V7 fix: EnsembleSurrogate with uncertainty quantification + OOD detection

---

## 8. Technical Notes

### 8.1 Zernike Analysis

- **Standard method**: Uses Z-displacement only at original (x,y) coordinates
- **OPD method**: Accounts for lateral (X,Y) displacement - **critical for lateral support optimization**
- **`extract_relative()` method** (V11+): Correct relative WFE computation:
  1. Compute WFE at each node for both subcases
  2. Compute node-by-node difference: `WFE_rel[i] = WFE_target[i] - WFE_ref[i]`
  3. Fit Zernike to the **difference field**
  4. Compute RMS of filtered difference

> **Important**: `abs(RMS_target - RMS_ref)` is WRONG. Always use `extract_relative()` for relative metrics.

See: [docs/physics/ZERNIKE_OPD_METHOD.md](../../docs/physics/ZERNIKE_OPD_METHOD.md)

### 8.2 WFE Convention

```
WFE = 2 × surface_error    (reflection doubles path length)
```

All WFE values in nanometers (nm).

### 8.3 Coordinate System

- **Z-axis**: Optical axis (positive toward sky)
- **Origin**: Mirror vertex
- **Concave mirror**: Surface curves toward -Z

---

## 9. File Structure

```
studies/M1_Mirror/
├── README.md                          # This file (master documentation)
├── m1_mirror_adaptive_V11/            # Sub-studies...
├── m1_mirror_adaptive_V12/
├── ...
├── m1_mirror_cost_reduction_V9/
│   ├── 1_setup/
│   │   ├── optimization_config.json   # Study configuration
│   │   └── model/                     # NX model files
│   ├── 2_iterations/                  # FEA iteration folders
│   ├── 3_results/                     # Optuna DB, logs, archives
│   ├── run_optimization.py            # Main entry point
│   └── README.md                      # Study-specific docs
```

---

## 10. Quick Reference

### Run Optimization

```bash
cd studies/M1_Mirror/m1_mirror_cost_reduction_V9
conda activate atomizer
python run_optimization.py --start
```

### Check Progress

```bash
python -c "
import optuna
study = optuna.load_study(study_name='m1_mirror_cost_reduction_V9',
                          storage='sqlite:///3_results/study.db')
print(f'Trials: {len(study.trials)}')
print(f'Best: {study.best_value:.2f}')
"
```

### Generate Insights

```bash
python -m optimization_engine.insights generate . --type zernike_wfe
python -m optimization_engine.insights generate . --type zernike_opd_comparison
```

---

## 11. Related Documentation

| Document | Description |
|----------|-------------|
| [M1_MIRROR_CAMPAIGN_SUMMARY.md](m1_mirror_adaptive_V15/M1_MIRROR_CAMPAIGN_SUMMARY.md) | V11-V15 campaign analysis |
| [docs/physics/ZERNIKE_FUNDAMENTALS.md](../../docs/physics/ZERNIKE_FUNDAMENTALS.md) | Zernike analysis basics |
| [docs/physics/ZERNIKE_OPD_METHOD.md](../../docs/physics/ZERNIKE_OPD_METHOD.md) | OPD method for lateral supports |
| [.claude/skills/modules/extractors-catalog.md](../../.claude/skills/modules/extractors-catalog.md) | Extractor quick reference |

---

*M1 Mirror Optimization Project*
*Atomizer Framework*
*Last Updated: 2026-01-20*