Integration methods

This is the list of all available integration methods in torchquad.

We are continuously implementing new methods in our library. For the code behind the integration methods, please see the code page or check out our full code and latest news at https://github.com/esa/torchquad.

Stochastic Methods

Monte Carlo Integrator

class torchquad.MonteCarlo[source]

Monte Carlo integration

integrate(fn, dim, N=1000, integration_domain=None, seed=None, rng=None, backend=None)[source]

Integrates the passed function on the passed domain using vanilla Monte Carlo Integration.

Parameters:
  • fn (func) – The function to integrate over.

  • dim (int) – Dimensionality of the function’s domain over which to integrate.

  • N (int, optional) – Number of sample points to use for the integration. Defaults to 1000.

  • integration_domain (list or backend tensor, optional) – Integration domain, e.g. [[-1,1],[0,1]]. Defaults to [-1,1]^dim. It can also determine the numerical backend.

  • seed (int, optional) – Random number generation seed to the sampling point creation, only set if provided. Defaults to None.

  • rng (RNG, optional) – An initialised RNG; this can be used when compiling the function for Tensorflow

  • backend (string, optional) – Numerical backend. Defaults to integration_domain’s backend if it is a tensor and otherwise to the backend from the latest call to set_up_backend or “torch” for backwards compatibility.

Raises:

ValueError – If len(integration_domain) != dim

Returns:

Integral value

Return type:

backend-specific number

VEGAS Enhanced

class torchquad.VEGAS[source]

VEGAS Enhanced. Refer to https://arxiv.org/abs/2009.05112 . Implementation inspired by https://github.com/ycwu1030/CIGAR/ . EQ <n> refers to equation <n> in the above paper. JAX and Tensorflow are unsupported. For Tensorflow there exists a VEGAS+ implementation called VegasFlow: https://github.com/N3PDF/vegasflow

integrate(fn, dim, N=10000, integration_domain=None, seed=None, rng=None, use_grid_improve=True, eps_rel=0, eps_abs=0, max_iterations=20, use_warmup=True, backend=None)[source]

Integrates the passed function on the passed domain using VEGAS.

If the integrand output is far away from zero, i.e. lies within [b, b+c] for a constant b with large absolute value and small constant c, VEGAS does not adapt well to the integrand. Shifting the integrand so that it is close to zero may improve the accuracy of the calculated integral in this case. This method does not support multi-dimensional/vectorized integrands (i.e., integrating an integrand repeatedly over a grid of points).

Parameters:
  • fn (func) – The function to integrate over.

  • dim (int) – Dimensionality of the function’s domain over which to integrate.

  • N (int, optional) – Approximate maximum number of function evaluations to use for the integration. This value can be exceeded if the vegas stratification distributes evaluations per hypercube very unevenly. Defaults to 10000.

  • integration_domain (list, optional) – Integration domain, e.g. [[-1,1],[0,1]]. Defaults to [-1,1]^dim.

  • seed (int, optional) – Random number generation seed for the sampling point creation; only set if provided. Defaults to None.

  • rng (RNG, optional) – An initialised RNG; this can be used as alternative to the seed argument and to avoid problems with integrand functions which reset PyTorch’s RNG seed.

  • use_grid_improve (bool, optional) – If True, improve the vegas map after each iteration. Defaults to True.

  • eps_rel (float, optional) – Relative error to abort at. Defaults to 0.

  • eps_abs (float, optional) – Absolute error to abort at. Defaults to 0.

  • max_iterations (int, optional) – Maximum number of vegas iterations to perform. The number of performed iterations is usually lower than this value because the number of sample points per iteration increases every fifth iteration. Defaults to 20.

  • use_warmup (bool, optional) – If True, execute a warmup to initialize the vegas map. Defaults to True.

  • backend (string, optional) – Numerical backend. “jax” and “tensorflow” are unsupported. Defaults to integration_domain’s backend if it is a tensor and otherwise to the backend from the latest call to set_up_backend or “torch” for backwards compatibility.

Raises:

ValueError – If the integration_domain or backend argument is invalid

Returns:

Integral value

Return type:

backend-specific float

Deterministic Methods

Boole’s Rule

class torchquad.Boole[source]

Boole’s rule. See https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas#Closed_Newton%E2%80%93Cotes_formulas .

integrate(fn, dim, N=None, integration_domain=None, backend=None)[source]

Integrates the passed function on the passed domain using Boole’s rule.

Parameters:
  • fn (func) – The function to integrate over.

  • dim (int) – Dimensionality of the integration domain.

  • N (int, optional) – Total number of sample points to use for the integration. N has to be such that N^(1/dim) - 1 % 4 == 0. Defaults to 5 points per dimension if None is given.

  • integration_domain (list or backend tensor, optional) – Integration domain, e.g. [[-1,1],[0,1]]. Defaults to [-1,1]^dim. It can also determine the numerical backend.

  • backend (string, optional) – Numerical backend. Defaults to integration_domain’s backend if it is a tensor and otherwise to the backend from the latest call to set_up_backend or “torch” for backwards compatibility.

Returns:

Integral value

Return type:

backend-specific number

Simpson’s Rule

class torchquad.Simpson[source]

Simpson’s rule. See https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas#Closed_Newton%E2%80%93Cotes_formulas .

integrate(fn, dim, N=None, integration_domain=None, backend=None)[source]

Integrates the passed function on the passed domain using Simpson’s rule.

