Remove some debugging prints and add comments
[maxima.git] / doc / info / hompack.texi
blob8e72ac82389cc8649e047a6216094f1366611746
1 @menu
2 * Introduction to hompack::
3 * Functions and Variables for hompack::  
4 @end menu
6 @node Introduction to hompack, Functions and Variables for hompack, , Package hompack
7 @section Introduction to hompack
9 @code{Hompack} is a Common Lisp translation (via @code{f2cl}) of the
10 Fortran library HOMPACK, as obtained from Netlib.
12 @opencatbox{Categories:}
13 @category{Numerical methods} 
14 @category{Share packages}
15 @category{Package hompack}
16 @closecatbox
18 @node Functions and Variables for hompack,  , Introduction to hompack, Package hompack
19 @section Functions and Variables for hompack
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.
29 The optional keyword arguments provide some control over the
30 algorithm.
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
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
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
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.
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
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.
182 @opencatbox{Categories:}
183 @category{Package hompack}
184 @closecatbox
186 @end deffn
188 @c Local Variables: 
189 @c mode: texinfo
190 @c TeX-master: "include-maxima"
191 @c End: