geometries.forbes#

This package contains the mathematical basis for Forbes polynomials, adapted for the Optiland backend.

class ForbesQ2dGeometry(coordinate_system: CoordinateSystem, surface_config: ForbesSurfaceConfig, solver_config: ForbesSolverConfig = None)[source]#

Forbes Q2D (freeform) surface geometry.

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:

the primal solve converged to the intended physical root;
that root stays on the same branch under small parameter changes;
dF/dt is not zero or numerically singular (no tangent/grazing intersection);
|n_z| is above the dtype-aware threshold, so the surface is a numerically valid local height function;
sag() and _surface_normal() describe the same surface;
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()#

Flip the geometry.

Changes the sign of the radius of curvature. The conic constant remains unchanged.

classmethod from_dict(data)[source]#

Creates an instance from a dictionary.

Parameters:: data (dict) – A dictionary representation of the geometry.
Returns:: An instance of the class.
Return type:: ForbesQbfsGeometry

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, y)[source]#

Calculate the sag of the Forbes Q2D freeform surface.

Parameters:

x (float or array_like) – x-coordinate
y (float or array_like) – y-coordinate

Returns:

The sag of the Forbes Q2D freeform surface.

Return type:

float or array_like

scale(scale_factor: float)[source]#

Scale the geometry parameters.

Scales the radius, normalization radius, and freeform coefficients. The polynomial coefficients scale linearly with the sag when the normalization radius is also scaled.

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

set_radius(value: float) → None#

Set the radius of curvature.

Parameters:: value (float) – The new radius of curvature.

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()[source]#

Serializes the geometry to a dictionary.

Returns:: A dictionary representation of the geometry.
Return type:: dict

update_normalization(semi_aperture: float) → None[source]#

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.

class ForbesQNormalSlopeGeometry(coordinate_system: CoordinateSystem, surface_config: ForbesSurfaceConfig, solver_config: ForbesSolverConfig = None)[source]#

Represents a Forbes Q surface using slope-orthogonal polynomials.

This surface uses the Forbes Q polynomials that are orthogonal with respect to the normal-departure slope metric. These were historically called Q^bfs (“best-fit sphere”) in Forbes 2007, but the implementation here supports a general conic reference surface following the Forbes 2011 generalization.

The surface sag is defined as: $z(rho) = z_{base}(rho) + phi(rho) left[ u^2(1-u^2) sum_{m=0}^{M} a_m Q_m(u^2) right]$

where:

$z_{base}(rho) = frac{crho^2}{1 + sqrt{1 - (1+k)c^2rho^2}}$ is the base conic.
$c = 1/R$ is the curvature, $k$ is the conic constant.
$u = rho/rho_{max}$ is the normalized radial coordinate.
$Q_m(u^2)$ are the Forbes slope-orthogonal polynomials.
$a_m$ are the polynomial coefficients.
$phi(rho) = sqrt{frac{1 - kc^2rho^2}{1 - (1+k)c^2rho^2}}$ is the conic correction factor that projects the normal departure onto the sag axis.

Note

The internal polynomial basis functions (named *_qbfs in the code) retain the historical “qbfs” identifier for stability. This does not imply a spherical reference; the conic constant $k$ can be nonzero.

Parameters:

coordinate_system (CoordinateSystem) – The local coordinate system of the surface.
surface_config (ForbesSurfaceConfig) – An object containing the core geometric parameters. The terms dictionary should be provided as radial_terms.
solver_config (ForbesSolverConfig, optional) – An object containing parameters for the numerical solver.

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:

the primal solve converged to the intended physical root;
that root stays on the same branch under small parameter changes;
dF/dt is not zero or numerically singular (no tangent/grazing intersection);
|n_z| is above the dtype-aware threshold, so the surface is a numerically valid local height function;
sag() and _surface_normal() describe the same surface;
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()#

Flip the geometry.

Changes the sign of the radius of curvature. The conic constant remains unchanged.

classmethod from_dict(data)[source]#

Creates an instance from a dictionary.

Accepts both “ForbesQNormalSlopeGeometry” and legacy “ForbesQbfsGeometry” type identifiers for backward compatibility.

Parameters:: data (dict) – A dictionary representation of the geometry.
Returns:: An instance of the class.
Return type:: ForbesQNormalSlopeGeometry

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=0, y=0)[source]#

