doc/info/minpack.texi

   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 The optional keyword arguments, @var{tolerance} and @var{jacobian}
  34 provide some control over the algorithm.  @var{tolerance} is the
  35 estimated relative error desired in the sum of squares.
  36 @var{jacobian} can be used to specify the Jacobian.  If @var{jacobian}
  37 is not given or is @code{true} (the default), the Jacobian is computed
  38 from @var{flist}.  If @var{jacobian} is @code{false}, a numerical
  39 approximation is used.
  40
  41 @code{minpack_lsquares} returns a list.  The first item is the
  42 estimated solution; the second is the sum of squares, and the third
  43 indicates the success of the algorithm.  The possible values are
  44
  45 @table @code
  46 @item 0
  47 improper input parameters.
  48 @item 1
  49 algorithm estimates that the relative error in the sum of squares is
  50 at most @code{tolerance}.
  51 @item 2
  52 algorithm estimates that the relative error between x and the solution
  53 is at most @code{tolerance}.
  54 @item 3
  55 conditions for info = 1 and info = 2 both hold.
  56 @item 4
  57 fvec is orthogonal to the columns of the jacobian to machine
  58 precision.
  59 @item 5
  60 number of calls to fcn with iflag = 1 has reached 100*(n+1).
  61 @item 6
  62 tol is too small. no further reduction in the sum of squares is
  63 possible.
  64 @item 7
  65 tol is too small. no further improvement in the approximate solution x
  66 is possible.
  67 @end table
  68
  69 @example
  70 /* Problem 6: Powell singular function */
  71 (%i1) powell(x1,x2,x3,x4) :=
  72          [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2,
  73               sqrt(10)*(x1-x4)^2]$
  74 (%i2) minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4],
  75                        [3,-1,0,1]);
  76 (%o2) [[1.652117596168394e-17, - 1.652117596168393e-18,
  77         2.643388153869468e-18, 2.643388153869468e-18],
  78        6.109327859207777e-34, 4]
  79 @end example
  80
  81 @example
  82 /* Same problem but use numerical approximation to Jacobian */
  83 (%i3) minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4],
  84                        [3,-1,0,1], jacobian = false);
  85 (%o3) [[5.060282149485331e-11, - 5.060282149491206e-12,
  86         2.179447843547218e-11, 2.179447843547218e-11],
  87        3.534491794847031e-21, 5]
  88 @end example
  89
  90 @opencatbox{Categories:}
  91 @category{Package minpack}
  92 @closecatbox
  93
  94 @end deffn
  95
  96 @anchor{minpack_solve}
  97 @deffn {Function} minpack_solve @
  98 @fname{minpack_solve} (@var{flist}, @var{varlist}, @var{guess}) @
  99 @fname{minpack_solve} (..., 'tolerance = @var{tolerance}) @
 100 @fname{minpack_solve} (..., 'jacobian = @var{jacobian})
 101
 102 Solve a system of @code{n} equations in @code{n} unknowns.
 103 The @code{n} equations are given in the list @var{flist}, and the
 104 unknowns are in @var{varlist}.  An initial guess of the solution must
 105 be provided in @var{guess}.
 106
 107 The optional keyword arguments, @var{tolerance} and @var{jacobian}
 108 provide some control over the algorithm.  @var{tolerance} is the
 109 estimated relative error desired in the sum of squares.
 110 @var{jacobian} can be used to specify the Jacobian.  If @var{jacobian}
 111 is not given or is @code{true} (the default), the Jacobian is computed
 112 from @var{flist}.  If @var{jacobian} is @code{false}, a numerical
 113 approximation is used.
 114
 115 @code{minpack_solve} returns a list.  The first item is the
 116 estimated solution; the second is the sum of squares, and the third
 117 indicates the success of the algorithm.  The possible values are
 118
 119 @table @code
 120 @item 0
 121 improper input parameters.
 122 @item 1
 123 algorithm estimates that the relative error in the solution is
 124 at most @code{tolerance}.
 125 @item 2
 126 number of calls to fcn with iflag = 1 has reached 100*(n+1).
 127 @item 3
 128 tol is too small. no further reduction in the sum of squares is
 129 possible.
 130 @item 4
 131 Iteration is not making good progress.
 132 @end table
 133
 134 @example
 135 /* Problem 6: Powell singular function */
 136 (%i1) powell(x1,x2,x3,x4) :=
 137          [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2,
 138               sqrt(10)*(x1-x4)^2]$
 139 (%i2) minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4],
 140                        [3,-1,0,1]);
 141 (%o2) [[8.586306796471285e-19, - 8.586306796471285e-20,
 142        1.902656479186597e-18, 1.902656479186597e-18], 1.552862701642987e-35, 4]
 143 @end example
 144 In this particular case, we can solve this analytically:
 145 @example
 146 (%i3) solve(powell(x1,x2,x3,x4),[x1,x2,x3,x4]);
 147 (%o3)       [[x1 = 0, x2 = 0, x3 = 0, x4 = 0]]
 148 @end example
 149 and we see that the numerical solution is quite close the analytical one.
 150
 151 @opencatbox{Categories:}
 152 @category{Package minpack}
 153 @closecatbox
 154
 155 @end deffn
 156
 157 @c Local Variables:
 158 @c mode: texinfo
 159 @c TeX-master: "include-maxima"
 160 @c End: