optiland.rays.ray_aiming.robust

Robust Ray Aiming Module

This module implements a chief-ray calibrated robust ray aiming algorithm.

For each field, a cheap chief-ray solve plus four cardinal edge probes ((+-1, 0), (0, +-1) on the stop) are fit to a 2x2 affine launch model (see pupil_map.py). That model seeds every requested pupil point, which is then driven to its exact target by the same Newton/Broyden polish used by IterativeRayAimer. Calibration is warm-started from the previous fit (or the nearest already-solved field) rather than a paraxial guess extrapolated across the whole field range, which is what allows this to converge cold at extreme field angles without the recursive homotopy subdivision the previous implementation relied on.

See optiland/jupyter/SPEC_ray_aiming_20260703.md for the full design.

Kramer Harrison, 2026

Classes

RobustRayAimer(optic[, max_iter, tol, ...])

Chief-ray calibrated robust ray aiming algorithm.

class RobustRayAimer(optic: Optic, max_iter: int = 20, tol: float = 1e-08, scale_fields: bool = True, **kwargs: Any)

Chief-ray calibrated robust ray aiming algorithm.

Designed to handle challenging optical systems (wide-angle, fisheye) where a cold paraxial seed for the iterative solver is too far from the real solution to converge directly. Per field, a chief-ray calibration (§4.2 of the spec) produces a cheap affine seed model; every requested ray is then polished to exactness (§4.3) via the reused IterativeRayAimer Newton/Broyden core. Individual ray failures (vignetting, TIR) are reported as NaN rather than aborting the batch.

optic

The optical system instance.

Type:

Optic

max_iter

Maximum number of iterations for the internal solver.

Type:

int

tol

Numerical tolerance for convergence.

Type:

float

scale_fields

Retained for constructor-signature stability; the calibration-based algorithm does not use homotopy field-scaling, so this is a no-op.

Type:

bool

aim_rays(fields: tuple, wavelengths: Any, pupil_coords: tuple, initial_guess: tuple | None = None) → tuple

Calculate ray starting coordinates using chief-ray calibration.

Parameters:

• fields (tuple) – Field coordinates (Hx, Hy).

• wavelengths (Any) – Wavelengths in microns.

• pupil_coords (tuple) – Normalized pupil coordinates (Px, Py).

• initial_guess (tuple | None, optional) – Optional starting guess. If provided, the method first attempts to solve directly using the iterative solver with this guess; only on failure does it fall back to the full calibrated solve below.

Returns:

Solved ray parameters (x, y, z, L, M, N).

Return type:

tuple

Raises:

ValueError – If every ray for a field fails to converge (a misconfiguration, not ordinary partial vignetting).