| name | optics-align |
| description | Align an optical bench in the Blender Optics Simulator — steer the beam onto its target, recover a dark port, or null an interferometric tilt using the influence-matrix solvers. Use when asked to "align the bench", "get the beam on the detector", "walk the beam", "null the tilt / fringes", "maximize coupling", or "/optics-align".
|
optics-align: close the loop onto the target
Alignment solvers MUTATE the trace (the bench moves) — unlike inspect/build's read-only steps. That is
expected; always report what moved and by how much.
Workflow
- See the miss first —
inspect_beam(target) (is there power on target? where is it landing?) and
diagnose() (beam_clipped / dark_detector / mount_limit). Quantify the error before solving.
- Pick the solver:
- Gross steering onto a target —
auto_align(...) (the generic influence-matrix aligner: it
calibrates a Jacobian over the available knobs and drives the beam onto the target element) or
align_element(name, target) for a single steering mirror.
- Interferometric tilt / fringe null —
tilt_null(...) (drives the inter-arm tilt to zero so the
fringes go null/flat).
- Mode-matching into a cavity/fiber —
mode_match (q-solver) + check coupling_efficiency.
- Re-verify — re-trace and confirm with
inspect_beam(target) (power recovered, beam centred) and
diagnose() (the gate that fired is now clear). For a coupling task, read coupling_efficiency.
- Report — what moved (element, DOF, amount), the before/after metric (power, tilt, η), and any
mount_limit you hit (a DOF ran out of travel → coarse-reposition first, then re-solve).
Disciplines
- A solver makes the trace no longer byte-identical — that's the point of aligning; say so.
- If
diagnose() shows mount_limit, the DOF is range-exhausted: coarse-reposition the mount
(place_relative) to recentre its travel, THEN re-run the fine solver.
- A "dark" port may be a healthy destructive-interference null, not a miss — check
inspect_beam
(per-arm power high, they cancel by phase) before "fixing" it. When in doubt, /optics-correct.