Pos version 0.1

Pos is a program for finding exact and approximate positive real solutions to
systems of polynomial equations. The equations must each consist of terms with
non-negative coefficients followed by a negative constant term. There is also a
restriction on the exponents.

Pos works by choosing a random starting point, followed by an iterative
hill-climbing method. If it is close to an exact solution, it will switch to
Newton's method, which typically converges very rapidly. In order to find
multiple solutions, the search is repeated with multiple starting points.

BUILDING

Pos should work on any POSIX-compatible system. To compile, type:

./configure && make

The configure script will check for the availablity of pthreads, in which case
Pos will be able to search for multiple solutions in parallel by using the -j
option. However, Pos should be able to compile and run without pthreads.

USING POS

After building Pos, you can use it by typing

./pos <input file>

The input file should consists of a series of equations, each followed by a
semicolon (;). The last term of the equation should be the constant term, which
is the only term which has a negative coefficient. Variables should be a letter
followed by letters or numbers. You must explicitly use a * to indicate the
product of variables, although * is not necessary between the coefficient and
the first variable. For exponentiation, ^ can be used. An example of a valid
equation is:

2.22e-3 x1^2 * x2 * y1 + 3 * x1*y1 - 3;

This equation could also have been written without any of the spaces.

The output consists of a single line indicating the number of solutions followed
by the list of solutions. Each solution is listed as either exact, near exact,
or neither. An exact solution is accurate to roughly machine precision. Near
exact means that the solution is near an exact solution, but Newton's method
nonetheless failed to converge. Near exact solutions should be rare. Otherwise,
the solution is approximate. Except in the exact case, the KL-divergence is
listed. The count indicates the number of times the algorithm converged to this
solution. The values for the variables are listed, with the variables always in
alphabetic order.

Note that Pos requires a certain condition on the monomials occuring in the
system. This can be stated as a matrix whose product with each monomial exponent
is a 0/1 vector, although in practice this matrix is rescaled to have integer
entries. If it cannot find such a matrix it prints an error "Coludn't find
appropriate grading" and quits. However, at present, it is not very
sophisticated in its search. For bilinear equations, one set of the variables
should begin with the letter x. Also, it can detect the case when all monomials
have the degree with respect to some grading, possibly not the standard grading.
In the future, more sophisticated searches will be possible, as well as a way to
manually specify the matrix.

MORE ADVANCED USAGE

Multiple systems can be put in a single file for batch processing. Each system
should be preceeded by a line beginning with # and followed by some sort of
identifier. In the output, the solutions to each equation will be preceeded by
by a line with # and the same identifier.

If you have multiple processors, you can conduct multiple searches by using the
-j flag followed by the number of threads to use. If the input file is a batch
file (beginning with #), then solutions may be output in a different order
than in the input file. Since they are nonetheless labelled with their
identifier, this probably is not a problem, but you can force the output order
to be the same as in the input file by using the -o flag.

Pos uses repeated searches to find multiple solutions. By default, it will stop
when it has either found 8 solutions or when it has performed 10 times as many
searches as it has found solutions. Thus, it will always perform at least 10
searches, and if these all converge to the same solution, then it will quit at
that point. These parameters can be changed by using the -s flag to specify the
maximum number of solutions and -i to specify the number of searches per
solution found.

Because Pos relies on repeated searches in order to find all solutions, it
uses thresholds to detect when distinct searches have converged to the same
solution. By default, solutions which differ from a previous solution
by less than 5% in each variable will be treated as a repeat of that solution.
In particular, this means that multiple solutions that differ by less than 5%
will not both be detected. This threshold can be changed by specifying -g whose
argument is the proportion, such as 0.05, not a percentage. Pos continues each
local search until each variable is within an estimated 0.05% of the local
minimum of the divergence function. This parameter can be set with the -t
option, again as a proportion, not a percentage.
