persunraveltorch.nn

Basic building blocks for unravelled persistence.

These are basic building blocks for unravelled persistence in PyTorch. All functions and methods processing tensors support a form of broadcasting.

class persunraveltorch.nn.BiplaneFromIntervals(*, pixel_columns: int, range_intervals: Tuple[float, float] = (0.0, pi / 2.0), padding: int, max_overhead: int | None = None, device=None, dtype=None)

Bases: Module

Creates a biplane from persistence intervals within a finite range.

This module takes persistence intervals within a finite range range_intervals as an Iterable by degree as input. So each item of the input is a torch.Tensor of shape $([\dots,] k, 2)$, where $k$ is the number of persistence intervals in the corresponding degree. The output can be thought of as a 3D bitmap with a depth of $2$ - henceforth called biplane - and two channels. So the output has shape $([\dots,] 2, 2, w, h)$ with the width $w$ being equal to padding + pixel_columns + padding. The $0$-th channel contains two sheared rasterizations of the Hilbert function of the unravelled relative homology lattice on top of each other and offset by a glide reflection corresponding to suspension. Similarly, the $1$-st channel contains two sheared rasterizations of the unravelled rank invariant on top of each other and offset by a glide reflection corresponding to suspension.

Parameters:

• pixel_columns (int) – The number of pixels used to raster each row or scanline of the strip supporting the relative homology lattice.

• range_intervals (Tuple[float, float], optional) – The finite range containing all persistence intervals, defaults to (0.0, pi/2.0).

• padding (int) – The amount of horizontal padding being added to both, the left and the right side.

• max_overhead (Optional[int], optional) – If this is set, then the input will be processed in batches as small as necessary to limit the number of bytes allocated as overhead to at most max_overhead. So if you’re not already processing your data in sufficiently small batches, setting this parameter is recommended. However, if the number of bytes required to process a single sample already exceeds max_overhead, the input is still processed sample by sample. The default is None.

biplane_from_triangles

BiplaneFromTriangles: The instance used internally.

forward(intervals: Iterable[Tensor], /) → Tensor

Biplane created from persistence intervals as described for BiplaneFromIntervals.

Parameters:

intervals (Iterable[torch.Tensor]) – Persistence intervals by degree.

Returns:

A biplane with two channels describing the Hilbert function of the unravelled relative homology lattice and the unravelled rank invariant.

Return type:

torch.Tensor

property pixel_area: float

The area covered by each pixel.

Type:

float

raster_triangle

RasterTriangle: The instance used internally.

class persunraveltorch.nn.BiplaneFromTriangles(*, pixel_columns: int, padding: int, max_overhead: int | None = None, device=None, dtype=None)

Bases: Module

Asembles a biplane from triangles.

This module takes triangles as created by RasterTriangle as an input and assembles a biplane from these triangles.

Parameters:

• pixel_columns (int) – The number of pixels used to raster each row or scanline of the strip assembled from triangles.

• max_overhead (Optional[int]) – If this is set, the input will be processed in batches as small as necessary to limit the number of bytes allocated as overhead to at most max_overhead. So if you’re not already processing your data in sufficiently small batches, setting this parameter is recommended. However, if the number of bytes required to process a single sample already exceeds max_overhead, the input is still processed sample by sample.

• padding (int) – The amount of horizontal padding being added to both, the left and the right side.

forward(triangles: Iterable[Tensor], /) → Tensor

Asemble a biplane from triangles.

Takes triangles as created by RasterTriangle as an input and assembles a biplane from these triangles.

Parameters:

triangles (Iterable[torch.Tensor]) – Triangles as for example created by RasterTriangle.

Returns:

A biplane assembled from triangles.

Return type:

torch.Tensor

class persunraveltorch.nn.ConvBiplane(in_channels: int, out_channels: int, kernel_size: int | Tuple[int, int, int], *, shift: int, stride: int | Tuple[int, int] = 1, padding: int | Tuple[int, int] = 0, dilation: int | Tuple[int, int] = 1, groups: int = 1, bias: bool = True, padding_mode: str = 'zeros', device=None, dtype=None)

Bases: Module

Biplane convolutional neural network layer.