Parameters:
  • fn (func) – The function to integrate over.

  • dim (int) – Dimensionality of the integration domain.

  • N (int, optional) – Total number of sample points to use for the integration. Should be odd. Defaults to 3 points per dimension if None is given.

  • integration_domain (list or backend tensor, optional) – Integration domain, e.g. [[-1,1],[0,1]]. Defaults to [-1,1]^dim. It can also determine the numerical backend.

  • backend (string, optional) – Numerical backend. Defaults to integration_domain’s backend if it is a tensor and otherwise to the backend from the latest call to set_up_backend or “torch” for backwards compatibility.

Returns:

Integral value

Return type:

backend-specific number

Trapezoid Rule

class torchquad.Trapezoid[source]

Trapezoidal rule. See https://en.wikipedia.org/wiki/Newton%E2%80%93Cotes_formulas#Closed_Newton%E2%80%93Cotes_formulas .

integrate(fn, dim, N=1000, integration_domain=None, backend=None)[source]

Integrates the passed function on the passed domain using the trapezoid rule.

Parameters:
  • fn (func) – The function to integrate over.

  • dim (int) – Dimensionality of the function to integrate.

  • N (int, optional) – Total number of sample points to use for the integration. Defaults to 1000.

  • integration_domain (list or backend tensor, optional) – Integration domain, e.g. [[-1,1],[0,1]]. Defaults to [-1,1]^dim. It can also determine the numerical backend.

  • backend (string, optional) – Numerical backend. Defaults to integration_domain’s backend if it is a tensor and otherwise to the backend from the latest call to set_up_backend or “torch” for backwards compatibility.

Returns:

Integral value

Return type:

backend-specific number

Gaussian Quadrature

class torchquad.Gaussian[source]

Base method for Gaussian Quadrature. Different Gaussian methods should inherit from this class, and override as necessary methods. Default behaviour is Gauss-Legendre quadrature on [-1,1] (i.e., this “parent” class should __not__ be used directly with other integration domains, and for this parent class integration_domain as an argument to integrate is ignored internally).

For an example of how to properly override the behavior to acheive different Gaussian Integration methods, please see the Custom Integrators section of the Tutorial or the implementation of GaussLegendre.

The primary methods/attributes of interest to override are _root_fn (for different polynomials, like numpy.polynomial.legendre.leggauss), _apply_composite_rule (as in other integration methods), and _resize_roots (for handling different integration domains).

name

A human-readable name for the integral.

Type:

str

_root_fn

A function that returns roots and weights like numpy.polynomial.legendre.leggauss.

Type:

function

_root_args

a way of adding information to be passed into _root_fn as needed. This is then used when caching roots/weights to potentially distinguish different calls to _root_fn based on arguments.

Type:

tuple

_cache

a cache for roots and weights, used internally.

Type:

dict

_resize_roots(integration_domain, roots)[source]

Resize the roots based on domain of [a,b]. Default behavior is to simply return the roots, unsized by integraton_domain.

Parameters:
  • integration_domain (backend tensor) – domain

  • roots (backend tensor) – polynomial nodes

Returns:

rescaled roots

Return type:

backend tensor

integrate(fn, dim, N=8, integration_domain=None, backend=None)[source]

Integrates the passed function on the passed domain using a Gaussian rule (Gauss-Legendre on [-1,1] as a default).

Parameters:
  • fn (func) – The function to integrate over.

  • dim (int) – Dimensionality of the integration domain.

  • N (int, optional) – Total number of sample points to use for the integration. Should be odd. Defaults to 3 points per dimension if None is given.

  • integration_domain (list or backend tensor, optional) – Integration domain, e.g. [[-1,1],[0,1]]. Defaults to [-1,1]^dim. It also determines the numerical backend if possible.

  • backend (string, optional) – Numerical backend. This argument is ignored if the backend can be inferred from integration_domain. Defaults to the backend from the latest call to set_up_backend or “torch” for backwards compatibility.

Returns:

Integral value

Return type:

backend-specific number

class torchquad.GaussLegendre[source]

Gauss Legendre quadrature rule in torch for any domain [a,b]. See https://en.wikipedia.org/wiki/Gaussian_quadrature#Gauss%E2%80%93Legendre_quadrature.

Examples

>>> gl=torchquad.GaussLegendre()
>>> integral = gl.integrate(lambda x:np.sin(x), dim=1, N=101, integration_domain=[[0,5]]) #integral from 0 to 5 of np.sin(x)
|TQ-INFO| Computed integral was 0.7163378000259399 #analytic result = 1-np.cos(5)
integrate(fn, dim, N=8, integration_domain=None, backend=None)

Integrates the passed function on the passed domain using a Gaussian rule (Gauss-Legendre on [-1,1] as a default).

Parameters:
  • fn (func) – The function to integrate over.

  • dim (int) – Dimensionality of the integration domain.

  • N (int, optional) – Total number of sample points to use for the integration. Should be odd. Defaults to 3 points per dimension if None is given.

  • integration_domain (list or backend tensor, optional) – Integration domain, e.g. [[-1,1],[0,1]]. Defaults to [-1,1]^dim. It also determines the numerical backend if possible.

  • backend (string, optional) – Numerical backend. This argument is ignored if the backend can be inferred from integration_domain. Defaults to the backend from the latest call to set_up_backend or “torch” for backwards compatibility.

Returns:

Integral value

Return type:

backend-specific number