{"id":22914926,"url":"https://github.com/esa/torchquad","last_synced_at":"2025-05-15T20:05:11.318Z","repository":{"id":37399435,"uuid":"310539496","full_name":"esa/torchquad","owner":"esa","description":"Numerical integration in arbitrary dimensions on the GPU using PyTorch / TF / JAX","archived":false,"fork":false,"pushed_at":"2024-11-25T17:31:02.000Z","size":1990,"stargazers_count":203,"open_issues_count":18,"forks_count":41,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-03T04:38:34.662Z","etag":null,"topics":["automatic-differentiation","gpu","high-performance-computing","integration","machine-learning","monte-carlo-integration","multidimensional-integration","numerical-integration","python","pytorch","torchquad","vegas","vegas-enhanced"],"latest_commit_sha":null,"homepage":"https://www.esa.int/gsp/ACT/open_source/torchquad/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/esa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-11-06T08:38:43.000Z","updated_at":"2025-04-27T03:07:04.000Z","dependencies_parsed_at":"2023-10-16T18:37:10.786Z","dependency_job_id":"57c6f99b-0350-442c-8188-5ccc3502c369","html_url":"https://github.com/esa/torchquad","commit_stats":{"total_commits":514,"total_committers":12,"mean_commits":"42.833333333333336","dds":0.6186770428015564,"last_synced_commit":"76c4a2475342628294d43f29fd2c5b6e15728792"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esa%2Ftorchquad","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esa%2Ftorchquad/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esa%2Ftorchquad/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esa%2Ftorchquad/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/esa","download_url":"https://codeload.github.com/esa/torchquad/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254057695,"owners_count":22007544,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automatic-differentiation","gpu","high-performance-computing","integration","machine-learning","monte-carlo-integration","multidimensional-integration","numerical-integration","python","pytorch","torchquad","vegas","vegas-enhanced"],"created_at":"2024-12-14T05:17:53.626Z","updated_at":"2025-05-15T20:05:03.976Z","avatar_url":"https://github.com/esa.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# torchquad\n\u003c!--\n*** Based on https://github.com/othneildrew/Best-README-Template\n--\u003e\n\n![Read the Docs (version)](https://img.shields.io/readthedocs/torchquad/main?style=flat-square) [![Tests](https://github.com/esa/torchquad/actions/workflows/run_tests.yml/badge.svg)](https://github.com/esa/torchquad/actions/workflows/run_tests.yml) ![GitHub last commit](https://img.shields.io/github/last-commit/esa/torchquad?style=flat-square)\n![GitHub](https://img.shields.io/github/license/esa/torchquad?style=flat-square) ![Conda (channel only)](https://img.shields.io/conda/vn/conda-forge/torchquad?style=flat-square) ![PyPI](https://img.shields.io/pypi/v/torchquad?style=flat-square) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/torchquad?style=flat-square)\n\n![GitHub contributors](https://img.shields.io/github/contributors/esa/torchquad?style=flat-square)\n![GitHub issues](https://img.shields.io/github/issues/esa/torchquad?style=flat-square) ![GitHub pull requests](https://img.shields.io/github/issues-pr/esa/torchquad?style=flat-square)\n![Conda](https://img.shields.io/conda/dn/conda-forge/torchquad?style=flat-square) ![PyPI - Downloads](https://img.shields.io/pypi/dm/torchquad?style=flat-square)\n[![JOSS](https://joss.theoj.org/papers/d6f22f83f1a889ddf83b3c2e0cd0919c/status.svg)](https://joss.theoj.org/papers/d6f22f83f1a889ddf83b3c2e0cd0919c?style=flat-square)\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/esa/torchquad\"\u003e\n    \u003cimg src=\"logos/torchquad_white_background_PNG.png\" alt=\"Logo\" width=\"280\" height=\"120\"\u003e\n  \u003c/a\u003e\n  \u003cp align=\"center\"\u003e\n    High-performance numerical integration on the GPU with PyTorch, JAX and Tensorflow\n    \u003cbr /\u003e\n    \u003ca href=\"https://torchquad.readthedocs.io\"\u003e\u003cstrong\u003eExplore the docs »\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/esa/torchquad/issues\"\u003eReport Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/esa/torchquad/issues\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003cdetails open=\"open\"\u003e\n  \u003csummary\u003eTable of Contents\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e\n      \u003ca href=\"#about-the-project\"\u003eAbout The Project\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#built-with\"\u003eBuilt With\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#goals\"\u003eGoals\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#getting-started\"\u003eGetting Started\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#prerequisites\"\u003ePrerequisites\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#test\"\u003eTest\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#roadmap\"\u003eRoadmap\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#FAQ\"\u003eFAQ\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contact\"\u003eContact\u003c/a\u003e\u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/details\u003e\n\n\n\n\u003c!-- ABOUT THE PROJECT --\u003e\n## About The Project\n\nThe torchquad module allows utilizing GPUs for efficient numerical integration with [PyTorch](https://pytorch.org/) and other numerical Python3 modules.\nThe software is free to use and is designed for the machine learning community and research groups focusing on topics requiring high-dimensional integration.\n\n### Built With\n\nThis project is built with the following packages:\n\n* [autoray](https://github.com/jcmgray/autoray), which means the implemented quadrature supports [NumPy](https://numpy.org/) and can be used for machine learning with modules such as [PyTorch](https://pytorch.org/), [JAX](https://github.com/google/jax/) and [Tensorflow](https://www.tensorflow.org/), where it is fully differentiable\n* [conda](https://docs.conda.io/en/latest/), which will take care of all requirements for you\n\n\nIf torchquad proves useful to you, please consider citing the [accompanying paper](https://joss.theoj.org/papers/10.21105/joss.03439).\n\n\u003c!-- GOALS --\u003e\n## Goals\n\n\n* **Supporting science**:  Multidimensional numerical integration is needed in many fields, such as physics (from particle physics to astrophysics), in applied finance, in medical statistics, and others. torchquad aims to assist research groups in such fields, as well as the general machine learning community.\n* **Withstanding the curse of dimensionality**: The [curse of dimensionality](https://en.wikipedia.org/wiki/Curse_of_dimensionality) makes deterministic methods in particular, but also stochastic ones, computationally expensive when the dimensionality increases. However, many integration methods are [embarrassingly parallel](https://en.wikipedia.org/wiki/Embarrassingly_parallel), which means they can strongly benefit from GPU parallelization. The curse of dimensionality still applies but the improved scaling alleviates the computational impact.\n* **Delivering a convenient and functional tool**: torchquad is built with autoray, which means it is [fully differentiable](https://en.wikipedia.org/wiki/Differentiable_programming) if the user chooses, for example, PyTorch as the numerical backend. Furthermore, the library of available and upcoming methods in torchquad offers high-effeciency integration for any need.\n\n\n\u003c!-- GETTING STARTED --\u003e\n## Getting Started\n\nThis is a brief guide for how to set up torchquad.\n\n### Prerequisites\n\nWe recommend using [conda](https://anaconda.org/conda-forge/torchquad), especially if you want to utilize the GPU.\nWith PyTorch it will automatically set up CUDA and the cudatoolkit for you, for example.\nNote that torchquad also works on the CPU; however, it is optimized for GPU usage. torchquad's GPU support is tested only on NVIDIA cards with CUDA. We are investigating future support for AMD cards through [ROCm](https://pytorch.org/blog/pytorch-for-amd-rocm-platform-now-available-as-python-package/).\n\nFor a detailed list of required packages and packages for numerical backends,\nplease refer to the conda environment files [environment.yml](/environment.yml) and [environment_all_backends.yml](/environment_all_backends.yml).\ntorchquad has been tested with JAX 0.2.25, NumPy 1.19.5, PyTorch 1.10.0 and Tensorflow 2.7.0 on Linux; other versions of the backends should work as well but some may require additional setup on other platforms such as Windows.\n\n\n### Installation\n\nThe easiest way to install torchquad is simply to\n   ```sh\n   conda install torchquad -c conda-forge\n   ```\n\nAlternatively, it is also possible to use\n   ```sh\n   pip install torchquad\n   ```\n\nThe PyTorch backend with CUDA support can be installed with\n   ```sh\n   conda install \"cudatoolkit\u003e=11.1\" \"pytorch\u003e=1.9=*cuda*\" -c conda-forge -c pytorch\n   ```\n\nNote that since PyTorch is not yet on *conda-forge* for Windows, we have explicitly included it here using `-c pytorch`.\nNote also that installing PyTorch with *pip* may **not** set it up with CUDA support. Therefore, we recommend to use *conda*.\n\nHere are installation instructions for other numerical backends:\n   ```sh\n   conda install \"tensorflow\u003e=2.6.0=cuda*\" -c conda-forge\n   pip install \"jax[cuda]\u003e=0.4.17\" --find-links https://storage.googleapis.com/jax-releases/jax_cuda_releases.html # linux only\n   conda install \"numpy\u003e=1.19.5\" -c conda-forge\n   ```\n\nMore installation instructions for numerical backends can be found in\n[environment_all_backends.yml](/environment_all_backends.yml) and at the\nbackend documentations, for example\nhttps://pytorch.org/get-started/locally/,\nhttps://github.com/google/jax/#installation and\nhttps://www.tensorflow.org/install/gpu, and often there are multiple ways to\ninstall them.\n\n\n### Test\n\nAfter installing `torchquad` and PyTorch through `conda` or `pip`,\nusers can test `torchquad`'s correct installation with:\n\n```py\nimport torchquad\ntorchquad._deployment_test()\n```\n\nAfter cloning the repository, developers can check the functionality of `torchquad` by running the following command in the `torchquad/tests` directory:\n\n```sh\npytest\n```\n\n\u003c!-- USAGE EXAMPLES --\u003e\n## Usage\n\nThis is a brief example how torchquad can be used to compute a simple integral with PyTorch. For a more thorough introduction please refer to the [tutorial](https://torchquad.readthedocs.io/en/main/tutorial.html) section in the documentation.\n\nThe full documentation can be found on [readthedocs](https://torchquad.readthedocs.io/en/main/).\n\n```Python3\n# To avoid copying things to GPU memory,\n# ideally allocate everything in torch on the GPU\n# and avoid non-torch function calls\nimport torch\nfrom torchquad import MonteCarlo, set_up_backend\n\n# Enable GPU support if available and set the floating point precision\nset_up_backend(\"torch\", data_type=\"float32\")\n\n# The function we want to integrate, in this example\n# f(x0,x1) = sin(x0) + e^x1 for x0=[0,1] and x1=[-1,1]\n# Note that the function needs to support multiple evaluations at once (first\n# dimension of x here)\n# Expected result here is ~3.2698\ndef some_function(x):\n    return torch.sin(x[:, 0]) + torch.exp(x[:, 1])\n\n# Declare an integrator;\n# here we use the simple, stochastic Monte Carlo integration method\nmc = MonteCarlo()\n\n# Compute the function integral by sampling 10000 points over domain\nintegral_value = mc.integrate(\n    some_function,\n    dim=2,\n    N=10000,\n    integration_domain=[[0, 1], [-1, 1]],\n    backend=\"torch\",\n)\n```\nTo change the logger verbosity, set the `TORCHQUAD_LOG_LEVEL` environment\nvariable; for example `export TORCHQUAD_LOG_LEVEL=DEBUG`.\n\nYou can find all available integrators [here](https://torchquad.readthedocs.io/en/main/integration_methods.html).\n\n\u003c!-- ROADMAP --\u003e\n## Roadmap\n\nSee the [open issues](https://github.com/esa/torchquad/issues) for a list of proposed features (and known issues).\n\n\n\u003c!-- PERFORMANCE --\u003e\n## Performance\n\nUsing GPUs torchquad scales particularly well with integration methods that offer easy parallelization. For example, below you see error and runtime results for integrating the function `f(x,y,z) = sin(x * (y+1)²) * (z+1)` on a consumer-grade desktop PC.\n\n![](https://github.com/esa/torchquad/blob/main/resources/torchquad_runtime.png?raw=true)\n*Runtime results of the integration. Note the far superior scaling on the GPU (solid line) in comparison to the CPU (dashed and dotted) for both methods.*\n\n![](https://github.com/esa/torchquad/blob/main/resources/torchquad_convergence.png?raw=true)\n*Convergence results of the integration. Note that Simpson quickly reaches floating point precision. Monte Carlo is not competitive here given the low dimensionality of the problem.*\n\n\u003c!-- CONTRIBUTING --\u003e\n## Contributing\n\nThe project is open to community contributions. Feel free to open an [issue](https://github.com/esa/torchquad/issues) or write us an email if you would like to discuss a problem or idea first.\n\nIf you want to contribute, please\n\n1. Fork the project on [GitHub](https://github.com/esa/torchquad).\n2. Get the most up-to-date code by following this quick guide for installing torchquad from source:\n     1. Get [miniconda](https://docs.conda.io/en/latest/miniconda.html) or similar\n     2. Clone the repo\n      ```sh\n      git clone https://github.com/esa/torchquad.git\n      ```\n     3. With the default configuration, all numerical backends with CUDA\n       support are installed.\n       If this should not happen, comment out unwanted packages in\n       `environment_all_backends.yml`.\n     4. Set up the environment. This creates a conda environment called\n      `torchquad` and installs the required dependencies.\n      ```sh\n      conda env create -f environment_all_backends.yml\n      conda activate torchquad\n      ```\n\nOnce the installation is done, you are ready to contribute.\nPlease note that PRs should be created from and into the `develop` branch. For each release the develop branch is merged into main.\n\n3. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n4. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n5. Push to the Branch (`git push origin feature/AmazingFeature`)\n6. Open a Pull Request on the `develop` branch, *not* `main` (NB: We autoformat every PR with black. Our GitHub actions may create additional commits on your PR for that reason.)\n\nand we will have a look at your contribution as soon as we can.\n\nFurthermore, please make sure that your PR passes all automated tests. Review will only happen after that.\nOnly PRs created on the `develop` branch with all tests passing will be considered. The only exception to this rule is if you want to update the documentation in relation to the current release on conda / pip. In that case you may ask to merge directly into `main`.\n\n\u003c!-- LICENSE --\u003e\n## License\n\nDistributed under the GPL-3.0 License. See [LICENSE](https://github.com/esa/torchquad/blob/main/LICENSE) for more information.\n\n\n\u003c!-- FAQ --\u003e\n## FAQ\n\n  1. Q: `Error enabling CUDA. cuda.is_available() returned False. CPU will be used.`  \u003cbr/\u003eA: This error indicates that PyTorch could not find a CUDA-compatible GPU. Either you have no compatible GPU or the necessary CUDA requirements are missing. Using `conda`, you can install them with `conda install cudatoolkit`. For more detailed installation instructions, please refer to the [PyTorch documentation](https://pytorch.org/get-started/locally/).\n\n\n\n\n\u003c!-- CONTACT --\u003e\n## Contact\n\nCreated by ESA's [Advanced Concepts Team](https://www.esa.int/gsp/ACT/index.html)\n\n- Pablo Gómez - `pablo.gomez at esa.int`\n- Gabriele Meoni - `gabriele.meoni at esa.int`\n- Håvard Hem Toftevaag\n\nProject Link: [https://github.com/esa/torchquad](https://github.com/esa/torchquad)\n\n\n\n\u003c!-- ACKNOWLEDGEMENTS\nThis README was based on https://github.com/othneildrew/Best-README-Template\n--\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesa%2Ftorchquad","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesa%2Ftorchquad","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesa%2Ftorchquad/lists"}