utils

Optiland Utilities Module

This module provides utility functions for optical system analysis, including the calculation of the working F-number (F/#) of an optical system.

Kramer Harrison, 2025

Functions

`active_fields`(resolved)	Return only FieldPoints with weight > 0.
`active_wavelengths`(resolved)	Return only WavelengthPoints with weight > 0.
`get_attr_by_path`(obj, path)	Retrieve an attribute of an object using a dot-separated path.
`get_working_FNO`(optic, field, wavelength)	Calculates the working F-number of the optical system for the single defined field point and given wavelength.
`globalize_coordinates`(surface, x_local, ...)	Transform local surface coordinates to global coordinates.
`resolve_fields`(optic, fields)	Resolve field input into a list of FieldPoints (coord + weight).
`resolve_wavelength`(optic, wavelength)	Resolves a single wavelength input into a float value.
`resolve_wavelengths`(optic, wavelengths)	Resolve wavelength input into a list of WavelengthPoints (value + weight).
`set_attr_by_path`(obj, path, value)	Set an attribute of an object using a dot-separated path.
`weighted_average`(values, weights)	Compute a weighted normalized average: Σ(w_i × x_i) / Σ(w_i).

Classes

`FieldPoint`(coord, weight)	A resolved field coordinate with its associated weight.
`WavelengthPoint`(value, weight)	A resolved wavelength value with its associated weight.

class FieldPoint(coord: tuple[float, float], weight: float)[source]

A resolved field coordinate with its associated weight.

coord

(x, y) field coordinate in the field coordinate system.

Type:: tuple[float, float]

weight

Non-negative relative importance scalar. Defaults to 1.0 for user-supplied raw coordinates. Refer to optiland weight semantics in SPEC_weights.md §2.1.

Type:: float

coord: tuple[float, float]: Alias for field number 0

count(value, /): Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

weight: float: Alias for field number 1

class WavelengthPoint(value: float, weight: float)[source]

A resolved wavelength value with its associated weight.

value

Wavelength in micrometers.

Type:: float

weight

Non-negative relative importance scalar. Defaults to 1.0 for user-supplied raw values. Refer to optiland weight semantics in SPEC_weights.md §2.1.

Type:: float

count(value, /): Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

value: float: Alias for field number 0

weight: float: Alias for field number 1

active_fields(resolved: list[FieldPoint]) → list[FieldPoint][source]

Return only FieldPoints with weight > 0. Use in weighted contexts.

Parameters:: resolved – A list of FieldPoint named tuples.
Returns:: Filtered list containing only items with positive weight.

active_wavelengths(resolved: list[WavelengthPoint]) → list[WavelengthPoint][source]

Return only WavelengthPoints with weight > 0. Use in weighted contexts.

Parameters:: resolved – A list of WavelengthPoint named tuples.
Returns:: Filtered list containing only items with positive weight.

get_attr_by_path(obj: Any, path: str) → Any[source]

Retrieve an attribute of an object using a dot-separated path. Supports list indexing, e.g., ‘surfaces[1].geometry.radius’.

Parameters:

obj – The object to retrieve the attribute from.
path – The dot-separated path to the attribute.

Returns:

The value of the attribute.

get_working_FNO(optic, field, wavelength)[source]

Calculates the working F-number of the optical system for the single defined field point and given wavelength.

Parameters:

optic (Optic) – The optic object.
field (tuple) – The field at which to calculate the F/#.
wavelength (float) – The wavelength at which to calculate the F/#.

Algorithm:

Retrieve the defined given wavelength and field coordinates.
Determine the image-space refractive index ‘n’ at the given wavelength.
Trace four marginal rays (top, bottom, left, right) at the pupil edges,
as well as the chief ray.

4. Compute the angle between each marginal ray and the chief ray. 4. Calculate the average of the squared numerical apertures from all traced

marginal rays.

Compute the working F-number as 1 / (2 * be.sqrt(average_NA_squared)).
Cap the calculated F/# at 10,000 if it exceeds this value.

Returns:: The working F-number.
Return type:: float

globalize_coordinates(surface, x_local, y_local, z_local)[source]

Transform local surface coordinates to global coordinates.

Parameters:

surface – The surface whose coordinate system is used for the transformation.
x_local (BEArray) – The local x-coordinates.
y_local (BEArray) – The local y-coordinates.
z_local (BEArray) – The local z-coordinates.

Returns:

(x_global, y_global, z_global) as flattened backend arrays.

Return type:

tuple

resolve_fields(optic, fields) → list[FieldPoint][source]

Resolve field input into a list of FieldPoints (coord + weight).

When fields=’all’, field weights come from optic.fields. For any user-supplied raw coordinates (list of tuples, a single tuple, or an integer index), weight defaults to 1.0 because there is no associated Field object to look up the weight from.

Parameters:

optic (Optic) – The optical system.
fields – ‘all’, a list of (x, y) tuples, a single (x, y) tuple, or an integer index into optic.fields.

Returns:

List of FieldPoint named tuples. Each has .coord (x, y) and .weight.

Raises:

ValueError – If fields is an invalid string.
TypeError – If fields is not one of the supported types.

resolve_wavelength(optic, wavelength)[source]

Resolves a single wavelength input into a float value.

Parameters:

optic (Optic) – The optic object.
wavelength (str or float or int) – The wavelength to resolve. Can be ‘primary’ or a numerical value.

Returns:

A single wavelength value.

Return type:

float

resolve_wavelengths(optic, wavelengths) → list[WavelengthPoint][source]

Resolve wavelength input into a list of WavelengthPoints (value + weight).

When wavelengths=’all’, weights come from optic.wavelengths. For ‘primary’, the primary wavelength’s weight is used. For user-supplied raw float values (list of floats), weight defaults to 1.0.

Parameters:

optic (Optic) – The optical system.
wavelengths – ‘all’, ‘primary’, or a list of float wavelength values in µm.

Returns:

List of WavelengthPoint named tuples. Each has .value (float, µm) and .weight.

Raises:

ValueError – If wavelengths is an invalid string.
TypeError – If wavelengths is not a string or list.

set_attr_by_path(obj: Any, path: str, value: Any) → None[source]

Set an attribute of an object using a dot-separated path. Supports list indexing, e.g., ‘surfaces[1].geometry.radius’.

Parameters:

obj – The object to set the attribute on.
path – The dot-separated path to the attribute.
value – The value to set.

weighted_average(values: list[float], weights: list[float]) → float[source]

Compute a weighted normalized average: Σ(w_i × x_i) / Σ(w_i).

Parameters:

values – Scalar values to average.
weights – Non-negative weights (must have same length as values). Zero-weight items contribute nothing; Σ(w_i) must be > 0.

Returns:

Weighted normalized average.

Raises:

ValueError – If all weights are zero.