A biplane convolutional neural network layer is a particular type of group equivariant neural network layer taking a biplane as an input and producing a new biplane as an output by applying a cross-correlation with respect to an action of a discretized version of the abelian group $\Z \times \R^2$. Thinking of the biplane as a discretization of a function on $\{0, 1\} \times \R^2$, the corresponding action of $\Z \times \R^2$ on $\{0, 1\} \times \R^2$ is

$$\begin{aligned} (\Z \times \R^2) \times (\{0, 1\} \times \R^2) & \to \{0, 1\} \times \R^2, \\ ((k, v), (d, p)) & \mapsto T^k(d, v+p), \end{aligned}$$

where

$$\begin{aligned} T \colon \{0, 1\} \times \R^2 & \to \{0, 1\} \times \R^2, \\ (0, p) & \mapsto (1, p), \\ (1, p) & \mapsto (0, p - (0, \mathrm{shift})) . \end{aligned}$$

Parameters:

• in_channels (int) – The number of channels in the input biplane.

• out_channels (int) – The number of channels produced by the cross-correlation.

• kernel_size (class:int | Tuple[int, int, int]) – The size of the convolution kernel.

• shift (int) – The $\mathrm{shift}$-parameter in the definition of ${T \colon \{0, 1\} \times \R^2 \to \{0, 1\} \times \R^2}$.

• stride (int | Tuple[int, int], optional) – The stride of the cross-correlation, defaults to 1.

• padding (int | Tuple[int, int], optional) – Padding added to all four sides of the biplane, defaults to 0.

• dilation (int | Tuple[int, int], optional) – The spacing between kernel elements, defaults to 1.

• groups (int, optional) – The number of blocked connections from input channels to output channels, defaults to 1.

• bias (bool, optional) – If this is set to True, then a learnable bias is added to the output, defaults to True.

• padding_mode (str, optional) – One of the four padding modes 'zeros', 'reflect', 'replicate' or 'circular', defaults to 'zeros'.

conv3d

The convolution module used internally.

Type:

torch.nn.Conv3d

forward(input: Tensor, /) → Tensor

Applies a cross-correlation as described for ConvBiplane.

Parameters:

input (torch.Tensor) – The biplane serving as an input to the cross-correlation.

Returns:

The result of the cross-correlation.

Return type:

torch.Tensor

class persunraveltorch.nn.HilbertGram(*, range_intervals: Tuple[float, float] = (0.0, pi / 2.0), partial_info: bool = False, device=None, dtype=None)

Bases: HilbertKernel

As HilbertKernel but for different sizes in dimension -3.

If the first input consists of tensors of shape $([\dots,] m, k, 2)$ for some ${m \in \N}$ and the second input consists of tensors of shape $([\dots,] n, k, 2)$ for some ${n \in \N}$, then the output has shape $([\dots,] m, n)$ containing all results of pairwise kernel computations as a Gram matrix. Parameters and attributes are inherited from HilbertKernel.

forward(intervals01: Sequence[Tensor], intervals02: Sequence[Tensor], /) → Tensor

Computes the Gram matrix of the corresponding Hilbert functions.

Parameters:

• intervals01 (Sequence[torch.Tensor]) – Persistence intervals for the first input as a Sequence[torch.Tensor] by degree. Each item of this sequence is a torch.Tensor of shape $([\dots,] m, k, 2)$, where $k$ is the number of persistence intervals in the corresponding degree.

• intervals02 (Sequence[torch.Tensor]) – Persistence intervals for the second input as a Sequence[torch.Tensor] by degree. Each item of this sequence is a torch.Tensor of shape $([\dots,] n, k, 2)$, where $k$ is the number of persistence intervals in the corresponding degree.

Returns:

The Gram matrix of the corresponding Hilbert functions.

Return type:

torch.Tensor

class persunraveltorch.nn.HilbertKernel(*, range_intervals: Tuple[float, float] = (0.0, pi / 2.0), partial_info: bool = False, device=None, dtype=None)

Bases: Module

Kernel induced by the embedding as Hilbert functions.

This is the kernel that is induced by the feature map that sends graded persistence intervals to the Hilbert function of the corresponding unravelled relative homology lattice using the inner product of square-integrable functions.

Parameters:

• range_intervals (Tuple[float, float], optional) – The finite range containing all persistence intervals, defaults to (0.0, pi/2.0).

• partial_info (bool, optional) – If this is set to True, the inner product of the corresponding truncated Hilbert functions is computed. This is sensible, whenever persistence intervals are only known up to a certain degree. The corresponding attribute partial_info can be changed after initialization. The default is False.

