CircularAperture

class dnois.optics.rt.CircularAperture(radius: Real | Tensor = inf)

Circular aperture with radius radius.

Parameters:

radius (float | Tensor) – Radius of the aperture.

evaluate(x: Tensor, y: Tensor) → BoolTensor

Returns a boolean tensor representing whether each point \((x,y)\) is inside the aperture. To jointly represent 2D coordinates, x and y must be broadcastable.

Parameters:

• x (Tensor) – x coordinates of the points.

• y (Tensor) – y coordinates of the points.

Returns:

See description above. The shape of returned tensor is the broadcast result of x and y.

Return type:

Tensor

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.

forward(ray: BatchedRay) → BatchedRay

Similar to evaluate(), but operates on rays.

Parameters:

ray (BatchedRay) – Incident rays.

Returns:

New rays among which those outside the aperture are marked as invalid.

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.

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.

pass_ray(ray: BatchedRay) → BoolTensor

Similar to evaluate(), but operates on rays.

Parameters:

ray (BatchedRay) – Incident rays.

Returns:

A mask tensor indicating whether corresponding rays can pass the aperture.

Return type:

torch.BoolTensor

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: str, *args, **kwargs) → tuple[Tensor, Tensor]

Samples points on this aperture, i.e. baseline plane of associated surface. Specific distribution depends on mode.

Parameters:

mode (str) – Sampling mode. Calling object of this method should possess a sample_{mode} method.

Returns:

Two 1D tensors of representing x and y coordinates of the points.

Return type:

tuple[Tensor, Tensor]

sample_center() → tuple[Tensor, Tensor]

Return the central point of the aperture.

Returns:

Two [0.] tensors.

Return type:

tuple[Tensor, Tensor]

sample_diameter(n: int = 64, theta: float | Tensor = 0.0) → tuple[Tensor, Tensor]

Samples points on diameter line segments of this aperture. Polar angle of the line is given by theta.

Parameters:

• n (int) – Number of points.

• theta (float | Tensor) – Polar angle of the line. A single float or a tensor with any shape.

Returns:

Two tensors representing x and y coordinates of the points. If theta is a float, with shape (n,); if a tensor with shape (...), with shape (..., n).

sample_random(n: int, sampling_curve: Callable[[Tensor], Tensor] = None) → tuple[Tensor, Tensor]

Returns n points randomly sampled on this aperture. An optional sampling_curve (denoted by \(\Gamma\)) can be specified to control the distribution of radial distance: \(r=\Gamma(t)R\) where \(t\) is drawn uniformly from \([0,1]\) and \(R\) is the radius.

Parameters:

• n (int) – Number of points.

• sampling_curve (Callable[[Tensor], Tensor]) – Sampling curve \(\Gamma(t)\). Default: \(\sqrt{t}\).

Returns:

Two 1D tensors of length n, representing x and y coordinates of the points.

Return type:

tuple[Tensor, Tensor]

sample_rect(n: int | tuple[int, int], mask_invalid: bool = True) → tuple[Tensor, Tensor]

Samples points on this aperture in a evenly spaced rectangular grid, where number of points in vertical and horizontal directions \((H, W)\) are given by n. Note that the points outside the aperture are dropped so total number of returned points are is less than \(HW\).

Parameters:

• n (int | tuple[int, int]) – A pair of int representing \((H, W)\).

• mask_invalid (bool) – Whether to discard points outside the aperture. Default: True.

Returns:

Two 1D tensors of representing x and y coordinates of the points.

Return type:

tuple[Tensor, Tensor]

sample_unipolar(n_radius: int = 6, n_angle: int = 6) → tuple[Tensor, Tensor]

Samples points on this aperture in a unipolar manner. Specifically, the aperture is divided into \(N_r\) rings with equal widths and points are sampled on the outer edge of each ring. The first ring contains \(N_\theta\) points, the second contains \(2N_\theta\) points … and so on, plus a point at center. Thus, there are \(N_\theta N_r(N_r+1)/2+1\) points in total.

Parameters:

• n_radius (int) – Number of rings \(N_r\). Default: 6.

• n_angle (int) – Level of points increase per ring \(N_\theta\). Default: 6.

Returns:

Two 1D tensors of representing x and y coordinates of the points.

Return type:

tuple[Tensor, Tensor]

sampler(mode: str, *args, **kwargs) → Callable[[], tuple[Tensor, Tensor]]

Returns a callable object that can be used to sample points on this aperture. When it is called, it will call sample() with given arguments and return its return value. See sample() for more details.

Returns:

A callable object that can be used to sample points on this aperture.

Return type:

Callable

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 d

Alias for diameter.

property device: device

Device of this object.

Type:

torch.device

property diameter

Diameter of the aperture.

Type:

0D Tensor

property dtype: dtype

Data type of this object.

Type:

torch.dtype

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 r

Alias for radius.

radius: nn.Parameter

Radius of the aperture.

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