paraxial

Paraxial Module

This module provides various functionalities for the computation of paraxial properties of lens systems.

Note that object-space coordinates are defined relative to the first surface (at index 1), while image-space coordinates are defined relative to the image surface. This is relevant for the focal points (F1 & F2), principal planes (P1 & P2), anti-principal planes (P1anti & P2anti), nodal planes (N1 & N2), and anti-nodal planes (N1anti & N2anti). In the Optiland convention, the 1 denotes object space and the 2 denotes image space. For example, P1 is the object space principle plane and F2 is the back focal point.

Kramer Harrison, 2024

Classes

Paraxial(optic)

A class representing a paraxial optical system.

class Paraxial(optic: Optic)[source]

A class representing a paraxial optical system.

This class provides methods to calculate various properties of the optical system, such as focal lengths, entrance pupil location, exit pupil location, entrance pupil diameter, exit pupil diameter, image-space F-number, magnification, and more.

optic

The optical system being analyzed.

Type:: Optic

surfaces

The surface group of the optical system.

Type:: SurfaceGroup

EPD() → ScalarOrArray[source]

Calculate the entrance pupil diameter (EPD).

Returns:: Entrance pupil diameter.

EPL() → ScalarOrArray[source]

Calculate the entrance pupil location (EPL).

This value is relative to the first physical surface (index 1), matching the convention of other first-order quantities on this class (XPL is relative to the image surface, N1anti / N2anti relative to their respective reference surfaces). The prescription report and the EPL optimization operand both surface this value as-is. Call sites that need a global z (object space, surface positions, ray launch points) should call entrance_pupil_z() instead.

Returns:

Entrance pupil position relative to the first surface: (which lies at z=0 by definition in its local coordinate system).

F1() → ScalarOrArray[source]

Calculate the front focal point (F1) location.

Note that this is defined relative to the first surface (at index 1).

Returns:: Front focal point location.

F2() → ScalarOrArray[source]

Calculate the back focal point (F2) location.

Note that this is defined relative to the image surface location.

Returns:: Back focal point location.

FNO() → ScalarOrArray[source]

Calculate the image-space F-number (FNO).

Returns:: Image-space F-number.
Return type:: float

N1() → ScalarOrArray[source]

Calculate the front nodal plane (N1) location.

Note that this is defined relative to the first surface (at index 1).

Returns:: Front nodal plane location.

N1anti() → ScalarOrArray[source]

Calculate the front anti-nodal plane (N1anti) location.

Note that this is defined relative to the first surface (at index 1).

Returns:: Front anti-nodal plane location.

N2() → ScalarOrArray[source]

Calculate the back nodal plane (N2) location.

Note that this is defined relative to the image surface location.

Returns:: Back nodal plane location.

N2anti() → ScalarOrArray[source]

Calculate the back anti-nodal plane (N2anti) location.

Note that this is defined relative to the image surface location.

Returns:: Back anti-nodal plane location.

P1() → ScalarOrArray[source]

Calculate the front principal plane (P1) location.

Note that this is defined relative to the first surface (at index 1).

Returns:: Front principal plane location.

P1anti() → ScalarOrArray[source]

Calculate the front anti-principal plane (P1anti) location.

Note that this is defined relative to the first surface (at index 1).

Returns:: Front anti-principal plane location.

P2() → ScalarOrArray[source]

Calculate the back principal plane (P2) location.

Note that this is defined relative to the image surface location.

Returns:: Back principal plane location.

P2anti() → ScalarOrArray[source]

Calculate the back anti-principal plane (P2anti) location.

Note that this is defined relative to the image surface location.

Returns:: Back anti-principal plane location.

XPD() → ScalarOrArray[source]

Calculate the exit pupil diameter (XPD).

Returns:: Exit pupil diameter.

XPL() → ScalarOrArray[source]

Calculate the exit pupil location (XPL).

Returns:: Exit pupil location relative to the image surface.

chief_ray() → tuple[BEArray, BEArray][source]

Calculates the chief ray heights and angles at each surface.

The chief ray originates from the edge of the field of view and passes through the center of the aperture stop.

Returns:

y_chief: Heights of the chief ray at each surface.
u_chief: Slopes of the chief ray after each surface.

Return type:

A tuple containing two arrays

entrance_pupil_z() → ScalarOrArray[source]

Entrance pupil location as a global z coordinate.

EPL() returns a value relative to the first physical surface (per the documented convention). Call sites that mix the pupil location with other global coordinates (object z, surface positions, ray launch points) should use this helper so the conversion lives in one place. Issue #613 was caused by call sites silently assuming EPL was global; routing them through this helper makes the convention explicit at the boundary.

f1() → ScalarOrArray[source]

Calculate the front focal length (f1).

Returns:: Front focal length.

f2() → ScalarOrArray[source]

Calculate the back focal length (f2), also known as effective focal length.

Returns:: Back focal length.

invariant() → ScalarOrArray[source]

Calculate the Lagrange invariant.

Returns:: The Lagrange invariant of the system.

magnification() → ScalarOrArray[source]

Calculate the transverse magnification.

Returns:: The system’s transverse magnification.

marginal_ray() → tuple[BEArray, BEArray][source]

Calculates the marginal ray heights and angles at each surface.

The marginal ray originates from the center of the object and passes through the edge of the aperture stop.

Returns:

y_marginal: Heights of the marginal ray at each surface.
u_marginal: Slopes of the marginal ray after each surface.

Return type:

A tuple containing two arrays

property surfaces: SurfaceGroup

the surface group of the optical system.

Type:: SurfaceGroup

trace(Hy: ArrayLike, Py: ArrayLike, wavelength: float)[source]

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

Parameters:

Hy (float) – Normalized field coordinate (typically in y).
Py (float) – Normalized pupil coordinate (typically in y).
wavelength (float) – Wavelength of the light in micrometers.

Returns:

A tuple containing two arrays:

y_ray: Heights of the traced ray at each surface.
u_ray: Slopes of the traced ray after each surface.

Return type:

tuple[be.ndarray, be.ndarray]

trace_generic(y: BEArray | float, u: BEArray | float, z: BEArray | float, wavelength: float, reverse: bool = False, skip: int = 0) → 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, relative to the first surface if tracing forward, or relative to the last surface if tracing in reverse (before internal reversal).
wavelength – The wavelength of the rays in micrometers.
reverse – If True, trace the rays in reverse direction (from image to object space). Defaults to False.
skip – The number of surfaces to skip from the beginning of the trace (or end if reverse). Defaults to 0.

Returns:

A tuple containing the height(s): and slope(s) of the rays at each surface interface after tracing.