isochor: PSD normalisation

hypercoil.functional.activation.isochor(input: Tensor, volume: float = 1, max_condition: float | None = None, softmax_temp: float | None = None) → Tensor

Volume-normalising activation function for symmetric, positive definite matrices.

This activation function first finds the eigendecomposition of each input matrix. The eigenvalues are then each divided by \(\sqrt[n]{\frac{v_{in}}{v_{target}}}\) to normalise the determinant to \(v_{target}\). Before normalisation, there are options to rescale the eigenvalues through a softmax and/or to enforce a maximal condition number for the output tensor. If the input tensors are being used to represent ellipsoids, for instance, this can constrain the eccentricity of those ellipsoids. Finally, the matrix is reconstituted using the original eigenvectors and the rescaled eigenvalues.

Dimension:

input : \((*, P, P)\)

P denotes the row and column dimensions of the input matrices. * denotes any number of additional dimensions.

output : \((*, P, P)\)

As above.

Parameters:

inputtensor

Tensor containing symmetric, positive definite matrices.

volumefloat (default 1)

Target volume for the normalisation procedure. All output tensors will have this determinant.

max_conditionfloat \(\in [1, \infty)\) or None (default None)

Maximum permissible condition number among output tensors. This can be used to constrain the eccentricity of isochoric ellipsoids. To enforce this maximum, the eigenvalues of the input tensors are replaced with a convex combination of the original eigenvalues and a vector of ones such that the largest eigenvalue is no more than max_condition times the smallest eigenvalue. Note that a max_condition of 1 will always return (a potentially isotropically scaled) identity.

softmax_tempfloat or None (default None)

If this is provided, then the eigenvalues of the input tensor are passed through a softmax with the specified temperature before any other processing.

Returns:

tensor

Volume-normalised tensor.