gsl 1.12.109 → 1.14.5

data/rdoc/ndlinear.rdoc

@@ -0,0 +1,247 @@
+#
+# = NDLINAR: multi-linear, multi-parameter least squares fitting 
+#
+# The multi-dimension fitting library NDLINEAR is not included in GSL,
+# but is provided as an extension library. This is available at the
+# {Patric Alken's page}[http://ucsu.colorado.edu/~alken/gsl/"target="_top].
+#
+# Contents:
+# 1. {Introduction}[link:files/rdoc/ndlinear_rdoc.html#1]
+# 1. {Class and methods}[link:files/rdoc/ndlinear_rdoc.html#2]
+# 1. {Examples}[link:files/rdoc/ndlinear_rdoc.html#3]
+#
+# == {}[link:index.html"name="1] Introduction
+# The NDLINEAR extension provides support for general linear least squares 
+# fitting to data which is a function of more than one variable (multi-linear or 
+# multi-dimensional least squares fitting). This model has the form where 
+# <tt>x</tt> is a vector of independent variables, a_i are the fit coefficients, 
+# and F_i are the basis functions of the fit. This GSL extension computes the 
+# design matrix X_{ij = F_j(x_i) in the special case that the basis functions 
+# separate: Here the superscript value j indicates the basis function 
+# corresponding to the independent variable x_j. The subscripts (i_1, i_2, i_3, 
+# �c) refer to which basis function to use from the complete set. These 
+# subscripts are related to the index i in a complex way, which is the main 
+# problem this extension addresses. The model then becomes where n is the 
+# dimension of the fit and N_i is the number of basis functions for the variable 
+# x_i. Computationally, it is easier to supply the individual basis functions 
+# u^{(j) than the total basis functions F_i(x). However the design matrix X is 
+# easiest to construct given F_i(x). Therefore the routines below allow the user 
+# to specify the individual basis functions u^{(j) and then automatically 
+# construct the design matrix X. 
+#
+#
+# == {}[link:index.html"name="2] Class and Methods
+# ---
+# * GSL::MultiFit::Ndlinear.alloc(n_dim, N, u, params)
+# * GSL::MultiFit::Ndlinear::Workspace.alloc(n_dim, N, u, params)
+#
+#   Creates a workspace for solving multi-parameter, multi-dimensional linear 
+#   least squares problems. <tt>n_dim</tt> specifies the dimension of the fit 
+#   (the number of independent variables in the model). The array <tt>N</tt> of 
+#   length <tt>n_dim</tt> specifies the number of terms in each sum, so that 
+#   <tt>N[i]</tt>
+#   specifies the number of terms in the sum of the i-th independent variable. 
+#   The array of <tt>Proc</tt> objects <tt>u</tt> of length <tt>n_dim</tt> specifies 
+#   the basis functions for each independent fit variable, so that <tt>u[i]</tt> 
+#   is a procedure to calculate the basis function for the i-th 
+#   independent variable.
+#   Each of the procedures <tt>u</tt> takes three block parameters: a point 
+#   <tt>x</tt> at which to evaluate the basis function, an array y of length 
+#   <tt>N[i]</tt> which is filled on output with the basis function values at 
+#   <tt>x</tt> for all i, and a params argument which contains parameters needed 
+#   by the basis function. These parameters are supplied in the <tt>params</tt>
+#   argument to this method. 
+#
+#   Ex)
+#
+#      N_DIM = 3
+#      N_SUM_R = 10
+#      N_SUM_THETA = 11
+#      N_SUM_PHI = 9
+#
+#      basis_r = Proc.new { |r, y, params|
+#        params.eval(r, y)
+#      }
+#
+#      basis_theta = Proc.new { |theta, y, params|
+#        for i in 0...N_SUM_THETA do
+#          y[i] = GSL::Sf::legendre_Pl(i, Math::cos(theta));
+#        end
+#      }
+#
+#      basis_phi = Proc.new { |phi, y, params|
+#        for i in 0...N_SUM_PHI do
+#          if i%2 == 0
+#            y[i] = Math::cos(i*0.5*phi)
+#          else
+#            y[i] = Math::sin((i+1.0)*0.5*phi)
+#          end
+#        end
+#      }
+#
+#      N = [N_SUM_R, N_SUM_THETA, N_SUM_PHI]
+#      u = [basis_r, basis_theta, basis_phi]
+#
+#      bspline = GSL::BSpline.alloc(4, N_SUM_R - 2)
+#
+#      ndlinear = GSL::MultiFit::Ndlinear.alloc(N_DIM, N, u, bspline)
+#
+# ---
+# * GSL::MultiFit::Ndlinear.design(vars, X, w)
+# * GSL::MultiFit::Ndlinear.design(vars, w)
+# * GSL::MultiFit::Ndlinear::Workspace#design(vars, X)
+# * GSL::MultiFit::Ndlinear::Workspace#design(vars)
+#
+#   Construct the least squares design matrix <tt>X</tt> from the input <tt>vars</tt>
+#   and the previously specified basis functions. vars is a ndata-by-n_dim 
+#   matrix where the ith row specifies the n_dim independent variables for the 
+#   ith observation. 
+#
+# ---
+# * GSL::MultiFit::Ndlinear.est(x, c, cov, w)
+# * GSL::MultiFit::Ndlinear::Workspace#est(x, c, cov)
+#
+#   After the least squares problem is solved via <tt>GSL::MultiFit::linear</tt>, 
+#   this method can be used to evaluate the model at the data point <tt>x</tt>. 
+#   The coefficient vector <tt>c</tt> and covariance matrix <tt>cov</tt> are 
+#   outputs from <tt>GSL::MultiFit::linear</tt>. The model output value and 
+#   its error [<tt>y, yerr</tt>] are returned as an array.
+#
+# ---
+# * GSL::MultiFit::Ndlinear.calc(x, c, w)
+# * GSL::MultiFit::Ndlinear::Workspace#calc(x, c)
+#
+#   This method is similar to <tt>GSL::MultiFit::Ndlinear.est</tt>, but does not compute the model error. It computes the model value at the data point <tt>x</tt>  using the coefficient vector <tt>c</tt> and returns the model value.
+#
+# == {}[link:index.html"name="3] Examples
+# This example program generates data from the 3D isotropic harmonic oscillator 
+# wavefunction (real part) and then fits a model to the data using B-splines in 
+# the r coordinate, Legendre polynomials in theta, and sines/cosines in phi. 
+# The exact form of the solution is (neglecting the normalization constant for 
+# simplicity) The example program models psi by default. 
+#
+#  #!/usr/bin/env ruby
+#  require("gsl")
+#
+#  N_DIM = 3
+#  N_SUM_R = 10
+#  N_SUM_THETA = 10
+#  N_SUM_PHI = 9
+#  R_MAX = 3.0
+#
+#  def psi_real_exact(k, l, m, r, theta, phi)
+#     rr = GSL::pow(r, l)*Math::exp(-r*r)*GSL::Sf::laguerre_n(k, l + 0.5, 2 * r * r)	 
+#     tt = GSL::Sf::legendre_sphPlm(l, m, Math::cos(theta))
+#     pp = Math::cos(m*phi)
+#     rr*tt*pp
+#  end
+#
+#  basis_r = Proc.new { |r, y, params|
+#    params.eval(r, y)
+#  }
+#
+#  basis_theta = Proc.new { |theta, y, params|
+#    for i in 0...N_SUM_THETA do
+#      y[i] = GSL::Sf::legendre_Pl(i, Math::cos(theta));
+#    end
+#  }
+#
+#  basis_phi = Proc.new { |phi, y, params|
+#    for i in 0...N_SUM_PHI do
+#      if i%2 == 0
+#        y[i] = Math::cos(i*0.5*phi)
+#      else
+#        y[i] = Math::sin((i+1.0)*0.5*phi)
+#      end
+#    end
+#  }
+#
+#
+#  GSL::Rng::env_setup()
+#
+#  k = 5
+#  l = 4
+#  m = 2
+#
+#  NDATA = 3000
+#
+#  N = [N_SUM_R, N_SUM_THETA, N_SUM_PHI]
+#  u = [basis_r, basis_theta, basis_phi]
+#
+#  rng = GSL::Rng.alloc()
+#
+#  bspline = GSL::BSpline.alloc(4, N_SUM_R - 2)
+#  bspline.knots_uniform(0.0, R_MAX)
+#
+#  ndlinear = GSL::MultiFit::Ndlinear.alloc(N_DIM, N, u, bspline)
+#  multifit = GSL::MultiFit.alloc(NDATA, ndlinear.n_coeffs)
+#  vars = GSL::Matrix.alloc(NDATA, N_DIM)
+#  data = GSL::Vector.alloc(NDATA)
+#
+#
+#  for i in 0...NDATA do
+#    r = rng.uniform()*R_MAX
+#    theta = rng.uniform()*Math::PI
+#    phi = rng.uniform()*2*Math::PI
+#    psi = psi_real_exact(k, l, m, r, theta, phi)
+#    dpsi = rng.gaussian(0.05*psi)
+#
+#    vars[i][0] = r
+#    vars[i][1] = theta
+#    vars[i][2] = phi		
+#
+#    data[i] = psi + dpsi
+#  end
+#
+#  X = GSL::MultiFit::Ndlinear::design(vars, ndlinear)
+#
+#  coeffs, cov, chisq, = GSL::MultiFit::linear(X, data, multifit)
+#
+#  rsq = 1.0 - chisq/data.tss
+#  STDERR.printf("chisq = %e, Rsq = %f\n", chisq, rsq)
+#
+#  eps_rms = 0.0
+#  volume = 0.0
+#  dr = 0.05;
+#  dtheta = 5.0 * Math::PI / 180.0
+#  dphi = 5.0 * Math::PI / 180.0
+#  x = GSL::Vector.alloc(N_DIM)
+#
+#  r = 0.01
+#  while r < R_MAX do
+#    theta = 0.0
+#    while theta < Math::PI do
+#      phi = 0.0
+#      while phi < 2*Math::PI do
+#        dV = r*r*Math::sin(theta)*r*dtheta*dphi
+#        x[0] = r
+#        x[1] = theta
+#        x[2] = phi
+#
+#        psi_model, err = GSL::MultiFit::Ndlinear.calc(x, coeffs, ndlinear)
+#        psi = psi_real_exact(k, l, m, r, theta, phi)
+#        err = psi_model - psi
+#        eps_rms += err * err * dV;
+#        volume += dV;
+#
+#        if phi == 0.0
+#          printf("%e %e %e %e\n", r, theta, psi, psi_model)
+#        end
+#
+#        phi += dphi
+#      end
+#      theta += dtheta
+#    end
+#    printf("\n");
+#    r += dr
+#  end
+#
+#  eps_rms /= volume
+#  eps_rms = Math::sqrt(eps_rms)
+#  STDERR.printf("rms error over all parameter space = %e\n", eps_rms)
+#
+#
+# {Reference index}[link:files/rdoc/ref_rdoc.html]
+# {top}[link:files/rdoc/index_rdoc.html]
+#
+#

