Blame doc/montecarlo.rst

Packit 67cb25
.. index::
Packit 67cb25
   single: Monte Carlo integration
Packit 67cb25
   single: stratified sampling in Monte Carlo integration
Packit 67cb25
   single: multidimensional integration
Packit 67cb25
Packit 67cb25
***********************
Packit 67cb25
Monte Carlo Integration
Packit 67cb25
***********************
Packit 67cb25
Packit 67cb25
This chapter describes routines for multidimensional Monte Carlo
Packit 67cb25
integration.  These include the traditional Monte Carlo method and
Packit 67cb25
adaptive algorithms such as VEGAS and MISER which use
Packit 67cb25
importance sampling and stratified sampling techniques. Each algorithm
Packit 67cb25
computes an estimate of a multidimensional definite integral of the
Packit 67cb25
form,
Packit 67cb25
Packit 67cb25
.. math:: I = \int_{x_l}^{x_u} dx \int_{y_l}^{y_u} dy ... f(x, y, ...)
Packit 67cb25
Packit 67cb25
over a hypercubic region :math:`((x_l,x_u)`, :math:`(y_l,y_u), ...)` using
Packit 67cb25
a fixed number of function calls.  The routines also provide a
Packit 67cb25
statistical estimate of the error on the result.  This error estimate
Packit 67cb25
should be taken as a guide rather than as a strict error bound---random 
Packit 67cb25
sampling of the region may not uncover all the important features
Packit 67cb25
of the function, resulting in an underestimate of the error.
Packit 67cb25
Packit 67cb25
The functions are defined in separate header files for each routine,
Packit 67cb25
:file:`gsl_monte_plain.h`, :file:`gsl_monte_miser.h` and
Packit 67cb25
:file:`gsl_monte_vegas.h`.
Packit 67cb25
Packit 67cb25
Interface
Packit 67cb25
=========
Packit 67cb25
Packit 67cb25
All of the Monte Carlo integration routines use the same general form of
Packit 67cb25
interface.  There is an allocator to allocate memory for control
Packit 67cb25
variables and workspace, a routine to initialize those control
Packit 67cb25
variables, the integrator itself, and a function to free the space when
Packit 67cb25
done.
Packit 67cb25
Packit 67cb25
Each integration function requires a random number generator to be
Packit 67cb25
supplied, and returns an estimate of the integral and its standard
Packit 67cb25
deviation.  The accuracy of the result is determined by the number of
Packit 67cb25
function calls specified by the user.  If a known level of accuracy is
Packit 67cb25
required this can be achieved by calling the integrator several times
Packit 67cb25
and averaging the individual results until the desired accuracy is
Packit 67cb25
obtained.  
Packit 67cb25
Packit 67cb25
Random sample points used within the Monte Carlo routines are always
Packit 67cb25
chosen strictly within the integration region, so that endpoint
Packit 67cb25
singularities are automatically avoided.
Packit 67cb25
Packit 67cb25
The function to be integrated has its own datatype, defined in the
Packit 67cb25
header file :file:`gsl_monte.h`.
Packit 67cb25
Packit 67cb25
.. type:: gsl_monte_function 
Packit 67cb25
Packit 67cb25
   This data type defines a general function with parameters for Monte
Packit 67cb25
   Carlo integration.
Packit 67cb25
Packit 67cb25
   ============================================================ ==========================================
Packit 67cb25
   :code:`double (* f) (double * x, size_t dim, void * params)` this function should return the value
Packit 67cb25
                                                                :math:`f(x,params)` for the argument
Packit 67cb25
                                                                :data:`x` and parameters :data:`params`,
Packit 67cb25
                                                                where :data:`x` is an array of size
Packit 67cb25
                                                                :data:`dim` giving the coordinates of the
Packit 67cb25
                                                                point where the function is to be
Packit 67cb25
                                                                evaluated.
Packit 67cb25
Packit 67cb25
   :code:`size_t dim`                                           the number of dimensions for :data:`x`.
Packit 67cb25
   :code:`void * params`                                        a pointer to the parameters of the
Packit 67cb25
                                                                function.
Packit 67cb25
   ============================================================ ==========================================
Packit 67cb25
Packit 67cb25
Here is an example for a quadratic function in two dimensions,
Packit 67cb25
Packit 67cb25
.. math:: f(x,y) = a x^2 + b x y + c y^2
Packit 67cb25
Packit 67cb25
with :math:`a = 3`, :math:`b = 2`, :math:`c = 1`.  The following code
Packit 67cb25
defines a :type:`gsl_monte_function` :code:`F` which you could pass to an
Packit 67cb25
integrator::
Packit 67cb25
Packit 67cb25
  struct my_f_params { double a; double b; double c; };
Packit 67cb25
Packit 67cb25
  double
Packit 67cb25
  my_f (double x[], size_t dim, void * p) {
Packit 67cb25
     struct my_f_params * fp = (struct my_f_params *)p;
Packit 67cb25
Packit 67cb25
     if (dim != 2)
Packit 67cb25
        {
Packit 67cb25
          fprintf (stderr, "error: dim != 2");
Packit 67cb25
          abort ();
Packit 67cb25
        }
Packit 67cb25
Packit 67cb25
     return  fp->a * x[0] * x[0] 
Packit 67cb25
               + fp->b * x[0] * x[1] 
Packit 67cb25
                 + fp->c * x[1] * x[1];
Packit 67cb25
  }
