doc/info/minpack.texi.m4

   1 @menu
   2 * Introduction to minpack::
   3 * Functions and Variables for minpack::
   4 @end menu
   5
   6 @node Introduction to minpack, Functions and Variables for minpack, Package minpack, Package minpack
   7 @section Introduction to minpack
   8
   9 @code{Minpack} is a Common Lisp translation (via @code{f2cl}) of the
  10 Fortran library MINPACK, as obtained from Netlib.
  11
  12 @opencatbox{Categories:}
  13 @category{Numerical methods}
  14 @category{Optimization}
  15 @category{Share packages}
  16 @category{Package minpack}
  17 @closecatbox
  18
  19 @node Functions and Variables for minpack,  , Introduction to minpack, Package minpack
  20 @section Functions and Variables for minpack
  21
  22 @anchor{minpack_lsquares}
  23 @deffn {Function} minpack_lsquares @
  24 @fname{minpack_lsquares} (@var{flist}, @var{varlist}, @var{guess}) @
  25 @fname{minpack_lsquares} (..., 'tolerance = @var{tolerance}) @
  26 @fname{minpack_lsquares} (..., 'jacobian = @var{jacobian})
  27
  28 Compute the point that minimizes the sum of the squares of the
  29 functions in the list @var{flist}.  The variables are in the list
  30 @var{varlist}.  An initial guess of the optimum point must be provided
  31 in @var{guess}.
  32
  33 Let @var{flist} be a list of @math{m} functions,
  34 m4_mathdot(<<<f_i(x_1, x_2, ..., x_n)>>>, <<<f_i(x_1, x_2, ..., x_n)>>>)
  35 Then this function can be used to find the values of
  36 m4_math(<<<x_1, x_2, ..., x_n>>>, <<<x_1, x_2, ..., x_n>>>)
  37 that solve the least squares problem
  38
  39 m4_displaymath(
  40 <<<\sum_i^m f_i(x_1, x_2,...,x_n)^2>>>,
  41 <<<
  42                m
  43               ____
  44               ╲      2
  45                ⟩    f (x_1, x_2,..., x_n)
  46               ╱      i
  47               ‾‾‾‾
  48               i = 1
  49 >>>)
  50
  51
  52 The optional keyword arguments, @var{tolerance} and @var{jacobian}
  53 provide some control over the algorithm.  @var{tolerance} is the
  54 estimated relative error desired in the sum of squares.
  55 @var{jacobian} can be used to specify the Jacobian.  If @var{jacobian}
  56 is not given or is @code{true} (the default), the Jacobian is computed
  57 from @var{flist}.  If @var{jacobian} is @code{false}, a numerical
  58 approximation is used.
  59
  60 @code{minpack_lsquares} returns a list.  The first item is the
  61 estimated solution; the second is the sum of squares, and the third
  62 indicates the success of the algorithm.  The possible values are
  63
  64 @table @code
  65 @item 0
  66 improper input parameters.
  67 @item 1
  68 algorithm estimates that the relative error in the sum of squares is
  69 at most @code{tolerance}.
  70 @item 2
  71 algorithm estimates that the relative error between x and the solution
  72 is at most @code{tolerance}.
  73 @item 3
  74 conditions for info = 1 and info = 2 both hold.
  75 @item 4
  76 fvec is orthogonal to the columns of the jacobian to machine
  77 precision.
  78 @item 5
  79 number of calls to fcn with iflag = 1 has reached 100*(n+1).
  80 @item 6
  81 tol is too small. no further reduction in the sum of squares is
  82 possible.
  83 @item 7
  84 tol is too small. no further improvement in the approximate solution x
  85 is possible.
  86 @end table
  87
  88 @c ===beg===
  89 @c load("minpack")$
  90 @c powell(x1,x2,x3,x4) := [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2, sqrt(10)*(x1-x4)^2];
  91 @c minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4], [3,-1,0,1]);
  92 @c ===end===
  93 @example
  94 /* Problem 6: Powell singular function */
  95 (%i1) powell(x1,x2,x3,x4) :=
  96          [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2,
  97               sqrt(10)*(x1-x4)^2]$
  98 (%i2) minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4],
  99                        [3,-1,0,1]);
 100 (%o2) [[1.652117596168394e-17, - 1.652117596168393e-18,
 101         2.643388153869468e-18, 2.643388153869468e-18],
 102        6.109327859207777e-34, 4]
 103 @end example
 104
 105
 106 @c ===beg===
 107 @c load("minpack")$
 108 @c powell(x1,x2,x3,x4) := [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2, sqrt(10)*(x1-x4)^2];
 109 @c minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4], [3,-1,0,1], jacobian = false);
 110 @c ===end===
 111 @example
 112 /* Same problem but use numerical approximation to Jacobian */
 113 (%i3) minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4],
 114                        [3,-1,0,1], jacobian = false);
 115 (%o3) [[5.060282149485331e-11, - 5.060282149491206e-12,
 116         2.179447843547218e-11, 2.179447843547218e-11],
 117        3.534491794847031e-21, 5]
 118 @end example
 119
 120 @opencatbox{Categories:}
 121 @category{Package minpack}
 122 @closecatbox
 123
 124 @end deffn
 125
 126 @anchor{minpack_solve}
 127 @deffn {Function} minpack_solve @
 128 @fname{minpack_solve} (@var{flist}, @var{varlist}, @var{guess}) @
 129 @fname{minpack_solve} (..., 'tolerance = @var{tolerance}) @
 130 @fname{minpack_solve} (..., 'jacobian = @var{jacobian})
 131
 132 Solve a system of @code{n} equations in @code{n} unknowns.
 133 The @code{n} equations are given in the list @var{flist}, and the
 134 unknowns are in @var{varlist}.  An initial guess of the solution must
 135 be provided in @var{guess}.
 136
 137 Let @var{flist} be a list of @math{m} functions,
 138 m4_mathdot(<<<f_i(x_1, x_2, ..., x_n)>>>, <<<f_i(x_1, x_2, ..., x_n)>>>)
 139 Then this functions solves the system of @math{m} nonlinear equations
 140 in @math{n} variables:
 141
 142 m4_displaymath(
 143 <<<f_i(x_1, x_2, ..., x_n) = 0>>>,
 144 <<<f_i(x_1, x_2, ..., x_n) = 0>>>)
 145
 146 The optional keyword arguments, @var{tolerance} and @var{jacobian}
 147 provide some control over the algorithm.  @var{tolerance} is the
 148 estimated relative error desired in the sum of squares.
 149 @var{jacobian} can be used to specify the Jacobian.  If @var{jacobian}
 150 is not given or is @code{true} (the default), the Jacobian is computed
 151 from @var{flist}.  If @var{jacobian} is @code{false}, a numerical
 152 approximation is used.
 153
 154 @code{minpack_solve} returns a list.  The first item is the
 155 estimated solution; the second is the sum of squares, and the third
 156 indicates the success of the algorithm.  The possible values are
 157
 158 @table @code
 159 @item 0
 160 improper input parameters.
 161 @item 1
 162 algorithm estimates that the relative error in the solution is
 163 at most @code{tolerance}.
 164 @item 2
 165 number of calls to fcn with iflag = 1 has reached 100*(n+1).
 166 @item 3
 167 tol is too small. no further reduction in the sum of squares is
 168 possible.
 169 @item 4
 170 Iteration is not making good progress.
 171 @end table
 172
 173 @c ===beg===
 174 @c powell(x1,x2,x3,x4) := [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2, sqrt(10)*(x1-x4)^2];
 175 @c minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4], [3,-1,0,1]);
 176 @c ===end===
 177 @example
 178 /* Problem 6: Powell singular function */
 179 (%i1) powell(x1,x2,x3,x4) :=
 180          [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2,
 181               sqrt(10)*(x1-x4)^2]$
 182 (%i2) minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4],
 183                        [3,-1,0,1]);
 184 (%o2) [[8.586306796471285e-19, - 8.586306796471285e-20,
 185        1.902656479186597e-18, 1.902656479186597e-18], 1.552862701642987e-35, 4]
 186 @end example
 187 In this particular case, we can solve this analytically:
 188 @c ===beg===
 189 @c powell(x1,x2,x3,x4) := [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2,
 190 @c sqrt(10)*(x1-x4)^2];
 191 @c solve(powell(x1,x2,x3,x4),[x1,x2,x3,x4]);
 192 @c ===end===
 193 @example
 194 (%i3) solve(powell(x1,x2,x3,x4),[x1,x2,x3,x4]);
 195 (%o3)       [[x1 = 0, x2 = 0, x3 = 0, x4 = 0]]
 196 @end example
 197 and we see that the numerical solution is quite close the analytical one.
 198
 199 @opencatbox{Categories:}
 200 @category{Package minpack}
 201 @closecatbox
 202
 203 @end deffn
 204
 205 @c Local Variables:
 206 @c mode: texinfo
 207 @c TeX-master: "include-maxima"
 208 @c End: