This package provides tools for estimating multidimensional integrals numerically using an enhanced version of the adaptive Monte Carlo vegas algorithm (G. P. Lepage, J. Comput. Phys. 27(1978) 192).
A vegas code generally involves two objects, one representing the integrand and the other representing an integration operator for a particular multidimensional volume. A typical code sequence for a D-dimensional integral has the structure:
# create the integrand
def f(x):
... compute the integrand at point x[d] d=0,1...D-1
...
# create an integrator for volume with
# xl0 <= x[0] <= xu0, xl1 <= x[1] <= xu1 ...
integration_region = [[xl0, xu0], [xl1, xu1], ...]
integrator = vegas.Integrator(integration_region)
# do the integral and print out the result
result = integrator(f, nitn=10, neval=10000)
print(result)
The algorithm iteratively adapts to the integrand over nitn iterations, each of which uses at most neval integrand samples to generate a Monte Carlo estimate of the integral. The final result is the weighted average of the results fom all iterations.
The integrator remembers how it adapted to f(x) and uses this information as its starting point if it is reapplied to f(x) or applied to some other function g(x). An integrator’s state can be archived for future applications using Python’s pickle module.
See the extensive Tutorial in the first section of the vegas documentation.
The central component of the vegas package is the integrator class:
Adaptive multidimensional Monte Carlo integration.
vegas.Integrator objects make Monte Carlo estimates of multidimensional functions f(x) where x[d] is a point in the integration volume:
integ = vegas.Integrator(integration_region)
result = integ(f, nitn=10, neval=10000)
The integator makes nitn estimates of the integral, each using at most neval samples of the integrand, as it adapts to the specific features of the integrand. Successive estimates typically improve in accuracy until the integrator has fully adapted. The integrator returns the weighted average of all nitn estimates, together with an estimate of the statistical (Monte Carlo) uncertainty in that estimate of the integral. The result is an object of type RunningWAvg (which is derived from gvar.GVar).
Parameters: |
|
---|
vegas.Integrator objects have attributes for each of these parameters. In addition they have the following methods:
Reset default parameters in integrator.
Usage is analogous to the constructor for vegas.Integrator: for example,
old_defaults = integ.set(neval=1e6, nitn=20)
resets the default values for neval and nitn in vegas.Integrator integ. A dictionary, here old_defaults, is returned. It can be used to restore the old defaults using, for example:
integ.set(old_defaults)
Assemble summary of integrator settings into string.
Parameters: | ngrid (int) – Number of grid nodes in each direction to include in summary. The default is 0. |
---|---|
Returns: | String containing the settings. |
vegas’s remapping of the integration variables is handled by a vegas.AdaptiveMap object, which maps the original integration variables x into new variables y in a unit hypercube. Each direction has its own map specified by a grid in x space:
where and
are the limits of integration.
The grid specifies the transformation function at the points
for
:
Linear interpolation is used between those points. The Jacobian for this transformation is:
vegas adjusts the increments sizes to optimize its Monte Carlo estimates of the integral. This involves training the grid. To illustrate how this is done with vegas.AdaptiveMaps consider a simple two dimensional integral over a unit hypercube with integrand:
def f(x):
return x[0] * x[1] ** 2
We want to create a grid that optimizes uniform Monte Carlo estimates of the integral in y space. We do this by sampling the integrand at a large number ny of random points y[j, d], where j=0...ny-1 and d=0,1, uniformly distributed throughout the integration volume in y space. These samples be used to train the grid using the following code:
import vegas
import numpy as np
def f(x):
return x[0] * x[1] ** 2
m = vegas.AdaptiveMap([[0, 1], [0, 1]], ninc=5)
ny = 1000
y = np.random.uniform(0., 1., (ny, 2)) # 1000 random y's
x = np.empty(y.shape, float) # work space
jac = np.empty(y.shape[0], float)
f2 = np.empty(y.shape[0], float)
print('intial grid:')
print(m.settings())
for itn in range(5): # 5 iterations to adapt
m.map(y, x, jac) # compute x's and jac
for j in range(ny): # compute training data
f2[j] = (jac[j] * f(x[j])) ** 2
m.add_training_data(y, f2) # adapt
m.adapt(alpha=1.5)
print('iteration %d:' % itn)
print(m.settings())
In each of the 5 iterations, the vegas.AdaptiveMap adjusts the map, making increments smaller where f2 is larger and larger where f2 is smaller. The map converges after only 2 or 3 iterations, as is clear from the output:
initial grid:
grid[ 0] = [ 0. 0.2 0.4 0.6 0.8 1. ]
grid[ 1] = [ 0. 0.2 0.4 0.6 0.8 1. ]
iteration 0:
grid[ 0] = [ 0. 0.411 0.618 0.772 0.89 1. ]
grid[ 1] = [ 0. 0.508 0.694 0.822 0.911 1. ]
iteration 1:
grid[ 0] = [ 0. 0.408 0.611 0.76 0.887 1. ]
grid[ 1] = [ 0. 0.542 0.718 0.835 0.922 1. ]
iteration 2:
grid[ 0] = [ 0. 0.411 0.612 0.76 0.887 1. ]
grid[ 1] = [ 0. 0.551 0.721 0.835 0.924 1. ]
iteration 3:
grid[ 0] = [ 0. 0.411 0.612 0.76 0.887 1. ]
grid[ 1] = [ 0. 0.554 0.721 0.836 0.924 1. ]
iteration 4:
grid[ 0] = [ 0. 0.411 0.612 0.76 0.887 1. ]
grid[ 1] = [ 0. 0.555 0.722 0.836 0.925 1. ]
The grid increments along direction 0 shrink at larger values x[0], varying as 1/x[0]. Along direction 1 the increments shrink more quickly varying like 1/x[1]**2.
vegas samples the integrand in order to estimate the integral. It uses those same samples to train its vegas.AdaptiveMap in this fashion, for use in subsequent iterations of the algorithm.
Adaptive map y->x(y) for multidimensional y and x.
An AdaptiveMap defines a multidimensional map y -> x(y) from the unit hypercube, with 0 <= y[d] <= 1, to an arbitrary hypercube in x space. Each direction is mapped independently with a Jacobian that is tunable (i.e., “adaptive”).
The map is specified by a grid in x-space that, by definition, maps into a uniformly spaced grid in y-space. The nodes of the grid are specified by grid[d, i] where d is the direction (d=0,1...dim-1) and i labels the grid point (i=0,1...N). The mapping for a specific point y into x space is:
y[d] -> x[d] = grid[d, i(y[d])] + inc[d, i(y[d])] * delta(y[d])
where i(y)=floor(y*N), delta(y)=y*N - i(y), and inc[d, i] = grid[d, i+1] - grid[d, i]. The Jacobian for this map,
dx[d]/dy[d] = inc[d, i(y[d])] * N,
is piece-wise constant and proportional to the x-space grid spacing. Each increment in the x-space grid maps into an increment of size 1/N in the corresponding y space. So regions in x space where inc[d, i] is small are stretched out in y space, while larger increments are compressed.
The x grid for an AdaptiveMap can be specified explicitly when the map is created: for example,
m = AdaptiveMap([[0, 0.1, 1], [-1, 0, 1]])
creates a two-dimensional map where the x[0] interval (0,0.1) and (0.1,1) map into the y[0] intervals (0,0.5) and (0.5,1) respectively, while x[1] intervals (-1,0) and (0,1) map into y[1] intervals (0,0.5) and (0.5,1).
More typically an initially uniform map is trained with data f[j] corresponding to ny points y[j, d], with j=0...ny-1, uniformly distributed in y space: for example,
m.add_training_data(y, f)
m.adapt(alpha=1.5)
m.adapt(alpha=1.5) shrinks grid increments where f[j] is large, and expands them where f[j] is small. Typically one has to iterate over several sets of ys and fs before the grid has fully adapted.
The speed with which the grid adapts is determined by parameter alpha. Large (positive) values imply rapid adaptation, while small values (much less than one) imply slow adaptation. As in any iterative process, it is usually a good idea to slow adaptation down in order to avoid instabilities.
Parameters: |
|
---|
Number of dimensions.
Number of increments along each grid axis.
The nodes of the grid defining the maps are self.grid[d, i] where d=0... specifies the direction and i=0...self.ninc the node.
The increment widths of the grid:
self.inc[d, i] = self.grid[d, i + 1] - self.grid[d, i]
Adapt grid to accumulated training data.
self.adapt(...) projects the training data onto each axis independently and maps it into x space. It shrinks x-grid increments in regions where the projected training data is large, and grows increments where the projected data is small. The grid along any direction is unchanged if the training data is constant along that direction.
The number of increments along a direction can be changed by setting parameter ninc.
The grid does not change if no training data has been accumulated, unless ninc is specified, in which case the number of increments is adjusted while preserving the relative density of increments at different values of x.
Parameters: |
|
---|
Add training data f for y-space points y.
Accumulates training data for later use by self.adapt(). Grid increments will be made smaller in regions where f is larger than average, and larger where f is smaller than average. The grid is unchanged (converged?) when f is constant across the grid.
Parameters: |
|
---|
Return x values corresponding to y.
y can be a single dim-dimensional point, or it can be an array y[i,j, ..., d] of such points (d=0..dim-1).
Return the map’s Jacobian at y.
y can be a single dim-dimensional point, or it can be an array y[d,i,j,...] of such points (d=0..dim-1).
Replace the grid with a uniform grid.
The new grid has ninc increments along each direction if ninc is specified. Otherwise it has the same number of increments as the old grid.
Map y to x, where jac is the Jacobian.
y[j, d] is an array of ny y-values for direction d. x[j, d] is filled with the corresponding x values, and jac[j] is filled with the corresponding Jacobian values. x and jac must be preallocated: for example,
x = numpy.empty(y.shape, float)
jac = numpy.empty(y.shape[0], float)
Parameters: |
|
---|
Display plots showing the current grid.
Parameters: |
|
---|---|
Nparam axes: | List of pairs of directions to use in different views of the grid. Using None in place of a direction plots the grid for only one direction. Omitting axes causes a default set of pairings to be used. |
Create string with information about grid nodes.
Creates a string containing the locations of the nodes in the map grid for each direction. Parameter ngrid specifies the maximum number of nodes to print (spread evenly over the grid).
Running weighted average of Monte Carlo estimates.
This class accumulates independent Monte Carlo estimates (e.g., of an integral) and combines them into a single weighted average. It is derived from gvar.GVar (from the lsqfit module if it is present) and represents a Gaussian random variable.
The mean value of the weighted average.
The standard deviation of the weighted average.
chi**2 of weighted average.
Number of degrees of freedom in weighted average.
Q or p-value of weighted average’s chi**2.
A list of the results from each iteration.
Add estimate g to the running average.
Assemble summary of independent results into a string.
Base class for classes providing vectorized integrands.
A class derived from vegas.VecInterand should provide a __call__(x, f, nx) member where:
x[i, d] is a contiguous array where i=0...nx-1 labels different integrtion points and d=0... labels different directions in the integration space.
f[i] is a buffer that is filled with the integrand values for points i=0...nx-1.
nx is the number of integration points.
Deriving from vegas.VecIntegrand is the easiest way to construct integrands in Cython, and gives the fastest results.