Euclidean neural networks
What is e3nn
?
e3nn
is a python library based on pytorch to create equivariant neural networks for the group \(O(3)\).
Where to start?
Guide to the
e3nn.o3.Irreps
: Irreducible representationsGuide to implement a Convolution
The simplest example to start with is Tetris Polynomial Example.
Guide to implement a Transformer
Demonstration
All the functions to manipulate rotations (rotation matrices, Euler angles, quaternions, convertions, …) can be found here Parametrization of Rotations.
The irreducible representations of \(O(3)\) (more info at Irreps) are represented by the class e3nn.o3.Irrep
.
The direct sum of multiple irrep is described by an object e3nn.o3.Irreps
.
If two tensors \(x\) and \(y\) transforms as \(D_x = 2 \times 1_o\) (two vectors) and \(D_y = 0_e + 1_e\) (a scalar and a pseudovector) respectively, where the indices \(e\) and \(o\) stand for even and odd – the representation of parity,
import torch
from e3nn import o3
irreps_x = o3.Irreps('2x1o')
irreps_y = o3.Irreps('0e + 1e')
x = irreps_x.randn(-1)
y = irreps_y.randn(-1)
irreps_x.dim, irreps_y.dim
(6, 4)
their outer product is a \(6 \times 4\) matrix of two indices \(A_{ij} = x_i y_j\).
A = torch.einsum('i,j', x, y)
A
tensor([[-0.4212, -0.2153, -0.0361, 0.1618],
[-0.4471, -0.2286, -0.0383, 0.1718],
[-0.3430, -0.1753, -0.0294, 0.1318],
[ 0.9442, 0.4827, 0.0808, -0.3628],
[ 0.6839, 0.3496, 0.0586, -0.2628],
[-0.2674, -0.1367, -0.0229, 0.1027]])
If a rotation is applied to the system, this matrix will transform with the representation \(D_x \otimes D_y\) (the tensor product representation).
Which can be represented by
R = o3.rand_matrix()
D_x = irreps_x.D_from_matrix(R)
D_y = irreps_y.D_from_matrix(R)
plt.imshow(torch.kron(D_x, D_y), cmap='bwr', vmin=-1, vmax=1);
This representation is not irreducible (is reducible). It can be decomposed into irreps by a change of basis. The outerproduct followed by the change of basis is done by the class e3nn.o3.FullTensorProduct
.
tp = o3.FullTensorProduct(irreps_x, irreps_y)
print(tp)
tp(x, y)
FullTensorProduct(2x1o x 1x0e+1x1e -> 2x0o+4x1o+2x2o | 8 paths | 0 weights)
tensor([-0.0703, 0.3718, -0.4212, -0.4471, -0.3430, 0.9442, 0.6839, -0.2674,
0.1423, -0.2384, 0.1361, -0.1696, 0.1599, -0.1901, -0.0096, -0.1871,
0.0028, 0.1007, 0.2454, -0.3532, 0.3044, -0.1912, -0.2020, -0.2687])
As a sanity check, we can verify that the representation of the tensor prodcut is block diagonal and of the same dimension.
D = tp.irreps_out.D_from_matrix(R)
plt.imshow(D, cmap='bwr', vmin=-1, vmax=1);
e3nn.o3.FullTensorProduct
is a special case of e3nn.o3.TensorProduct
, other ones like e3nn.o3.FullyConnectedTensorProduct
can contained weights what can be learned, very useful to create neural networks.