torchquad

Read the Docs（版本） GitHub 最后提交 GitHub Conda（仅限频道） PyPI PyPI - Python 版本

GitHub 贡献者 GitHub 问题 GitHub 拉取请求 Conda PyPI - 下载量

<a href="https://github.com/esa/torchquad"> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/4ed8b186-2696-4cf7-bb2f-40ce441f5647.png" alt="Logo" width="280" height="120"> </a> 基于PyTorch、JAX和Tensorflow的GPU高性能数值积分 <a href="https://torchquad.readthedocs.io">浏览文档 »</a> <a href="https://github.com/esa/torchquad/issues">报告Bug</a> · <a href="https://github.com/esa/torchquad/issues">请求新功能</a> <details open="open"> <summary>目录</summary> <ol> <li> <a href="#about-the-project">关于项目</a> <ul> <li><a href="#built-with">构建工具</a></li> </ul> </li> <li><a href="#goals">目标</a></li> <li> <a href="#getting-started">入门</a> <ul> <li><a href="#prerequisites">前提条件</a></li> <li><a href="#installation">安装</a></li> <li><a href="#test">测试</a></li> </ul> </li> <li><a href="#usage">使用方法</a></li> <li><a href="#roadmap">路线图</a></li> <li><a href="#contributing">贡献</a></li> <li><a href="#license">许可证</a></li> <li><a href="#FAQ">常见问题</a></li> <li><a href="#contact">联系方式</a></li> </ol> </details>

关于项目

torchquad模块允许利用GPU进行高效的数值积分，支持PyTorch和其他Python3数值计算模块。该软件可免费使用，专为机器学习社区和需要高维积分的研究团队设计。

构建工具

本项目使用以下软件包构建：

autoray，这意味着实现的求积方法支持NumPy，并可用于PyTorch、JAX和Tensorflow等机器学习模块，且完全可微
conda，它将为您处理所有依赖项

如果torchquad对您有用，请考虑引用相关论文。

目标

支持科学研究：多维数值积分在许多领域都有需求，如物理学（从粒子物理到天体物理学）、应用金融、医学统计等。torchquad旨在为这些领域的研究团队以及整个机器学习社区提供支持。
应对维度灾难：维度灾难使得确定性方法，甚至随机方法在维度增加时计算成本昂贵。然而，许多积分方法都是易于并行化的，这意味着它们可以从GPU并行化中获得显著收益。虽然维度灾难仍然存在，但改进的扩展性能够减轻计算影响。
提供便捷实用的工具：torchquad基于autoray构建，这意味着如果用户选择PyTorch作为数值后端，它是完全可微分的。此外，torchquad中现有和即将推出的方法库可以满足任何需求，提供高效的积分计算。

入门指南

这是一个关于如何设置torchquad的简要指南。

先决条件

我们建议使用conda，特别是如果你想利用GPU的话。例如，使用PyTorch时，它会自动为你设置CUDA和cudatoolkit。请注意，torchquad也可以在CPU上运行；然而，它是为GPU使用而优化的。torchquad的GPU支持仅在具有CUDA的NVIDIA显卡上进行测试。我们正在研究通过ROCm为AMD显卡提供未来支持。

关于所需包和数值后端包的详细列表，请参考conda环境文件environment.yml和environment_all_backends.yml。torchquad已在Linux上使用JAX 0.2.25、NumPy 1.19.5、PyTorch 1.10.0和Tensorflow 2.7.0进行测试；其他版本的后端也应该可以工作，但在Windows等其他平台上可能需要额外的设置。

安装

安装torchquad最简单的方法是：

conda install torchquad -c conda-forge

或者，也可以使用：

pip install torchquad

带CUDA支持的PyTorch后端可以通过以下命令安装：

conda install "cudatoolkit>=11.1" "pytorch>=1.9=*cuda*" -c conda-forge -c pytorch

请注意，由于PyTorch在Windows上还没有进入conda-forge，我们在这里明确使用了-c pytorch。还要注意，使用pip安装PyTorch可能不会设置CUDA支持。因此，我们建议使用conda。

以下是其他数值后端的安装说明：

conda install "tensorflow>=2.6.0=cuda*" -c conda-forge
pip install "jax[cuda]>=0.2.22" --find-links https://storage.googleapis.com/jax-releases/jax_cuda_releases.html # 仅限Linux
conda install "numpy>=1.19.5" -c conda-forge

更多数值后端的安装说明可以在environment_all_backends.yml和各后端的文档中找到，例如https://pytorch.org/get-started/locally/、https://github.com/google/jax/#installation和https://www.tensorflow.org/install/gpu，通常有多种安装方式。

测试

通过conda或pip安装torchquad和PyTorch后，用户可以使用以下命令测试torchquad是否正确安装：

import torchquad
torchquad._deployment_test()

克隆仓库后，开发者可以在torchquad/tests目录下运行以下命令来检查torchquad的功能：

pytest

使用示例

这是一个简短的示例，展示如何使用torchquad和PyTorch计算一个简单的积分。如需更详细的介绍，请参阅文档中的教程部分。

完整文档可在readthedocs上找到。

# 为避免将数据复制到GPU内存，
# 理想情况下应在GPU上分配所有torch对象
# 并避免非torch函数调用
import torch
from torchquad import MonteCarlo, set_up_backend

