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 Here is an example using Powell's singular function.
  89 @c ===beg===
  90 @c load("minpack")$
  91 @c powell(x1,x2,x3,x4) := [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2, sqrt(10)*(x1-x4)^2]$
  92 @c minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4], [3,-1,0,1]);
  93 @c ===end===
  94 @example
  95 (%i1) load("minpack")$
  96 (%i2) powell(x1,x2,x3,x4) := [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2, sqrt(10)*(x1-x4)^2]$
  97 @group
  98 (%i3) minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4], [3,-1,0,1]);
  99 (%o3) [[1.6521175961683935e-17, - 1.6521175961683934e-18,
 100 2.6433881538694683e-18, 2.6433881538694683e-18],
 101 6.109327859207777e-34, 4]
 102 @end group
 103 @end example
 104
 105 Same problem but use numerical approximation to Jacobian.
 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 (%i1) load("minpack")$
 113 (%i2) powell(x1,x2,x3,x4) := [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2, sqrt(10)*(x1-x4)^2]$
 114 @group
 115 (%i3) minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4], [3,-1,0,1], jacobian = false);
 116 (%o3) [[5.060282149485331e-11, - 5.060282149491206e-12,
 117 2.1794478435472183e-11, 2.1794478435472183e-11],
 118 3.534491794847031e-21, 5]
 119 @end group
 120 @end example
 121
 122 @opencatbox{Categories:}
 123 @category{Package minpack}
 124 @closecatbox
 125
 126 @end deffn
 127
 128 @anchor{minpack_solve}
 129 @deffn {Function} minpack_solve @
 130 @fname{minpack_solve} (@var{flist}, @var{varlist}, @var{guess}) @
 131 @fname{minpack_solve} (..., 'tolerance = @var{tolerance}) @
 132 @fname{minpack_solve} (..., 'jacobian = @var{jacobian})
 133
 134 Solve a system of @code{n} equations in @code{n} unknowns.
 135 The @code{n} equations are given in the list @var{flist}, and the
 136 unknowns are in @var{varlist}.  An initial guess of the solution must
 137 be provided in @var{guess}.
 138
 139 Let @var{flist} be a list of @math{m} functions,
 140 m4_mathdot(<<<f_i(x_1, x_2, ..., x_n)>>>, <<<f_i(x_1, x_2, ..., x_n)>>>)
 141 Then this functions solves the system of @math{m} nonlinear equations
 142 in @math{n} variables:
 143
 144 m4_displaymath(
 145 <<<f_i(x_1, x_2, ..., x_n) = 0>>>,
 146 <<<f_i(x_1, x_2, ..., x_n) = 0>>>)
 147
 148 The optional keyword arguments, @var{tolerance} and @var{jacobian}
 149 provide some control over the algorithm.  @var{tolerance} is the
 150 estimated relative error desired in the sum of squares.
 151 @var{jacobian} can be used to specify the Jacobian.  If @var{jacobian}
 152 is not given or is @code{true} (the default), the Jacobian is computed
 153 from @var{flist}.  If @var{jacobian} is @code{false}, a numerical
 154 approximation is used.
 155
 156 @code{minpack_solve} returns a list.  The first item is the
 157 estimated solution; the second is the sum of squares, and the third
 158 indicates the success of the algorithm.  The possible values are
 159
 160 @table @code
 161 @item 0
 162 improper input parameters.
 163 @item 1
 164 algorithm estimates that the relative error in the solution is
 165 at most @code{tolerance}.
 166 @item 2
 167 number of calls to fcn with iflag = 1 has reached 100*(n+1).
 168 @item 3
 169 tol is too small. no further reduction in the sum of squares is
 170 possible.
 171 @item 4
 172 Iteration is not making good progress.
 173 @end table
 174
 175 @c ===beg===
 176 @c load("minpack")$
 177 @c powell(x1,x2,x3,x4) := [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2, sqrt(10)*(x1-x4)^2]$
 178 @c minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4], [3,-1,0,1]);
 179 @c ===end===
 180 @example
 181 (%i1) load("minpack")$
 182 (%i2) powell(x1,x2,x3,x4) := [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2, sqrt(10)*(x1-x4)^2]$
 183 @group
 184 (%i3) minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4], [3,-1,0,1]);
 185 (%o3) [[1.6521175961683935e-17, - 1.6521175961683934e-18,
 186 2.6433881538694683e-18, 2.6433881538694683e-18],
 187 6.109327859207777e-34, 4]
 188 @end group
 189 @end example
 190 In this particular case, we can solve this analytically:
 191 @c ===beg===
 192 @c powell(x1,x2,x3,x4) := [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2, sqrt(10)*(x1-x4)^2]$
 193 @c solve(powell(x1,x2,x3,x4),[x1,x2,x3,x4]);
 194 @c ===end===
 195 @example
 196 (%i1) powell(x1,x2,x3,x4) := [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2, sqrt(10)*(x1-x4)^2]$
 197 @group
 198 (%i2) solve(powell(x1,x2,x3,x4),[x1,x2,x3,x4]);
 199 (%o2)          [[x1 = 0, x2 = 0, x3 = 0, x4 = 0]]
 200 @end group
 201 @end example
 202 and we see that the numerical solution is quite close the analytical one.
 203
 204 @opencatbox{Categories:}
 205 @category{Package minpack}
 206 @closecatbox
 207
 208 @end deffn
 209
 210 @c Local Variables:
 211 @c mode: texinfo
 212 @c TeX-master: "include-maxima"
 213 @c End: