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]
- 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.
- 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:
- 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
*_qbfsin 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.
- 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:
- 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:
ForbesQNormalSlopeGeometryinstead. 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.
- 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:
- 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.
- tol
Tolerance for the iterative solver.
- Type:
float
- max_iter
Maximum number of iterations for the solver.
- Type:
int
- 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.
- radius
The vertex radius of curvature of the base surface.
- Type:
float
- conic
The conic constant of the base surface.
- Type:
float
- norm_radius
The normalization radius for the polynomial terms. If None, the radius scales automatically during paraxial updates. Defaults to None.
- Type:
float, optional
- terms
A dictionary of polynomial coefficients.
- Type:
dict, optional
- The key format depends on the
specific geometry type (e.g., radial_terms for Qbfs, freeform_coeffs for Q2d).
- conic: float = 0.0
- radius: float