@menu
* Introduction to hompack::
* Functions and Variables for hompack::  
@end menu

@node Introduction to hompack, Functions and Variables for hompack, , Package hompack
@section Introduction to hompack

@code{Hompack} is a Common Lisp translation (via @code{f2cl}) of the
Fortran library HOMPACK, as obtained from Netlib.

@opencatbox{Categories:}
@category{Numerical methods} 
@category{Share packages}
@category{Package hompack}
@closecatbox

@node Functions and Variables for hompack,  , Introduction to hompack, Package hompack
@section Functions and Variables for hompack

@anchor{hompack_polsys}
@deffn {Function} hompack_polsys (@var{eqnlist}, @var{varlist} [, @var{iflg1}, @var{epsbig}, @var{epssml}, @var{numrr}])
Finds the roots of the system of polynomials in the variables
@var{varlist} in the system of equations in @var{eqnlist}.  The number
of equations must match number of variables.  Each equation must be a
polynomial with variables in @var{varlist}.  The coefficients must be
real numbers.

The optional keyword arguments provide some control over the
algorithm.

@table @code
@item epsbig
is the local error tolerance allowed by the
path tracker, defaulting to 1e-4.
@item epssml
is the accuracy
desired for the final solution, defaulting to 1d-14.
@item numrr
is the number of multiples of 1000 steps that will be tried
before abandoning a path, defaulting to 10.
@item iflg1
defaulting to 0, controls the algorithm as follows:
@table @code
@item 0
If the problem is to be solved without calling @code{polsys}' scaling
routine, @code{sclgnp}, and without using the projective
transformation.
@item 1
If scaling but no projective transformation is to be used.
@item 10
If no scaling but projective transformation is to be used.
@item 11
If both scaling and projective transformation are to be used.
@end table
@end table

@code{hompack_polsys} returns a list.  The elements of the list are:
@table @code
@item retcode
Indicates whether the solution is valid or not.
@table @code
@item 0
Solution found without problems
@item 1
Solution succeeded but @code{iflg2} indicates some issues with a
root. (That is, @code{iflg2} is not all ones.)
@item -1
@code{NN}, the declared dimension of the number of terms in the
polynomials,  is too small.  (This should not happen.)
@item -2
@code{MMAXT}, the declared dimension for the internal coefficient and
degree arrays, is too small.  (This should not happen.)
@item -3
@code{TTOTDG}, the total degree of the equations,  is too small.
(This should not happen.)
@item -4
@code{LENWK}, the length of the internal real work array, is too
small.  (This should not happen.)
@item -5
@code{LENIWK}, the length of the internal integer work array, is too
small.  (This should not happen.)
@item -6
@var{iflg1} is not 0 or 1, or 10 or 11.  (This should not happen; an
error should be thrown before @code{polsys} is called.)
@end table
@item roots
The roots of the system of equations.  This is in the same format as
@code{solve} would return.
@item iflg2
A list containing information on how the path for the m'th root terminated:
@table @code
@item 1
Normal return
@item 2
Specified error tolerance cannot be met.  Increase @var{epsbig} and
@var{epssml}  and rerun.
@item 3
Maximum number of steps exceeded.  To track the path further, increase
@var{numrr} and rerun the path.  However, the path may be diverging, if the
lambda value is near 1 and the roots values are large.
@item 4
Jacobian matrix does not have full rank.  The algorithm has failed
(the zero curve of the homotopy map cannot be followed any further).
@item 5
The tracking algorithm has lost the zero curve of the homotopy map and
is not making progress.  The error tolerances @var{epsbig} and
@var{epssml} were too lenient.  The problem should be restarted with
smaller error tolerances.
@item 6
The normal flow newton iteration in @code{stepnf} or @code{rootnf}
failed to converge.  The error tolerance @var{epsbig} may be too
stringent.
@item 7
Illegal input parameters, a fatal error.
@end table
@item lambda
A list of the final lambda value for the m-th root, where lambda is the
continuation parameter.
@item arclen
A list of the arc length of the m-th root.
@item nfe
A list of the number of jacobian matrix evaluations required to track the m-th
root.
@end table

