Zernike¶

class dnois.optics.rt.Zernike(roc: Real | Tensor = inf, conic: Real | Tensor = 0, a: Sequence[Real | Tensor] = (), z: Sequence[Real | Tensor] = (), norm_radius: float = None, material: Material | str = 'vacuum', aperture: Aperture | Real | Tensor = inf, reflective: bool = False, intersection_config: IntersectionConfig = IntersectionConfig(max_iteration=10, threshold=2e-08, threshold_strict=2e-08, update_bound=5.0, epsilon=1e-09, force_before=True, force_non_negative=False, use_analytical=True), *, d: Real | Tensor = None)¶

extra_repr() → str¶

Return the extra representation of the module.

To print customized extra information, you should re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.

flip_() → Self¶

Flip the surface along the optical axis.

Note

This method does not consider material (and distance).

Returns:: Self.
Return type:: Identical to self
Raises:: RuntimeError – If the surface is reflective.

forward(ray: BatchedRay, forward: bool = True) → BatchedRay¶

Returns the refracted rays of a group of incident rays ray.

Parameters:

ray (BatchedRay) – Incident rays.
forward (bool) – Whether the incident rays propagate along positive-z direction.

Returns:

Refracted rays with origin on this surface. A new BatchedRay object.

Return type:

BatchedRay

classmethod from_dict(d: dict)¶

Constructs an instance of cls from a dict.

Parameters:: d (dict) – A dict typically returned by to_dict().
Returns:: An instance of cls.

h(x: Tensor, y: Tensor) → Tensor¶

Computes surface function \(h(x,y)\).

Parameters:

x (Tensor) – x coordinate.
y (Tensor) – y coordinate.

Returns:

Corresponding value of the surface function.

Return type:

Tensor

h_extended(x: Tensor, y: Tensor) → Tensor¶

Computes extended surface function:

