Atomizer/studies/M1_Mirror/SAT3_Trajectory/README.md

# SAT3_Trajectory - Zernike Trajectory Method Optimization

**Status:** Active
**Created:** 2026-01-29
**Method:** Zernike Trajectory Analysis
**Optimizer:** TPE (Tree-Parzen Estimator)

---

## Executive Summary

First production implementation of the **Zernike Trajectory Method** for M1 mirror optimization. Instead of optimizing discrete WFE values at fixed angles, this study optimizes integrated RMS metrics across the full 20°-60° operating range with mode-specific aberration tracking.

**Key Innovation:** Physics-based trajectory model tracks how each Zernike mode (coma, astigmatism, trefoil, spherical) evolves with elevation angle.

---

## Study Overview

### Primary Objective
- **total_filtered_rms_nm** - Integrated RMS across full operating range (weight=1.0)

### Logged Objectives (Not Optimized, weight=0)
- **coma_rms_nm** - Coma aberration (Z7, Z8)
- **astigmatism_rms_nm** - Astigmatism (Z5, Z6)
- **trefoil_rms_nm** - Trefoil (Z9, Z10)
- **spherical_rms_nm** - Spherical aberration (Z11)
- **linear_fit_r2** - Physics model validation (should be ~1.0)

### Design Variables (9 enabled)

| Parameter | Min | Max | Baseline | Units | Category |
|-----------|-----|-----|----------|-------|----------|
| lateral_inner_angle | 20.0 | 30.0 | 30.18 | deg | Lateral Support |
| lateral_outer_angle | 11.0 | 17.0 | 15.09 | deg | Lateral Support |
| lateral_outer_pivot | 4.0 | 9.0 | 6.036 | mm | Lateral Support |
| lateral_inner_pivot | 5.0 | 13.0 | 12.072 | mm | Lateral Support |
| lateral_middle_pivot | 12.0 | 25.0 | 14.0 | mm | Lateral Support |
| lateral_closeness | 5.0 | 12.5 | 7.89 | mm | Lateral Support |
| whiffle_min | 30.0 | 72.0 | 56.7 | mm | Whiffle Tree |
| whiffle_outer_to_vertical | 60.0 | 80.0 | 75.67 | deg | Whiffle Tree |
| whiffle_triangle_closeness | 50.0 | 80.0 | 60.00 | mm | Whiffle Tree |

**Disabled (fixed at baseline):**
- blank_backface_angle = 4.00 deg
- inner_circular_rib_dia = 537.86 mm

### Optimizer Configuration
- **Algorithm:** TPE (Tree-Parzen Estimator)
- **Budget:** 100 trials
- **Startup Trials:** 15 (random sampling for initial exploration)
- **Seed:** 42 (for reproducibility)

### Constraints
1. **Mass:** blank_mass <= 120 kg (hard constraint, penalty=1e6)
2. **R² fit:** linear_fit_r2 >= 0.95 (soft constraint, ensures physics model validity)

---

## Trajectory Method Details

### Physics Basis

At elevation angle θ, gravity decomposes into:
```
Axial load:   F_axial ∝ sin(θ)
Lateral load: F_lateral ∝ cos(θ)
```

Each Zernike coefficient follows:
```
c_j(θ) = a_j·(sin θ - sin θ_ref) + b_j·(cos θ - cos θ_ref)
```

The sensitivity matrix `[a_j, b_j]` reveals which modes respond to axial vs lateral loads.

### Elevation Angles Analyzed
- **90°** - Manufacturing reference (excluded from trajectory)
- **20°** - Measurement/polishing reference
- **30°** - New trajectory point
- **40°** - Primary operational angle
- **50°** - New trajectory point
- **60°** - Secondary operational angle

### Extractor Configuration
- **Method:** Zernike Trajectory
- **Reference Angle:** 20° (polishing/measurement)
- **Focal Length:** 22000 mm (OPD correction for lateral displacements)
- **Inner Radius:** 135.75 mm (annular aperture, excludes 271.5mm central hole)
- **N Modes:** 50 (filtered from mode 5 onward)

---

## Expected Performance

