链接：https://docs.e3nn.org/en/latest/examples/examples.html

---

docs：e3nn

e3nn是一个用于构建欧几里得(E(3))等变神经网络的Python库，这意味着它们能自动保持三维旋转和反射的对称性。

该库使用不可约表示(Irreps)来描述数据变换方式，通过张量积以原则性的方式组合这些对称特征。

此外，该库还利用球谐函数处理方向性数据，提供专门的等变神经网络模块（如线性层和激活函数），包含用于稳定训练的归一化策略，并支持TorchScript JIT以实现优化部署。

可视化

章节列表

1. 不可约表示(Irreps)
2. 球谐函数
3. 张量积
4. 等变神经网络模块
5. 归一化
6. TorchScript JIT支持

---

e3nn库文档

该库旨在帮助 开发E(3)等变神经网络，包含张量积和球谐函数等基础数学运算。

快速入门

import torch
from e3nn import o3# 创建由标量(0e)和向量(1o)组成的随机数组
irreps_in = o3.Irreps("0e + 1o")
x = irreps_in.randn(-1)# 应用线性层
irreps_out = o3.Irreps("2x0e + 2x1o")
linear = o3.Linear(irreps_in=irreps_in, irreps_out=irreps_out)
y = linear(x)# 计算自张量积
tp = o3.FullTensorProduct(irreps_in1=irreps_in, irreps_in2=irreps_in)
z = tp(x, x)# 可选：编译张量积运算
tp_pt2 = torch.compile(tp, fullgraph=True)
z_pt2 = tp_pt2(x, x)  # 注意：由于编译过程，前几次调用可能较慢
torch.testing.assert_close(z, z_pt2)

安装指南

重要提示：请先安装PyTorch，再执行以下命令

pip install --upgrade pip
pip install --upgrade e3nn

详细安装说明和可选依赖项请参阅INSTALL.md文件

版本变更说明

e3nn目前处于开发阶段。建议使用pip安装。主分支被视为不稳定版本。当代码发生破坏性变更时，次版本号会递增。

版本号格式：
0.(破坏性变更时递增).(兼容性更新时递增)

---

第1章：不可约表示(Irreps)

欢迎来到e3nn的精彩世界🐻‍❄️

这个库能帮助我们构建对三维空间中物体行为"有认知"的神经网络，特别是在物体旋转或反射时。

• 想象训练一个神经网络来理解分子。

• 当你旋转一个分子时，它仍然是同一个分子！

• 真正智能的网络应该能识别这一点，而无需展示所有可能的旋转。

这种特性被称为**等变性**，而e3nn使之成为可能。

e3nn的核心是一个称为不可约表示(简称Irreps)的基本概念。

• 可以将Irreps视为标签，告诉e3nn你的数据代表哪种物理量。

• 这个标签至关重要，因为它决定了当三维世界旋转或反射时，数据应如何表现。

让我们从一个简单例子开始。假设你有一个球的两条信息：

1. 温度：这是一个单一数字。旋转球时，其温度(比如在中心点)不会改变。
2. 位置处的风向和风速：这是一个矢量，既有大小又有方向。旋转球时，风矢量会随之改变旋转。

温度(标量)和风(矢量)在旋转下的表现不同。e3nn需要知道这种差异来构建等变神经网络。这正是Irreps提供的功能

什么是Irrep(单数)？

一个Irrep(发音为"ear-rep")描述一种基本的信息"类型"或"类别"，是最小的构建模块。

每个Irrep由两个关键属性定义：

1. l(角动量/阶数)：这是一个非负整数(0,1,2,…)

   • l=0：表示标量。如温度示例，标量是旋转坐标系时不变的单一数字。
   • l=1：表示矢量。如风示例，矢量有方向和大小，会随物体旋转。
   • l=2及以上：表示更复杂的量，有时称为张量或多极子，在旋转下以特定方式变换。

   阶数为l的Irrep维度总是2l + 1。因此标量(l=0)维度为1，矢量(l=1)维度为3。

