raytrace.paraxial_ray_tracer#

Paraxial Ray Tracer Module

This module contains the ParaxialRayTracer class, which is responsible for tracing paraxial rays through an optical system.

Kramer Harrison, 2025

Classes

ParaxialRayTracer(optic)

Class to trace paraxial rays through an optical system
class ParaxialRayTracer(optic: Optic)[source]#

Class to trace paraxial rays through an optical system

prepare_scalar_sequence(wavelength: float, *, path: ParaxialPath | None = None, reverse: bool = False, operation: str = 'scalar paraxial analysis') → _ScalarParaxialSequence[source]#

Build the validated scalar sequence shared by all first-order APIs.

Exactly one of these preparation steps runs per scalar first-order operation (explicit trace or matrix assembly):

  1. a fresh ParaxialPath is built when none is supplied;

  2. folded/off-axis paths are validated against the supported scalar domain (path.require_scalar_paraxial);

  3. straight paths surface their scalar-approximation advisories (path.warn_scalar_approximations);

  4. authored radii and explicit focal lengths of centered/collinear powered surfaces are mapped to paraxial-effective values via the collinear orientation policy (path.effective_orientation_signs), preserving radius infinities exactly – genuinely oblique surfaces are never re-signed by a heuristic;

  5. the reverse transformation is applied exactly once when requested.

Parameters:

  • wavelength – Wavelength in micrometers for the refractive indices.

  • path – Optional prebuilt path snapshot to reuse. Must be fresh for the surfaces being traced.

  • reverse – Whether to produce the reversed (image-to-object) sequence.

  • operation – Operation name used in diagnostics and warnings.

Returns:

The assembled _ScalarParaxialSequence.

Raises:

UnsupportedParaxialGeometryError – If the geometry lies outside the supported scalar folded domain (and no seed scope is active).

trace(Hy: ScalarOrArray, Py: ScalarOrArray, wavelength: ScalarOrArray)[source]#

Trace paraxial ray through the optical system based on specified field and pupil coordinates.

Parameters:

  • Hy – Normalized field coordinate.

  • Py – Normalized pupil coordinate.

  • wavelength – Wavelength of the light.

trace_generic(y: BEArray | float, u: BEArray | float, z: BEArray | float, wavelength: float, reverse: bool = False, skip: int = 0, path: ParaxialPath | None = None) → tuple[BEArray, BEArray][source]#

Trace generically-defined paraxial rays through the optical system.

Parameters:

  • y – The initial height(s) of the rays.

  • u – The initial slope(s) of the rays.

  • z – The initial axial position(s) of the rays.

  • wavelength – The wavelength of the rays.

  • reverse – If True, trace the rays in reverse direction. Defaults to False.

  • skip – The number of surfaces to skip during tracing. Defaults to 0.

  • path – Optional prebuilt ParaxialPath for the current geometry, so a high-level operation making several traces pays the path construction once. Must be a fresh snapshot of the surfaces being traced – never one built before a geometry mutation.

Returns:

A tuple containing the final height(s) and slope(s) of the

rays after tracing.

Return type:

tuple