gsl 1.12.109 → 1.14.5

data/rdoc/min.rdoc

@@ -0,0 +1,189 @@
+#
+# = One dimensional Minimization
+#
+# This chapter describes routines for finding minima of arbitrary 
+# one-dimensional functions.
+#
+#
+# Contents:
+# 1. {Introduction}[link:files/rdoc/min_rdoc.html#1]
+# 1. {GSL::Min::FMinimizer class}[link:files/rdoc/min_rdoc.html#2]
+# 1. {Iteration}[link:files/rdoc/min_rdoc.html#3]
+# 1. {Stopping Parameters}[link:files/rdoc/min_rdoc.html#4]
+# 1. {Examples}[link:files/rdoc/min_rdoc.html#5]
+#
+# == {}[link:index.html"name="1] Introduction
+#
+# The minimization algorithms begin with a bounded region known to contain 
+# a minimum. The region is described by <tt>a</tt> lower bound a and an upper bound 
+# <tt>b</tt>, with an estimate of the location of the minimum <tt>x</tt>.
+#
+# The value of the function at <tt>x</tt> must be less than the value of the 
+# function at the ends of the interval,
+#   f(a) > f(x) < f(b)
+# This condition guarantees that a minimum is contained somewhere within the 
+# interval. On each iteration a new point <tt>x'</tt> is selected using one of the
+# available algorithms. If the new point is a better estimate of the minimum, 
+# <tt>f(x') < f(x)</tt>, then the current estimate of the minimum <tt>x</tt> is 
+# updated. The new point also allows the size of the bounded interval to be 
+# reduced, by choosing the most compact set of points which satisfies the 
+# constraint <tt>f(a) > f(x) < f(b)</tt>. The interval is reduced until it 
+# encloses the true minimum to a desired tolerance. This provides a best 
+# estimate of the location of the minimum and a rigorous error estimate.
+#
+# Several bracketing algorithms are available within a single framework. 
+# The user provides a high-level driver for the algorithm, and the library 
+# provides the individual functions necessary for each of the steps. There 
+# are three main phases of the iteration. The steps are,
+# * initialize minimizer (or <tt>solver</tt>) state, <tt>s</tt>, for algorithm <tt>T</tt>
+# * update <tt>s</tt> using the iteration <tt>T</tt>
+# * test <tt>s</tt> for convergence, and repeat iteration if necessary
+#
+# The state of the minimizers is held in a <tt>GSL::Min::FMinimizer</tt> object. 
+# The updating procedure use only function evaluations (not derivatives).
+# The function to minimize is given as an instance of the {GSL::Function}[link:files/rdoc/function_rdoc.html] class to the minimizer.
+#
+#
+# == {}[link:index.html"name="2] GSL::Min::FMinimizer class
+# ---
+# * GSL::Min::FMinimizer.alloc(t)
+#
+#   These method create an instance of the <tt>GSL::Min::FMinimizer</tt> class of 
+#   type <tt>t</tt>. The type <tt>t</tt> is given by a String,
+#   * "goldensection"
+#   * "brent"
+#   * "quad_golden"
+#   or by a Ruby constant,
+#   * GSL::Min::FMinimizer::GOLDENSECTION
+#   * GSL::Min::FMinimizer::BRENT
+#   * GSL::Min::FMinimizer::QUAD_GOLDEN (GSL-1.13)
+#
+#   ex)
+#       include GSL::Min
+#       s = FMinimizer.alloc(FMinimizer::BRENT)
+#
+# ---
+# * GSL::Min::FMinimizer#set(f, xmin, xlow, xup)
+#
+#   This method sets, or resets, an existing minimizer <tt>self</tt> to use 
+#   the function <tt>f</tt> (given by a <tt>GSL::Function</tt>
+#   object) and the initial search interval [<tt>xlow, xup</tt>], 
+#   with a guess for the location of the minimum <tt>xmin</tt>.
+#
+#   If the interval given does not contain a minimum, then the 
+#   method returns an error code of <tt>GSL::FAILURE</tt>.
+#
+# ---
+# * GSL::Min::FMinimizer#set_with_values(f, xmin, fmin, xlow, flow, xup, fup)
+#
+#   This method is equivalent to <tt>Fminimizer#set</tt> but uses the values 
+#   <tt>fmin, flowe</tt> and <tt>fup</tt> instead of computing 
+#   <tt>f(xmin), f(xlow)</tt> and <tt>f(xup)</tt>.
+#
+# ---
+# * GSL::Min::FMinimizer#name
+#
+#   This returns the name of the minimizer. 
+#
+# == {}[link:index.html"name="3] Iteration
+# ---
+# * GSL::Min::FMinimizer#iterate
+#
+#   This method performs a single iteration of the minimizer <tt>self</tt>. 
+#   If the iteration encounters an unexpected problem then an error code 
+#   will be returned,
+#   * <tt>GSL::EBADFUNC</tt>: the iteration encountered a singular point where the 
+#     function evaluated to <tt>Inf</tt> or <tt>NaN</tt>.
+#   * <tt>GSL::FAILURE</tt>: the algorithm could not improve the current best 
+#     approximation or bounding interval.
+#   The minimizer maintains a current best estimate of the position of 
+#   the minimum at all times, and the current interval bounding the minimum. 
+#   This information can be accessed with the following auxiliary methods
+#
+# ---
+# * GSL::Min::FMinimizer#x_minimum
+#
+#   Returns the current estimate of the position of the minimum 
+#   for the minimizer <tt>self</tt>.
+#
+# ---
+# * GSL::Min::FMinimizer#x_upper
+# * GSL::Min::FMinimizer#x_lower
+#
+#   Return the current upper and lower bound of the interval for the 
+#   minimizer <tt>self</tt>.
+#
+# ---
+# * GSL::Min::FMinimizer#f_minimum
+# * GSL::Min::FMinimizer#f_upper
+# * GSL::Min::FMinimizer#f_lower
+#
+#   Return the value of the function at the current estimate of the 
+#   minimum and at the upper and lower bounds of interval 
+#   for the minimizer <tt>self</tt>.
+#
+# == {}[link:index.html"name="4] Stopping Parameters
+# ---
+# * GSL::Min::FMinimizer#test_interval(epsabs, epsrel)
+# * GSL::Min.test_interval(xlow, xup, epsabs, epsrel)
+#
+#   These methoeds test for the convergence of the interval 
+#   [<tt>xlow, xup</tt>] with absolute error <tt>epsabs</tt> and relative 
+#   error <tt>epsrel</tt>. The test returns <tt>GSL::SUCCESS</tt> 
+#   if the following condition is achieved,
+#     |a - b| < epsabs + epsrel min(|a|,|b|) 
+#   when the interval <tt>x = [a,b]</tt> does not include the origin. 
+#   If the interval includes the origin then <tt>min(|a|,|b|)</tt> is 
+#   replaced by zero (which is the minimum value of |x| over the interval). 
+#   This ensures that the relative error is accurately estimated for minima 
+#   close to the origin.
+#
+#   This condition on the interval also implies that any estimate of the 
+#   minimum x_m in the interval satisfies the same condition with respect 
+#   to the true minimum x_m^*,
+#     |x_m - x_m^*| < epsabs + epsrel x_m^*
+#   assuming that the true minimum x_m^* is contained within the interval.
+#
+# == {}[link:index.html"name="5] Example
+# To find the minimum of the function f(x) = cos(x) + 1.0:
+#
+#      #!/usr/bin/env ruby
+#      require("gsl")
+#      include GSL::Min
+#
+#      fn1 = Function.alloc { |x| Math::cos(x) + 1.0 }
+#
+#      iter = 0;  max_iter = 500
+#      m = 2.0             # initial guess
+#      m_expected = Math::PI
+#      a = 0.0
+#      b = 6.0
+#
+#      gmf = FMinimizer.alloc(FMinimizer::BRENT)
+#      gmf.set(fn1, m, a, b)
+#
+#      printf("using %s method\n", gmf.name)
+#      printf("%5s [%9s, %9s] %9s %10s %9s\n", "iter", "lower", "upper", "min",
+#             "err", "err(est)")
+#
+#      printf("%5d [%.7f, %.7f] %.7f %+.7f %.7f\n", iter, a, b, m, m - m_expected, b - a)
+#
+#      begin
+#        iter += 1
+#        status = gmf.iterate
+#        status = gmf.test_interval(0.001, 0.0)
+#        puts("Converged:") if status == GSL::SUCCESS
+#        a = gmf.x_lower
+#        b = gmf.x_upper
+#        m = gmf.x_minimum
+#        printf("%5d [%.7f, %.7f] %.7f %+.7f %.7f\n",
+#               iter, a, b, m, m - m_expected, b - a);
+#      end while status == GSL::CONTINUE and iter < max_iter
+#
+# {prev}[link:files/rdoc/roots_rdoc.html]
+# {next}[link:files/rdoc/multiroot_rdoc.html]
+#
+# {Reference index}[link:files/rdoc/ref_rdoc.html]
+# {top}[link:files/rdoc/index_rdoc.html]
+#
+#