Packit 67cb25
Packit 67cb25
  gsl_monte_function F;
Packit 67cb25
  struct my_f_params params = { 3.0, 2.0, 1.0 };
Packit 67cb25
Packit 67cb25
  F.f = &my_f;
Packit 67cb25
  F.dim = 2;
Packit 67cb25
  F.params = ¶m;;
Packit 67cb25
Packit 67cb25
The function :math:`f(x)` can be evaluated using the following macro::
Packit 67cb25
Packit 67cb25
  #define GSL_MONTE_FN_EVAL(F,x) 
Packit 67cb25
      (*((F)->f))(x,(F)->dim,(F)->params)
Packit 67cb25
Packit 67cb25
.. index:: plain Monte Carlo
Packit 67cb25
Packit 67cb25
PLAIN Monte Carlo
Packit 67cb25
=================
Packit 67cb25
Packit 67cb25
The plain Monte Carlo algorithm samples points randomly from the
Packit 67cb25
integration region to estimate the integral and its error.  Using this
Packit 67cb25
algorithm the estimate of the integral :math:`E(f; N)` for :math:`N`
Packit 67cb25
randomly distributed points :math:`x_i` is given by,
Packit 67cb25
Packit 67cb25
.. only:: not texinfo
Packit 67cb25
Packit 67cb25
   .. math:: E(f; N) =  V \langle f \rangle = {V \over N} \sum_i^N f(x_i)
Packit 67cb25
Packit 67cb25
.. only:: texinfo
Packit 67cb25
Packit 67cb25
   ::
Packit 67cb25
Packit 67cb25
      E(f; N) = =  V <f> = (V / N) \sum_i^N f(x_i)
Packit 67cb25
Packit 67cb25
where :math:`V` is the volume of the integration region.  The error on
Packit 67cb25
this estimate :math:`\sigma(E;N)` is calculated from the estimated
Packit 67cb25
variance of the mean,
Packit 67cb25
Packit 67cb25
.. only:: not texinfo
Packit 67cb25
Packit 67cb25
   .. math:: \sigma^2 (E; N) = {V^2 \over N^2 } \sum_i^N (f(x_i) - \langle f \rangle)^2.
Packit 67cb25
Packit 67cb25
.. only:: texinfo
Packit 67cb25
Packit 67cb25
   ::
Packit 67cb25
Packit 67cb25
      \sigma^2 (E; N) = (V^2 / N^2) \sum_i^N (f(x_i) -  <f>)^2.
Packit 67cb25
Packit 67cb25
For large :math:`N` this variance decreases asymptotically as
Packit 67cb25
:math:`\Var(f)/N`, where :math:`\Var(f)` is the true variance of the
Packit 67cb25
function over the integration region.  The error estimate itself should
Packit 67cb25
decrease as :math:`\sigma(f)/\sqrt{N}`.
Packit 67cb25
The familiar law of errors
Packit 67cb25
decreasing as :math:`1/\sqrt{N}`
Packit 67cb25
applies---to reduce the error by a
Packit 67cb25
factor of 10 requires a 100-fold increase in the number of sample
Packit 67cb25
points.
Packit 67cb25
Packit 67cb25
The functions described in this section are declared in the header file
Packit 67cb25
:file:`gsl_monte_plain.h`.
Packit 67cb25
Packit 67cb25
.. type:: gsl_monte_plain_state
Packit 67cb25
Packit 67cb25
   This is a workspace for plain Monte Carlo integration
Packit 67cb25
Packit 67cb25
.. function:: gsl_monte_plain_state * gsl_monte_plain_alloc (size_t dim)
Packit 67cb25
Packit 67cb25
   This function allocates and initializes a workspace for Monte Carlo
Packit 67cb25
   integration in :data:`dim` dimensions.  
Packit 67cb25
Packit 67cb25
.. function:: int gsl_monte_plain_init (gsl_monte_plain_state* s)
Packit 67cb25
Packit 67cb25
   This function initializes a previously allocated integration state.
Packit 67cb25
   This allows an existing workspace to be reused for different
Packit 67cb25
   integrations.
Packit 67cb25
Packit 67cb25
.. function:: int gsl_monte_plain_integrate (gsl_monte_function * f, const double xl[], const double xu[], size_t dim, size_t calls, gsl_rng * r, gsl_monte_plain_state * s, double * result, double * abserr)
Packit 67cb25
Packit 67cb25
   This routines uses the plain Monte Carlo algorithm to integrate the
Packit 67cb25
   function :data:`f` over the :data:`dim`-dimensional hypercubic region
Packit 67cb25
   defined by the lower and upper limits in the arrays :data:`xl` and
Packit 67cb25
   :data:`xu`, each of size :data:`dim`.  The integration uses a fixed number
Packit 67cb25
   of function calls :data:`calls`, and obtains random sampling points using
Packit 67cb25
   the random number generator :data:`r`. A previously allocated workspace
Packit 67cb25
   :data:`s` must be supplied.  The result of the integration is returned in