forward(intervals01: Sequence[Tensor], intervals02: Sequence[Tensor], /) → Tensor

Computes the inner product of the corresponding Hilbert functions.

Parameters:

• intervals01 (Sequence[torch.Tensor]) – Persistence intervals for the first input as a Sequence[torch.Tensor] by degree. So each item of this sequence is a torch.Tensor of shape $([\dots,] k, 2)$, where $k$ is the number of persistence intervals in the corresponding degree.

• intervals02 (Sequence[torch.Tensor]) – Persistence intervals for the second input as a Sequence[torch.Tensor] by degree analogous to the first parameter intervals01.

Returns:

The inner product of the corresponding Hilbert functions.

Return type:

torch.Tensor

partial_info

bool: Whether Hilbert functions should be truncated before computing the inner product; also see the description of the corresponding parameter.

class persunraveltorch.nn.MaxPoolBiplane(kernel_size: int | Tuple[int, int], stride: int | Tuple[int, int] | None = None, padding: int | Tuple[int, int] = 0, dilation: int | Tuple[int, int] = 1, return_indices: bool = False, ceil_mode: bool = False)

Bases: Module

Essentialy torch.nn.MaxPool2d with more flexible broadcasting.

This works almost the same as torch.nn.MaxPool2d except that it has more flexible broadcasting behaviour to accomodate processing biplanes.

Parameters:

• kernel_size (int | Tuple[int, int]) – The size of the window to take max over.

• stride (Optional[ int | Tuple[int, int] ], optional) – The stride of the window, defaults to None.

• padding (int | Tuple[int, int], optional) – Implicit negative infinity padding to be added on both sides, defaults to 0.

• dilation (int | Tuple[int, int], optional) – This parameter controls the stride of elements in the window, defaults to 1.

• return_indices (bool, optional) – If this is set to True, tnen the max indices will be returned with the output. The default is False.

• ceil_mode (bool, optional) – If this is set to True, then ceil() instead of floor() will be used to compute the output shape. The default is False.

forward(input: Tensor, /) → Tensor

Applies max pooling as described for MaxPoolBiplane.

Parameters:

input (torch.Tensor) – The biplane max pooling is applied to.

Returns:

The biplane after max pooling.

Return type:

torch.Tensor

class persunraveltorch.nn.PlaneSelect(plane: int)

Bases: Module

Selects one of the planes in a biplane.

This module takes a biplane as an input and outputs one of the two planes.

Parameters:

plane (int) – The index of the plane to select, which can be 0 or 1. The corresponding attribute plane can be changed after initialization.

forward(input: Tensor, /) → Tensor

Selects the plane with index plane.

Parameters:

input (torch.Tensor) – The biplane to process.

Returns:

The selected plane.

Return type:

torch.Tensor

plane

The index of the plane to select.

Type:

int

class persunraveltorch.nn.RasterTriangle(pixel_columns: int, *, range_intervals: Tuple[float, float] = (0.0, pi / 2.0), max_overhead: int | None = None, device=None, dtype=None)

Bases: Module

Rasters a triangle corresponding to a single patch of a biplane.

This module takes persistence intervals within a finite range range_intervals of two consecutive degrees as input and rasters the corresponding single triangular patch to an unsheared biplane.

Parameters:

• pixel_columns (int) – The number of pixels used to raster each row or scanline of the strip supporting the relative homology lattice.

• range_intervals (Tuple[float, float], optional) – The finite range containing all persistence intervals, defaults to (0.0, pi/2.0).

• max_overhead (Optional[int], optional) – If this is set, then the input will be processed in batches as small as necessary to limit the number of bytes allocated as overhead to at most max_overhead. So if you’re not already processing your data in sufficiently small batches, setting this parameter is recommended. However, if the number of bytes required to process a single sample already exceeds max_overhead, the input is still processed sample by sample. The corresponding attribute max_overhead can be changed after initialization. The default is None.

forward(intervals00: Tensor, intervals01: Tensor, /) → Tensor

Triangle created from persistence intervals as described for RasterTriangle.

Parameters:

• intervals00 (torch.Tensor) – Persistence intervals for the lower of the two consecutive degrees.

• intervals01 (torch.Tensor) – Persistence intervals for the higher of the two consecutive degrees.

Returns:

A triangle with two channels describing a single patch to an unsheared corresponding biplane.

