From 84a752088df247d81dc88eae4807de470e22c16f Mon Sep 17 00:00:00 2001
From: Thierry Moisan <thierry.moisan@gmail.com>
Date: Fri, 25 Jul 2008 13:00:43 -0400
Subject: [PATCH] Adding some documentation and a test to Multifit

---
 Multifit.i                    | 17 ++++++++++-------
 lib/Math/GSL/Multifit/Test.pm |  6 ++++++
 2 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/Multifit.i b/Multifit.i
index 617c22c..96b102b 100644
--- a/Multifit.i
+++ b/Multifit.i
@@ -38,7 +38,9 @@
                gsl_multifit_fdfsolver_name 
                gsl_multifit_fdfsolver_position 
                gsl_multifit_test_delta 
-               gsl_multifit_test_gradient 
+               gsl_multifit_test_gradient
+               $gsl_multifit_fdfsolver_lmder
+               $gsl_multifit_fdfsolver_lmsder; 
              /;
 %EXPORT_TAGS = ( all => [ @EXPORT_OK ] );
 
@@ -74,13 +76,17 @@ Here is a list of all the functions in this module :
 
 =item C<gsl_multifit_linear_est($x, $c, $cov)> - This function uses the best-fit multilinear regression coefficients vector $c and their covariance matrix $cov to compute the fitted function value $y and its standard deviation $y_err for the model y = x.c at the point $x, in the form of a vector. The functions returns 3 values in this order : 0 if the operation succeeded, 1 otherwise, the fittes function value and its standard deviation. 
 
-=item C<gsl_multifit_linear_residuals($X, $y, $c, $r) > - This function computes the vector of residuals r = y - X c for the observations vector $y, coefficients vector $c and matrix of predictor variables $X. $r is also a vector.
+=item C<gsl_multifit_linear_residuals($X, $y, $c, $r)> - This function computes the vector of residuals r = y - X c for the observations vector $y, coefficients vector $c and matrix of predictor variables $X. $r is also a vector.
 
-=item C<gsl_multifit_gradient >
+=item C<gsl_multifit_gradient($J, $f, $g)> - This function computes the gradient $g of \Phi(x) = (1/2) ||F(x)||^2 from the Jacobian matrix $J and the function values $f, using the formula $g = $J^T $f. $g and $f are vectors.
+
+=item C<gsl_multifit_test_gradient($g, $epsabas)> - This function tests the residual gradient vector $g against the absolute error bound $epsabs. Mathematically, the gradient should be exactly zero at the minimum. The test returns $GSL_SUCCESS if the following condition is achieved, \sum_i |g_i| < $epsabs and returns $GSL_CONTINUE 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. 
+
+=item C<gsl_multifit_test_delta($dx, $x, $epsabs, $epsrel)> - This function tests for the convergence of the sequence by comparing the last step vector $dx with the absolute error $epsabs and relative error $epsrel to the current position x. The test returns $GSL_SUCCESS if the following condition is achieved, |dx_i| < epsabs + epsrel |x_i| for each component of x and returns $GSL_CONTINUE otherwise. 
 
 =item C<gsl_multifit_covar >
 
-=item C<gsl_multifit_fsolver_alloc >
+=item C<gsl_multifit_fsolver_alloc($T, $n, $p)>
 
 =item C<gsl_multifit_fsolver_free >
 
@@ -104,9 +110,6 @@ Here is a list of all the functions in this module :
 
 =item C<gsl_multifit_fdfsolver_position >
 
-=item C<gsl_multifit_test_delta >
-
-=item C<gsl_multifit_test_gradient >
 
 =back
 
diff --git a/lib/Math/GSL/Multifit/Test.pm b/lib/Math/GSL/Multifit/Test.pm
index 100c34f..ace775c 100644
--- a/lib/Math/GSL/Multifit/Test.pm
+++ b/lib/Math/GSL/Multifit/Test.pm
@@ -249,4 +249,10 @@ my $filip_y = [0.8116, 0.9072, 0.9052, 0.9039, 0.8053, 0.8377,
     @got = gsl_blas_ddot($r, $r);
     ok(is_similar_relative($got[1], $expected_chisq, 10**-7), "filip gsl_fit_wmultilinear residuals") ;
 }
+
+sub GSL_MULTIFIT_FSOLVER_ALLOC : Tests {
+   local $TODO = "The first argument comes from gsl_multifit_nlin.h and is of the right type, how to fix this?";
+#   my $fsolver = gsl_multifit_fsolver_alloc($gsl_multifit_fdfsolver_lmder, 100, 3);
+#   isa_ok($fsolver, 'Math::GSL::Multifit');
+}
 1;
-- 
2.11.4.GIT