CoaxialContext

class dnois.optics.rt.CoaxialContext(surface: Surface, surface_sequence: SurfaceSequence, distance: Real | Tensor = None)

A subclass of Context for coaxial systems. In coaxial systems, default origins of local coordinate systems are arranged on z-axis and are determined by the distance from each surface to the next one. These points are called baseline s. Baseline of the first surface is fixed to 0. Shift and rotation of local coordinate systems can also be specified in order to, for example, simulate fabrication errors.

Note that the origin of this class is defined relative to baseline. In other words, origin is (0, 0, 0) means the global coordinate of origin is (0, 0, baseline).

See Context for descriptions of more parameters.

Parameters:

distance (float | Tensor) – Distance between baselines of the host surface and the next one.

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

property baseline: Tensor

The z-coordinate of the related surface’s baseline. A 0D tensor.

Type:

Tensor

chi: Ts

Spin angle of local coordinate.

property device: device

Device of this object.

Type:

torch.device

distance: Parameter

Distance between baselines of the host surface and the next one.

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: Ts

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: Ts

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: Ts

x-coordinate of the origin of local coordinate.

y: Ts

y-coordinate of the origin of local coordinate.

z: Ts

z-coordinate of the origin of local coordinate.