2. p(宇称)：取值为+1(偶，记作’e’)或-1(奇，记作’o’)。宇称描述数据在反射(如镜面反射)时的行为：

   • 偶宇称(e)：反射后数据保持不变。标量温度(0e)具有偶宇称。
   • 奇宇称(o)：反射后数据符号或方向翻转。矢量(1o)具有奇宇称——如果反射一个指向右侧的矢量，它将指向左侧(其分量符号翻转)。

e3nn使用简洁的字符串表示法。例如：

• 0e：偶宇称标量(l=0)
• 1o：奇宇称矢量(l=1)，这是表示3D矢量的标准方式
• 2e：偶宇称张量(l=2)

可以在e3nn中这样创建Irrep对象：

from e3nn.o3 import Irrep# 标量(l=0, 偶宇称)
scalar_irrep = Irrep("0e")
print(f"标量Irrep: {scalar_irrep}, l={scalar_irrep.l}, p={scalar_irrep.p}, 维度={scalar_irrep.dim}")# 矢量(l=1, 奇宇称)
vector_irrep = Irrep("1o")
print(f"矢量Irrep: {vector_irrep}, l={vector_irrep.l}, p={vector_irrep.p}, 维度={vector_irrep.dim}")

输出：

标量Irrep: 0e, l=0, p=1, 维度=1
矢量Irrep: 1o, l=1, p=-1, 维度=3

什么是Irreps(复数)？

现实世界的数据通常不是单一标量或矢量，而是不同类型信息的组合。

例如空间中的一个点可能同时具有温度(标量)和速度(矢量)。

这时就需要Irreps(复数)。Irreps对象描述多个Irrep类型的集合或直和，就像是复杂数据结构的配方。

Irreps的字符串表示法组合了单个Irrep字符串，通常带有"多重性"数字表示特定Irrep类型出现的次数：

• 1x0e：一个标量(单实例时1x可省略)
• 2x0e：两个独立标量
• 0e + 1o：一个标量和一个矢量
• 3x0e + 5x1o + 2x2e： 三个标量、五个矢量和两个l=2偶宇称张量

创建Irreps对象的方式：

from e3nn.o3 import Irreps# 一个标量和一个矢量的组合
my_irreps = Irreps("0e + 1o")
print(f"我的Irreps: {my_irreps}")
print(f"总维度: {my_irreps.dim}")# 更复杂的组合
complex_irreps = Irreps("2x0e + 1x1o + 1x2e")
print(f"复杂Irreps: {complex_irreps}")
print(f"总维度: {complex_irreps.dim}")

输出：

我的Irreps: 1x0e+1x1o
总维度: 4
复杂Irreps: 2x0e+1x1o+1x2e
总维度: 9

注意complex_irreps的总维度计算为：
(2 * (2*0 + 1))(两个0e标量) +
(1 * (2*1 + 1))(一个1o矢量) +
(1 * (2*2 + 1))(一个2e张量) =
(2 * 1) + (1 * 3) + (1 * 5) = 2 + 3 + 5 = 10。

e3nn如何使用Irreps

Irreps对象本质上是数据在e3nn神经网络中流动的蓝图。

当在e3nn中定义层时，需要指定其输入和输出的Irreps。

以下是e3nnREADME中的示例：

import torch
from e3nn import o3# 定义输入数据的Irreps：一个标量和一个矢量的组合
irreps_in = o3.Irreps("0e + 1o")
print(f"输入Irreps: {irreps_in}")# 创建符合这些Irreps的随机输入数据
x = irreps_in.randn(10, -1) # 10个样本，-1会被替换为irreps_in.dim(4)
print(f"输入数据形状: {x.shape}")# 定义输出数据的Irreps：两个标量和两个矢量的组合
irreps_out = o3.Irreps("2x0e + 2x1o")
print(f"输出Irreps: {irreps_out}")# 创建将'irreps_in'数据转换为'irreps_out'数据的线性层
# e3nn确保该层保持旋转/反射等变性
linear = o3.Linear(irreps_in=irreps_in, irreps_out=irreps_out)
print(f"创建的线性层: {linear}")# 将线性层应用于输入数据
y = linear(x)
print(f"输出数据形状: {y.shape}")

