Package: torchquad
torchquadHigh-performance numerical integration on the GPU with PyTorch, JAX and TensorflowExplore the docs »Report Bug·Request FeatureTable of ContentsAbout The ProjectBuilt WithGoalsGetting StartedPrerequisitesInstallationTestUsageRoadmapContributingLicenseFAQContactAbout The ProjectThe torchquad module allows utilizing GPUs for efficient numerical integration withPyTorchand other numerical Python3 modules.
The software is free to use and is designed for the machine learning community and research groups focusing on topics requiring high-dimensional integration.Built WithThis project is built with the following packages:autoray, which means the implemented quadrature supportsNumPyand can be used for machine learning with modules such asPyTorch,JAXandTensorflow, where it is fully differentiableconda, which will take care of all requirements for youIf torchquad proves useful to you, please consider citing theaccompanying paper.GoalsSupporting 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.Withstanding the curse of dimensionality: Thecurse of dimensionalitymakes deterministic methods in particular, but also stochastic ones, computationally expensive when the dimensionality increases. However, many integration methods areembarrassingly parallel, which means they can strongly benefit from GPU parallelization. The curse of dimensionality still applies but the improved scaling alleviates the computational impact.Delivering a convenient and functional tool: torchquad is built with autoray, which means it isfully differentiableif 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.Getting StartedThis is a brief guide for how to set up torchquad.PrerequisitesWe recommend usingconda, especially if you want to utilize the GPU.
With PyTorch it will automatically set up CUDA and the cudatoolkit for you, for example.
Note 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 throughROCm.For a detailed list of required packages and packages for numerical backends,
please refer to the conda environment filesenvironment.ymlandenvironment_all_backends.yml.
torchquad 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.InstallationThe easiest way to install torchquad is simply tocondainstalltorchquad-cconda-forgeAlternatively, it is also possible to usepipinstalltorchquadThe PyTorch backend with CUDA support can be installed withcondainstall"cudatoolkit>=11.1""pytorch>=1.9=*cuda*"-cconda-forge-cpytorchNote that since PyTorch is not yet onconda-forgefor Windows, we have explicitly included it here using-c pytorch.
Note also that installing PyTorch withpipmaynotset it up with CUDA support. Therefore, we recommend to useconda.Here are installation instructions for other numerical backends:condainstall"tensorflow>=2.6.0=cuda*"-cconda-forge
pipinstall"jax[cuda]>=0.2.22"--find-linkshttps://storage.googleapis.com/jax-releases/jax_cuda_releases.html# linux onlycondainstall"numpy>=1.19.5"-cconda-forgeMore installation instructions for numerical backends can be found inenvironment_all_backends.ymland at the
backend documentations, for examplehttps://pytorch.org/get-started/locally/,https://github.com/google/jax/#installationandhttps://www.tensorflow.org/install/gpu, and often there are multiple ways to
install them.TestAfter installingtorchquadand PyTorch throughcondaorpip,
users can testtorchquad's correct installation with:importtorchquadtorchquad._deployment_test()After cloning the repository, developers can check the functionality oftorchquadby running the following command in thetorchquad/testsdirectory:pytestUsageThis is a brief example how torchquad can be used to compute a simple integral with PyTorch. For a more thorough introduction please refer to thetutorialsection in the documentation.The full documentation can be found onreadthedocs.# To avoid copying things to GPU memory,# ideally allocate everything in torch on the GPU# and avoid non-torch function callsimporttorchfromtorchquadimportMonteCarlo,set_up_backend# Enable GPU support if available and set the floating point precisionset_up_backend("torch",data_type="float32")# The function we want to integrate, in this example# f(x0,x1) = sin(x0) + e^x1 for x0=[0,1] and x1=[-1,1]# Note that the function needs to support multiple evaluations at once (first# dimension of x here)# Expected result here is ~3.2698defsome_function(x):returntorch.sin(x[:,0])+torch.exp(x[:,1])# Declare an integrator;# here we use the simple, stochastic Monte Carlo integration methodmc=MonteCarlo()# Compute the function integral by sampling 10000 points over domainintegral_value=mc.integrate(some_function,dim=2,N=10000,integration_domain=[[0,1],[-1,1]],backend="torch",)To change the logger verbosity, set theTORCHQUAD_LOG_LEVELenvironment
variable; for exampleexport TORCHQUAD_LOG_LEVEL=DEBUG.You can find all available integratorshere.RoadmapSee theopen issuesfor a list of proposed features (and known issues).PerformanceUsing GPUs torchquad scales particularly well with integration methods that offer easy parallelization. For example, below you see error and runtime results for integrating the functionf(x,y,z) = sin(x * (y+1)²) * (z+1)on a consumer-grade desktop PC.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.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.ContributingThe project is open to community contributions. Feel free to open anissueor write us an email if you would like to discuss a problem or idea first.If you want to contribute, pleaseFork the project onGitHub.Get the most up-to-date code by following this quick guide for installing torchquad from source:Getminicondaor similarClone the repogitclonehttps://github.com/esa/torchquad.gitWith the default configuration, all numerical backends with CUDA
support are installed.
If this should not happen, comment out unwanted packages inenvironment_all_backends.yml.Set up the environment. This creates a conda environment calledtorchquadand installs the required dependencies.condaenvcreate-fenvironment_all_backends.yml
condaactivatetorchquadOnce the installation is done, you are ready to contribute.
Please note that PRs should be created from and into thedevelopbranch. For each release the develop branch is merged into main.Create your Feature Branch (git checkout -b feature/AmazingFeature)Commit your Changes (git commit -m 'Add some AmazingFeature')Push to the Branch (git push origin feature/AmazingFeature)Open a Pull Request on thedevelopbranch,notmain(NB: We autoformat every PR with black. Our GitHub actions may create additional commits on your PR for that reason.)and we will have a look at your contribution as soon as we can.Furthermore, please make sure that your PR passes all automated tests. Review will only happen after that.
Only PRs created on thedevelopbranch 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 intomain.LicenseDistributed under the GPL-3.0 License. SeeLICENSEfor more information.FAQQ:Error enabling CUDA. cuda.is_available() returned False. CPU will be used.A: 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. Usingconda, you can install them withconda install cudatoolkit. For more detailed installation instructions, please refer to thePyTorch documentation.ContactCreated by ESA'sAdvanced Concepts TeamPablo Gómez -pablo.gomez at esa.intGabriele Meoni -gabriele.meoni at esa.intHåvard Hem ToftevaagProject Link:https://github.com/esa/torchquad