### Baseline (from test on M1_Tensor model)
- **Total Filtered RMS:** 4.30 nm
- **Coma RMS:** 9.16 nm
- **Astigmatism RMS:** 6.55 nm
- **Trefoil RMS:** 6.44 nm
- **Spherical RMS:** 10.51 nm
- **R² fit:** 1.0000 (perfect)
- **Dominant mode:** Spherical

### Optimization Targets
- **Total Filtered RMS:** < 4.0 nm
- **Coma RMS:** < 5.0 nm
- **R² fit:** > 0.95 (validates physics model)

---

## Usage

### Start Optimization
```bash
cd studies/M1_Mirror/SAT3_Trajectory
python run_optimization.py --start
```

### Resume Optimization
```bash
python run_optimization.py --start --resume
```

### Custom Trial Count
```bash
python run_optimization.py --start --trials 150
```

### Test Single FEA Run
```bash
python run_optimization.py --test
```

### Analyze Results
```bash
# View convergence
python -m optimization_engine.reporting.visualizer 3_results/study.db

# Generate report
python -m optimization_engine.reporting.markdown_report 3_results/study.db
```

---

## File Structure

```
SAT3_Trajectory/
├── README.md                    (This file)
├── STUDY_REPORT.md              (Results report - updated after optimization)
├── run_optimization.py          (Main optimization script)
├── 1_setup/
│   ├── optimization_config.json (Study configuration)
│   └── model/                   (NX model files - copied from M1_Tensor)
│       ├── ASSY_M1.prt
│       ├── ASSY_M1_assyfem1.afm
│       ├── ASSY_M1_assyfem1_sim1.sim
│       ├── M1_Blank.prt
│       ├── M1_Blank_fem1.fem
│       ├── M1_Blank_fem1_i.prt
│       ├── M1_Vertical_Support_Skeleton.prt
│       ├── M1_Vertical_Support_Skeleton_fem1.fem
│       └── M1_Vertical_Support_Skeleton_fem1_i.prt
├── 2_iterations/
│   ├── iter_0001/               (Trial 1 FEA files)
│   ├── iter_0002/               (Trial 2 FEA files)
│   └── ...
└── 3_results/
    ├── study.db                 (Optuna database)
    ├── optimization.log         (Execution log)
    └── trajectory_analysis/     (Mode-specific analysis plots)
```

---

## Key Differences from Previous Studies

### vs. Discrete WFE Optimization (V11-V15)
- **Old:** Optimize `6*wfe_40_20 + 5*wfe_60_20 + 3*mfg_90`
- **New:** Optimize integrated RMS across continuous operating range
- **Benefit:** Physics-based, mode-specific tracking, better understanding of support behavior

### vs. SAT (Surrogate-Assisted Tuning)
- **SAT:** Builds neural surrogate for fast exploration (100 FEA + 10K surrogate)
- **TPE:** Direct Bayesian optimization (100 FEA, no surrogate)
- **This Study:** TPE for initial trajectory exploration, may switch to SAT later

---

## Dependencies

- **NX 2512** (FEA solver)
- **Python 3.9+** (Atomizer environment)
- **Optuna** (TPE sampler)
- **pyNastran** (OP2 reading)
- **NumPy** (trajectory fitting)

---

## References

- **Physics Documentation:** `docs/physics/ZERNIKE_TRAJECTORY_METHOD.md`
- **Implementation:** `optimization_engine/extractors/extract_zernike_trajectory.py`
- **Example Config:** `docs/examples/trajectory_optimization_config.yaml`
- **Handoff Doc:** `docs/handoff/SETUP_TRAJECTORY_OPTIMIZATION.md`

---

## Notes

1. **R² Monitoring:** If R² drops below 0.95, it indicates nonlinearity (e.g., contact lifting). Designs with poor R² should be investigated.

2. **Mode-Specific Insights:** After optimization, analyze which modes improved most. Coma improvements indicate lateral support changes were effective.

3. **Comparison with V15:** After completion, compare trajectory-based results with V15 NSGA-II Pareto front to validate new method.

4. **Future Work:** If this study succeeds, extend to SAT with trajectory objectives for 10K+ design exploration.

---

*Study created by Atomizer, 2026-01-29*
*First implementation of Zernike Trajectory Method for M1 GigaBIT mirror*