输出：

输入Irreps: 1x0e+1x1o
输入数据形状: torch.Size([10, 4])
输出Irreps: 2x0e+2x1o
创建的线性层: Linear(1x0e+1x1o -> 2x0e+2x1o)
输出数据形状: torch.Size([10, 8])

注意o3.Linear以irreps_in和irreps_out为参数。

这告诉层如何解释其输入以及应产生何种输出，同时保持等变性。

内部机制：Irreps的结构

快速了解e3nn如何存储这些Irrep和Irreps对象：

classDiagramdirection LRclass Irrep {+int l+int p+dim: int}class _MulIr {+int mul+Irrep ir+dim: int}class Irreps {+tuple[tuple] internal_structure+dim: int+num_irreps: int}Irreps "1" * "0..*" _MulIr_MulIr "1" * "1" Irrepnote for Irrep: 表示单个不可约表示(如1o)note for _MulIr: 将多重性与Irrep结合(如2x0e)note for Irreps: _MulIr对象的集合(直和)(如2x0e+1x1o)

1. Irrep：存储为包含(l, p)的简单tuple。例如Irrep("1o")内部是(1, -1)，其dim属性计算为2l+1。
2. _MulIr：另一个简单tuple，包含(多重性, Irrep_object)。所以2x0e会是(2, Irrep(0, 1))，其dim计算为多重性 * Irrep_object.dim。
3. Irreps：_MulIr对象的tuple。当给出字符串如Irreps("2x0e + 1x1o")时，它会解析字符串，创建_MulIr(2, Irrep(0, 1))和_MulIr(1, Irrep(1, -1))，并将它们存储在元组中。其dim属性是所有_MulIr组件维度的总和。

当要求Irreps对象提供其变换矩阵(如通过irreps.D_from_matrix(R))时，e3nn会为每个单独的Irrep计算变换矩阵(使用称为wigner_D的函数，我们将在下一章详细介绍)，然后将它们组合成一个大的块对角矩阵。这种块对角结构意味着每种Irrep类型独立变换，这是不可约表示的关键特性。

Irrep与Irreps快速对比

特性	Irrep(单数)	Irreps(复数)
概念	单一基本的数据变换类型	多个Irrep类型的集合或"直和"
属性	l(阶数)和p(宇称)	(多重性, Irrep)对的列表
示例	0e(标量), 1o(矢量)	2x0e + 1o(两个标量和一个矢量)
维度	2l + 1	所有组件的多重性 * (2l + 1)之和
用途	定义单个组件	定义e3nn中数据的整体结构

结论

本章中，我们了解到Irreps是e3nn中描述数据(如标量或矢量)在旋转和反射下行为的基本"标签"。这种理解对于构建等变神经网络至关重要，这些网络本质上尊重3D空间的对称性。我们学习了如何创建Irrep和Irreps对象，以及e3nn如何使用它们来定义其层的输入和输出类型。

下一章中，我们将深入探讨这些Irreps如何通过球谐函数在3D空间中数学表示，这些函数是表达这些旋转和反射场的"基"。

第2章：球谐函数

---

e3nn 概述

e3nn 是一个用于构建欧几里得等变神经网络（E(3)-equivariant neural networks）的 Python 库，能够自动保持三维旋转和反射的对称性。

该库通过不可约表示（Irreps）描述数据变换方式，利用球谐函数处理方向性数据，并提供专门的等变神经网络模块。

核心功能

基于不可约表示的数据描述系统

• 使用 Irreps 定义数据类型（如标量 0e、矢量 1o）
• 支持组合多种数据类型（如 "0e + 1o" 表示标量和矢量组合）

基础数学运算

• 张量积运算
• 球谐函数处理

神经网络组件

• 等变线性层
• 归一化策略
• TorchScript JIT 支持

应用示例:

• 分子性质预测
• 3D 点云处理

前文传送：[GICP] 点云数据结构 | 点云配准 | KD树 | 常见树状搜索结构

安装与版本

• 安装简单，但需先安装 PyTorch
• 该库使用版本号 0.X.Y 格式，次版本号递增表示破坏性变更