Packit 67cb25
   :data:`result`, with an estimated absolute error :data:`abserr`.
Packit 67cb25
Packit 67cb25
.. function:: void gsl_monte_plain_free (gsl_monte_plain_state * s)
Packit 67cb25
Packit 67cb25
   This function frees the memory associated with the integrator state
Packit 67cb25
   :data:`s`.
Packit 67cb25
Packit 67cb25
.. index::
Packit 67cb25
   single: MISER monte carlo integration
Packit 67cb25
   single: recursive stratified sampling, MISER
Packit 67cb25
Packit 67cb25
MISER
Packit 67cb25
=====
Packit 67cb25
Packit 67cb25
The MISER algorithm of Press and Farrar is based on recursive
Packit 67cb25
stratified sampling.  This technique aims to reduce the overall
Packit 67cb25
integration error by concentrating integration points in the regions of
Packit 67cb25
highest variance.
Packit 67cb25
Packit 67cb25
The idea of stratified sampling begins with the observation that for two
Packit 67cb25
disjoint regions :math:`a` and :math:`b` with Monte Carlo estimates of the
Packit 67cb25
integral :math:`E_a(f)` and :math:`E_b(f)` and variances
Packit 67cb25
:math:`\sigma_a^2(f)` and :math:`\sigma_b^2(f)`, the variance
Packit 67cb25
:math:`\Var(f)` of the combined estimate 
Packit 67cb25
:math:`E(f) = {1\over 2} (E_a(f) + E_b(f))`
Packit 67cb25
is given by,
Packit 67cb25
Packit 67cb25
.. only:: not texinfo
Packit 67cb25
Packit 67cb25
   .. math:: \Var(f) = {\sigma_a^2(f) \over 4 N_a} + {\sigma_b^2(f) \over 4 N_b}.
Packit 67cb25
Packit 67cb25
.. only:: texinfo
Packit 67cb25
Packit 67cb25
   ::
Packit 67cb25
Packit 67cb25
      \Var(f) = (\sigma_a^2(f) / 4 N_a) + (\sigma_b^2(f) / 4 N_b).
Packit 67cb25
Packit 67cb25
It can be shown that this variance is minimized by distributing the
Packit 67cb25
points such that,
Packit 67cb25
Packit 67cb25
.. only:: not texinfo
Packit 67cb25
Packit 67cb25
   .. math:: {N_a \over N_a+N_b} = {\sigma_a \over \sigma_a + \sigma_b}.
Packit 67cb25
Packit 67cb25
.. only:: texinfo
Packit 67cb25
Packit 67cb25
   ::
Packit 67cb25
Packit 67cb25
      N_a / (N_a + N_b) = \sigma_a / (\sigma_a + \sigma_b).
Packit 67cb25
Packit 67cb25
Hence the smallest error estimate is obtained by allocating sample
Packit 67cb25
points in proportion to the standard deviation of the function in each
Packit 67cb25
sub-region.
Packit 67cb25
Packit 67cb25
The MISER algorithm proceeds by bisecting the integration region
Packit 67cb25
along one coordinate axis to give two sub-regions at each step.  The
Packit 67cb25
direction is chosen by examining all :math:`d` possible bisections and
Packit 67cb25
selecting the one which will minimize the combined variance of the two
Packit 67cb25
sub-regions.  The variance in the sub-regions is estimated by sampling
Packit 67cb25
with a fraction of the total number of points available to the current
Packit 67cb25
step.  The same procedure is then repeated recursively for each of the
Packit 67cb25
two half-spaces from the best bisection. The remaining sample points are
Packit 67cb25
allocated to the sub-regions using the formula for :math:`N_a` and
Packit 67cb25
:math:`N_b`.  This recursive allocation of integration points continues
Packit 67cb25
down to a user-specified depth where each sub-region is integrated using
Packit 67cb25
a plain Monte Carlo estimate.  These individual values and their error
Packit 67cb25
estimates are then combined upwards to give an overall result and an
Packit 67cb25
estimate of its error.
Packit 67cb25
Packit 67cb25
The functions described in this section are declared in the header file
Packit 67cb25
:file:`gsl_monte_miser.h`.
Packit 67cb25
Packit 67cb25
.. type:: gsl_monte_miser_state
Packit 67cb25
Packit 67cb25
   This workspace is used for MISER Monte Carlo integration
Packit 67cb25
Packit 67cb25
.. function:: gsl_monte_miser_state * gsl_monte_miser_alloc (size_t dim)
Packit 67cb25
Packit 67cb25
   This function allocates and initializes a workspace for Monte Carlo
Packit 67cb25
   integration in :data:`dim` dimensions.  The workspace is used to maintain
Packit 67cb25
   the state of the integration.
Packit 67cb25
Packit 67cb25
.. function:: int gsl_monte_miser_init (gsl_monte_miser_state* s)
Packit 67cb25
Packit 67cb25
   This function initializes a previously allocated integration state.
Packit 67cb25
   This allows an existing workspace to be reused for different
Packit 67cb25
   integrations.