Return type:

torch.Tensor

max_overhead

Optional[int]: Limits overhead as described for RasterTriangle.

property pixel_area: float

The area covered by each pixel.

Type:

float

class persunraveltorch.nn.Reshear(*, shape: Size, mode: ReshearMode = ReshearMode.ZERO, device=None, dtype=None)

Bases: Module

Reshears a biplane.

The biplanes rendered by BiplaneFromIntervals and BiplaneFromTriangles are sheared in comparison to the strip indexing the unravelled relative homology lattice to save on memory and computation. This module undoes the sheering inherents to these two classes and can be used for visualization purposes.

Parameters:

• shape (torch.Size) – The shape of the tensors to be processed. Only the last two components matter, the others are ignored.

• mode (ReshearMode, optional) – See ReshearMode for details. The corresponding attribute mode can be changed after initialization. The default is ReshearMode.ZERO.

classmethod create_n_apply(input: Tensor, *, mode: ReshearMode = ReshearMode.ZERO, device=None, dtype=None) → Tuple[Tensor, None]

Creates a matching instance and applies it.

This class method creates an instance with the shape parameter matching the input and applies it to input. Both the processed input tensor as well as the instance are returned.

Parameters:

• input (torch.Tensor) – The tensor to be resheared.

• mode (ReshearMode, optional) – See ReshearMode for details. The corresponding attribute mode can be changed after initialization. The default is ReshearMode.ZERO.

Returns:

Pair with the first component containing the sheared tensor and the second component the instance that was used to create it.

Return type:

Tuple[torch.Tensor, Reshear]

forward(input: Tensor, /) → Tensor

Reshears the input.

Parameters:

input (torch.Tensor) – The tensor to be resheared.

Returns:

The resheared tensor.

Return type:

torch.Tensor

mode

See ReshearMode for details.

Type:

ReshearMode

class persunraveltorch.nn.ReshearMode(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Initialization parameter and attribute to Reshear.

REPLICATE = 'replicate'

Replicate the pixels of the left and right most columns horizontally.

ZERO = 'zero'

Fill the surrounding pixels with zeros.

class persunraveltorch.nn.StripAffineFunctional(weight: Tensor, bias: Tensor, pixel_area: float)

Bases: Module

Affine functional induced by a sheared bitmap and a bias.

The affine functional on sheared bitmaps induced by a single sheared bitmap as a weight and a bias.

Parameters:

• weight (torch.Tensor) – The sheared bitmap used as a weight.

• bias (torch.Tensor) – The singleton tensor used as a bias.

• pixel_area (float) – The area covered by each pixel.

bias

The singleton parameter used as a bias.

Type:

nn.Parameter

energy() → Tensor

torch.Tensor: The energy of the weight.

forward(input: Tensor) → Tensor

Applies the affine functional to the input.

Parameters:

input (torch.Tensor) – The sheared bitmap passed as an argument to the affine functional.

Returns:

The singleton tensor obtained as a result.

Return type:

torch.Tensor

pixel_area

The area covered by each pixel.

Type:

float

variational_energy() → Tensor

torch.Tensor: The energy of the gradient of the weight.

weight

The sheared bitmap used as a weight.

Type:

nn.Parameter

class persunraveltorch.nn.Unravel(*, range_intervals: Tuple[float, float] = (0.0, pi / 2.0), neg_x: bool = False, neg_y: bool = False, device=None, dtype=None)

Bases: Module

Computes the associated unravelled persistence diagram.

This module computes the unravelled persistence diagram associated to persistence intervals within a finite range range_intervals.

Parameters:

• range_intervals (Tuple[float, float], optional) – The finite range containing all persistence intervals, defaults to (0.0, pi/2.0).

• neg_x (bool, optional) – Whether the x-axis is negated with respect to Cartesian coordintes, defaults to False

• neg_y (bool, optional) – Whether the y-axis is negated with respect to Cartesian coordintes, defaults to False

forward(intervals: Iterable[Tensor], /) → Sequence[Tensor]

Computes the associated unravelled persistence diagram.

Parameters:

intervals (Iterable[torch.Tensor]) – Persistence intervals by degree.

Returns:

The associated unravelled persistence diagram.

Return type:

Sequence[torch.Tensor]

• persunraveltorch.nn.functional
  • max_pool_biplane()
  • plane_select()