Here are some examples of using @code{hompack_polsys}.
@c ===beg===
@c load(hompack)$
@c hompack_polsys([x1^2-1, x2^2-2],[x1,x2]);
@c ===end===
@example maxima
(%i1) load(hompack)$
@group
(%i2) hompack_polsys([x1^2-1, x2^2-2],[x1,x2]);
(%o2) [0, [[x1 = 7.493410174972965e-17 %i - 1.0, 
x2 = - 2.1199276810167172e-16 %i - 1.4142135623730951], 
[x1 = 1.0 - 1.7812202259088373e-17 %i, 
x2 = - 9.892128000334418e-17 %i - 1.4142135623730951], 
[x1 = - 8.745710933584358e-17 %i - 1.0, 
x2 = 1.4142135623730951 - 3.1543521174128613e-17 %i], 
[x1 = 1.0 - 5.5487454344135625e-18 %i, 
x2 = 9.617653810456737e-17 %i + 1.4142135623730951]], 
[1, 1, 1, 1], [1.0, 1.0, 0.9999999999999999, 
0.9999999999999999], [4.6126237693413445, 4.6126230108601, 
4.612623872939582, 4.6126231144843475], [40, 40, 40, 40]]
@end group
@end example

The analytical solution can be obtained with solve:
@c ===beg===
@c solve([x1^2-1, x2^2-2],[x1,x2]);
@c ===end===
@example maxima
@group
(%i1) solve([x1^2-1, x2^2-2],[x1,x2]);
(%o1) [[x1 = 1, x2 = - sqrt(2)], [x1 = 1, x2 = sqrt(2)], 
            [x1 = - 1, x2 = - sqrt(2)], [x1 = - 1, x2 = sqrt(2)]]
@end group
@end example
We see that @code{hompack_polsys} returned the correct answer except
that the roots are in a different order and there is a small imaginary
part.

Another example, with corresponding solution from solve:
@c ===beg===
@c load(hompack)$
@c hompack_polsys([x1^2 + 2*x2^2 + x1*x2 - 5, 2*x1^2 + x2^2 + x2-4],[x1,x2]);
@c solve([x1^2+2*x2^2+x1*x2 - 5, 2*x1^2+x2^2+x2-4],[x1,x2]);
@c ===end===
@example maxima
(%i1) load(hompack)$
@group
(%i2) hompack_polsys([x1^2 + 2*x2^2 + x1*x2 - 5, 2*x1^2 + x2^2 + x2-4],[x1,x2]);
(%o2) [0, [[x1 = 1.2015573017007832 - 6.51849608628558e-16 %i, 
x2 = - 2.2667444298167825e-16 %i - 1.6672703634801431], 
[x1 = - 5.901956169878514e-17 %i - 1.4285291895653132, 
x2 = - 6.670215053038164e-17 %i - 0.9106199083334114], 
[x1 = 1.942890293094024e-16 %i + 0.5920619420732687, 
x2 = 1.383859154368197 - 1.942890293094024e-16 %i], 
[x1 = 0.08945540033671631 - 8.534583737796769e-16 %i, 
x2 = 2.415141536592239e-16 %i + 1.5576674810817213]], 
[1, 1, 1, 1], [1.0000000000000004, 1.0000000000000002, 1.0, 
0.9999999999999999], [6.205795654034981, 7.7222132593900525, 
7.228287079174324, 5.6114742835849105], [35, 41, 48, 40]]
@end group
@group
(%i3) solve([x1^2+2*x2^2+x1*x2 - 5, 2*x1^2+x2^2+x2-4],[x1,x2]);
(%o3) [[x1 = 0.08945540336850383, x2 = 1.5576673866090713], 
[x1 = 0.5920619554695062, x2 = 1.3838592860838075], 
[x1 = 1.2015573525007488, x2 = - 1.66727025803531], 
[x1 = - 1.428529150636283, x2 = - 0.9106198942815954]]
@end group
@end example

Note that @code{hompack_polsys} can sometimes be very slow.  Perhaps
@code{solve} can be used.  Or perhaps @code{eliminate} can be used to
convert the system of polynomials into one polynomial for which
@code{allroots} can find all the roots.

@opencatbox{Categories:}
@category{Package hompack}
@closecatbox

@end deffn

@c Local Variables: 
@c mode: texinfo
@c TeX-master: "include-maxima"
@c End: 
