cmass: Centre of mass, array coordinates

hypercoil.functional.cmass.cmass(X: Tensor, axes: Sequence[int] | None = None, na_rm: bool = False) → Tensor

Differentiably compute a weight’s centre of mass. This can be used to regularise the weight so that its centre of mass is close to a provided coordinate.

Dimension:

Input : \((*, k_1, k_2, ..., k_n)\)

* denotes any number of batch and intervening dimensions, and the `k_i`s are dimensions along which the centre of mass is computed

Output : \((*, n)\)

n denotes the number of dimensions of each centre of mass vector

Parameters:

XTensor

Tensor containing the weights whose centres of mass are to be computed.

axesiterable or None (default None)

Axes of the input tensor that together define each slice of the tensor within which a single centre-of-mass vector is computed. If this is set to None, then the centre of mass is computed across all axes. If this is [-3, -2, -1], then the centre of mass is computed separately for each 3-dimensional slice spanned by the last three axes of the tensor.

na_rmfloat or False (default False)

If any single slice of the input tensor has zero mass, then the centre of mass within that slice is undefined and populated with NaN. The na_rm parameter specified how such undefined values are handled. If this is False, then NaN values are left intact; if this is a float, then NaN values are replaced by the specified float.

Returns:

cmassTensor

Centre of mass vectors for each slice from the input tensor. The coordinates are ordered according to the specification in axes.