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