欧几里得神经网络

文档 | 代码 | 变更日志 | Colab

本库旨在助力 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.(每次不兼容发布时递增).(每次兼容发布时递增)

帮助

我们非常乐意提供帮助！获取 e3nn 支持的最佳方式是提交一个 问题 或 错误报告。

想参与进来吗？太好了！

如果您希望参与并贡献于 e3nn 的开发、改进和应用，请在 讨论区 中自我介绍。

行为准则

我们的社区遵守 贡献者契约行为准则。

引用

如果您在研究中使用了 e3nn，请引用以下论文：

欧几里得神经网络：

• N. Thomas 等人，“张量场网络：用于三维点云的旋转和平移等变神经网络”（2018年）。arXiv:1802.08219
• M. Weiler 等人，“3D 可转向 CNN：学习体积数据中的旋转等变特征”（2018年）。arXiv:1807.02547
• R. Kondor 等人，“克莱布什-高登网络：全傅里叶空间球面卷积神经网络”（2018年）。arXiv:1806.09231

e3nn：

• M. Geiger 和 T. Smidt，“e3nn：欧几里得神经网络”（2022年）。arXiv:2207.09453
• M. Geiger 等人，“欧几里得神经网络：e3nn”（2022年）。Zenodo

BibTeX 条目请参考本仓库中的 CITATION.bib 文件。

版权

欧几里得神经网络（e3nn）版权 © 2020，归加利福尼亚大学董事会所有，经劳伦斯伯克利国家实验室（需获得美国能源部的必要批准）、洛桑联邦理工学院（EPFL）、柏林自由大学以及 Kostiantyn Lapchevskyi 共同拥有。保留所有权利。

如您对使用或分发本软件的权利有任何疑问，请联系伯克利实验室知识产权办公室，邮箱地址为 IPO@lbl.gov。

注意。本软件是在美国能源部资助下开发的，因此美国政府保留某些权利。据此，美国政府及其代表已获授予一项全球范围内、已付清费用、非独占、不可撤销的许可，允许其复制、向公众分发副本、制作衍生作品，并公开表演和展示本软件，同时也有权授权他人行使上述权利。

e3nn 快速上手指南

e3nn 是一个用于开发 E(3) 等变神经网络（Euclidean equivariant neural networks）的 Python 库。它提供了构建旋转和平移等变模型所需的基础数学运算，如张量积（tensor products）和球谐函数（spherical harmonics），特别适用于处理 3D 点云和体素数据。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：建议 Python 3.8 及以上
• 核心依赖：必须预先安装 PyTorch。
  • 请访问 PyTorch 官网 获取适合您环境的安装命令。
  • 国内用户提示：如果下载缓慢，可使用清华源或阿里源加速 PyTorch 安装（例如在 pip 命令后添加 -i https://pypi.tuna.tsinghua.edu.cn/simple）。

安装步骤

重要提示：请务必先安装 PyTorch，然后再安装 e3nn。

1. 升级 pip 工具（推荐）：

   pip install --upgrade pip
   

2. 安装 e3nn：

   pip install --upgrade e3nn
   

   国内加速方案：

   pip install --upgrade e3nn -i https://pypi.tuna.tsinghua.edu.cn/simple
   

注意：e3nn 目前处于活跃开发中，主分支（main）可能不稳定。版本号格式为 0.(不兼容更新).(兼容更新)，建议通过 pip 安装稳定版本。如需更多可选依赖详情，请参考官方 INSTALL.md。

基本使用

以下是最简单的代码示例，演示了如何定义不可约表示（Irreps）、创建线性层以及执行张量积运算。

import torch
from e3nn import o3

# 1. 创建由标量 (0e) 和向量 (1o) 组成的随机输入数组
irreps_in = o3.Irreps("0e + 1o")
x = irreps_in.randn(-1)

# 2. 应用一个线性层
irreps_out = o3.Irreps("2x0e + 2x1o")
linear = o3.Linear(irreps_in=irreps_in, irreps_out=irreps_out)
y = linear(x)

# 3. 计算与自身的张量积
tp = o3.FullTensorProduct(irreps_in1=irreps_in, irreps_in2=irreps_in)
z = tp(x, x)

# 4. (可选) 编译张量积以加速 (基于 torch.compile)
tp_pt2 = torch.compile(tp, fullgraph=True)
z_pt2 = tp_pt2(x, x) # 警告：由于编译原因，前几次调用可能会较慢
torch.testing.assert_close(z, z_pt2)

下一步

• 完整文档：访问 docs.e3nn.org
• 在线体验：尝试官方提供的 Google Colab 示例
• 源码仓库：GitHub - e3nn/e3nn