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, minpack-pkg, minpack-pkg
   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, minpack-pkg
  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 @end deffn
  91
  92 @anchor{minpack_solve}
  93 @deffn {Function} minpack_solve @
  94 @fname{minpack_solve} (@var{flist}, @var{varlist}, @var{guess}) @
  95 @fname{minpack_solve} (..., 'tolerance = @var{tolerance}) @
  96 @fname{minpack_solve} (..., 'jacobian = @var{jacobian})
  97
  98 Solve a system of @code{n} equations in @code{n} unknowns.
  99 The @code{n} equations are given in the list @var{flist}, and the
 100 unknowns are in @var{varlist}.  An initial guess of the solution must
 101 be provided in @var{guess}.
 102
 103 The optional keyword arguments, @var{tolerance} and @var{jacobian}
 104 provide some control over the algorithm.  @var{tolerance} is the
 105 estimated relative error desired in the sum of squares.
 106 @var{jacobian} can be used to specify the Jacobian.  If @var{jacobian}
 107 is not given or is @code{true} (the default), the Jacobian is computed
 108 from @var{flist}.  If @var{jacobian} is @code{false}, a numerical
 109 approximation is used.
 110
 111 @code{minpack_solve} returns a list.  The first item is the
 112 estimated solution; the second is the sum of squares, and the third
 113 indicates the success of the algorithm.  The possible values are
 114
 115 @table @code
 116 @item 0
 117 improper input parameters.
 118 @item 1
 119 algorithm estimates that the relative error in the solution is
 120 at most @code{tolerance}.
 121 @item 2
 122 number of calls to fcn with iflag = 1 has reached 100*(n+1).
 123 @item 3
 124 tol is too small. no further reduction in the sum of squares is
 125 possible.
 126 @item 4
 127 Iteration is not making good progress.
 128 @end table
 129
 130 @example
 131 /* Problem 6: Powell singular function */
 132 (%i1) powell(x1,x2,x3,x4) :=
 133          [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2,
 134               sqrt(10)*(x1-x4)^2]$
 135 (%i2) minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4],
 136                        [3,-1,0,1]);
 137 (%o2) [[8.586306796471285e-19, - 8.586306796471285e-20,
 138        1.902656479186597e-18, 1.902656479186597e-18], 1.552862701642987e-35, 4]
 139 @end example
 140 In this particular case, we can solve this analytically:
 141 @example
 142 (%i3) solve(powell(x1,x2,x3,x4),[x1,x2,x3,x4]);
 143 (%o3)       [[x1 = 0, x2 = 0, x3 = 0, x4 = 0]]
 144 @end example
 145 and we see that the numerical solution is quite close the analytical one.
 146
 147 @end deffn
 148
 149 @c Local Variables:
 150 @c mode: texinfo
 151 @c TeX-master: "include-maxima"
 152 @c End: