Vegas

=============================
The last (probably) in a series of very minor changes. Here only the
documentation has been changed. There is a new section in the Tutorial
showing how to use multiple CPUs to evaluate costly integrands in parallel.
There is also a new section on how to use vegas to do multi-dimensional sums,
rather than integrals.

Also fixed errors in the documentation for random and random_batch generators.

============================
Another very minor (backwards compatibile) modification. Internally vegas processes
integration points in batches. These were called vectors initially but this name
has proven confusing, especially now that integrands can be array-valued.
To remove the potential confusion, collections of integration points are
now called batches, and: VecIntegrand is now BatchIntegrand; vecintegrand is
now batchintegrand; and nhcube_vec has become nhcube_batch. The old names
are still available, as aliases, to support legacy code.

==========================
This is a very minor upgrade. Missed out a couple of variable declarations
in one of the cython routines that slowed the routine (and vegas) down
significantly (eg, 20%) in some situations. These are now fixed. This
changes nothing other than the run time.

=========================
vegas normally uses weighted averages to combine results from different
iterations. This is important since earlier iterations may have much larger
errors and so should carry less weight in the average. The weighted averages
mean, however, that the integral estimates are biased (see discussion of
systematic error in the Tutorial). The bias is completely negligible compared
to the statistical errors, and so unproblematic, unless the number of
iterations (nitn) is made very large (eg, thousands). vegas does not need to,
and no longer does use weighted averages when parameter adapt=False, because
then different iterations are all the same (since there is no adaptation
going on). Consequently the estimates for the mean and std deviation
are unbiased when adapt=False. This is likely a non-issue for most
and possibly all applications (since the bias vanishes so quickly with
increasing neval --- like 1/neval), but taking unweighted averages is
more correct when adapt=False so that is what vegas does now.

Other changes:

- Added parameter adapt to Integrator, as mentioned above. Setting alpha=False
prevents vegas from adapting any further. See the discussion in the Tutorial.

- RWAvg and RWAvgArray have changed names to RAvg and RAvgArray. The R
stands for "running", since these objects keep a running total. The "W"
used to stand for "weighted" but is inappropriate now since averages
may be weighted or unweighted (depending upon parameter Integrator.adapt).

- Changed the way vegas handles situations where variances
(or diagonal elements of covariance matrices) are negative or otherwise
afflicted by roundoff error. A small positive number is added, scaled by
the mean**2 (roughly 1e-15 * mean**2). This helps vegas survive unusual
situations like a constant integrand (independent of x) without generating
nan's or divide checks.

- Have more robust mechanisms for defining integrands for vegas's vector
mode. Deriving from vegas.VecIntegand but failing to define a __call__
results in an error message (saying there is no __call__). Also there
is now a function decorator, vegas.vecintegrand, that can be applied
to an ordinary function to make it suitable as an integrand.

===========================
Tiny improvement in how vegas interacts with the gvar module. The gvar
module can now be installed by itself, without the rest of the lsqfit
distribution: pip install gvar. Array-valued integrands work much better
with gvar installed.

==========================
This is a significant upgrade and cleanup of the code. As a result
it is not entirely backwards compatible with earlier versions (see below).

- Integrands are allowed to be array-valued now, with different elements
of the array representing different integrands. vegas always tunes on
the first function in the array. vegas determines whether the
integrand is scalar- or array-valued automatically, and returns
results that are either scalar or array-valued, as appropriate.
This functionality replaces method Integrator.multi, and is
implemented quite a bit differently (and better);
Integrator.multi has now disappeared. There is no longer a need for a
separate method for array-valued integrands.

- The calling conventions for integrands in vector mode have been changed
(simplified): eg,

class fv(vegas.VecIntegrand):
def __call__(self, x):
return x[:, 0] ** 2 + x[:, 1] ** 4

See discussion in the tutorial. This is not compatible with the old
convention. The fcntype argument to Integrator is no longer needed.

- Renamed RunningWAvg to RWAvg -- shorter name. Also introduced RWAvgArray
for arrays of same.

- Major reorganization of the internal code to simplify the developer's
life. The code appears to be somewhat faster, though probably not
enough to be noticed by anyone other than the developer.