scimba_torch.utils¶

Utility functions and classes.

class Mapping(from_dim, to_dim, map, jac=None, inv=None, jac_inv=None)[source]¶

Bases: object

A class to represent a mapping between two spaces.

Parameters:

from_dim (int) – The dimension of the input space.
to_dim (int) – The dimension of the output space.
map (FuncTypeCallable) – The mapping function.
jac (FuncTypeCallable | None) – The Jacobian of the mapping (optional, default=None).
inv (FuncTypeCallable | None) – The inverse of the mapping (optional, default=None).
jac_inv (FuncTypeCallable | None) – The Jacobian of the inverse of the mapping (optional, default=None).

Note

The map/inv/jac/jac_inv functions must accept batched inputs, i.e. Tensor of shape (batch_size, from_dim/to_dim). If you don’t want to write a version of the function, you can use torch.func.vmap to vectorize it.

from_dim¶: The dimension of the input space

to_dim¶: The dimension of the output space

is_invertible¶: A flag to indicate if the mapping is invertible

map: FuncTypeCallable¶: The mapping function

jac: FuncTypeCallable¶: The Jacobian of the mapping

inv: FuncTypeCallable¶: The inverse of the mapping (ONLY IF is_invertible=True)

jac_inv: FuncTypeCallable¶: The Jacobian of the inverse of the mapping (ONLY IF is_invertible=True)

static compose(map1, map2)[source]¶

Compose two mappings.

Parameters:

map1 (Mapping) – The first mapping.
map2 (Mapping) – The second mapping.

Returns:

math: map2 circ map1: (invertible if both map1 and map2 are invertible).

Return type:

The composed mapping

Raises:

ValueError – If the dimensions of the mappings are not compatible.

static invert(map)[source]¶

Invert a mapping.

From \(f: \mathbb{R}^n \to \mathbb{R}^m\) get \(f^{-1}: \mathbb{R}^m \to \mathbb{R}^n\).

Parameters:: map (Mapping) – The mapping to invert.
Return type:: Mapping
Returns:: The inverse mapping.
Raises:: ValueError – If the mapping is not invertible.

static identity(dim)[source]¶

Identity mapping in dimension dim.

Parameters:: dim (int) – The dimension of the identity mapping.
Return type:: Mapping
Returns:: The identity mapping.

static inv_identity(dim)[source]¶

Inverse identity mapping in dimension dim.

\(f: \mathbb{R}^n \to \mathbb{R}^n\) defined by \(f(x) = -x\).

Parameters:: dim (int) – The dimension of the inverse identity mapping.
Return type:: Mapping
Returns:: The inverse identity mapping.

static circle(center, radius)[source]¶

Mapping from \((0, 2\pi)\) to the circle.

Parameters:

center (Tensor) – The center of the circle.
radius (float) – The radius of the circle.

Return type:

Mapping

Returns:

The mapping of the circle (non-invertible).

static sphere(center, radius)[source]¶

Mapping from \((0, 1) \times (0, 2\pi)\) to the sphere.

Parameters:

center (Tensor) – The center of the sphere.
radius (float) – The radius of the sphere.

Return type:

Mapping

Returns:

The mapping of the sphere (non-invertible).

static segment(pt1, pt2)[source]¶

Maps \((0, 1)\) to (point1, point2).

Parameters:

pt1 (Tensor) – The first point of the segment.
pt2 (Tensor) – The second point of the segment.

Return type:

Mapping

Returns:

The mapping from point1 to point2.

static square(origin, x_dir, y_dir)[source]¶

Maps \((0, 1) \times (0, 1)\) to the square.

Parameters:

origin (Tensor) – Vector defining the origin of the square.
x_dir (Tensor) – Vector defining the x direction.
y_dir (Tensor) – Vector defining the y direction.

Return type:

Mapping

Returns:

The mapping from \((0, 1) \times (0, 1)\) to the square: (non-invertible).

Note

The vectors x_dir and y_dir must be orthogonal.
Changing the roles of x_dir and y_dir will change the orientation of the square but not the square itself.

static rot_2d(angle, center=None)[source]¶

2D rotation of angle about center.

Parameters:

angle (float) – The angle.
center (Tensor | None) – The center of the rotation; if None then use origin. Defaults to None.

Return type:

Mapping

Returns:

The 2D rotation of angle about center.

static rot_3d(axis, angle, center=None)[source]¶

3D rotation of angle around invariant axis about center.

Parameters:

axis (Tensor) – The invariant axis of the rotation.
angle (float) – The angle.
center (Tensor | None) – The center of the rotation.

Return type:

Mapping

Returns:

The 3D rotation of angle around invariant axis about center.

static translate(translation_vector)[source]¶

Translation mapping in an arbitrary dimension.

Parameters:: translation_vector (Tensor) – The translation vector.
Return type:: Mapping
Returns:: The translation mapping.

static surface_torus_3d(radius, tube_radius, center=tensor([0., 0., 0.], dtype=torch.float32))[source]¶

Mapping from \((0, 2\pi) \times (0, 2\pi)\) to the surface of the torus.

Maps \((0, 2\pi) \times (0, 2\pi)\) to the surface of a: torus of major radius \(R\) and minor radius \(r\).

Parameters:

radius (float) – The major radius of the torus.
tube_radius (float) – The minor radius of the torus.
center (Tensor) – The center of the torus.

Return type:

Mapping

Returns:

The mapping to the surface of the torus (non-invertible).

Modules

`mapping`	Define and compose mappings between spaces.
`paths`	Path and file utilities for scimba_torch.
`scimba_tensors`	Utility classes for handling tensors with associated labels in PyTorch.
`typing_protocols`	Common typing protocols to replace mypy_extensions usage.
`verbosity`	Verbosity utilities for scimba_torch.