data/rdoc/monte.rdoc

@@ -0,0 +1,234 @@
+#
+# = Monte Carlo Integration
+#
+# == {}[link:index.html"name="1] The GSL::Monte::Function class
+# The function to be integrated has its own datatype, the <tt>GSL::Monte::Function</tt> class.
+#
+# ---
+# * GSL::Munte::Function.alloc(proc, dim, params)
+# * GSL::Munte::Function.alloc(proc, dim)
+#
+#   Constructor. The following example shows how to use this:
+#
+#   * ex:
+#       proc_f = Proc.new { |x, dim, params|
+#         a = params[0]; b = params[1]; c = params[2]
+#         if dim != 2; raise("dim != 2"); end
+#         a*x[0]*x[0] + b*x[0]*x[1] + c*x[1]*x[1]
+#       }
+#       dim = 2
+#       mf = Monte::Function.alloc(proc_f, dim)
+#       mf.set_params([3, 2, 1])    
+#
+# ---
+# * GSL::Munte::Function#set(proc, dim, params)
+# * GSL::Munte::Function#set(proc, dim)
+# * GSL::Munte::Function#set(proc)
+# * GSL::Munte::Function#set_proc(proc)
+# * GSL::Munte::Function#set_proc(proc, dim)
+# * GSL::Munte::Function#set_params(params)
+# * GSL::Munte::Function#params
+# * GSL::Munte::Function#eval
+# * GSL::Munte::Function#call
+#
+#
+# == {}[link:index.html"name="2] Monte Carlo plans, alrgorithms 
+# === {}[link:index.html"name="2.1] PLAIN Monte Carlo
+# ---
+# * GSL::Monte::Plain.alloc(dim)
+# * GSL::Monte::Plain#init
+#
+# === {}[link:index.html"name="2.2] Miser
+# ---
+# * GSL::Monte::Miser.alloc(dim)
+# * GSL::Monte::Miser#init
+#
+# === {}[link:index.html"name="2.3] Vegas
+# ---
+# * GSL::Monte::Vegas.alloc(dim)
+# * GSL::Monte::Vegas#init
+#
+#
+# == {}[link:index.html"name="3] Integration
+# ---
+# * GSL:Monte::Function#integrate(xl, xu, dim, calls, rng, s)
+# * GSL:Monte::Function#integrate(xl, xu, dim, calls, s)
+# * GSL:Monte::Function#integrate(xl, xu, calls, rng, s)
+# * GSL:Monte::Function#integrate(xl, xu, calls, s)
+#
+#   This method performs Monte-Carlo integration of the function <tt>self</tt> 
+#   using the algorithm <tt>s</tt>, over the <tt>dim</tt>-dimensional hypercubic 
+#   region defined by the lower and upper 
+#   limits in the arrays <tt>xl</tt> and <tt>xu</tt>, each of size <tt>dim</tt>. 
+#   The integration uses a fixed number of function calls <tt>calls</tt>.
+#   The argument <tt>rng</tt> is a random number generator (optional). If it is not
+#   given, a new generator is created internally and freed when the calculation
+#   finishes.
+#
+#   See sample scripts <tt>sample/monte*.rb</tt> for more details.
+#
+# == {}[link:index.html"name="4] Accessing internal state of the Monte Carlo classes
+# ---
+# * GSL::Monte::Miser#estimate_frac
+# * GSL::Monte::Miser#estimate_frac=
+# * GSL::Monte::Miser#min_calls
+# * GSL::Monte::Miser#min_calls=
+# * GSL::Monte::Miser#min_call_per_bisection
+# * GSL::Monte::Miser#min_calls_per_bisection=
+# * GSL::Monte::Miser#alpha
+# * GSL::Monte::Miser#alpha=
+# * GSL::Monte::Miser#dither
+# * GSL::Monte::Miser#dither=
+# * GSL::Monte::Vegas#alpha
+# * GSL::Monte::Vegas#result
+# * GSL::Monte::Vegas#sigma
+# * GSL::Monte::Vegas#chisq
+#
+#   Returns the chi-squared per degree of freedom for the weighted estimate of the integral. The returned value should be close to 1. A value which differs significantly from 1 indicates that the values from different iterations are inconsistent. In this case the weighted error will be under-estimated, and further iterations of the algorithm are needed to obtain reliable results.
+# ---
+# * GSL::Monte::Vegas#runval
+#
+#   Returns the raw (unaveraged) values of the integral and its error <tt>[result, sigma]</tt> from the most recent iteration of the algorithm.
+# ---
+# * GSL::Monte::Vegas#iterations
+# * GSL::Monte::Vegas#iterations=
+# * GSL::Monte::Vegas#alpha
+# * GSL::Monte::Vegas#alpha=
+# * GSL::Monte::Vegas#stage
+# * GSL::Monte::Vegas#stage=
+# * GSL::Monte::Vegas#mode
+# * GSL::Monte::Vegas#mode=
+# * GSL::Monte::Vegas#verbose
+# * GSL::Monte::Vegas#verbose=
+#
+#
+# == {}[link:index.html"name="5] Miser Parameters (GSL-1.13 or later)
+# ---
+# * GSL::Monte::Miser#params_get
+#
+#   Returns the parameters of the integrator state as an instance of <tt>GSL::Monte::Miser::Params</tt> class.
+# ---
+# * GSL::Monte::Miser#params_set(params)
+#
+#   Sets the integrator parameters based on values provided in an object of the <tt>GSL::Monte::Miser::Params</tt> class <tt>params</tt>.
+# === {}[link:index.html"name="5.1] Accessors of <tt>GSL::Monte::Miser::Params</tt>
+# ---
+# * GSL::Monte::Miser::Params#estimate_frac
+# * GSL::Monte::Miser::Params#estimate_frac=
+#
+#   The fraction of the currently available number of function calls which are allocated to estimating the variance at each recursive step. The default value is 0.1.
+# ---
+# * GSL::Monte::Miser::Params#min_calls
+# * GSL::Monte::Miser::Params#min_calls=
+#
+#   The minimum number of function calls required for each estimate of the variance. If the number of function calls allocated to the estimate using <tt>estimate_frac</tt> falls below <tt>min_calls</tt> then <tt>min_calls</tt> are used instead. This ensures that each estimate maintains a reasonable level of accuracy. The default value of min_calls is 16 * dim.
+# ---
+# * GSL::Monte::Miser::Params#min_calls_per_bisection
+# * GSL::Monte::Miser::Params#min_calls_per_bisection=
+#
+#   The minimum number of function calls required to proceed with a bisection step. When a recursive step has fewer calls available than <tt>min_calls_per_bisection</tt> it performs a plain Monte Carlo estimate of the current sub-region and terminates its branch of the recursion. The default value of this parameter is 32 * min_calls.
+# ---
+# * GSL::Monte::Miser::Params#alpha
+# * GSL::Monte::Miser::Params#alpha=
+#
+#   This parameter controls how the estimated variances for the two sub-regions of a bisection are combined when allocating points. With recursive sampling the overall variance should scale better than 1/N, since the values from the sub-regions will be obtained using a procedure which explicitly minimizes their variance. To accommodate this behavior the MISER algorithm allows the total variance to depend on a scaling parameter <tt>alpha</tt>, The authors of the original paper describing MISER recommend the value <tt>alpha</tt> = 2 as a good choice, obtained from numerical experiments, and this is used as the default value in this implementation.
+# ---
+# * GSL::Monte::Miser::Params#dither
+# * GSL::Monte::Miser::Params#dither=
+#
+# This parameter introduces a random fractional variation of size dither into each bisection, which can be used to break the symmetry of integrands which are concentrated near the exact center of the hypercubic integration region. The default value of dither is zero, so no variation is introduced. If needed, a typical value of dither is 0.1.
+#
+# == {}[link:index.html"name="6] Vegas Parameters (GSL-1.13 or later)
+# ---
+# * GSL::Monte::Vegas#params_get
+#
+#   Returns the parameters of the integrator state as an instance of <tt>GSL::Monte::Vegas::Params</tt> class.
+# ---
+# * GSL::Monte::Vegas#params_set(params)
+#
+#   Sets the integrator parameters based on values provided in an object of the <tt>GSL::Monte::Vegas::Params</tt> class <tt>params</tt>.
+#
+# === {}[link:index.html"name="6.1] Accessors of <tt>GSL::Monte::Vegas::Params</tt>
+# ---
+# * GSL::Monte::Vegas::Params#alpha
+# * GSL::Monte::Vegas::Params#alpha=
+#
+#   Controls the stiffness of the rebinning algorithm. It is typically set between one and two. A value of zero prevents rebinning of the grid. The default value is 1.5.
+# ---
+# * GSL::Monte::Vegas::Params#iterations
+# * GSL::Monte::Vegas::Params#iterations=
+#
+#   The number of iterations to perform for each call to the routine. The default value is 5 iterations.
+# ---
+# * GSL::Monte::Vegas::Params#stage
+# * GSL::Monte::Vegas::Params#stage=
+#
+#   Setting this determines the stage of the calculation. Normally, stage = 0 which begins with a new uniform grid and empty weighted average. Calling vegas with stage = 1 retains the grid from the previous run but discards the weighted average, so that one can "tune" the grid using a relatively small number of points and then do a large run with stage = 1 on the optimized grid. Setting stage = 2 keeps the grid and the weighted average from the previous run, but may increase (or decrease) the number of histogram bins in the grid depending on the number of calls available. Choosing stage = 3 enters at the main loop, so that nothing is changed, and is equivalent to performing additional iterations in a previous call.
+# ---
+# * GSL::Monte::Vegas::Params#mode
+# * GSL::Monte::Vegas::Params#mode=
+#
+#   The possible choices are <tt>GSL::VEGAS::MODE_IMPORTANCE</tt>, <tt>GSL::VEGAS::MODE_STRATIFIED</tt>, <tt>GSL::VEGAS::MODE_IMPORTANCE_ONLY</tt>. This determines whether VEGAS will use importance sampling or stratified sampling, or whether it can pick on its own. In low dimensions VEGAS uses strict stratified sampling (more precisely, stratified sampling is chosen if there are fewer than 2 bins per box).
+# ---
+# * GSL::Monte::Vegas::Params#verbose
+# * GSL::Monte::Vegas::Params#verbose=
+#
+#   Set the level of information printed by VEGAS. All information is written to the stream ostream. The default setting of verbose is -1, which turns off all output. A verbose value of 0 prints summary information about the weighted average and final result, while a value of 1 also displays the grid coordinates. A value of 2 prints information from the rebinning procedure for each iteration.
+#
+# == {}[link:index.html"name="7] Example
+#
+#      #!/usr/bin/env ruby
+#      require("gsl")
+#      include GSL::Monte
+#      include Math
+#
+#      proc_f = Proc.new { |k, dim, params|
+#        pi = Math::PI
+#        a = 1.0/(pi*pi*pi)
+#        a/(1.0 - cos(k[0])*cos(k[1])*cos(k[2]))
+#      }
+#
+#      def display_results(title, result, error)
+#        exact = 1.3932039296856768591842462603255
+#
+#        diff = result - exact
+#        printf("%s ==================\n", title);
+#        printf("result = % .6f\n", result);
+#        printf("sigma  = % .6f\n", error);
+#        printf("exact  = % .6f\n", exact);
+#        printf("error  = % .6f = %.1g sigma\n", diff, diff.abs/error)
+#      end
+#
+#      dim = 3
+#      xl = Vector.alloc(0, 0, 0)
+#      xu = Vector.alloc(PI, PI, PI)
+#      G = Monte::Function.alloc(proc_f, dim)
+#      calls = 500000
+#      r = GSL::Rng.alloc(Rng::DEFAULT)
+#
+#      plain = Monte::Plain.alloc(dim)
+#      result, error = G.integrate(xl, xu, dim, calls, r, plain)
+#      display_results("plain", result, error)
+#
+#      miser = Monte::Miser.alloc(dim)
+#      result, error = G.integrate(xl, xu, dim, calls, r, miser)
+#      display_results("miser", result, error)
+#
+#      vegas = Monte::Vegas.alloc(dim)
+#      result, error = G.integrate(xl, xu, dim, 10000, r, vegas)
+#      display_results("vegas warm-up", result, error)
+#      puts("converging...");
+#      begin
+#        result, error = G.integrate(xl, xu, dim, calls/5, r, vegas)
+#        printf("result = % .6f sigma = % .6f chisq/dof = %.1f\n", 
+#                result, error, vegas.chisq)
+#      end while (vegas.chisq-1.0).abs > 0.5
+#      display_results("vegas final", result, error)
+#
+# {prev}[link:files/rdoc/ntuple_rdoc.html]
+# {next}[link:files/rdoc/siman_rdoc.html]
+#
+# {Reference index}[link:files/rdoc/ref_rdoc.html]
+# {top}[link:files/rdoc/index_rdoc.html]
+#
+#