\[\begin{split}\tilde{h}(x,y)=\left\{\begin{array}{ll} h(x,y) & \text{if}(x,y)\in\text{dom} h,\\ \text{extended value} & \text{else} \end{array}\right.\end{split}\]

Parameters:

x (Tensor) – x coordinate.
y (Tensor) – y coordinate.

Returns:

Corresponding value of extended surface function.

Return type:

Tensor

h_grad(x: Tensor, y: Tensor, r2: Tensor = None) → tuple[Tensor, Tensor]¶

Computes the partial derivatives of surface function \(\pfrac{h(x,y)}{x}\) and \(\pfrac{h(x,y)}{y}\).

Parameters:

x (Tensor) – x coordinate.
y (Tensor) – y coordinate.

Returns:

Corresponding value of two partial derivatives.

Return type:

tuple[Tensor, Tensor]

h_grad_extended(x: Tensor, y: Tensor) → tuple[Tensor, Tensor]¶

Computes partial derivatives of extended surface function: \(\pfrac{\tilde{h}(x,y)}{x}\) and \(\pfrac{\tilde{h}(x,y)}{y}\). See h_extended().

Parameters:

x (Tensor) – x coordinate.
y (Tensor) – y coordinate.

Returns:

Corresponding value of two partial derivatives.

Return type:

tuple[Tensor, Tensor]

h_r2_extended(r2: Tensor) → Tensor¶: Computes extended version of \(\hat{h}(r^2)\). See h_r2() and h_extended().

intercept(ray: BatchedRay) → BatchedRay¶

Returns a new BatchedRay whose directions are identical to those of ray and origins are the intersections of ray and this surface. The intersections are solved by Newton’s method . The rays for which no intersection with sufficient precision, within the aperture and resulted from a positive marching distance will be marked as invalid.

Parameters:: ray (BatchedRay) – Incident rays.
Returns:: Intercepted rays.
Return type:: BatchedRay

classmethod load_json(file, **kwargs) → Self¶

Constructs an instance of cls through loading JSON from a file, converting it to a dict and then calling from_dict().

Parameters:

file (str or pathlib.Path or file-like object) – The JSON file to load. Either its path (str or pathlib.Path) or a file-like object.
kwargs – Keyword arguments passed to json.load().

Returns:

An instance of cls.

normal(x: Tensor, y: Tensor) → Tensor¶

Returns unit normal vector of the surface pointing to positive-z direction, i.e., from before the surface to behind it.

Parameters:

x (Tensor) – x coordinate.
y (Tensor) – y coordinate.

Returns:

A tensor whose shape depends on x and y, with an additional dimension of size 3 following.

Return type:

Tensor

paraxialize(wl: Real | Tensor) → ParaxialSystem¶

Abstract this surface into a paraxial surface.

Note

Focal lengths of resulted paraxial surface depend on wavelength because refractive index does.

Parameters:: wl (int, float or Tensor.) – Wavelength to be evaluated.
Returns:: Equivalent paraxial surface of self.
Return type:: ParaxialSystem
Raises:: NotImplementedError – If the surface is not paraxializable.

reflect(ray: BatchedRay) → BatchedRay¶

Returns a new BatchedRay whose origins are identical to those of ray and directions are reflected by this surface. See dnois.reflect() for more details.

Parameters:: ray (BatchedRay) – Incident rays.
Returns:: Reflected rays with origin on this surface. A new BatchedRay object.
Return type:: BatchedRay

refract(ray: BatchedRay, forward: bool = True) → BatchedRay¶

Returns a new BatchedRay whose origins are identical to those of ray and directions are refracted by this surface. See dnois.refract() for more details.

Parameters:

ray (BatchedRay) – Incident rays.
forward (bool) – Whether the incident rays propagate along positive-z direction.

Returns:

Refracted rays with origin on this surface. A new BatchedRay object.

Return type:

BatchedRay

register_latent_parameter(name: str, param: Parameter | None, transform: Transform)¶

Similar to register_parameter(), but takes as input the latent value rather than nominal value. In this way, the inverse transformation need not be provided since the initial latent value is known.

If name corresponds to a vanilla parameter (i.e. not transformed parameter) it will be converted to a transformed one.

Parameters:

name (str) – Name of the parameter.
param (Parameter) – Latent torch.nn.Parameter instance to be registered.
transform (Transform) – Transformation object.

register_parameter(name: str, param: Parameter | None, transform: Transform = None) → None¶

Similar to torch.nn.Module.register_parameter(), but allows you to register a transformed parameter as long as transform is given.

If name corresponds to a vanilla parameter (i.e. not transformed parameter) but transform is given, it will be converted to a transformed one.

Parameters:

name (str) – Name of the parameter.
param (Parameter) – Nominal torch.nn.Parameter instance to be registered.
transform (Transform) – Transformation object.

remove_transform(name: str)¶

Remove transformation for parameter name.

Parameters:: name (str) – Name of the parameter.

sample(mode, *args, **kwargs) → Tensor¶

Samples points on this surface. They are first sampled by Aperture.sample(). This method has two overloaded forms with same return value:

sample(self, mode: str, *args, **kwargs) → Ts

Parameters:: mode (str) – Sampling mode. See Aperture.sample().

sample(self, sampler: Sampler) → Ts

Parameters:: sampler (Sampler) – Sampler function. See Aperture.sampler().

Returns:: A tensor with shape (n, 3) where n is number of samples. 3 means 3D spatial coordinates.
Return type:: Tensor

save_json(file, **kwargs)¶

Save self into a JSON file file.

Parameters:

file – The JSON file to save. Either its path (str or pathlib.Path) or a file-like object.
kwargs – Keyword arguments passed to json.dump().

set_transform(name: str, transform: Transform)¶

Set transformation for parameter name.

If name corresponds to a vanilla parameter (i.e. not transformed parameter) it will be converted to a transformed one.

Parameters:

name (str) – Name of the parameter.
transform (Transform) – Transformation object.

to_dict(keep_tensor=True) → dict[str, Any]¶

Converts self into a dict which recursively contains only primitive Python objects.

Return type:: dict

to_json(**kwargs) → str¶

Converts self into a JSON string.

Parameters:: kwargs – Keyword arguments passed to json.dumps().
Return type:: str

property a: list[Tensor]¶

Aspherical coefficients. Note that the element with index i represents coefficient \(a_{i+1}\).

Returns:: A list containing the coefficients.
Return type:: list[torch.nn.Parameter]

aperture: Aperture¶: Aperture of this surface.

property apt: Aperture¶

Alias for aperture.

Type:: Aperture

property aspheric_items: int¶

Number of aspherical coefficients.

Type:: int

conic: nn.Parameter¶: Conic coefficient. One of optimizable parameters.

context: Context | None¶: The context object of the surface in a surface list. This is created by the surface list object containing the surface.

property ctx: Context | None¶

Alias for context.

Type:: Context or None

curvature: nn.Parameter¶: Curvature. One of optimizable parameters.

property device: device¶

Device of this object.

Type:: torch.device

property distance: Tensor¶

Attribute CoaxialContext.distance of associated context.

Type:: Tensor
Raises:: RuntimeError – If the context associated to self is not a coaxial context.

property dtype: dtype¶

Data type of this object.

Type:: torch.dtype

material: mt.Material¶: Material following the surface.

property nominal_values: dict[str, Tensor]¶

A dict whose keys are names of all parameters of this module and values are their values. The values are nominal ones for transformed parameters.

Type:: dict[str, Tensor]

reflective: bool¶: Whether this surface reflects (rather than refracts) rays.

property transformed_parameters: dict[str, tuple[Parameter, Transform]]¶

A dict whose keys are names of all transformed parameters of this module. The value corresponding to each key is a tuple containing:

The latent value, a torch.nn.Parameter instance;
Corresponding transformation object.

Type:: dict[str, tuple[Parameter, Transform]]

property z: list[Tensor]¶

Zernike coefficients. Note that the element with index i represents coefficient \(z_{i+1}\).

Returns:: A list containing the coefficients.
Return type:: list[torch.nn.Parameter]

property zernike_items: int¶

Number of even aspherical coefficients.

Type:: int