doc/info/mnewton.texi

   1 @menu
   2 * Introduction to mnewton::
   3 * Functions and Variables for mnewton::
   4 @end menu
   5
   6 @c -----------------------------------------------------------------------------
   7 @node Introduction to mnewton, Functions and Variables for mnewton, Package mnewton, Package mnewton
   8 @section Introduction to mnewton
   9 @c -----------------------------------------------------------------------------
  10
  11 @code{mnewton} is an implementation of Newton's method for solving nonlinear
  12 equations in one or more variables.
  13
  14 @opencatbox{Categories:}
  15 @category{Numerical methods}
  16 @category{Share packages}
  17 @category{Package mnewton}
  18 @closecatbox
  19
  20 @c -----------------------------------------------------------------------------
  21 @node Functions and Variables for mnewton,  , Introduction to mnewton, Package mnewton
  22 @section Functions and Variables for mnewton
  23 @c -----------------------------------------------------------------------------
  24
  25 @c -----------------------------------------------------------------------------
  26 @anchor{newtonepsilon}
  27 @defvr {Option variable} newtonepsilon
  28 Default value: @code{10.0^(-fpprec/2)}
  29
  30 Precision to determine when the @code{mnewton} function has converged towards
  31 the solution.
  32
  33 When @code{newtonepsilon} is a bigfloat,
  34 @code{mnewton} computations are done with bigfloats;
  35 otherwise, ordinary floats are used.
  36
  37 See also @mrefdot{mnewton}
  38
  39 @opencatbox{Categories:}
  40 @category{Package mnewton}
  41 @closecatbox
  42 @end defvr
  43
  44 @c -----------------------------------------------------------------------------
  45 @anchor{newtonmaxiter}
  46 @defvr {Option variable} newtonmaxiter
  47 Default value: @code{50}
  48
  49 Maximum number of iterations to stop the @code{mnewton} function
  50 if it does not converge or if it converges too slowly.
  51
  52 See also @mrefdot{mnewton}
  53
  54 @opencatbox{Categories:}
  55 @category{Package mnewton}
  56 @closecatbox
  57 @end defvr
  58
  59 @c -----------------------------------------------------------------------------
  60 @anchor{newtondebug}
  61 @defvr {Option variable} newtondebug
  62 Default value: @code{false}
  63
  64 When @code{newtondebug} is @code{true},
  65 @code{mnewton} prints out debugging information while solving a problem.
  66
  67 @opencatbox{Categories:}
  68 @category{Package mnewton}
  69 @closecatbox
  70 @end defvr
  71
  72 @c -----------------------------------------------------------------------------
  73 @anchor{mnewton}
  74 @deffn {Function} mnewton @
  75 @fname{mnewton} (@var{FuncList}, @var{VarList}, @var{GuessList}) @
  76 @fname{mnewton} (@var{FuncList}, @var{VarList}, @var{GuessList}, @var{DF})
  77
  78 Approximate solution of multiple nonlinear equations by Newton's method.
  79
  80 @var{FuncList} is a list of functions to solve,
  81 @var{VarList} is a list of variable names, and
  82 @var{GuessList} is a list of initial approximations.
  83 The optional argument @var{DF} is the Jacobian matrix of the list of functions;
  84 if not supplied, it is calculated automatically from @var{FuncList}.
  85
  86 @var{FuncList} may be specified as a list of equations,
  87 in which case the function to be solved is the left-hand side of each equation minus the right-hand side.
  88
  89 If there is only a single function, variable, and initial point,
  90 they may be specified as a single expression, variable, and initial value;
  91 they need not be lists of one element.
  92
  93 A variable may be a simple symbol or a subscripted symbol.
  94
  95 The solution, if any, is returned as a list of one element,
  96 which is a list of equations, one for each variable,
  97 specifying an approximate solution;
  98 this is the same format as returned by @code{solve}.
  99 If the solution is not found, @code{[]} is returned.
 100
 101 Functions and initial points may contain complex numbers,
 102 and solutions likewise may contain complex numbers.
 103
 104 @code{mnewton} is governed by global variables @mref{newtonepsilon} and
 105 @mrefcomma{newtonmaxiter} and the global flag @mrefdot{newtondebug}
 106
 107 @code{load("mnewton")} loads this function.
 108
 109 See also @mrefcomma{realroots} @mrefcomma{allroots} @mref{find_root} and
 110 @mrefdot{newton}
 111
 112 Examples:
 113
 114 @example
 115 (%i1) load("mnewton")$
 116
 117 (%i2) mnewton([x1+3*log(x1)-x2^2, 2*x1^2-x1*x2-5*x1+1],
 118               [x1, x2], [5, 5]);
 119 (%o2) [[x1 = 3.756834008012769, x2 = 2.779849592817897]]
 120 (%i3) mnewton([2*a^a-5],[a],[1]);
 121 (%o3)             [[a = 1.70927556786144]]
 122 (%i4) mnewton([2*3^u-v/u-5, u+2^v-4], [u, v], [2, 2]);
 123 (%o4) [[u = 1.066618389595407, v = 1.552564766841786]]
 124 @end example
 125
 126 The variable @code{newtonepsilon} controls the precision of the
 127 approximations.  It also controls if computations are performed with
 128 floats or bigfloats.
 129
 130 @example
 131 (%i1) load("mnewton")$
 132
 133 (%i2) (fpprec : 25, newtonepsilon : bfloat(10^(-fpprec+5)))$
 134
 135 (%i3) mnewton([2*3^u-v/u-5, u+2^v-4], [u, v], [2, 2]);
 136 (%o3) [[u = 1.066618389595406772591173b0,
 137                                v = 1.552564766841786450100418b0]]
 138 @end example
 139
 140 @opencatbox{Categories:}
 141 @category{Package mnewton}
 142 @closecatbox
 143 @end deffn
 144