data/rdoc/multimin.rdoc

@@ -0,0 +1,312 @@
+#
+# = Multidimensional Minimization
+# This chapter describes routines for finding minima of arbitrary 
+# multidimensional functions. The library provides low level components for a 
+# variety of iterative minimizers and convergence tests. These can be combined 
+# by the user to achieve the desired solution, while providing full access to 
+# the intermediate steps of the algorithms. Each class of methods uses the 
+# same framework, so that you can switch between minimizers at runtime without 
+# needing to recompile your program. Each instance of a minimizer keeps track 
+# of its own state, allowing the minimizers to be used in multi-threaded 
+# programs. 
+#
+# Contents:
+# 1. {Overview}[link:files/rdoc/multimin_rdoc.html#1]
+# 1. {Caveats}[link:files/rdoc/multimin_rdoc.html#2]
+# 1. {Initializing the Multidimensional Minimizer}[link:files/rdoc/multimin_rdoc.html#3]
+# 1. {Providing a function to minimize}[link:files/rdoc/multimin_rdoc.html#4]
+# 1. {Iteration}[link:files/rdoc/multimin_rdoc.html#5]
+# 1. {Stopping Criteria}[link:files/rdoc/multimin_rdoc.html#6]
+# 1. {Examples}[link:files/rdoc/multimin_rdoc.html#7]
+#    1. {FdfMinimizer}[link:files/rdoc/multimin_rdoc.html#7.1]
+#    1. {FMinimizer}[link:files/rdoc/multimin_rdoc.html#7.2]
+#
+# == {}[link:index.html"name="1] Overview
+# The problem of multidimensional minimization requires finding a point x such 
+# that the scalar function, takes a value which is lower than at any neighboring 
+# point. For smooth functions the gradient g = \nabla f vanishes at the minimum. 
+# In general there are no bracketing methods available for the minimization of 
+# n-dimensional functions. The algorithms proceed from an initial guess using a 
+# search algorithm which attempts to move in a downhill direction. 
+#
+# Algorithms making use of the gradient of the function perform a 
+# one-dimensional line minimisation along this direction until the lowest point 
+# is found to a suitable tolerance. The search direction is then updated with 
+# local information from the function and its derivatives, and the whole process 
+# repeated until the true n-dimensional minimum is found. 
+#
+# The Nelder-Mead Simplex algorithm applies a different strategy. It maintains 
+# n+1 trial parameter vectors as the vertices of a n-dimensional simplex. 
+# In each iteration step it tries to improve the worst vertex by a simple 
+# geometrical transformation until the size of the simplex falls below a given 
+# tolerance. 
+#
+# Both types of algorithms use a standard framework. The user provides a 
+# high-level driver for the algorithms, and the library provides the individual 
+# functions necessary for each of the steps. There are three main phases of the 
+# iteration. The steps are, 
+#
+# * initialize minimizer state, s, for algorithm T 
+# * update s using the iteration T 
+# * test s for convergence, and repeat iteration if necessary 
+#
+# Each iteration step consists either of an improvement to the line-minimisation 
+# in the current direction or an update to the search direction itself. The 
+# state for the minimizers is held in a <tt>GSL::MultiMin::FdfMinimizer</tt> or 
+# a <tt>GSL::MultiMin::FMinimizer</tt> object.
+#
+# == {}[link:index.html"name="2] Caveats
+# Note that the minimization algorithms can only search for one local minimum 
+# at a time. When there are several local minima in the search area, the first 
+# minimum to be found will be returned; however it is difficult to predict which 
+# of the minima this will be. In most cases, no error will be reported if you 
+# try to find a local minimum in an area where there is more than one. 
+#
+# It is also important to note that the minimization algorithms find local 
+# minima; there is no way to determine whether a minimum is a global minimum of 
+# the function in question. 
+#
+#
+# == {}[link:index.html"name="3] Initializing the Multidimensional Minimizer
+# ---
+# * GSL::MultiMin::FdfMinimizer.alloc(type, n)
+# * GSL::MultiMin::FMinimizer.alloc(type, n)
+#
+#   These method create a minimizer of type <tt>type</tt> for an <tt>n</tt>-dimension function. 
+#   The type is given by a string, or by a Ruby constant.
+#
+#   * <tt>GSL::MultiMin::FdfMinimizer::CONJUGATE_FR</tt> or <tt>"conjugate_fr"</tt>
+#   * <tt>GSL::MultiMin::FdfMinimizer::CONJUGATE_PR</tt> or <tt>"conjugate_pr"</tt>
+#   * <tt>GSL::MultiMin::FdfMinimizer::VECTOR_BFGS</tt> or <tt>"vector_bfgs"</tt>
+#   * <tt>GSL::MultiMin::FdfMinimizer::VECTOR_BFGS2</tt> or <tt>"vector_bfgs2"</tt> (GSL-1.9 or later)
+#   * <tt>GSL::MultiMin::FdfMinimizer::STEEPEST_DESCENT</tt> or <tt>"steepest_descent"</tt>
+#   * <tt>GSL::MultiMin::FMinimizer::NMSIMPLEX</tt> or <tt>"nmsimplex"</tt>
+#   * <tt>GSL::MultiMin::FMinimizer::NMSIMPLEX2RAND</tt> or <tt>"nmsimplex2rand"</tt> (GSL-1.13)
+#
+#   ex:
+#       include GSL::MultiMin
+#       m1 = FdfMinimizer.alloc(FdfMinimizer::CONJUGATE_FR, 2)
+#       m2 = FdfMinimizer.alloc("steepest_descent", 4)
+#       m3 = FMinimizer.alloc(FMinimizer::NMSIMPLEX, 3)
+#       m4 = FMinimizer.alloc("nmsimplex", 2)
+#
+# ---
+# * GSL::MultiMin::FdfMinimizer#set(func, x, step_size, tol)
+#
+#   This method initializes the minimizer <tt>self</tt> to minimize the function 
+#   <tt>fdf</tt> (the <tt>GSL::MultiMin::Function_fdf</tt> class, see below) starting from 
+#   the initial point <tt>x</tt> (<tt>GSL::Vector</tt>). The size of the first trial step is 
+#   given by <tt>step_size</tt> (<tt>Vector</tt>). The accuracy of the line minimization is 
+#   specified by <tt>tol</tt>.
+#
+# ---
+# * GSL::MultiMin::FMinimizer#set(func, x, step_size)
+#
+#   This method initializes the minimizer <tt>self</tt> to minimize the function <tt>func</tt>, 
+#   starting from the initial point <tt>x</tt> (Vector). The size of the initial trial steps 
+#   is given in vector <tt>step_size</tt>.
+#
+# ---
+# * GSL::MultiMin::FdfMinimizer#name
+# * GSL::MultiMin::FMinimizer#name
+#
+#   These return the name of the minimizer <tt>self</tt>.
+#
+# == {}[link:index.html"name="4] Providing a function to minimize
+# You must provide a parametric function of <tt>n</tt> variables for the minimizers to 
+# operate on. You may also need to provide a routine which calculates the gradient of the 
+# function. In order to allow for general parameters the functions are defined by the 
+# classes, <tt>GSL::MultiMin::Function_fdf</tt> and <tt>GSL::MultiMin::Function</tt>.
+#
+# ---
+# * GSL::MultiMin:Function_fdf.alloc(proc_f, proc_df, n)
+# * GSL::MultiMin:Function_fdf.alloc(proc_f, proc_df, proc_fdf, n)
+# * GSL::MultiMin:Function_fdf#set_procs(proc_f, proc_df)
+# * GSL::MultiMin:Function_fdf#set_procs(proc_f, proc_df, n)
+# * GSL::MultiMin:Function_fdf#set_procs(proc_f, proc_df, proc_fdf, n)
+# * GSL::MultiMin:Function_fdf#set_params(params)
+#
+#   See example below.
+#
+#     include GSL::MultiMin
+#
+#     my_f = Proc.new { |v, params|
+#       x = v[0]; y = v[1]
+#       p0 = params[0]; p1 = params[1]
+#       10.0*(x - p0)*(x - p0) + 20.0*(y - p1)*(y - p1) + 30.0
+#     }
+#
+#     my_df = Proc.new { |v, params, df|
+#       x = v[0]; y = v[1]
+#       p0 = params[0]; p1 = params[1]
+#       df[0] = 20.0*(x-p0)
+#       df[1] = 40.0*(y-p1)
+#     }
+#
+#     my_func = Function_fdf.alloc(my_f, my_df, 2)
+#     my_func.set_params([1.0, 2.0])      # parameters
+#
+# ---
+# * GSL::MultiMin:Function.alloc(proc_f, n)
+# * GSL::MultiMin:Function#set_proc(proc_f)
+# * GSL::MultiMin:Function#set_proc(proc_f, n)
+# * GSL::MultiMin:Function#set_params(params)
+#
+#   See example below.
+#
+#     include GSL::MultiMin
+#
+#     np = 2
+#     my_f = Proc.alloc { |v, params|
+#       x = v[0]; y = v[1]
+#       p0 = params[0]; p1 = params[1]
+#       10.0*(x - p0)*(x - p0) + 20.0*(y - p1)*(y - p1) + 30.0
+#     }
+#
+#     my_func = Function.alloc(my_f, np)
+#     my_func.set_params([1.0, 2.0])      # parameters
+#
+# == {}[link:index.html"name="5] Iteration
+# ---
+# * GSL::MultiMin::FdfMinimizer#iterate
+# * GSL::MultiMin::FMinimizer#iterate
+#
+#   These methods perform a single iteration of the minimizer <tt>self</tt>. 
+#   If the iteration encounters an unexpected problem then an error code will be returned.
+#   The minimizer maintains a current best estimate of the minimum at all times. 
+#   This information can be accessed with the following methods,
+#
+# ---
+# * GSL::MultiMin::FdfMinimizer#x
+# * GSL::MultiMin::FdfMinimizer#minimum
+# * GSL::MultiMin::FdfMinimizer#gradient
+# * GSL::MultiMin::FMinimizer#x
+# * GSL::MultiMin::FMinimizer#minimum
+# * GSL::MultiMin::FMinimizer#size
+#
+#   These method return the current best estimate of the location of the minimum, 
+#   the value of the function at that point, its gradient, and minimizer specific 
+#   characteristic size for the minimizer <tt>self</tt>.
+#
+# ---
+# * GSL::MultiMin::FdfMinimizer#restart
+#
+#   This method resets the minimizer <tt>self</tt> to use the current point as a new 
+#   starting point.
+#
+# == {}[link:index.html"name="6] Stopping Criteria
+# A minimization procedure should stop when one of the following conditions is true:
+# * A minimum has been found to within the user-specified precision.
+# * A user-specified maximum number of iterations has been reached.
+# * An error has occurred.
+# The handling of these conditions is under user control. The methods below allow the 
+# user to test the precision of the current result.
+#
+# ---
+# * GSL::MultiMin::FdfMinimizer#test_gradient(epsabs)
+# * GSL::MultiMin::FdfMinimizer.test_gradient(g, epsabs)
+#
+#   These method test the norm of the gradient <tt>g</tt> against the absolute tolerance 
+#   <tt>epsabs</tt>. The gradient of a multidimensional function goes to zero at a minimum. 
+#   The tests return <tt>GSL::SUCCESS</tt> if the following condition is achieved,
+#     |g| < epsabs
+#   and returns <tt>GSL::CONTINUE</tt> otherwise. A suitable choice of <tt>epsabs</tt> can 
+#   be made from the desired accuracy in the function for small variations in <tt>x</tt>. 
+#   The relationship between these quantities is given by <tt>\delta f = g \delta x</tt>.
+#
+# ---
+# * GSL::MultiMin::FdfMinimizer#test_size(epsabs)
+# * GSL::MultiMin::FdfMinimizer.test_size(size, epsabs)
+#
+#   These method test the minimizer specific characteristic <tt>size</tt> 
+#   (if applicable to the used minimizer) against absolute tolerance <tt>epsabs</tt>. 
+#   The tests return (<tt>GSL::SUCCESS</tt> if the size is smaller than tolerance, 
+#   otherwise <tt>GSL::CONTINUE</tt> is returned.
+#
+# == {}[link:index.html"name="7] Examples
+#
+# === {}[link:index.html"name="7.1] FdfMinimizer
+#      #!/usr/bin/env ruby
+#      require("gsl")
+#      include GSL::MultiMin
+#
+#      my_f = Proc.new { |v, params|
+#        x = v[0]; y = v[1]
+#        p0 = params[0]; p1 = params[1]
+#        10.0*(x - p0)*(x - p0) + 20.0*(y - p1)*(y - p1) + 30.0
+#      }
+#
+#      my_df = Proc.new { |v, params, df|
+#        x = v[0]; y = v[1]
+#        p0 = params[0]; p1 = params[1]
+#        df[0] = 20.0*(x-p0)
+#        df[1] = 40.0*(y-p1)
+#      }
+#
+#      my_func = Function_fdf.alloc(my_f, my_df, 2)
+#      my_func.set_params([1.0, 2.0])      # parameters
+#
+#      x = Vector.alloc(5.0, 7.0)          # starting point
+#
+#      minimizer = FdfMinimizer.alloc("conjugate_fr", 2)
+#      minimizer.set(my_func, x, 0.01, 1e-4)
+#
+#      iter = 0
+#      begin
+#        iter += 1
+#        status = minimizer.iterate()
+#        status = minimizer.test_gradient(1e-3)
+#        if status == GSL::SUCCESS
+#          puts("Minimum found at")
+#        end
+#        x = minimizer.x
+#        f = minimizer.f
+#        printf("%5d %.5f %.5f %10.5f\n", iter, x[0], x[1], f)
+#      end while status == GSL::CONTINUE and iter < 100
+#
+# === {}[link:index.html"name="7.2] FMinimizer
+#      #!/usr/bin/env ruby
+#      require("gsl")
+#      include GSL::MultiMin
+#
+#      np = 2
+#  
+#      my_f = Proc.new { |v, params|
+#        x = v[0]; y = v[1]
+#        p0 = params[0]; p1 = params[1]
+#        10.0*(x - p0)*(x - p0) + 20.0*(y - p1)*(y - p1) + 30.0
+#      }
+#
+#      my_func = Function.alloc(my_f, np)
+#      my_func.set_params([1.0, 2.0])      # parameters
+#
+#      x = Vector.alloc([5, 7])
+#      ss = Vector.alloc(np)
+#      ss.set_all(1.0)
+#
+#      minimizer = FMinimizer.alloc("nmsimplex", np)
+#      minimizer.set(my_func, x, ss)
+#
+#      iter = 0
+#      begin
+#        iter += 1
+#        status = minimizer.iterate()
+#        status = minimizer.test_size(1e-2)
+#        if status == GSL::SUCCESS
+#          puts("converged to minimum at")
+#        end
+#        x = minimizer.x
+#        printf("%5d ", iter);
+#        for i in 0...np do
+#          printf("%10.3e ", x[i])
+#        end
+#        printf("f() = %7.3f size = %.3f\n", minimizer.fval, minimizer.size);
+#      end while status == GSL::CONTINUE and iter < 100
+#
+# {prev}[link:files/rdoc/multiroot_rdoc.html]
+# {next}[link:files/rdoc/fit_rdoc.html]
+#
+# {Reference index}[link:files/rdoc/ref_rdoc.html]
+# {top}[link:files/rdoc/index_rdoc.html]
+#
+#