ThinLens¶

A model for thin lens. Focal length in object space and image space can be specified separately. Note that “object space” here means the \(z<0\) half-space in surface-local coordinate.

See Planar for more description of arguments.

Parameters:

fl1 (float or Tensor) – Object focal length of this surface. A float or 0d tensor.
fl2 (float or Tensor) – Image focal length of the next surface. A float or 0d tensor. Default to fl1.
fl_equal (bool) – If True, fl2 is ignored and fl1 is used as both object and image focal length. They will also share same torch.nn.Parameter. Default: True.
eps (float) – A small positive number to avoid division by zero. Specifically, rays that cosine of the angles between optical axis of this thin lens and their directions are smaller than eps is considered as invalid. Default: 1e-3.

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.

fl_equal(equal: bool = None) → bool | Self¶

Set or get the flag indicating whether fl2 is identical to fl1.

Parameters:: equal (bool) – Same as parameter fl_equal in ThinLens. If None, the current value is returned.
Returns:: The current value of fl_equal if equal is None. Otherwise, return self.
Return type:: bool | ThinLens

flip_() → Self¶

Flip the surface w.r.t. the optical axis.

Note

This method does not change material (and distance in coaxial systems).

Returns:: Self.
Return type:: Identical to self

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

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

Parameters:

ray (BatchedRay) – Incident rays.
forward (bool) – Whether the incident rays originate from object space and propagate towards image space. Default: True.
aperture (bool) – Whether to block out rays that are outside the aperture. Default: True.
intercept_only (bool) – Whether to only intercept rays, without refraction or reflection. Default: False.

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

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

Parameters:

x (Tensor) – x coordinate.
y (Tensor) – y coordinate.
r2 (Tensor) – Squared r (i.e. \(x^2+y^2\)). It may be used in some surface types to avoid redundant computation. Default: None.

Returns:

Corresponding value of the 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 r (i.e. \(x^2+y^2\)). It may be used in some surface types to avoid redundant computation. Default: None.

Returns:

Corresponding value of two partial derivatives.

Return type:

tuple[Tensor, Tensor]

intercept(ray: BatchedRay, forward: bool = True, aperture: bool = True) → 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.
forward (bool) – Whether the incident rays originate from object space and propagate towards image space. Default: True.
aperture (bool) – Whether to block out rays that are outside the aperture. Default: True.

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

Returns unit normal vector of the surface pointing to positive-z direction.

Parameters:

x (Tensor) – x coordinate.
y (Tensor) – y coordinate.
r2 (Tensor) – Squared r (i.e. \(x^2+y^2\)). It may be used in some surface types to avoid redundant computation. Default: None.

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. Coordinates are all global.
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

circularly_symmetric: bool = True¶: Whether the surface type is circularly symmetric.

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

eps: float¶: See ThinLens.

fl1: nn.Parameter¶: Object focal length.

fl2: nn.Parameter¶: Image focal length.

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

utilize_r2: bool = False¶: Whether the surface can utilize computed r2 to improve efficiency.