BatchedRay

class dnois.optics.rt.BatchedRay(origin: Tensor, direction: Tensor, wl: float | Tensor, init_opl: float | Tensor = None, init_phase: float | Tensor = None, init_intensity: float | Tensor = None, *, d_normed: bool = False)

A class representing a batch of rays, which means both the origin and direction are tensors with the last dimension as 3, representing three coordinates x, y and z. Shapes of all the tensor arguments of __init__ method and all the tensors associated to an object of this class can be different but must be broadcastable, other than the last dimension of origin and direction. The broadcast shape is called shape of rays.

One may intend to record the accumulative optical path lengths (OPL) and phases or rays. In this case, provide initial OPLs or phases as init_opl or init_phase, respectively. If there is no initial value, just provide 0.. If either of them is not provided, corresponding quantity will not be recorded.

Note

As mentioned above, tensors bound to a ray object may have different shapes, so do its properties of tensor type. However, their shapes should be broadcastable, and shape always returns broadcast shape.

Warning

Some properties (attributes) depending on other properties may be cached for efficiency purpose. DO NOT modify the tensor properties with in-place operations.

Parameters:

  • origin (Tensor) – The origin of the rays. A tensor of shape (..., 3).

  • direction (Tensor) – The direction of the rays. A tensor of shape (..., 3).

  • wl (float or Tensor) – The wavelength of the rays. A tensor of shape (...).

  • init_opl (float or Tensor) – Initial optical path lengths. A tensor of shape (...). Default: do not record optical path lengths.

  • init_phase (float or Tensor) – Initial phase. A tensor of shape (...). Default: do not record phase.

broadcast() → Self

Return a copy of this object with tensors broadcast to shape of rays.

Returns:

A copy of this object.

broadcast_() → Self

Broadcast all the associated tensors to shape of rays shape.

Returns:

self

clone(deep: bool = False) → BatchedRay

Return a copy of this object.

Parameters:

deep (bool) – Whether to clone associated tensors by calling torch.Tensor.clone(). If False, returned object will hold the reference to the tensors bound to this object.

Returns:

The cloned object.

Return type:

BatchedRay

copy_valid_() → Self

Replace all invalid rays with one of valid ray. There is little data copy in this method.

Returns:

self

discard_() → Tensor

Discard invalid rays. This method can be called only if the shape of rays (i.e. len(self.shape)) is 1. flatten_() can be called to make an instance to satisfy this requirement. Note that this will lead to change of shape and data copy.

Returns:

A 1D torch.LongTensor indicating the indices of remaining rays.

Return type:

torch.LongTensor

expand_dim(dim: int, multiple: int) → Self

Expand the shape of rays by repeating bound tensors along given dimension. The tensors whose size in that dimension is 1 (i.e. broadcastable) will not be repeated.

Parameters:

  • dim (int) – The dimension along which the tensors are expanded.

  • multiple (int) – The number of times to repeat the tensors.

Returns:

A new ray object with expanded shape.

Return type:

BatchedRay

flatten_() → Self

Flatten the shape of rays to 1D.

Returns:

self

focus(dim: int = -1) → Tensor

Computes the focus of rays along a given dimension. It is determined as the point \(\mathbf{x}\) whose total squared distance to rays is minimum:

\[\mathbf{x}=\arg\min_x\sum_i\left(|\mathbf{x}-\mathbf{o}_i|^2- \left((\mathbf{x}-\mathbf{o}_i)\cdot\mathbf{d}_i\right)^2\right)\]

which can be solved by least square method. The sum is performed along dim.

Parameters:

dim (int) – The dimension along which the focus is computed. Default: -1.

Returns:

The focus of rays. Its shape is shape except for the dimension dim.

Return type:

Tensor

march(t: float | Tensor, n: float | Tensor = None) → BatchedRay

Out-of-place version of march_().

march_(t: float | Tensor, n: float | Tensor = None) → Self

March forward by a distance t. The origin will be updated.

Parameters:

  • t (Tensor) – Propagation distance. A tensor whose shape must be broadcastable with the shape of rays.

  • n (float or Tensor) – Refractive index of the medium in where the rays propagate. A float or a tensor with shape of rays. Default: 1.

