\chapter[RSOLVE: Rational polynomial solver]%
        {RSOLVE: \protect\\ Rational/integer polynomial solvers}
\label{RSOLVE}
\typeout{[RSOLVE: Rational polynomial solver]}

{\footnotesize
\begin{center}
Francis J. Wright \\
School of Mathematical Sciences, Queen Mary and Westfield College \\
University of London \\
Mile End Road \\
London E1 4NS, England \\[0.05in]
e--mail:  F.J.Wright@QMW.ac.uk
\end{center}
}
\ttindex{RSOLVE}

The exact rational zeros of a single univariate polynomial using fast
modular methods can be calculated.
The operator \verb|r_solve|\ttindex{R\_SOLVE} computes
all rational zeros and the operator \verb|i_solve|
\ttindex{I\_SOLVE} computes only
integer zeros in a way that is slightly more efficient than extracting
them from the rational zeros.

The first argument is either a univariate polynomial expression or
equation with integer, rational or rounded coefficients.  Symbolic
coefficients are not allowed.  The argument is simplified to a
quotient of integer polynomials and the denominator is silently
ignored.

Subsequent arguments are optional.  If the polynomial variable is to
be specified then it must be the first optional argument.  However,
since the variable in a non-constant univariate polynomial can be
deduced from the polynomial it is unnecessary to specify it
separately, except in the degenerate case that the first argument
simplifies to either 0 or $0 = 0$.  In this case the result is
returned by \verb|i_solve| in terms of the operator \verb|arbint| and
by \verb|r_solve| in terms of the (new) analogous operator
\verb|arbrat|.  The operator \verb|i_solve| will generally run
slightly faster than \verb|r_solve|.

The (rational or integer) zeros of the first argument are returned as
a list and the default output format is the same as that used by
\verb|solve|.  Each distinct zero is returned in the form of an
equation with the variable on the left and the multiplicities of the
zeros are assigned to the variable \verb|root_multiplicities| as a
list.  However, if the switch {\ttfamily multiplicities} is turned on then
each zero is explicitly included in the solution list the appropriate
number of times (and \verb|root_multiplicities| has no value).

\begin{sloppypar}
Optional keyword arguments acting as local switches allow other output
formats.  They have the following meanings:
\begin{description}
\item[{\ttfamily separate}:] assign the multiplicity list to the global
  variable \verb|root_multiplicities| (the default);
\item[{\ttfamily expand} or {\ttfamily multiplicities}:] expand the solution
  list to include multiple zeros multiple times (the default if the
  {\ttfamily multiplicities} switch is on);
\item[{\ttfamily together}:] return each solution as a list whose second
  element is the multiplicity;
\item[{\ttfamily nomul}:] do not compute multiplicities (thereby saving
  some time);
\item[{\ttfamily noeqs}:] do not return univariate zeros as equations but
  just as values.
\end{description}
\end{sloppypar}


\section{Examples}

\begin{verbatim}
r_solve((9x^2 - 16)*(x^2 - 9), x);
\end{verbatim}
\[
  \left\{x=\frac{-4}{3},x=3,x=-3,x=\frac{4}{3}\right\}
\]
\begin{verbatim}
i_solve((9x^2 - 16)*(x^2 - 9), x);
\end{verbatim}
\[
  \{x=3,x=-3\}
\]