# 启用GPU支持（如果可用）并设置浮点精度
set_up_backend("torch", data_type="float32")

# 我们要积分的函数，在这个例子中
# f(x0,x1) = sin(x0) + e^x1，其中x0=[0,1]，x1=[-1,1]
# 注意该函数需要支持同时进行多次评估（x的第一维）
# 这里的预期结果约为3.2698
def some_function(x):
    return torch.sin(x[:, 0]) + torch.exp(x[:, 1])

# 声明一个积分器；
# 这里我们使用简单的随机蒙特卡洛积分方法
mc = MonteCarlo()

通过在域上采样10000个点来计算函数积分

integral_value = mc.integrate( some_function, dim=2, N=10000, integration_domain=[[0, 1], [-1, 1]], backend="torch", )

要更改日志记录的详细程度，请设置`TORCHQUAD_LOG_LEVEL`环境变量；例如`export TORCHQUAD_LOG_LEVEL=DEBUG`。

您可以在[这里](https://torchquad.readthedocs.io/en/main/integration_methods.html)找到所有可用的积分器。

<!-- 路线图 -->
## 路线图

查看[未解决的问题](https://github.com/esa/torchquad/issues)以了解提议的功能列表（和已知问题）。

<!-- 性能 -->
## 性能

使用GPU，torchquad在易于并行化的积分方法上表现特别出色。例如，下面显示了在消费级台式电脑上积分函数`f(x,y,z) = sin(x * (y+1)²) * (z+1)`的误差和运行时间结果。

![](https://yellow-cdn.veclightyear.com/0a4dffa0/7cb7a19f-62cb-45be-a793-d8ba533d99ee.png?raw=true)
*积分的运行时间结果。注意GPU（实线）相比CPU（虚线和点线）在两种方法上都有更好的扩展性。*

![](https://yellow-cdn.veclightyear.com/0a4dffa0/f91a39c6-205f-467c-9d32-88507177d0ea.png?raw=true)
*积分的收敛结果。注意Simpson方法快速达到浮点精度。由于问题的低维度，蒙特卡洛方法在这里不具有竞争力。*

<!-- 贡献 -->
## 贡献

本项目欢迎社区贡献。如果您想讨论问题或想法，请随时打开[issue](https://github.com/esa/torchquad/issues)或给我们发送电子邮件。

如果您想贡献，请：

1. 在[GitHub](https://github.com/esa/torchquad)上fork项目。
2. 按照以下快速指南从源代码安装torchquad，获取最新代码：
     1. 获取[miniconda](https://docs.conda.io/en/latest/miniconda.html)或类似工具
     2. 克隆仓库
      ```sh
      git clone https://github.com/esa/torchquad.git
      ```
     3. 默认配置下，所有支持CUDA的数值后端都会被安装。
       如果不想这样，请在`environment_all_backends.yml`中注释掉不需要的包。
     4. 设置环境。这将创建一个名为`torchquad`的conda环境并安装所需依赖。
      ```sh
      conda env create -f environment_all_backends.yml
      conda activate torchquad
      ```

安装完成后，您就可以开始贡献了。
请注意，PR应该从`develop`分支创建并合并到`develop`分支。每次发布时，develop分支会被合并到main分支。

3. 创建您的特性分支（`git checkout -b feature/AmazingFeature`）
4. 提交您的更改（`git commit -m 'Add some AmazingFeature'`）
5. 推送到分支（`git push origin feature/AmazingFeature`）
6. 在`develop`分支上打开Pull Request，而不是`main`分支（注意：我们使用black自动格式化每个PR。我们的GitHub Actions可能会在您的PR上创建额外的提交以进行格式化。）

我们会尽快查看您的贡献。

此外，请确保您的PR通过所有自动测试。只有在测试通过后才会进行审核。
只有在`develop`分支上创建并通过所有测试的PR才会被考虑。唯一的例外是如果您想更新与当前conda/pip发布相关的文档。在这种情况下，您可以请求直接合并到`main`分支。

<!-- 许可证 -->
## 许可证

根据GPL-3.0许可证分发。有关更多信息，请参阅[LICENSE](https://github.com/esa/torchquad/blob/main/LICENSE)。

<!-- 常见问题 -->
## 常见问题

  1. 问：`Error enabling CUDA. cuda.is_available() returned False. CPU will be used.`  <br/>答：这个错误表明PyTorch无法找到兼容CUDA的GPU。要么您没有兼容的GPU，要么缺少必要的CUDA要求。使用`conda`，您可以通过`conda install cudatoolkit`安装它们。有关更详细的安装说明，请参阅[PyTorch文档](https://pytorch.org/get-started/locally/)。

<!-- 联系方式 -->
## 联系方式

由欧洲航天局[先进概念团队](https://www.esa.int/gsp/ACT/index.html)创建

- Pablo Gómez - `pablo.gomez at esa.int`
- Gabriele Meoni - `gabriele.meoni at esa.int`
- Håvard Hem Toftevaag

项目链接：[https://github.com/esa/torchquad](https://github.com/esa/torchquad)

<!-- 致谢
本README基于https://github.com/othneildrew/Best-README-Template
-->