Context

class dnois.optics.rt.Context(surface: Surface, surface_sequence: SurfaceSequence)

A class representing the context of a Surface in a list of surfaces. As component of the surface list, a surface does not hold the reference to the list but can access the information that depends on other surfaces in it via this class. Every surface contained in a surface list has a related context object. If it is not contained in any group, its context attribute is None.

This class also implements the conversion between global and surface-local coordinates. See Surface-local coordinate system for more details.

Parameters:

• surface (Surface) – The host surface that this context belongs to.

• surface_sequence (SurfaceSequence) – The surface list containing surface.

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.

classmethod from_dict(d: dict) → Self

Constructs an instance of cls from a dict.

Parameters:

d (dict) – A dict typically returned by to_dict().

Returns:

An instance of cls.

g2l(x: Tensor, direction: bool = False) → Tensor

Converts global vectors x to local ones. If x represents positions, it is

\[\mathbf{x}'=\mathbf{R}(\mathbf{x}-\mathbf{x}_0)\]

where \(\mathbf{R}\) is rotation matrix and \(\mathbf{x}_0\) is origin. If x represents directions, instead, it is

\[\mathbf{x}'=\mathbf{R}\mathbf{x}\]

Parameters:

• x (Tensor) – Global vectors, a tensor of shape (..., 3).

• direction (bool) – Whether x represents directions. Default: False.

Returns:

Local vectors, a tensor of shape (..., 3).

Return type:

Tensor

l2g(x: Tensor, direction: bool = False) → Tensor

Converts local vectors x to global ones. If x represents positions, it is

\[\mathbf{x}'=\mathbf{R}^{-1}\mathbf{x}+\mathbf{x}_0\]

where \(\mathbf{R}\) is rotation matrix and \(\mathbf{x}_0\) is origin. If x represents directions, instead, it is

\[\mathbf{x}'=\mathbf{R}^{-1}\mathbf{x}\]

Parameters:

• x (Tensor) – Local vectors, a tensor of shape (..., 3).

• direction (bool) – Whether x represents directions. Default: False.

Returns:

Global vectors, a tensor of shape (..., 3).

Return type:

Tensor

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.

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.

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: bool = 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 axis: Tensor

A unit vector of shape (3,) indicating rotated z axis in global coordinate system:

\[\mathbf{A}=\left(\sin\theta\cos\phi, \sin\theta\sin\phi, \cos\theta\right)\]

If assigning a tensor to it, it will be normalized to unit length automatically.

Type:

Tensor

chi: Tensor

Spin angle of local coordinate.

property device: device

Device of this object.

Type:

torch.device

property dtype: dtype

Data type of this object.

Type:

torch.dtype

property index: int

The index of the host surface in the surface list.

Type:

int

property material_before: Material

Material object before ths host surface.

Type:

Material

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 origin: Tensor

Coordinate of the origin of local coordinate system in the global one. A tensor of shape (3,). This property can be deleted to fix local origin to global origin.

Type:

Tensor

phi: Tensor

Azimuthal angle of z-axis of local coordinate.

property rotated: bool

Whether the local coordinate system is rotated.

Type:

bool

seq: SurfaceSequence

The surface list containing the surface.

property shifted: bool

Whether the local coordinate system is shifted.

Type:

bool

surface: Surface

The host surface that this context belongs to.

property surface_before: Surface

The surface before the host surface.

Type:

Surface

theta: Tensor

Polar angle of z-axis of local coordinate.

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

x: Tensor

x-coordinate of the origin of local coordinate.

y: Tensor

y-coordinate of the origin of local coordinate.

z: Tensor

z-coordinate of the origin of local coordinate.