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