data/rdoc/nonlinearfit.rdoc

@@ -0,0 +1,348 @@
+#
+# = Nonlinear Least-Squares Fitting
+# This chapter describes functions for multidimensional nonlinear least-squares 
+# fitting. The library provides low level components for a variety of iterative 
+# solvers and convergence tests. These can be combined by the user to achieve 
+# the desired solution, with full access to the intermediate steps of the 
+# iteration. Each class of methods uses the same framework, so that you can 
+# switch between solvers at runtime without needing to recompile your program. 
+# Each instance of a solver keeps track of its own state, allowing the solvers 
+# to be used in multi-threaded programs. 
+#
+# Contents:
+# 1. {Overview}[link:files/rdoc/nonlinearfit_rdoc.html#1]
+# 1. {Initializing the Solver}[link:files/rdoc/nonlinearfit_rdoc.html#2]
+#    1. {GSL::MultiFit::FdfSolver class}[link:files/rdoc/nonlinearfit_rdoc.html#2.1]
+# 1. {Providing the function to be minimized}[link:files/rdoc/nonlinearfit_rdoc.html#3]
+#    1. {GSL::MultiFit::Function_fdf class}[link:files/rdoc/nonlinearfit_rdoc.html#3.1]
+# 1. {Iteration}[link:files/rdoc/nonlinearfit_rdoc.html#4]
+# 1. {Search Stopping Parameters}[link:files/rdoc/nonlinearfit_rdoc.html#5]
+# 1. {Computing the covariance matrix of best fit parameters}[link:files/rdoc/nonlinearfit_rdoc.html#6]
+# 1. {Higher level interfaces}[link:files/rdoc/nonlinearfit_rdoc.html#7]
+# 1. {Examples}[link:files/rdoc/nonlinearfit_rdoc.html#8]
+#    1. {Fitting to user-defined functions}[link:files/rdoc/nonlinearfit_rdoc.html#8.1]
+#    1. {Fitting to built-in functions}[link:files/rdoc/nonlinearfit_rdoc.html#8.2]
+#
+# == {}[link:index.html"name="1] Overview
+# The problem of multidimensional nonlinear least-squares fitting requires the 
+# minimization of the squared residuals of n functions, f_i, in p parameters, 
+# x_i, All algorithms proceed from an initial guess using the linearization, 
+# where x is the initial point, p is the proposed step and J is the Jacobian 
+# matrix J_{ij} = d f_i / d x_j. Additional strategies are used to enlarge the 
+# region of convergence. These include requiring a decrease in the norm ||F|| 
+# on each step or using a trust region to avoid steps which fall outside the 
+# linear regime. 
+#
+# To perform a weighted least-squares fit of a nonlinear model Y(x,t) to data 
+# (t_i, y_i) with independent gaussian errors \sigma_i, use function components 
+# of the following form, Note that the model parameters are denoted by x in this 
+# chapter since the non-linear least-squares algorithms are described 
+# geometrically (i.e. finding the minimum of a surface). The independent 
+# variable of any data to be fitted is denoted by t. 
+#
+# With the definition above the Jacobian is 
+# J_{ij} =(1 / \sigma_i) d Y_i / d x_j, where Y_i = Y(x,t_i). 
+#
+# == {}[link:index.html"name="2] Initializing the Solver 
+#
+# === {}[link:index.html"name="2.1] GSL::MultiFit::FdfSolver class
+# ---
+# * GSL::MultiFit::FdfSolver.alloc(T, n, p)
+#
+#   This creates an instance of the <tt>GSL::MultiFit::FdfSolver</tt> class of 
+#   type <tt>T</tt> for <tt>n</tt> observations and <tt>p</tt> parameters. The type <tt>T</tt>
+#   is given by a <tt>Fixnum</tt> constant or a <tt>String</tt>, 
+#   * <tt>GSL::MultiFit::LMSDER</tt> or <tt>"lmsder"</tt>
+#   * <tt>GSL::MultiFit::LMDER</tt> or <tt>"lmder"</tt>
+#   For example, the following code creates an instance of a Levenberg-Marquardt 
+#   solver for 100 data points and 3 parameters,
+#
+#       solver = MultiFit::FdfSolver.alloc(MultiFit::LMDER, 100, 3)
+#
+# ---
+# * GSL::MultiFit::FdfSolver#set(f, x)
+#
+#   This method initializes, or reinitializes, an existing solver <tt>self</tt> 
+#   to use the function <tt>f</tt> and the initial guess <tt>x</tt>. The function <tt>f</tt>
+#   is an instance of the <tt>GSL::MultiFit::Function_fdf</tt> class (see below). The
+#   initial guess of the parameters <tt>x</tt> is given by a {GSL::Vector}[link:files/rdoc/vector_rdoc.html] object.
+#
+# ---
+# * GSL::MultiFit::FdfSolver#name
+#
+#   This returns the name of the solver <tt>self</tt> as a String.
+#
+#
+# ---
+# * GSL::MultiFit::FdfSolver#x
+# * GSL::MultiFit::FdfSolver#dx
+# * GSL::MultiFit::FdfSolver#f
+# * GSL::MultiFit::FdfSolver#J
+# * GSL::MultiFit::FdfSolver#jacobian
+# * GSL::MultiFit::FdfSolver#jac
+#
+#   Access to the members (see <tt>gsl_multifit_nlin.h</tt>)
+#
+# == {}[link:index.html"name="3] Providing the function to be minimized
+# === {}[link:index.html"name="3.1] GSL::MultiFit::Function_fdf class
+# ---
+# * GSL::MultiFit::Function_fdf.alloc()
+# * GSL::MultiFit::Function_fdf.alloc(f, df, p)
+# * GSL::MultiFit::Function_fdf.alloc(f, df, fdf, p)
+#
+#   Constructor for the <tt>Function_fdf</tt> class, to a
+#   function with <tt>p</tt> parameters, The first two or three arguments are Ruby Proc objects 
+#   to evaluate the function to minimize and its derivative (Jacobian). 
+#
+# ---
+# * GSL::MultiFit::Function_fdf#set_procs(f, df, p)
+# * GSL::MultiFit::Function_fdf#set_procs(f, df, fdf, p)
+#
+#   This initialize of reinitialize the function <tt>self</tt> with <tt>p</tt> parameters
+#   by two or three Proc objects <tt>f, df</tt> and <tt>fdf</tt>.
+#
+# ---
+# * GSL::MultiFit::Function_fdf#set_data(t, y)
+# * GSL::MultiFit::Function_fdf#set_data(t, y, sigma)
+#
+#   This sets the data <tt>t, y, sigma</tt> of length <tt>n</tt>, to the function <tt>self</tt>.
+#       
+# == {}[link:index.html"name="4] Iteration
+# ---
+# * GSL::MultiFit::FdfSolver#iterate
+#
+#   THis performs a single iteration of the solver <tt>self</tt>. If the iteration 
+#   encounters an unexpected problem then an error code will be returned. 
+#   The solver maintains a current estimate of the best-fit parameters at all 
+#   times. This information can be accessed with the method <tt>position</tt>.
+#
+# ---
+# * GSL::MultiFit::FdfSolver#position
+#
+#   This returns the current position (i.e. best-fit parameters) of the solver 
+#   <tt>self</tt>, as a <tt>GSL::Vector</tt> object.
+#
+#
+# == {}[link:index.html"name="5] Search Stopping Parameters
+# 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 method below allows
+# the user to test the current estimate of the best-fit parameters.
+#
+# ---
+# * GSL::MultiFit::FdfSolver#test_delta(epsabs, epsrel)
+#
+#   This method tests for the convergence of the sequence by comparing the last 
+#   step with the absolute error <tt>epsabs</tt> and relative error (<tt>epsrel</tt> 
+#   to the current position. The test returns <tt>GSL::SUCCESS</tt> if the following 
+#   condition is achieved,
+#     |dx_i| < epsabs + epsrel |x_i|
+#   for each component of <tt>x</tt> and returns <tt>GSL::CONTINUE</tt> otherwise.
+#
+# ---
+# * GSL::MultiFit::FdfSolver#test_gradient(g, epsabs)
+# * GSL::MultiFit::FdfSolver#test_gradient(epsabs)
+#
+#   This function tests the residual gradient <tt>g</tt> against the absolute error 
+#   bound <tt>epsabs</tt>. If <tt>g</tt> is not given, it is calculated internally. 
+#   Mathematically, the gradient should be exactly zero at the minimum. 
+#   The test returns <tt>GSL::SUCCESS</tt> if the following condition is achieved,
+#     \sum_i |g_i| < epsabs
+#   and returns <tt>GSL::CONTINUE</tt> otherwise. This criterion is suitable for 
+#   situations where the precise location of the minimum, x, is unimportant provided 
+#   a value can be found where the gradient is small enough.
+#
+# ---
+# * GSL::MultiFit::FdfSolver#gradient
+#
+#   This method returns the gradient g of \Phi(x) = (1/2) ||F(x)||^2 from the 
+#   Jacobian matrix and the function values, using the formula g = J^T f.
+#
+# ---
+# * GSL::MultiFit.test_delta(dx, x, epsabs, epsrel)
+# * GSL::MultiFit.test_gradient(g, epsabs)
+# * GSL::MultiFit.gradient(jac, f, g)
+# * GSL::MultiFit.covar(jac, epsrel)
+# * GSL::MultiFit.covar(jac, epsrel, covar)
+#
+#   Singleton methods of the <tt>GSL::MultiFit</tt> module.
+#
+#
+# == {}[link:index.html"name="6] Computing the covariance matrix of best fit parameters
+# ---
+# * GSL::MultiFit.covar(J, epsrel)
+# * GSL::MultiFit.covar(J, epsrel, covar)
+#
+#   This method uses the Jacobian matrix <tt>J</tt> to compute the covariance 
+#   matrix of the best-fit parameters. If an existing matrix <tt>covar</tt> is given,
+#   it is overwritten, and if not, this method returns a new matrix. 
+#   The parameter <tt>epsrel</tt> is used to remove linear-dependent columns when 
+#   <tt>J</tt> is rank deficient.
+#
+#   The covariance matrix is given by,
+#      covar = (J^T J)^{-1}
+#   and is computed by QR decomposition of <tt>J</tt> with column-pivoting. 
+#   Any columns of R which satisfy
+#     |R_{kk}| <= epsrel |R_{11}|
+#   are considered linearly-dependent and are excluded from the covariance matrix 
+#   (the corresponding rows and columns of the covariance matrix are set to zero).
+#
+# == {}[link:index.html"name="7] Higher level interfaces
+# ---
+# * GSL::MultiFit::FdfSolver.fit(x, y, type[, guess])
+# * GSL::MultiFit::FdfSolver.fit(x, w, y, type[, guess])
+#
+#   This method uses <tt>FdfSolver</tt> with the LMSDER algorithm to fit the data
+#   <tt>[x, y]</tt> to a function of type <tt>type</tt>. The returned value is 
+#   an array of 4 elements, <tt>[coef, err, chisq, dof]</tt>,
+#   where <tt>coef</tt> is an array of the fitting coefficients, <tt>err</tt> contains
+#   errors in estimating <tt>coef</tt>, <tt>chisq</tt> is the 
+#   chi-squared, and <tt>dof</tt> is the degree-of-freedom in the fitting 
+#   which equals to (data length - number of fitting coefficients). The optional
+#   argument <tt>guess</tt> is an array of initial guess of the coefficients.
+#   The fitting type <tt>type</tt> is given by a <tt>String</tt> as follows.
+#   * <tt>"gaussian"</tt>: Gaussian fit, 
+#     <tt>y = y0 + A exp(-(x-x0)^2/2/var)</tt>, <tt>coef = [y0, A, x0, var]</tt>
+#   * <tt>"gaussian_2peaks"</tt>: 2-peak Gaussian fit,
+#     <tt>y = y0 + A1 exp(-(x-x1)^2/2/var1) + A2 exp(-(x-x2)^2/2/var2)</tt>, <tt>coef = [y0, A1, x1, var1, A2, x2, var2]</tt>
+#   * <tt>"exp"</tt>: Exponential fit, 
+#     <tt>y = y0 + A exp(-b x)</tt>, <tt>coef = [y0, A, b]</tt>
+#   * <tt>"dblexp"</tt>: Double exponential fit, 
+#     <tt>y = y0 + A1 exp(-b1 x) + A2 exp(-b2 x)</tt>, <tt>coef = [y0, A1, b1, A2, b2]</tt>
+#   * <tt>"sin"</tt>: Sinusoidal fit, 
+#     <tt>y = y0 + A sin(f x + phi)</tt>, <tt>coef = [y0, A, f, phi]</tt>
+#   * <tt>"lor"</tt>: Lorentzian peak fit, 
+#     <tt>y = y0 + A/((x-x0)^2 + B)</tt>, <tt>coef = [y0, A, x0, B]</tt>
+#   * <tt>"hill"</tt>: Hill's equation fit, 
+#     <tt>y = y0 + (m - y0)/(1 + (xhalf/x)^r)</tt>, <tt>coef = [y0, n, xhalf, r]</tt>
+#   * <tt>"sigmoid"</tt>: Sigmoid (Fermi-Dirac) function fit, 
+#     <tt>y = y0 + m/(1 + exp((x0-x)/r))</tt>, <tt>coef = [y0, m, x0, r]</tt>
+#   * <tt>"power"</tt>: Power-law fit, 
+#     <tt>y = y0 + A x^r</tt>, <tt>coef = [y0, A, r]</tt>
+#   * <tt>"lognormal"</tt>: Lognormal peak fit, 
+#     <tt>y = y0 + A exp[ -(log(x/x0)/width)^2 ]</tt>, <tt>coef = [y0, A, x0, width]</tt>
+#
+#   See {Linear fitting}[link:files/rdoc/fit_rdoc.html#2.3] for linear and polynomical fittings.
+#
+# == {}[link:index.html"name="8] Examples
+# === {}[link:index.html"name="8.1] Fitting to user-defined functions
+#
+# The following example program fits a weighted exponential model with background 
+# to experimental data, Y = A exp(-lambda t) + b. The first part of the program sets 
+# up the functions <tt>procf</tt> and <tt>procdf</tt> to calculate the model and its Jacobian. 
+# The appropriate fitting function is given by,
+#   f_i = ((A exp(-lambda t_i) + b) - y_i)/sigma_i
+# where we have chosen t_i = i. The Jacobian matrix <tt>jac</tt> is the derivative of 
+# these functions with respect to the three parameters (A, lambda, b). It is given by,
+#   J_{ij} = d f_i / d x_j
+# where x_0 = A, x_1 = lambda and x_2 = b.
+#
+#
+#   require("gsl")
+#   include GSL::MultiFit
+#
+#   # x: Vector, list of the parameters to determine
+#   # t, y, sigma: Vectors, observational data
+#   # f: Vector, function to minimize
+#   procf = Proc.new { |x, t, y, sigma, f|
+#     a = x[0]
+#     lambda = x[1]
+#     b = x[2]
+#     n = t.size
+#     for i in 0...n do
+#       yi = a*Math::exp(-lambda*t[i]) + b
+#       f[i] = (yi - y[i])/sigma[i]
+#     end
+#   }
+#
+#   # jac: Matrix, Jacobian
+#   procdf = Proc.new { |x, t, y, sigma, jac|
+#     a = x[0]
+#     lambda = x[1]
+#     n = t.size
+#     for i in 0...n do
+#       ti = t[i]
+#       si = sigma[i]
+#       ei = Math::exp(-lambda*ti)
+#       jac.set(i, 0, ei/si)
+#       jac.set(i, 1, -ti*a*ei/si)
+#       jac.set(i, 2, 1.0/si)
+#     end
+#   }
+#
+#   f = GSL::MultiFit::Function_fdf.alloc(procf, procdf, 2)
+#
+#   # Create data
+#   r = GSL::Rng.alloc()
+#   t = GSL::Vector.alloc(n)
+#   y = GSL::Vector.alloc(n)
+#   sigma = Vector.alloc(n)
+#   for i in 0...n do
+#     t[i] = i
+#     y[i] = 1.0 + 5*Math::exp(-0.1*t[i]) + r.gaussian(0.1)
+#     sigma[i] = 0.1
+#   end
+#
+#   f.set_data(t, y, sigma)
+#   x = GSL::Vector.alloc(1.0, 0.0, 0.0)    # initial guess
+#
+#   solver = GSL::FdfSolver.alloc(FdfSolver::LMSDER, n, np)
+#
+#   solver.set(f, x)
+#
+#   iter = 0
+#   solver.print_state(iter)
+#   begin
+#     iter += 1
+#     status = solver.iterate
+#     solver.print_state(iter)
+#     status = solver.test_delta(1e-4, 1e-4)
+#   end while status == GSL::CONTINUE and iter < 500
+#
+#   covar = solver.covar(0.0)
+#   position = solver.position
+#   chi2 = pow_2(solver.f.dnrm2)
+#   dof = n - np
+#   printf("A      = %.5f +/- %.5f\n", position[0], Math::sqrt(chi2/dof*covar[0][0]))
+#   printf("lambda = %.5f +/- %.5f\n", position[1], Math::sqrt(chi2/dof*covar[1][1]))
+#   printf("b      = %.5f +/- %.5f\n", position[2], Math::sqrt(chi2/dof*covar[2][2]))
+#
+#
+# === {}[link:index.html"name="8.2] Fitting to built-in functions
+#   #!/usr/bin/env ruby
+#   require("gsl")
+#   include MultiFit
+#
+#   N = 100
+#
+#   y0 = 1.0
+#   A = 2.0
+#   x0 = 3.0
+#   w = 0.5
+#
+#   r = Rng.alloc
+#   x = Vector.linspace(0.01, 10, N)
+#   sig = 1
+#   # Lognormal function with noise
+#   y =  y0 + A*Sf::exp(-pow_2(Sf::log(x/x0)/w)) + 0.1*Ran::gaussian(r, sig, N)
+#
+#   guess = [0, 3, 2, 1]
+#   coef, err, chi2, dof = MultiFit::FdfSolver.fit(x, y, "lognormal", guess)
+#   y0 = coef[0]
+#   amp = coef[1]
+#   x0 = coef[2]
+#   w = coef[3]
+#
+#   graph(x, y, y0+amp*Sf::exp(-pow_2(Sf::log(x/x0)/w)))
+#
+#
+# {prev}[link:files/rdoc/fit_rdoc.html]
+# {next}[link:files/rdoc/bspline_rdoc.html]
+#
+# {Reference index}[link:files/rdoc/ref_rdoc.html]
+# {top}[link:files/rdoc/index_rdoc.html]
+#
+#
+#