PolynomialPhase¶

A planar surface imparting a phase shift to incident rays, parameterized as follows:

\[\phi(r)=\sum_{i=1}^n a_i r^{2i}+\sum_{i=1}^m b_i p_i(x,y)\]

where \(r=\sqrt{x^2+y^2}\). \(p_i\) is the \(i\)-th polynomial of \((x,y)\), i.e. \(x\), \(y\), \(x^2\), \(xy\), \(y^2\), \(x^3\) and so on.

See CircularSurface for descriptions of more parameters.

Parameters:

a (Sequence[float | Tensor]) – Radial coefficients \(a_1,\ldots,a_n\).
b (Sequence[float | Tensor]) – Rectangular coefficients \(b_1,\ldots,b_m\).

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_derivative_r2(r2: Tensor) → Tensor¶

Computes derivative \(\frac{\d\hat{h}(r^2)}{\d r^2}\).

Parameters:: r2 (Tensor) – Squared radial distance.
Returns:: Corresponding value of the derivative.
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) → 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.
r2 (Tensor) – Squared radial distance. It can be passed in to avoid repeated computation if already computed outside this method.

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.
r2 (Tensor) – Squared radial distance. It can be passed in to avoid repeated computation if already computed outside this method.

Returns:

Corresponding value of two partial derivatives.

Return type:

tuple[Tensor, Tensor]

h_r2(r2: Tensor) → Tensor¶

Computes surface function \(\hat{h}(r^2)\).

Parameters:: r2 (Tensor) – Squared radial distance.
Returns:: Corresponding value of the surface function.
Return type:: 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.

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

Computes gradient of imparted phase shift \((\pfrac{\phi}{x},\pfrac{\phi}{y})\).

Parameters:

x (Tensor) – x coordinate. A tensor of shape (…).
y (Tensor) – y coordinate. A tensor of shape (…).

Returns:

Gradient. A tensor of shape (…, 2).

Return type:

tuple[Tensor, Tensor]

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¶

Refracts rays with direction \(\mathbf{d}=(d_x,d_y,d_z)\) according to generalized Snell’s law [1]:

\[\begin{split}\left\{\begin{array}{l} n_2d_x'=n_1d_x+\frac{\lambda}{2\pi}\pfrac{\phi}{x}(x_0,y_0)\\ n_2d_y'=n_1d_y+\frac{\lambda}{2\pi}\pfrac{\phi}{y}(x_0,y_0)\\ d_z'=\sqrt{1-d_x'^2-d_y'^2} \end{array}\right.\end{split}\]

where \(\mathbf{d'}=(d_x',d_y',d_z')\) is direction of refractive ray, \(n_1\) and \(n_2\) are refractive indices before and behind this surface, \(\lambda\) is the wavelength in vacuum, \(\phi\) is imparted phase and \((x_0,y_0)\) is the ray-surface intersection. Both direction vectors have length 1. Note that this formula holds in both forward and backward directions, except that refractive indices are exchanged.

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[Parameter]¶

Radial coefficients \(a_1,\ldots,a_n\). 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 b: list[Parameter]¶

Rectangular coefficients \(b_1,\ldots,b_m\). Note that the element with index i represents coefficient \(b_{i+1}\).

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

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

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

property geo_radius: Tensor¶

Geometric radius of the surface, i.e. maximum radial distance that makes the surface function mathematically meaningful. A 0D tensor.

Type:: Tensor

m: int¶: Number of rectangular coefficients \(m\).

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

n: int¶: Number of radial coefficients \(n\).

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]

norm_radius: float¶: Normalization radius.

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]]