doc/info/hompack.texi

   1 @menu
   2 * Introduction to hompack::
   3 * Functions and Variables for hompack::
   4 @end menu
   5
   6 @node Introduction to hompack, Functions and Variables for hompack, , Package hompack
   7 @section Introduction to hompack
   8
   9 @code{Hompack} is a Common Lisp translation (via @code{f2cl}) of the
  10 Fortran library HOMPACK, as obtained from Netlib.
  11
  12 @opencatbox{Categories:}
  13 @category{Numerical methods}
  14 @category{Share packages}
  15 @category{Package hompack}
  16 @closecatbox
  17
  18 @node Functions and Variables for hompack,  , Introduction to hompack, Package hompack
  19 @section Functions and Variables for hompack
  20
  21 @anchor{hompack_polsys}
  22 @deffn {Function} hompack_polsys (@var{eqnlist}, @var{varlist} [, @var{iflg1}, @var{epsbig}, @var{epssml}, @var{numrr}])
  23 Finds the roots of the system of polynomials in the variables
  24 @var{varlist} in the system of equations in @var{eqnlist}.  The number
  25 of equations must match number of variables.  Each equation must be a
  26 polynomial with variables in @var{varlist}.  The coefficients must be
  27 real numbers.
  28
  29 The optional keyword arguments provide some control over the
  30 algorithm.
  31
  32 @table @code
  33 @item epsbig
  34 is the local error tolerance allowed by the
  35 path tracker, defaulting to 1e-4.
  36 @item epssml
  37 is the accuracy
  38 desired for the final solution, defaulting to 1d-14.
  39 @item numrr
  40 is the number of multiples of 1000 steps that will be tried
  41 before abandoning a path, defaulting to 10.
  42 @item iflg1
  43 defaulting to 0, controls the algorithm as follows:
  44 @table @code
  45 @item 0
  46 If the problem is to be solved without calling @code{polsys}' scaling
  47 routine, @code{sclgnp}, and without using the projective
  48 transformation.
  49 @item 1
  50 If scaling but no projective transformation is to be used.
  51 @item 10
  52 If no scaling but projective transformation is to be used.
  53 @item 11
  54 If both scaling and projective transformation are to be used.
  55 @end table
  56 @end table
  57
  58 @code{hompack_polsys} returns a list.  The elements of the list are:
  59 @table @code
  60 @item retcode
  61 Indicates whether the solution is valid or not.
  62 @table @code
  63 @item 0
  64 Solution found without problems
  65 @item 1
  66 Solution succeeded but @code{iflg2} indicates some issues with a
  67 root. (That is, @code{iflg2} is not all ones.)
  68 @item -1
  69 @code{NN}, the declared dimension of the number of terms in the
  70 polynomials,  is too small.  (This should not happen.)
  71 @item -2
  72 @code{MMAXT}, the declared dimension for the internal coefficient and
  73 degree arrays, is too small.  (This should not happen.)
  74 @item -3
  75 @code{TTOTDG}, the total degree of the equations,  is too small.
  76 (This should not happen.)
  77 @item -4
  78 @code{LENWK}, the length of the internal real work array, is too
  79 small.  (This should not happen.)
  80 @item -5
  81 @code{LENIWK}, the length of the internal integer work array, is too
  82 small.  (This should not happen.)
  83 @item -6
  84 @var{iflg1} is not 0 or 1, or 10 or 11.  (This should not happen; an
  85 error should be thrown before @code{polsys} is called.)
  86 @end table
  87 @item roots
  88 The roots of the system of equations.  This is in the same format as
  89 @code{solve} would return.
  90 @item iflg2
  91 A list containing information on how the path for the m'th root terminated:
  92 @table @code
  93 @item 1
  94 Normal return
  95 @item 2
  96 Specified error tolerance cannot be met.  Increase @var{epsbig} and
  97 @var{epssml}  and rerun.
  98 @item 3
  99 Maximum number of steps exceeded.  To track the path further, increase
 100 @var{numrr} and rerun the path.  However, the path may be diverging, if the
 101 lambda value is near 1 and the roots values are large.
 102 @item 4
 103 Jacobian matrix does not have full rank.  The algorithm has failed
 104 (the zero curve of the homotopy map cannot be followed any further).
 105 @item 5
 106 The tracking algorithm has lost the zero curve of the homotopy map and
 107 is not making progress.  The error tolerances @var{epsbig} and
 108 @var{epssml} were too lenient.  The problem should be restarted with
 109 smaller error tolerances.
 110 @item 6
 111 The normal flow newton iteration in @code{stepnf} or @code{rootnf}
 112 failed to converge.  The error tolerance @var{epsbig} may be too
 113 stringent.
 114 @item 7
 115 Illegal input parameters, a fatal error.
 116 @end table
 117 @item lambda
 118 A list of the final lambda value for the m-th root, where lambda is the
 119 continuation parameter.
 120 @item arclen
 121 A list of the arc length of the m-th root.
 122 @item nfe
 123 A list of the number of jacobian matrix evaluations required to track the m-th
 124 root.
 125 @end table
 126
 127 Here are some examples of using @code{hompack_polsys}.
 128 @example
 129 (%i1) load(hompack)$
 130 (%i2) hompack_polsys([x1^2-1, x2^2-2],[x1,x2]);
 131 (%o2) [0,
 132        [[x1 = (-1.354505666901954e-16*%i)-0.9999999999999999,
 133          x2 = 3.52147935979316e-16*%i-1.414213562373095],
 134         [x1 = 1.0-5.536432658639868e-18*%i,
 135          x2 = (-4.213674137126362e-17*%i)-1.414213562373095],
 136         [x1 = (-9.475939894034927e-17*%i)-1.0,
 137          x2 = 2.669654624736742e-16*%i+1.414213562373095],
 138         [x1 = 9.921253413273088e-18*%i+1.0,
 139          x2 = 1.414213562373095-5.305667769855424e-17*%i]],[1,1,1,1],
 140        [1.0,1.0,0.9999999999999996,1.0],
 141        [4.612623769341193,4.612623010859902,4.612623872939383,
 142         4.612623114484402],[40,40,40,40]]
 143 @end example
 144
 145 The analytical solution can be obtained with solve:
 146 @example
 147 (%i1) solve([x1^2-1, x2^2-2],[x1,x2]);
 148 (%o1) [[x1 = 1,x2 = -sqrt(2)],[x1 = 1,x2 = sqrt(2)],[x1 = -1,x2 = -sqrt(2)],
 149         [x1 = -1,x2 = sqrt(2)]]
 150 @end example
 151 We see that @code{hompack_polsys} returned the correct answer except
 152 that the roots are in a different order and there is a small imaginary
 153 part.
 154
 155 Another example, with corresponding solution from solve:
 156 @example
 157 (%i1) hompack_polsys([x1^2 + 2*x2^2 + x1*x2 - 5, 2*x1^2 + x2^2 + x2-4],[x1,x2]);
 158 (%o1) [0,
 159        [[x1 = 1.201557301700783-1.004786320788336e-15*%i,
 160          x2 = (-4.376615092392437e-16*%i)-1.667270363480143],
 161         [x1 = 1.871959754090949e-16*%i-1.428529189565313,
 162          x2 = (-6.301586314393093e-17*%i)-0.9106199083334113],
 163         [x1 = 0.5920619420732697-1.942890293094024e-16*%i,
 164          x2 = 6.938893903907228e-17*%i+1.383859154368197],
 165         [x1 = 7.363503717463654e-17*%i+0.08945540033671608,
 166          x2 = 1.557667481081721-4.109128293931921e-17*%i]],[1,1,1,1],
 167        [1.000000000000001,1.0,1.0,1.0],
 168        [6.205795654034752,7.722213259390295,7.228287079174351,
 169         5.611474283583368],[35,41,48,40]]
 170 (%i2) solve([x1^2+2*x2^2+x1*x2 - 5, 2*x1^2+x2^2+x2-4],[x1,x2]);
 171 (%o2) [[x1 = 0.08945540336850383,x2 = 1.557667386609071],
 172        [x1 = 0.5920619554695062,x2 = 1.383859286083807],
 173        [x1 = 1.201557352500749,x2 = -1.66727025803531],
 174        [x1 = -1.428529150636283,x2 = -0.9106198942815954]]
 175 @end example
 176
 177 Note that @code{hompack_polsys} can sometimes be very slow.  Perhaps
 178 @code{solve} can be used.  Or perhaps @code{eliminate} can be used to
 179 convert the system of polynomials into one polynomial for which
 180 @code{allroots} can find all the roots.
 181
 182 @opencatbox{Categories:}
 183 @category{Package hompack}
 184 @closecatbox
 185
 186 @end deffn
 187
 188 @c Local Variables:
 189 @c mode: texinfo
 190 @c TeX-master: "include-maxima"
 191 @c End: