optiland.rays.ray_aiming.cached#
Cached Ray Aiming Module
This module implements a caching wrapper for ray aiming algorithms. It stores previous results to speed up repetitive calculations when the inputs and optical system remain unchanged.
Retained for backward compatibility (explicit cache=True) but no longer
the default warm-start mechanism for "robust", which has its own
intrinsic, always-on PupilMapCache (see pupil_map.py and
robust.py).
Kramer Harrison, 2025
Classes
|
Cached ray aiming strategy. |
- class CachedRayAimer(optic: Optic, wrapped_aimer: BaseRayAimer, max_cache_size: int = 128, **kwargs: Any)[source]#
Cached ray aiming strategy.
This class wraps another ray aimer and caches its results. It checks if the inputs and the optical system state have changed. If they match a cached entry in the same numerical execution context, the result is returned immediately. Otherwise, the wrapped aimer computes a fresh result without an automatic initial guess. Explicit caller guesses bypass caching.
Coordinate-frame note: cached entries are full launch states in global coordinates. The system hash covers every surface, so any rigid pose change (translation, fold reorientation) misses the exact-reuse path. After a system change, a cached launch is not used as a starting guess: its fixed field-dependent components may no longer represent the requested field, even if the ray still satisfies the stop constraint.
Torch calls clear and bypass this cache whenever either backend gradient tracking or ambient autograd is enabled, so computation graphs are never reused. Backend, precision, device, and Torch inference-mode changes also clear numerical entries. The wrapped robust aimer’s detached pupil-map seed cache is independent.
- Variables:
optic (Optic) – The optical system being traced.
wrapped_aimer (BaseRayAimer) – The actual aiming strategy being cached.
max_cache_size (int) – Maximum number of entries in the cache.