Calculate the sag of the Forbes Q (slope-orthogonal) surface.

Parameters:

x (int, optional) – x-coordinate. Defaults to 0.
y (int, optional) – y-coordinate. Defaults to 0.

Returns:

The sag of the Forbes Q (slope-orthogonal) surface.

scale(scale_factor: float)[source]#

Scale the geometry parameters.

Scales the radius, normalization radius, and radial coefficients. The polynomial coefficients scale linearly with the sag when the normalization radius is also scaled.

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

set_radius(value: float) → None#

Set the radius of curvature.

Parameters:: value (float) – The new radius of curvature.

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()[source]#

Serializes the geometry to a dictionary.

Returns:: A dictionary representation of the geometry.
Return type:: dict

update_normalization(semi_aperture: float) → None[source]#

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.

class ForbesQbfsGeometry(coordinate_system: CoordinateSystem, surface_config: ForbesSurfaceConfig, solver_config: ForbesSolverConfig = None)[source]#

Deprecated alias for ForbesQNormalSlopeGeometry.

Deprecated since version Use: ForbesQNormalSlopeGeometry instead. The name “Qbfs” was historically used in the Forbes literature for the slope-orthogonal Q basis, but it misleadingly suggests a best-fit sphere reference. The implementation supports a general conic reference.

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:

the primal solve converged to the intended physical root;
that root stays on the same branch under small parameter changes;
dF/dt is not zero or numerically singular (no tangent/grazing intersection);
|n_z| is above the dtype-aware threshold, so the surface is a numerically valid local height function;
sag() and _surface_normal() describe the same surface;
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()#

Flip the geometry.

Changes the sign of the radius of curvature. The conic constant remains unchanged.

classmethod from_dict(data)#

Creates an instance from a dictionary.

Accepts both “ForbesQNormalSlopeGeometry” and legacy “ForbesQbfsGeometry” type identifiers for backward compatibility.

Parameters:: data (dict) – A dictionary representation of the geometry.
Returns:: An instance of the class.
Return type:: ForbesQNormalSlopeGeometry

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=0, y=0)#

Calculate the sag of the Forbes Q (slope-orthogonal) surface.

Parameters:

x (int, optional) – x-coordinate. Defaults to 0.
y (int, optional) – y-coordinate. Defaults to 0.

Returns:

The sag of the Forbes Q (slope-orthogonal) surface.

scale(scale_factor: float)#

Scale the geometry parameters.

Scales the radius, normalization radius, and radial coefficients. The polynomial coefficients scale linearly with the sag when the normalization radius is also scaled.

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

set_radius(value: float) → None#

Set the radius of curvature.

Parameters:: value (float) – The new radius of curvature.

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()#

Serializes the geometry to a dictionary.

Returns:: A dictionary representation of the 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.

class ForbesSolverConfig(tol: float = 1e-10, max_iter: int = 100)[source]#

Configuration for the Newton-Raphson numerical solver.

Variables:

tol (float) – Tolerance for the iterative solver.
max_iter (int) – Maximum number of iterations for the solver.

max_iter: int = 100#

tol: float = 1e-10#

class ForbesSurfaceConfig(radius: float, conic: float = 0.0, norm_radius: float | None = None, terms: dict[Any, float] | None = None)[source]#

Configuration for a surface’s core geometric properties.

Variables:

radius (float) – The vertex radius of curvature of the base surface.
conic (float) – The conic constant of the base surface.
norm_radius (float, optional) – The normalization radius for the polynomial terms. If None, the radius scales automatically during paraxial updates. Defaults to None.
terms (dict, optional) – A dictionary of polynomial coefficients.
the (The key format depends on) – specific geometry type (e.g., radial_terms for Qbfs, freeform_coeffs for Q2d).

conic: float = 0.0#

norm_radius: float | None = None#

radius: float#

terms: dict[Any, float] | None = None#

compute_z_zprime_q2d(cm0, ams, bms, u, t, _no_trim: bool = False)[source]#: Computes the polynomial sum components for a Q2D surface.

q2d_nm_coeffs_to_ams_bms(nms: list[tuple[int, int]], coefs: list[float])[source]#: Converts a list of (n, m) indexed coefficients to grouped a_m and b_m lists.