Returns:

self

march_to(z: float | Tensor, n: float | Tensor = None) → BatchedRay

Out-of-place version of march_to_().

march_to_(z: float | Tensor, n: float | Tensor = None) → Self

March forward to a given z value z. This is similar to march_(), but all the rays end up with identical z coordinate rather than marching distance.

Parameters:

  • z (Tensor) – Target value of z coordinate. A tensor whose shape must be broadcastable with the shape of rays.

  • n (float or Tensor) – Refractive index of the medium in where the rays propagate. A float or a tensor with shape of rays. Default: 1.

Returns:

self

to_(*args, **kwargs) → Self

Call torch.Tensor.to() for all the tensors bound to self and update them by the returned tensor.

This method will not update the dtype of self.valid, which is always torch.bool.

Parameters:

  • args – Positional arguments accepted by torch.Tensor.to().

  • kwargs – Keyword arguments accepted by torch.Tensor.to().

Returns:

self

update_valid(valid: Tensor) → Self

Out-of-place version of update_valid().

update_valid_(valid: Tensor) → Self

Update the validity flags with valid. The new validity flag will be its logical & with the old.

Parameters:

valid (Tensor) – Another validity flag.

Returns:

self

valid_percentage(dims: int | Sequence[int] = None) → Tensor

Compute the percentage of valid rays along given dimensions.

Parameters:

dims (int or Sequence[int]) – The dimensions along which the percentage is computed. If None, compute the percentage along all dimensions. Default: None.

Returns:

Percentage of valid rays. Its shape is shape except for the dimensions specified by dims.

Return type:

Tensor

property d: Tensor

The direction of the rays. The length or returned direction (i.e. 2-norm along the last dimension) is normalized to 1.

Type:

Tensor

property d_x: Tensor

The projection of the direction to \(x\) axis. Its shape is that of d without the last dimension.

Type:

Tensor

property d_y: Tensor

The projection of the direction to \(y\) axis. Its shape is that of d without the last dimension.

Type:

Tensor

property d_z: Tensor

The projection of the direction to \(z\) axis. Its shape is that of d without the last dimension.

Type:

Tensor

property device: device

Device of this object.

Type:

torch.device

property dtype: dtype

Data type of this object.

Type:

torch.dtype

property intensity: Tensor | None

The intensities of the rays which is always positive. This property is None if intensity is not recorded.

Type:

Tensor

property ndim: int

Number of dimensions of rays i.e. length of shape.

Type:

int

property o: Tensor

The origin of the rays.

Type:

Tensor

property opl: Tensor | None

The accumulative OPL of the rays in meters which is always positive. This property is None if OPL is not recorded.

Warning

Direct modification to this property do not reflect on phase if it is recorded. Using march_() to ensure they are updated synchronously.

Type:

Tensor

property phase: Tensor | None

The phase shift of the rays, ranging in \([0,2\pi]\). This property is None if phase is not recorded.

Warning

Direct modification to this property do not reflect on opl if it is recorded. Using march_() to ensure they are updated synchronously.

Type:

Tensor

property r2: Tensor

\(x^2+y^2\) of the origin. Its shape is that of o without the last dimension.

Type:

Tensor

property recording_intensity: bool

Whether intensities are recorded.

Type:

bool

property recording_opl: bool

Whether OPLs are recorded.

Type:

bool

property recording_phase: bool

Whether phases are recorded.

Type:

bool

property shape: Size

Shape of rays, i.e. the broadcast shape of all the tensors bound to self.

Type:

torch.Size

property valid: Tensor

The validity flag of the rays.

Type:

torch.BoolTensor

property with_wl: bool

Whether wavelengths are set.

Type:

bool

property wl: Tensor

The wavelengths of rays.

Type:

Tensor

property x: Tensor

\(x\) coordinate of the origin. Its shape is that of o without the last dimension.

Type:

Tensor

property y: Tensor

\(y\) coordinate of the origin. Its shape is that of o without the last dimension.

Type:

Tensor

property z: Tensor

\(z\) coordinate of the origin. Its shape is that of o without the last dimension.

Type:

Tensor