compactness: Compactness

compactness

hypercoil.loss.compactness(X: Tensor, coor: Tensor, *, norm: int | float | Literal['inf'] = 2, floor: float = 0.0, radius: float | None = 100.0, key: PRNGKey | None = None) → Tensor

Distance of masses in each object from the centre of mass of that object.

A diffuse object will have a high score, while a compact object will have a low score.

Parameters:

XTensor

Tensor block containing the data to be evaluated. Each row is a collection of masses assigned to the single object or parcel, and each column denotes the distribution of masses across objects or parcels at a single spatial location.

coorTensor

Coordinates of the spatial locations in each of the columns of X.

radiusfloat or None (default 100)

Radius of the spherical manifold on which the coordinates are located. If this is specified as None, it is assumed that the coordinates are in a space induced by the norm parameter.

normint, float or ‘inf’ (default 2)

The norm to use to calculate the distance between the centres of mass and the masses. Ignored if radius is specified; in this case, the spherical geodesic distance is used.

floorfloat (default 0)

Minimum distance to be penalised. This can be used to avoid penalising masses that are already very close to the centre of mass.

Returns:

Tensor

Distance of the masses in each object from the centre of mass of that object.

CompactnessLoss

class hypercoil.loss.CompactnessLoss(nu: float = 1.0, name: str | None = None, *, coor: Tensor | None = None, radius: float | None = 100.0, norm: int | float | Literal['inf'] = 2, floor: float = 0.0, scalarisation: Callable | None = None, key: 'jax.random.PRNGKey' | None = None)

Loss function penalising distances between locations in a mass and the centroid of that mass.

Compactness

The compactness is defined as

\(\mathbf{1}^\intercal\left(A \circ \left\|C - \frac{AC}{A\mathbf{1}} \right\|_{cols} \right)\mathbf{1}\)

Given a coordinate set \(C\) for the columns of a weight \(A\), the compactness measures the weighted average norm of the displacement of each of the weight’s entries from its row’s centre of mass. (The centre of mass is expressed above as \(\frac{AC}{A\mathbf{1}}\)).

In this simulation, the compactness loss is applied with a multi-logit domain mapper and without any other losses or regularisations. The weights collapse to compact but unstructured regions of the field.

Penalising this quantity can promote more compact rows (i.e., concentrate the weight in each row over columns corresponding to coordinates close to the row’s spatial centre of mass).

Warning

This loss can have a large memory footprint, because it requires computing an intermediate tensor with dimensions equal to the number of rows in the weight, multiplied by the number of columns in the weight, multiplied by the dimension of the coordinate space.

Parameters:

name: str

Designated name of the loss function. It is not required that this be specified, but it is recommended to ensure that the loss function can be identified in the context of a reporting utilities. If not explicitly specified, the name will be inferred from the class name and the name of the scoring function.

nu: float

Loss strength multiplier. This is a scalar multiplier that is applied to the loss value before it is returned. This can be used to modulate the relative contributions of different loss functions to the overall loss value. It can also be used to implement a schedule for the loss function, by dynamically adjusting the multiplier over the course of training.

coorTensor

Coordinates of the spatial locations in each of the columns of X.

radiusfloat or None (default 100)

Radius of the spherical manifold on which the coordinates are located. If this is specified as None, it is assumed that the coordinates are in a space induced by the norm parameter.

normint, float or ‘inf’ (default 2)

The norm to use to calculate the distance between the centres of mass and the masses. Ignored if radius is specified; in this case, the spherical geodesic distance is used.

floorfloat (default 0)

Minimum distance to be penalised. This can be used to avoid penalising masses that are already very close to the centre of mass.

scalarisation: Callable

The scalarisation function to be used to aggregate the values returned by the scoring function. This function should take a single argument, which is a tensor of arbitrary shape, and return a single scalar value. By default, the mean scalarisation is used.

Methods

__call__(X[, coor, key])

Call self as a function.