From af195c3a75a6146f0ba8d4ad2e618a13cb8f4a02 Mon Sep 17 00:00:00 2001 From: Antoine Date: Thu, 29 Jan 2026 16:46:55 +0000 Subject: [PATCH] docs: add handoff document for trajectory optimization setup --- docs/handoff/SETUP_TRAJECTORY_OPTIMIZATION.md | 208 ++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 docs/handoff/SETUP_TRAJECTORY_OPTIMIZATION.md diff --git a/docs/handoff/SETUP_TRAJECTORY_OPTIMIZATION.md b/docs/handoff/SETUP_TRAJECTORY_OPTIMIZATION.md new file mode 100644 index 00000000..aaabfe44 --- /dev/null +++ b/docs/handoff/SETUP_TRAJECTORY_OPTIMIZATION.md @@ -0,0 +1,208 @@ +# Handoff: Set Up Trajectory-Based Optimization for M1 Mirror + +**From:** Mario (Clawdbot) +**To:** Claude (Windows/LAC) +**Date:** 2026-01-29 +**Context:** M1 GigaBIT mirror optimization using new Zernike Trajectory Method + +--- + +## Summary + +A new Zernike Trajectory extractor has been implemented and validated. It provides mode-specific optimization metrics (coma, astigmatism, trefoil, etc.) integrated across the full 20°-60° operating range instead of discrete weighted sums. + +**Your task:** Set up an Atomizer optimization study using TPE optimizer with `total_filtered_rms_nm` as the primary objective, logging mode-specific metrics. + +--- + +## What's Already Done + +1. ✅ **Extractor implemented:** `optimization_engine/extractors/extract_zernike_trajectory.py` +2. ✅ **Validated on M1 model:** R² = 1.0 (physics model confirmed) +3. ✅ **Documentation:** `docs/physics/ZERNIKE_TRAJECTORY_METHOD.md` +4. ✅ **Example config:** `docs/examples/trajectory_optimization_config.yaml` + +**Pull latest from Gitea:** +```bash +git pull origin main +``` + +--- + +## What You Need to Set Up + +### 1. Create New Study: `SAT3_Trajectory` + +Location: `studies/SAT3_Trajectory/` (or similar) + +### 2. FEA Configuration + +The FEA must solve **6 subcases** with these elevation angles: +- 90° (manufacturing reference) +- 20° (measurement/polishing reference) +- 30° (new - for trajectory) +- 40° (primary operational) +- 50° (new - for trajectory) +- 60° (secondary operational) + +**Subcase labels in NX must be the angle numbers** (e.g., LABEL = 20, LABEL = 40, etc.) + +### 3. Extractor Configuration + +Use the trajectory extractor: + +```yaml +extractors: + - id: ext_trajectory + name: "Zernike Trajectory" + type: zernike_trajectory + config: + reference_angle: 20.0 + # Subcases auto-detected from OP2 labels +``` + +### 4. Objectives + +**Primary objective (what optimizer minimizes):** +```yaml +objectives: + - id: obj_total + name: "Total Integrated RMS" + source: + extractor_id: ext_trajectory + output_name: total_filtered_rms_nm + direction: minimize + weight: 1.0 +``` + +**Secondary objectives (logged but not optimized, weight=0):** +```yaml + - id: obj_coma + name: "Coma RMS" + source: + extractor_id: ext_trajectory + output_name: coma_rms_nm + direction: minimize + weight: 0.0 + + - id: obj_astig + name: "Astigmatism RMS" + source: + extractor_id: ext_trajectory + output_name: astigmatism_rms_nm + direction: minimize + weight: 0.0 + + - id: obj_trefoil + name: "Trefoil RMS" + source: + extractor_id: ext_trajectory + output_name: trefoil_rms_nm + direction: minimize + weight: 0.0 + + - id: obj_spherical + name: "Spherical RMS" + source: + extractor_id: ext_trajectory + output_name: spherical_rms_nm + direction: minimize + weight: 0.0 +``` + +### 5. Optimizer Configuration + +**Use TPE (recommended for fresh start):** +```yaml +optimizer: + type: tpe + config: + n_trials: 100 + n_startup_trials: 15 +``` + +### 6. Constraints (Optional but Recommended) + +```yaml +constraints: + # Sanity check: linear model should fit well + - id: con_r2 + name: "Trajectory fit quality" + source: + extractor_id: ext_trajectory + output_name: linear_fit_r2 + type: soft + operator: ">=" + threshold: 0.95 +``` + +### 7. Design Variables + +Use Antoine's existing wiffle tree and geometry parameters. Key ones likely include: +- Wiffle tree radial positions (R1, R2, R3) +- Wiffle tree angular offsets +- Rib thickness +- Back pocket geometry +- Support pad locations + +**Ask Antoine for the current parameter names and ranges.** + +--- + +## Validation Checklist + +Before running optimization, verify: + +- [ ] FEA solves all 6 subcases (90, 20, 30, 40, 50, 60) +- [ ] OP2 contains displacement results for all subcases +- [ ] Subcase labels in OP2 are angle numbers (check with extractor) +- [ ] Extractor returns valid results (run standalone test first) +- [ ] R² ≈ 1.0 (confirms physics model holds) + +**Test command:** +```python +from optimization_engine.extractors.extract_zernike_trajectory import extract_zernike_trajectory + +result = extract_zernike_trajectory('path/to/solution.op2') +print(f"R² = {result['linear_fit_r2']}") +print(f"Total RMS = {result['total_filtered_rms_nm']} nm") +print(f"Coma RMS = {result['coma_rms_nm']} nm") +``` + +--- + +## Expected Outputs + +After running the extractor, you should see: +- `total_filtered_rms_nm`: ~4-10 nm (integrated across angles) +- `coma_rms_nm`: ~3-10 nm +- `astigmatism_rms_nm`: ~3-10 nm +- `linear_fit_r2`: ~1.0 + +During optimization, track: +- How `total_filtered_rms_nm` decreases +- Which modes (coma, astig, etc.) improve most +- Whether R² stays high (if it drops, something is wrong) + +--- + +## Key Files to Reference + +| File | Purpose | +|------|---------| +| `docs/physics/ZERNIKE_TRAJECTORY_METHOD.md` | Full method documentation | +| `docs/examples/trajectory_optimization_config.yaml` | Example config | +| `optimization_engine/extractors/extract_zernike_trajectory.py` | Extractor code | +| `2-Projects/P04-GigaBIT-M1/Technical-Analysis/Tensor_Project/TECH-SPEC-Zernike-Trajectory-Optimization.md` | Physics derivation + validation results | + +--- + +## Questions? + +If anything is unclear, the tech spec in PKM has the full physics derivation and validation results. The extractor auto-detects angles from OP2 subcase labels, so as long as the FEA is set up correctly, it should "just work." + +Good luck! 🚀 + +--- + +*Handoff document by Mario (Clawdbot), 2026-01-29*