Packit 67cb25
Packit 67cb25
.. function:: int gsl_monte_miser_integrate (gsl_monte_function * f, const double xl[], const double xu[], size_t dim, size_t calls, gsl_rng * r, gsl_monte_miser_state * s, double * result, double * abserr)
Packit 67cb25
Packit 67cb25
   This routines uses the MISER Monte Carlo algorithm to integrate the
Packit 67cb25
   function :data:`f` over the :data:`dim`-dimensional hypercubic region
Packit 67cb25
   defined by the lower and upper limits in the arrays :data:`xl` and
Packit 67cb25
   :data:`xu`, each of size :data:`dim`.  The integration uses a fixed number
Packit 67cb25
   of function calls :data:`calls`, and obtains random sampling points using
Packit 67cb25
   the random number generator :data:`r`. A previously allocated workspace
Packit 67cb25
   :data:`s` must be supplied.  The result of the integration is returned in
Packit 67cb25
   :data:`result`, with an estimated absolute error :data:`abserr`.
Packit 67cb25
Packit 67cb25
.. function:: void gsl_monte_miser_free (gsl_monte_miser_state * s)
Packit 67cb25
Packit 67cb25
   This function frees the memory associated with the integrator state
Packit 67cb25
   :data:`s`.
Packit 67cb25
Packit 67cb25
The MISER algorithm has several configurable parameters which can
Packit 67cb25
be changed using the following two functions [#f1]_.
Packit 67cb25
Packit 67cb25
.. function:: void gsl_monte_miser_params_get (const gsl_monte_miser_state * s, gsl_monte_miser_params * params) 
Packit 67cb25
Packit 67cb25
   This function copies the parameters of the integrator state into the
Packit 67cb25
   user-supplied :data:`params` structure.
Packit 67cb25
Packit 67cb25
.. function:: void gsl_monte_miser_params_set (gsl_monte_miser_state * s, const gsl_monte_miser_params * params)
Packit 67cb25
Packit 67cb25
   This function sets the integrator parameters based on values provided
Packit 67cb25
   in the :data:`params` structure.
Packit 67cb25
Packit 67cb25
Typically the values of the parameters are first read using
Packit 67cb25
:func:`gsl_monte_miser_params_get`, the necessary changes are made to
Packit 67cb25
the fields of the :data:`params` structure, and the values are copied
Packit 67cb25
back into the integrator state using
Packit 67cb25
:func:`gsl_monte_miser_params_set`.  The functions use the
Packit 67cb25
:type:`gsl_monte_miser_params` structure which contains the following
Packit 67cb25
fields:
Packit 67cb25
Packit 67cb25
.. type:: gsl_monte_miser_params
Packit 67cb25
Packit 67cb25
   .. var:: double estimate_frac
Packit 67cb25
Packit 67cb25
      This parameter specifies the fraction of the currently available number of
Packit 67cb25
      function calls which are allocated to estimating the variance at each
Packit 67cb25
      recursive step. The default value is 0.1.
Packit 67cb25
Packit 67cb25
   .. var:: size_t min_calls
Packit 67cb25
Packit 67cb25
      This parameter specifies the minimum number of function calls required
Packit 67cb25
      for each estimate of the variance. If the number of function calls
Packit 67cb25
      allocated to the estimate using :data:`estimate_frac` falls below
Packit 67cb25
      :data:`min_calls` then :data:`min_calls` are used instead.  This ensures
Packit 67cb25
      that each estimate maintains a reasonable level of accuracy.  The
Packit 67cb25
      default value of :data:`min_calls` is :code:`16 * dim`.
Packit 67cb25
Packit 67cb25
   .. var:: size_t min_calls_per_bisection
Packit 67cb25
Packit 67cb25
      This parameter specifies the minimum number of function calls required
Packit 67cb25
      to proceed with a bisection step.  When a recursive step has fewer calls
Packit 67cb25
      available than :data:`min_calls_per_bisection` it performs a plain Monte
Packit 67cb25
      Carlo estimate of the current sub-region and terminates its branch of
Packit 67cb25
      the recursion.  The default value of this parameter is :code:`32 * min_calls`.
Packit 67cb25
Packit 67cb25
   .. var:: double alpha
Packit 67cb25
Packit 67cb25
      This parameter controls how the estimated variances for the two
Packit 67cb25
      sub-regions of a bisection are combined when allocating points.  With
Packit 67cb25
      recursive sampling the overall variance should scale better than
Packit 67cb25
      :math:`1/N`, since the values from the sub-regions will be obtained using
Packit 67cb25
      a procedure which explicitly minimizes their variance.  To accommodate
Packit 67cb25
      this behavior the MISER algorithm allows the total variance to
Packit 67cb25
      depend on a scaling parameter :math:`\alpha`,
Packit 67cb25
Packit 67cb25
      .. only:: not texinfo
Packit 67cb25
Packit 67cb25
         .. math:: \Var(f) = {\sigma_a \over N_a^\alpha} + {\sigma_b \over N_b^\alpha}.
Packit 67cb25
Packit 67cb25
      .. only:: texinfo
Packit 67cb25
Packit 67cb25
         ::
Packit 67cb25
Packit 67cb25
            \Var(f) = {\sigma_a \over N_a^\alpha} + {\sigma_b \over N_b^\alpha}.
Packit 67cb25
Packit 67cb25
      The authors of the original paper describing MISER recommend the
Packit 67cb25
      value :math:`\alpha = 2` as a good choice, obtained from numerical
Packit 67cb25
      experiments, and this is used as the default value in this
Packit 67cb25
      implementation.
Packit 67cb25
Packit 67cb25
   .. var:: double dither
Packit 67cb25
Packit 67cb25
      This parameter introduces a random fractional variation of size
Packit 67cb25
      :data:`dither` into each bisection, which can be used to break the
Packit 67cb25
      symmetry of integrands which are concentrated near the exact center of
Packit 67cb25
      the hypercubic integration region.  The default value of dither is zero,
Packit 67cb25
      so no variation is introduced. If needed, a typical value of
Packit 67cb25
      :data:`dither` is 0.1.
Packit 67cb25
Packit 67cb25
.. index::
Packit 67cb25
   single: VEGAS Monte Carlo integration
Packit 67cb25
   single: importance sampling, VEGAS
Packit 67cb25
Packit 67cb25
VEGAS
Packit 67cb25
=====
Packit 67cb25
Packit 67cb25
The VEGAS algorithm of Lepage is based on importance sampling.  It
Packit 67cb25
samples points from the probability distribution described by the
Packit 67cb25
function :math:`|f|`, so that the points are concentrated in the regions
Packit 67cb25
that make the largest contribution to the integral.
Packit 67cb25
Packit 67cb25
In general, if the Monte Carlo integral of :math:`f` is sampled with
Packit 67cb25
points distributed according to a probability distribution described by
Packit 67cb25
the function :math:`g`, we obtain an estimate :math:`E_g(f; N)`,
Packit 67cb25
Packit 67cb25
.. math:: E_g(f; N) = E(f/g; N)
Packit 67cb25
Packit 67cb25
with a corresponding variance,
Packit 67cb25
Packit 67cb25
.. math:: \Var_g(f; N) = \Var(f/g; N)
Packit 67cb25
Packit 67cb25
If the probability distribution is chosen as :math:`g = |f|/I(|f|)` then
Packit 67cb25
it can be shown that the variance :math:`V_g(f; N)` vanishes, and the
Packit 67cb25
error in the estimate will be zero.  In practice it is not possible to
Packit 67cb25
sample from the exact distribution :math:`g` for an arbitrary function, so
Packit 67cb25
importance sampling algorithms aim to produce efficient approximations
Packit 67cb25
to the desired distribution.
Packit 67cb25
Packit 67cb25
The VEGAS algorithm approximates the exact distribution by making a
Packit 67cb25
number of passes over the integration region while histogramming the
Packit 67cb25
function :math:`f`. Each histogram is used to define a sampling
Packit 67cb25
distribution for the next pass.  Asymptotically this procedure converges
Packit 67cb25
to the desired distribution. In order
Packit 67cb25
to avoid the number of histogram bins growing like :math:`K^d` the
Packit 67cb25
probability distribution is approximated by a separable function:
Packit 67cb25
:math:`g(x_1, x_2, \ldots) = g_1(x_1) g_2(x_2) \ldots`
Packit 67cb25
so that the number of bins required is only :math:`Kd`.     
Packit 67cb25
This is equivalent to locating the peaks of the function from the
Packit 67cb25
projections of the integrand onto the coordinate axes.  The efficiency
Packit 67cb25
of VEGAS depends on the validity of this assumption.  It is most
Packit 67cb25
efficient when the peaks of the integrand are well-localized.  If an
Packit 67cb25
integrand can be rewritten in a form which is approximately separable
Packit 67cb25
this will increase the efficiency of integration with VEGAS.
Packit 67cb25
Packit 67cb25
VEGAS incorporates a number of additional features, and combines both
Packit 67cb25
stratified sampling and importance sampling.  The integration region is
Packit 67cb25
divided into a number of "boxes", with each box getting a fixed
Packit 67cb25
number of points (the goal is 2).  Each box can then have a fractional
Packit 67cb25
number of bins, but if the ratio of bins-per-box is less than two, Vegas switches to a
Packit 67cb25
kind variance reduction (rather than importance sampling).
Packit 67cb25
Packit 67cb25
.. type:: gsl_monte_vegas_state
Packit 67cb25
Packit 67cb25
   This workspace is used for VEGAS Monte Carlo integration
Packit 67cb25
Packit 67cb25
.. function:: gsl_monte_vegas_state * gsl_monte_vegas_alloc (size_t dim)
Packit 67cb25
Packit 67cb25
   This function allocates and initializes a workspace for Monte Carlo
Packit 67cb25
   integration in :data:`dim` dimensions.  The workspace is used to maintain
Packit 67cb25
   the state of the integration.
Packit 67cb25
Packit 67cb25
.. function:: int gsl_monte_vegas_init (gsl_monte_vegas_state* s)
Packit 67cb25
Packit 67cb25
   This function initializes a previously allocated integration state.
Packit 67cb25
   This allows an existing workspace to be reused for different
Packit 67cb25
   integrations.
Packit 67cb25
Packit 67cb25
.. function:: int gsl_monte_vegas_integrate (gsl_monte_function * f, double xl[], double xu[], size_t dim, size_t calls, gsl_rng * r, gsl_monte_vegas_state * s, double * result, double * abserr)
Packit 67cb25
Packit 67cb25
   This routines uses the VEGAS Monte Carlo algorithm to integrate the
Packit 67cb25
   function :data:`f` over the :data:`dim`-dimensional hypercubic region
Packit 67cb25
   defined by the lower and upper limits in the arrays :data:`xl` and
Packit 67cb25
   :data:`xu`, each of size :data:`dim`.  The integration uses a fixed number
Packit 67cb25
   of function calls :data:`calls`, and obtains random sampling points using
Packit 67cb25
   the random number generator :data:`r`. A previously allocated workspace
Packit 67cb25
   :data:`s` must be supplied.  The result of the integration is returned in
Packit 67cb25
   :data:`result`, with an estimated absolute error :data:`abserr`.  The result
Packit 67cb25
   and its error estimate are based on a weighted average of independent
Packit 67cb25
   samples. The chi-squared per degree of freedom for the weighted average
Packit 67cb25
   is returned via the state struct component, :code:`s->chisq`, and must be
Packit 67cb25
   consistent with 1 for the weighted average to be reliable.
Packit 67cb25
Packit 67cb25
.. function:: void gsl_monte_vegas_free (gsl_monte_vegas_state * s)
Packit 67cb25
Packit 67cb25
   This function frees the memory associated with the integrator state
Packit 67cb25
   :data:`s`.
Packit 67cb25
Packit 67cb25
The VEGAS algorithm computes a number of independent estimates of the
Packit 67cb25
integral internally, according to the :code:`iterations` parameter
Packit 67cb25
described below, and returns their weighted average.  Random sampling of
Packit 67cb25
the integrand can occasionally produce an estimate where the error is
Packit 67cb25
zero, particularly if the function is constant in some regions. An
Packit 67cb25
estimate with zero error causes the weighted average to break down and
Packit 67cb25
must be handled separately. In the original Fortran implementations of
Packit 67cb25
VEGAS the error estimate is made non-zero by substituting a small
Packit 67cb25
value (typically :code:`1e-30`).  The implementation in GSL differs from
Packit 67cb25
this and avoids the use of an arbitrary constant---it either assigns
Packit 67cb25
the value a weight which is the average weight of the preceding
Packit 67cb25
estimates or discards it according to the following procedure,
Packit 67cb25
Packit 67cb25
* current estimate has zero error, weighted average has finite error
Packit 67cb25
Packit 67cb25
  The current estimate is assigned a weight which is the average weight of
Packit 67cb25
  the preceding estimates.
Packit 67cb25
Packit 67cb25
* current estimate has finite error, previous estimates had zero error
Packit 67cb25
Packit 67cb25
  The previous estimates are discarded and the weighted averaging
Packit 67cb25
  procedure begins with the current estimate.
Packit 67cb25
Packit 67cb25
* current estimate has zero error, previous estimates had zero error
Packit 67cb25
Packit 67cb25
  The estimates are averaged using the arithmetic mean, but no error is computed.
Packit 67cb25
Packit 67cb25
The convergence of the algorithm can be tested using the overall
Packit 67cb25
chi-squared value of the results, which is available from the
Packit 67cb25
following function:
Packit 67cb25
Packit 67cb25
.. function:: double gsl_monte_vegas_chisq (const gsl_monte_vegas_state * s)
Packit 67cb25
Packit 67cb25
   This function returns the chi-squared per degree of freedom for the
Packit 67cb25
   weighted estimate of the integral.  The returned value should be close
Packit 67cb25
   to 1.  A value which differs significantly from 1 indicates that the
Packit 67cb25
   values from different iterations are inconsistent.  In this case the
Packit 67cb25
   weighted error will be under-estimated, and further iterations of the
Packit 67cb25
   algorithm are needed to obtain reliable results.
Packit 67cb25
Packit 67cb25
.. function:: void gsl_monte_vegas_runval (const gsl_monte_vegas_state * s, double * result, double * sigma)
Packit 67cb25
Packit 67cb25
   This function returns the raw (unaveraged) values of the integral
Packit 67cb25
   :data:`result` and its error :data:`sigma` from the most recent iteration
Packit 67cb25
   of the algorithm.
Packit 67cb25
Packit 67cb25
The VEGAS algorithm is highly configurable. Several parameters
Packit 67cb25
can be changed using the following two functions.
Packit 67cb25
Packit 67cb25
.. function:: void gsl_monte_vegas_params_get (const gsl_monte_vegas_state * s, gsl_monte_vegas_params * params) 
Packit 67cb25
Packit 67cb25
   This function copies the parameters of the integrator state into the
Packit 67cb25
   user-supplied :data:`params` structure.
Packit 67cb25
Packit 67cb25
.. function:: void gsl_monte_vegas_params_set (gsl_monte_vegas_state * s, const gsl_monte_vegas_params * params)
Packit 67cb25
Packit 67cb25
   This function sets the integrator parameters based on values provided
Packit 67cb25
   in the :data:`params` structure.
Packit 67cb25
Packit 67cb25
Typically the values of the parameters are first read using
Packit 67cb25
:func:`gsl_monte_vegas_params_get`, the necessary changes are made to
Packit 67cb25
the fields of the :data:`params` structure, and the values are copied
Packit 67cb25
back into the integrator state using
Packit 67cb25
:func:`gsl_monte_vegas_params_set`.  The functions use the
Packit 67cb25
:type:`gsl_monte_vegas_params` structure which contains the following
Packit 67cb25
fields:
Packit 67cb25
Packit 67cb25
.. type:: gsl_monte_vegas_params
Packit 67cb25
Packit 67cb25
   .. var:: double alpha
Packit 67cb25
Packit 67cb25
      The parameter :data:`alpha` controls the stiffness of the rebinning
Packit 67cb25
      algorithm.  It is typically set between one and two. A value of zero
Packit 67cb25
      prevents rebinning of the grid.  The default value is 1.5.
Packit 67cb25
Packit 67cb25
   .. var:: size_t iterations
Packit 67cb25
Packit 67cb25
      The number of iterations to perform for each call to the routine. The
Packit 67cb25
      default value is 5 iterations.
Packit 67cb25
Packit 67cb25
   .. var:: int stage
Packit 67cb25
Packit 67cb25
      Setting this determines the *stage* of the calculation.  Normally,
Packit 67cb25
      :code:`stage = 0` which begins with a new uniform grid and empty weighted
Packit 67cb25
      average.  Calling VEGAS with :code:`stage = 1` retains the grid from the
Packit 67cb25
      previous run but discards the weighted average, so that one can "tune"
Packit 67cb25
      the grid using a relatively small number of points and then do a large
Packit 67cb25
      run with :code:`stage = 1` on the optimized grid.  Setting :code:`stage = 2`
Packit 67cb25
      keeps the grid and the weighted average from the previous run, but
Packit 67cb25
      may increase (or decrease) the number of histogram bins in the grid
Packit 67cb25
      depending on the number of calls available.  Choosing :code:`stage = 3`
Packit 67cb25
      enters at the main loop, so that nothing is changed, and is equivalent
Packit 67cb25
      to performing additional iterations in a previous call.
Packit 67cb25
Packit 67cb25
   .. var:: int mode
Packit 67cb25
Packit 67cb25
      The possible choices are :macro:`GSL_VEGAS_MODE_IMPORTANCE`,
Packit 67cb25
      :macro:`GSL_VEGAS_MODE_STRATIFIED`, :macro:`GSL_VEGAS_MODE_IMPORTANCE_ONLY`.
Packit 67cb25
      This determines whether VEGAS will use importance sampling or
Packit 67cb25
      stratified sampling, or whether it can pick on its own.  In low
Packit 67cb25
      dimensions VEGAS uses strict stratified sampling (more precisely,
Packit 67cb25
      stratified sampling is chosen if there are fewer than 2 bins per box).
Packit 67cb25
Packit 67cb25
   .. var:: int verbose
Packit 67cb25
            FILE * ostream
Packit 67cb25
Packit 67cb25
      These parameters set the level of information printed by VEGAS. All
Packit 67cb25
      information is written to the stream :data:`ostream`.  The default setting
Packit 67cb25
      of :data:`verbose` is :code:`-1`, which turns off all output.  A
Packit 67cb25
      :data:`verbose` value of :code:`0` prints summary information about the
Packit 67cb25
      weighted average and final result, while a value of :code:`1` also
Packit 67cb25
      displays the grid coordinates.  A value of :code:`2` prints information
Packit 67cb25
      from the rebinning procedure for each iteration.
Packit 67cb25
Packit 67cb25
The above fields and the :data:`chisq` value can also be accessed
Packit 67cb25
directly in the :type:`gsl_monte_vegas_state` but such use is
Packit 67cb25
deprecated.
Packit 67cb25
Packit 67cb25
Examples
Packit 67cb25
========
Packit 67cb25
Packit 67cb25
The example program below uses the Monte Carlo routines to estimate the
Packit 67cb25
value of the following 3-dimensional integral from the theory of random
Packit 67cb25
walks,
Packit 67cb25
Packit 67cb25
.. only:: not texinfo
Packit 67cb25
Packit 67cb25
   .. math::
Packit 67cb25
Packit 67cb25
      I = \int_{-\pi}^{+\pi} {dk_x \over 2\pi} 
Packit 67cb25
          \int_{-\pi}^{+\pi} {dk_y \over 2\pi} 
Packit 67cb25
          \int_{-\pi}^{+\pi} {dk_z \over 2\pi} 
Packit 67cb25
           { 1 \over (1 - \cos(k_x)\cos(k_y)\cos(k_z))}.
Packit 67cb25
Packit 67cb25
.. only:: texinfo
Packit 67cb25
Packit 67cb25
   ::
Packit 67cb25
Packit 67cb25
      I = \int_{-pi}^{+pi} {dk_x/(2 pi)} 
Packit 67cb25
          \int_{-pi}^{+pi} {dk_y/(2 pi)} 
Packit 67cb25
          \int_{-pi}^{+pi} {dk_z/(2 pi)} 
Packit 67cb25
           1 / (1 - cos(k_x)cos(k_y)cos(k_z)).
Packit 67cb25
Packit 67cb25
The analytic value of this integral can be shown to be
Packit 67cb25
:math:`I = \Gamma(1/4)^4/(4 \pi^3) = 1.393203929685676859...`.  The integral gives
Packit 67cb25
the mean time spent at the origin by a random walk on a body-centered
Packit 67cb25
cubic lattice in three dimensions.
Packit 67cb25
Packit 67cb25
For simplicity we will compute the integral over the region
Packit 67cb25
:math:`(0,0,0)` to :math:`(\pi,\pi,\pi)` and multiply by 8 to obtain the
Packit 67cb25
full result.  The integral is slowly varying in the middle of the region
Packit 67cb25
but has integrable singularities at the corners :math:`(0,0,0)`,
Packit 67cb25
:math:`(0,\pi,\pi)`, :math:`(\pi,0,\pi)` and :math:`(\pi,\pi,0)`.  The
Packit 67cb25
Monte Carlo routines only select points which are strictly within the
Packit 67cb25
integration region and so no special measures are needed to avoid these
Packit 67cb25
singularities.
Packit 67cb25
Packit 67cb25
.. include:: examples/monte.c
Packit 67cb25
   :code:
Packit 67cb25
Packit 67cb25
With 500,000 function calls the plain Monte Carlo algorithm achieves a
Packit 67cb25
fractional error of 1%.  The estimated error :code:`sigma` is roughly
Packit 67cb25
consistent with the actual error--the computed result differs from
Packit 67cb25
the true result by about 1.4 standard deviations::
Packit 67cb25
Packit 67cb25
  plain ==================
Packit 67cb25
  result =  1.412209
Packit 67cb25
  sigma  =  0.013436
Packit 67cb25
  exact  =  1.393204
Packit 67cb25
  error  =  0.019005 = 1.4 sigma
Packit 67cb25
Packit 67cb25
The MISER algorithm reduces the error by a factor of four, and also
Packit 67cb25
correctly estimates the error::
Packit 67cb25
Packit 67cb25
  miser ==================
Packit 67cb25
  result =  1.391322
Packit 67cb25
  sigma  =  0.003461
Packit 67cb25
  exact  =  1.393204
Packit 67cb25
  error  = -0.001882 = 0.54 sigma
Packit 67cb25
Packit 67cb25
In the case of the VEGAS algorithm the program uses an initial
Packit 67cb25
warm-up run of 10,000 function calls to prepare, or "warm up", the grid.
Packit 67cb25
This is followed by a main run with five iterations of 100,000 function
Packit 67cb25
calls. The chi-squared per degree of freedom for the five iterations are
Packit 67cb25
checked for consistency with 1, and the run is repeated if the results
Packit 67cb25
have not converged. In this case the estimates are consistent on the
Packit 67cb25
first pass::
Packit 67cb25
Packit 67cb25
  vegas warm-up ==================
Packit 67cb25
  result =  1.392673
Packit 67cb25
  sigma  =  0.003410
Packit 67cb25
  exact  =  1.393204
Packit 67cb25
  error  = -0.000531 = 0.16 sigma
Packit 67cb25
  converging...
Packit 67cb25
  result =  1.393281 sigma =  0.000362 chisq/dof = 1.5
Packit 67cb25
  vegas final ==================
Packit 67cb25
  result =  1.393281
Packit 67cb25
  sigma  =  0.000362
Packit 67cb25
  exact  =  1.393204
Packit 67cb25
  error  =  0.000077 = 0.21 sigma
Packit 67cb25
Packit 67cb25
If the value of :code:`chisq` had differed significantly from 1 it would
Packit 67cb25
indicate inconsistent results, with a correspondingly underestimated
Packit 67cb25
error.  The final estimate from VEGAS (using a similar number of
Packit 67cb25
function calls) is significantly more accurate than the other two
Packit 67cb25
algorithms.
Packit 67cb25
Packit 67cb25
References and Further Reading
Packit 67cb25
==============================
Packit 67cb25
Packit 67cb25
The MISER algorithm is described in the following article by Press
Packit 67cb25
and Farrar,
Packit 67cb25
Packit 67cb25
* W.H. Press, G.R. Farrar, *Recursive Stratified Sampling for
Packit 67cb25
  Multidimensional Monte Carlo Integration*,
Packit 67cb25
  Computers in Physics, v4 (1990), pp190--195.
Packit 67cb25
Packit 67cb25
The VEGAS algorithm is described in the following papers,
Packit 67cb25
Packit 67cb25
* G.P. Lepage,
Packit 67cb25
  *A New Algorithm for Adaptive Multidimensional Integration*,
Packit 67cb25
  Journal of Computational Physics 27, 192--203, (1978)
Packit 67cb25
Packit 67cb25
* G.P. Lepage,
Packit 67cb25
  *VEGAS: An Adaptive Multi-dimensional Integration Program*,
Packit 67cb25
  Cornell preprint CLNS 80-447, March 1980
Packit 67cb25
Packit 67cb25
.. rubric:: Footnotes
Packit 67cb25
Packit 67cb25
.. [#f1] The previous method of accessing these fields directly through the
Packit 67cb25
         :type:`gsl_monte_miser_state` struct is now deprecated.