geometries.toroidal#

Toroidal Geometry

This module defines a toroidal surface geometry based on the Zemax definition: A base curve in the YZ plane (conic + polynomials) is rotated around an axis parallel to Y, offset by the radius of rotation R along Z.

z_y = yz_sag(y) = (c*y^2)/(1 + sqrt(1-(1+k)*c^2*y^2)) + sum(alpha_i * y^(2i+2)) z(x,y) = R - sqrt((R - z_y)^2 - x^2)

where: - R is the radius of rotation (X-Z curvature radius at vertex) - R_y = 1/c is the Y-Z curvature radius at vertex - k is the conic constant for the YZ curve - alpha_i are polynomial coefficients for the YZ curve (powers y^2, y^4, …)

Last Corrected by Manuel Fragata Mendes, July 2025

Classes

ToroidalGeometry(coordinate_system, ...[, ...])

Represents a simplified toroidal geometry (no Zernike terms as in zemax - - may be added later if necessary).
class ToroidalGeometry(coordinate_system: CoordinateSystem, radius_x: float, radius_y: float, conic: float = 0.0, coeffs_poly_y: list[float] = None, tol: float = 1e-10, max_iter: int = 100)[source]#

Represents a simplified toroidal geometry (no Zernike terms as in zemax - - may be added later if necessary).

Parameters:

  • coordinate_system (CoordinateSystem) – The coordinate system.

  • radius_x (float) – Radius of rotation R (X-Z radius).

  • radius_y (float) – Base Y-Z radius R_y.

  • conic (float, optional) – Conic constant k for the Y-Z curve. Defaults to 0.0.

  • coeffs_poly_y (list[float], optional) – Polynomial coefficients alpha_i for the Y-Z curve, where coeffs_poly_y[i] corresponds to the coefficient for y^(2*(i+1)). Defaults to an empty list.

  • tol (float, optional) – Tolerance for Newton-Raphson iteration. Defaults to 1e-10.

  • max_iter (int, optional) – Maximum iterations for Newton-Raphson. Defaults to 100.

Variables:

  • R_rot (be.ndarray) – Radius of rotation R (X-Z radius).

  • R_yz (be.ndarray) – Base Y-Z radius R_y.

  • k_yz (be.ndarray) – Conic constant k for the Y-Z curve.

  • coeffs_poly_y (be.ndarray) – Polynomial coefficients alpha_i for the Y-Z curve.

  • c_yz (be.ndarray or float) – Curvature of the Y-Z profile (1/R_yz).

  • eps (float) – Small epsilon value for safe division.

distance(rays)#

Calculates the distance from the ray origin to the surface intersection using a robust Newton-Raphson method. This version uses the base conic intersection as a strong initial guess.

Differentiable mode (torch backend with grad enabled):

The primal Newton-Raphson solve runs inside torch.no_grad() so that the iterative loop is never recorded in the autograd graph. A one step implicit correction (in DiffOptics style) is then applied:

t_implicit = t_detached - F(t_detached) / (dF/dt)_detached

Since F is near zero at convergence, the forward value is unchanged, but the gradients are correct to first order via the implicit function theorem.

Note

This implicit correction is intended for correct first-order gradients. Higher order derivatives (double backward and beyond) are not guaranteed to match the exact unrolled Newton system.

Non differentiable mode (numpy backend, or torch without grad):

Returns the converged t directly.

Assumptions required for the implicit derivative to be exact:

  1. the primal solve converged to the intended physical root;

  2. that root stays on the same branch under small parameter changes;

  3. dF/dt is not zero or numerically singular (no tangent/grazing intersection);

  4. |n_z| is above the dtype-aware threshold, so the surface is a numerically valid local height function;

  5. sag() and _surface_normal() describe the same surface;

  6. only first derivatives are supported.

Rays that fail any of (1)-(4) keep their detached primal forward value and are never evaluated through a grad-attached residual, so a failed or singular root never carries a confident-looking but invalid gradient and never contaminates the gradients of valid rays in the same batch. A grouped RuntimeWarning reports the rejections by category.

Parameters:

rays (RealRays) – The rays used for calculating distance.

Returns:

An array of propagation distances ‘t’ from each ray’s current position to its intersection point with the geometry.

Return type:

be.ndarray

flip()[source]#

Flip the geometry.

Changes the sign of the radius of rotation (R_rot) and the base Y-Z radius (R_yz). Updates the Y-Z curvature (c_yz) accordingly.

classmethod from_dict(data: dict) → ToroidalGeometry[source]#

Creates a ToroidalGeometry from a dictionary representation.

Parameters:

data (dict) – Dictionary containing toroidal geometry parameters.

Returns:

An instance of ToroidalGeometry.

Return type:

ToroidalGeometry

globalize(rays)#

Convert rays from the local coordinate system to the global coordinate system.

Parameters:

rays (RealRays) – The rays to convert.

localize(rays)#

Convert rays from the global coordinate system to the local coordinate system.

Parameters:

rays (RealRays) – The rays to convert.

sag(x: float, y: float) → float[source]#

Calculate the sag z(x, y) of the toroidal surface.

Parameters:

  • x (float or be.ndarray) – X-coordinate(s).

  • y (float or be.ndarray) – Y-coordinate(s).

Returns:

Sag value(s) of the toroidal surface.

Return type:

float or be.ndarray

scale(scale_factor: float)[source]#

Scale the geometry parameters.

Parameters:

scale_factor (float) – The factor by which to scale the geometry.

set_radius(value: float) → None[source]#

Set the default radius, which is the Y-Z profile radius.

Parameters:

value – New Y-Z profile radius.

set_radius_x(value: float) → None[source]#

Set the X-Z radius of rotation.

Parameters:

value – New X-Z radius of rotation.

set_radius_y(value: float) → None[source]#

Set the Y-Z profile radius and dependent geometry state.

Parameters:

value – New Y-Z profile radius.

surface_normal(rays)#

Calculates the surface normal of the geometry at the given rays.

Parameters:

rays (RealRays) – The rays, positioned at the surface, for which to calculate the surface normal.

Returns:

The surface normal components (nx, ny, nz).

Return type:

tuple[be.ndarray, be.ndarray, be.ndarray]

to_dict() → dict[source]#

Converts the geometry to a dictionary.

Returns:

A dictionary representation of the toroidal geometry.

Return type:

dict

update_normalization(semi_aperture: float) → None#

Update the normalization attributes of the geometry based on its defined normalization_mode (‘auto’ or ‘manual’). Base geometry generally does not maintain a normalization radius.

Parameters:

semi_aperture (float) – The current semi-aperture of the surface.