EvenAspherical

class dnois.optics.rt.EvenAspherical(roc: Real | Tensor = inf, conic: Real | Tensor = 0, coefficients: Sequence[Real | Tensor] = (), 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)

Even aspherical surfaces.

Surface Function

\[h(x,y)=\hat{h}(r^2)=\frac{cr^2}{1+\sqrt{1-(1+k)c^2r^2}}+\sum_{i=1}^N a_i r^{2i}\]

where \(c\) is radius of curvature, \(k\) is conic coefficient and \(\{a_i\}_{i=1}^N\) are even aspherical coefficients.

See CircularSurface for more description of arguments.

Parameters:

  • roc (float or Tensor) – Radius of curvature.

  • conic (float or Tensor) – Conic coefficient.

  • coefficients (Sequence[float | Tensor]) – Even aspherical coefficients.

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, 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.

  • 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, r2: Tensor = None) → 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.

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

aperture: Aperture

Aperture of this surface.

property apt: Aperture

Alias for aperture.

Type:

Aperture

property coefficients: 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]

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

property even_aspherical_items: int

Number of even aspherical coefficients.

Type:

int

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

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]

property px_curvature: Tensor

Paraxial curvature.

Type:

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