@menu
* Functions and Variables for Equations::   
* Examples for algsys::
* References for equations::
@end menu

@c -----------------------------------------------------------------------------
@node Functions and Variables for Equations,  , Equations, Equations
@section Functions and Variables for Equations
@c -----------------------------------------------------------------------------

@anchor{%rnum}
@defvr {System variable} %rnum
Default value: @code{0}

@code{%rnum} is the counter for the @code{%r} variables introduced in solutions by
@mref{solve} and @mrefdot{algsys}.  The next @code{%r} variable is numbered
@code{%rnum+1}.

See also @mref{%rnum_list}.

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{%rnum_list}
@defvr {System variable} %rnum_list
Default value: @code{[]}

@code{%rnum_list} is the list of variables introduced in solutions by
@mref{solve} and @mrefdot{algsys}  @code{%r} variables are added to
@code{%rnum_list} in the order they are created.  This is convenient for doing
substitutions into the solution later on.

See also @mref{%rnum}.

@c WHAT DOES THIS STATEMENT MEAN ??
It's recommended to use this list rather than doing @code{concat ('%r, j)}.

@c ===beg===
@c solve ([x + y = 3], [x,y]);
@c %rnum_list;
@c sol : solve ([x + 2*y + 3*z = 4], [x,y,z]);
@c %rnum_list;
@c for i : 1 thru length (%rnum_list) do
@c   sol : subst (t[i], %rnum_list[i], sol)$
@c sol;
@c ===end===
@example maxima
@group
(%i1) solve ([x + y = 3], [x,y]);
(%o1)               [[x = 3 - %r1, y = %r1]]
@end group
@group
(%i2) %rnum_list;
(%o2)                         [%r1]
@end group
@group
(%i3) sol : solve ([x + 2*y + 3*z = 4], [x,y,z]);
(%o3)     [[x = - 2 %r3 - 3 %r2 + 4, y = %r3, z = %r2]]
@end group
@group
(%i4) %rnum_list;
(%o4)                      [%r2, %r3]
@end group
@group
(%i5) for i : 1 thru length (%rnum_list) do
  sol : subst (t[i], %rnum_list[i], sol)$
@end group
@group
(%i6) sol;
(%o6)       [[x = - 2 t  - 3 t  + 4, y = t , z = t ]]
                       2      1           2       1
@end group
@end example

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{algepsilon}
@defvr {Option variable} algepsilon
Default value: 10^8

@c WHAT IS algepsilon, EXACTLY ??? describe ("algsys") IS NOT VERY INFORMATIVE !!!
@code{algepsilon} is used by @mrefdot{algsys}

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{algexact}
@defvr {Option variable} algexact
Default value: @code{false}

@code{algexact} affects the behavior of @mref{algsys} as follows:

If @code{algexact} is @code{true}, @code{algsys} always calls @mref{solve} and
then uses @mref{realroots} on @code{solve}'s failures.

If @code{algexact} is @code{false}, @code{solve} is called only if the
eliminant was not univariate, or if it was a quadratic or biquadratic.

Thus @code{algexact: true} does not guarantee only exact solutions, just that
@code{algsys} will first try as hard as it can to give exact solutions, and
only yield approximations when all else fails.

@c ABOVE DESCRIPTION NOT TOO CLEAR -- MAYBE EXAMPLES WILL HELP

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{algsys}
@deffn  {Function} algsys @
@fname{algsys} ([@var{expr_1}, @dots{}, @var{expr_m}], [@var{x_1}, @dots{}, @var{x_n}]) @
@fname{algsys} ([@var{eqn_1}, @dots{}, @var{eqn_m}], [@var{x_1}, @dots{}, @var{x_n}])

Solves the simultaneous polynomials @var{expr_1}, @dots{}, @var{expr_m} or
polynomial equations @var{eqn_1}, @dots{}, @var{eqn_m} for the variables
@var{x_1}, @dots{}, @var{x_n}.  An expression @var{expr} is equivalent to an
equation @code{@var{expr} = 0}.  There may be more equations than variables or
vice versa.

@code{algsys} returns a list of solutions, with each solution given as a list
of equations stating values of the variables @var{x_1}, @dots{}, @var{x_n}
which satisfy the system of equations.  If @code{algsys} cannot find a solution,
an empty list @code{[]} is returned.

The symbols @code{%r1}, @code{%r2}, @dots{}, are introduced as needed to
represent arbitrary parameters in the solution; these variables are also
appended to the list @mrefdot{%rnum_list}

The method is as follows:

@enumerate
@item
First the equations are factored and split into subsystems.

@item
For each subsystem @var{S_i}, an equation @var{E} and a variable @var{x} are
selected.  The variable is chosen to have lowest nonzero degree.  Then the
resultant of @var{E} and @var{E_j} with respect to @var{x} is computed for each
of the remaining equations @var{E_j} in the subsystem @var{S_i}.  This yields a
new subsystem @var{S_i'} in one fewer variables, as @var{x} has been eliminated.
The process now returns to (1).

@item
Eventually, a subsystem consisting of a single equation is obtained.  If the
equation is multivariate and no approximations in the form of floating point
numbers have been introduced, then @mref{solve} is called to find an exact
solution.

In some cases, @code{solve} is not be able to find a solution, or if it does
the solution may be a very large expression.

@c REMAINDER OF (3) IS PRETTY COMPLEX. HOW CAN IT BE CLARIFIED ??
If the equation is univariate and is either linear, quadratic, or biquadratic,
then again @code{solve} is called if no approximations have been introduced.
If approximations have been introduced or the equation is not univariate and
neither linear, quadratic, or biquadratic, then if the switch
@mref{realonly} is @code{true}, the function @mref{realroots} is called to find
the real-valued solutions.  If @code{realonly} is @code{false}, then
@mref{allroots} is called which looks for real and complex-valued solutions.

If @code{algsys} produces a solution which has fewer significant digits than
required, the user can change the value of @mref{algepsilon} to a higher value.

If @code{algexact} is set to @code{true}, @code{solve} will always be called.
@c algepsilon IS IN Floating.texi -- MAY WANT TO BRING IT INTO THIS FILE

@item
Finally, the solutions obtained in step (3) are substituted into
previous levels and the solution process returns to (1).
@c "PREVIOUS LEVELS" -- WHAT ARE THOSE ??
@end enumerate

When @code{algsys} encounters a multivariate equation which contains floating
point approximations (usually due to its failing to find exact solutions at an
earlier stage), then it does not attempt to apply exact methods to such
equations and instead prints the message:
"@code{algsys} cannot solve - system too complicated."

Interactions with @mref{radcan} can produce large or complicated expressions.
In that case, it may be possible to isolate parts of the result with
@mref{pickapart} or @mrefdot{reveal}

Occasionally, @code{radcan} may introduce an imaginary unit @code{%i} into a
solution which is actually real-valued.

Examples:

@c ===beg===
@c e1: 2*x*(1 - a1) - 2*(x - 1)*a2;
@c e2: a2 - a1;
@c e3: a1*(-y - x^2 + 1);
@c e4: a2*(y - (x - 1)^2);
@c algsys ([e1, e2, e3, e4], [x, y, a1, a2]);
@c e1: x^2 - y^2;
@c e2: -1 - y + 2*y^2 - x + x^2;
@c algsys ([e1, e2], [x, y]);
@c ===end===
@example maxima
@group
(%i1) e1: 2*x*(1 - a1) - 2*(x - 1)*a2;
(%o1)              2 (1 - a1) x - 2 a2 (x - 1)
@end group
@group
(%i2) e2: a2 - a1;
(%o2)                        a2 - a1
@end group
@group
(%i3) e3: a1*(-y - x^2 + 1);
                                   2
(%o3)                   a1 (- y - x  + 1)
@end group
@group
(%i4) e4: a2*(y - (x - 1)^2);
                                       2
(%o4)                   a2 (y - (x - 1) )
@end group
@group
(%i5) algsys ([e1, e2, e3, e4], [x, y, a1, a2]);
(%o5) [[x = 0, y = %r1, a1 = 0, a2 = 0], 
                                  [x = 1, y = 0, a1 = 1, a2 = 1]]
@end group
@group
(%i6) e1: x^2 - y^2;
                              2    2
(%o6)                        x  - y
@end group
@group
(%i7) e2: -1 - y + 2*y^2 - x + x^2;
                         2        2
(%o7)                 2 y  - y + x  - x - 1
@end group
@group
(%i8) algsys ([e1, e2], [x, y]);
                 1            1
(%o8) [[x = - -------, y = -------], 
              sqrt(3)      sqrt(3)
        1              1             1        1
[x = -------, y = - -------], [x = - -, y = - -], [x = 1, y = 1]]
     sqrt(3)        sqrt(3)          3        3
@end group
@end example

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{allroots}
@deffn  {Function} allroots @
@fname{allroots} (@var{expr}) @
@fname{allroots} (@var{eqn})

Computes numerical approximations of the real and complex roots of the
polynomial @var{expr} or polynomial equation @var{eqn} of one variable.

The flag @mref{polyfactor} when @code{true} causes @code{allroots} to factor
the polynomial over the real numbers if the polynomial is real, or over the
complex numbers, if the polynomial is complex.

@code{allroots} may give inaccurate results in case of multiple roots.
If the polynomial is real, @code{allroots (%i*@var{p})} may yield
more accurate approximations than @code{allroots (@var{p})}, as @code{allroots}
invokes a different algorithm in that case.

@code{allroots} rejects non-polynomials.  It requires that the numerator
after @code{rat}'ing should be a polynomial, and it requires that the
denominator be at most a complex number.  As a result of this @code{allroots}
will always return an equivalent (but factored) expression, if
@code{polyfactor} is @code{true}.

For complex polynomials an algorithm by Jenkins and Traub is used
(Algorithm 419, @i{Comm. ACM}, vol. 15, (1972), p. 97).  For real polynomials
the algorithm used is due to Jenkins (Algorithm 493, @i{ACM TOMS}, vol. 1,
(1975), p.178).

Examples:

@c ===beg===
@c eqn: (1 + 2*x)^3 = 13.5*(1 + x^5);
@c soln: allroots (eqn);
@c for e in soln
@c         do (e2: subst (e, eqn), disp (expand (lhs(e2) - rhs(e2))));
@c polyfactor: true$
@c allroots (eqn);
@c ===end===
@example maxima
@group
(%i1) eqn: (1 + 2*x)^3 = 13.5*(1 + x^5);
                            3          5
(%o1)              (2 x + 1)  = 13.5 (x  + 1)
@end group
@group
(%i2) soln: allroots (eqn);
(%o2) [x = 0.8296749902129361, x = - 1.0157555438281212, 
x = 0.9659625152196369 %i - 0.4069597231924075, 
x = - 0.9659625152196369 %i - 0.4069597231924075, x = 1.0]
@end group
@group
(%i3) for e in soln
        do (e2: subst (e, eqn), disp (expand (lhs(e2) - rhs(e2))));
                     - 3.552713678800501e-15

                     - 8.43769498715119e-15

        2.6645352591003757e-15 %i - 6.217248937900877e-15

       - 2.6645352591003757e-15 %i - 6.217248937900877e-15

                               0.0

(%o3)                         done
@end group
(%i4) polyfactor: true$
@group
(%i5) allroots (eqn);
(%o5) - 13.5 (x - 1.0) (x - 0.8296749902129361)
                            2
 (x + 1.0157555438281212) (x  + 0.813919446384815 x
 + 1.0986997971102883)
@end group
@end example

@opencatbox{Categories:}
@category{Polynomials}
@category{Numerical methods}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{bfallroots}
@deffn  {Function} bfallroots @
@fname{bfallroots} (@var{expr}) @
@fname{bfallroots} (@var{eqn})

Computes numerical approximations of the real and complex roots of the
polynomial @var{expr} or polynomial equation @var{eqn} of one variable.

In all respects, @code{bfallroots} is identical to @code{allroots} except
that @code{bfallroots} computes the roots using bigfloats.  See 
@mref{allroots} for more information.

@opencatbox{Categories:}
@category{Polynomials}
@category{Numerical methods}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{backsubst}
@defvr {Option variable} backsubst
Default value: @code{true}

@c WHAT IS THE CONTEXT HERE ?? (TO WHICH OTHER FUNCTION DOES THIS APPLY ??)
@c --- According to the documentation, to linsolve
When @code{backsubst} is @code{false}, prevents back substitution in
@mref{linsolve} after the equations have been triangularized.  This may
be helpful in very big problems where back substitution would cause
the generation of extremely large expressions.

@c ===beg===
@c eq1 : x + y + z = 6$
@c eq2 : x - y + z = 2$
@c eq3 : x + y - z = 0$
@c backsubst : false$
@c linsolve ([eq1, eq2, eq3], [x,y,z]);
@c backsubst : true$
@c linsolve ([eq1, eq2, eq3], [x,y,z]);
@c ===end===
@example maxima
(%i1) eq1 : x + y + z = 6$
(%i2) eq2 : x - y + z = 2$
(%i3) eq3 : x + y - z = 0$
(%i4) backsubst : false$
@group
(%i5) linsolve ([eq1, eq2, eq3], [x,y,z]);
(%o5)               [x = z - y, y = 2, z = 3]
@end group
(%i6) backsubst : true$
@group
(%i7) linsolve ([eq1, eq2, eq3], [x,y,z]);
(%o7)                 [x = 1, y = 2, z = 3]
@end group
@end example

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{breakup}
@defvr {Option variable} breakup
Default value: @code{true}

When @code{breakup} is @code{true}, @mref{solve} expresses solutions of cubic
and quartic equations in terms of common subexpressions, which are assigned to
intermediate expression labels (@code{%t1}, @code{%t2}, etc.).
Otherwise, common subexpressions are not identified.

@code{breakup: true} has an effect only when @mref{programmode} is @code{false}.

Examples:

@c ===beg===
@c programmode: false$
@c breakup: true$
@c solve (x^3 + x^2 - 1);
@c breakup: false$
@c solve (x^3 + x^2 - 1);
@c ===end===
@example maxima
(%i1) programmode: false$
(%i2) breakup: true$
@group
(%i3) solve (x^3 + x^2 - 1);
                        sqrt(23)   25 1/3
(%t3)                  (-------- + --)
                            3/2    54
                         2 3
solve: solution:

                                    sqrt(3) %i   - 1
                                    ---------- + ---
            - 1   sqrt(3) %i            2         2    - 1
(%t4)  x = (--- - ----------) %t3 + ---------------- + ---
             2        2                  9 %t3          3

                                    - 1   sqrt(3) %i
                                    --- - ----------
            sqrt(3) %i   - 1         2        2        - 1
(%t5)  x = (---------- + ---) %t3 + ---------------- + ---
                2         2              9 %t3          3

                                  1     - 1
(%t6)                 x = %t3 + ----- + ---
                                9 %t3    3
(%o6)                    [%t4, %t5, %t6]
@end group
(%i7) breakup: false$
@group
(%i8) solve (x^3 + x^2 - 1);
solve: solution:

            sqrt(3) %i   - 1
            ---------- + ---
                2         2       sqrt(23)   25 1/3
(%t8) x = -------------------- + (-------- + --)
             sqrt(23)   25 1/3        3/2    54
          9 (-------- + --)        2 3
                 3/2    54
              2 3
                                          - 1   sqrt(3) %i    - 1
                                         (--- - ----------) + ---
                                           2        2          3

           sqrt(23)   25 1/3  sqrt(3) %i   - 1
(%t9) x = (-------- + --)    (---------- + ---)
               3/2    54          2         2
            2 3
                                         - 1   sqrt(3) %i
                                         --- - ----------
                                          2        2          - 1
                                     + -------------------- + ---
                                          sqrt(23)   25 1/3    3
                                       9 (-------- + --)
                                              3/2    54
                                           2 3

            sqrt(23)   25 1/3            1             - 1
(%t10) x = (-------- + --)    + -------------------- + ---
                3/2    54          sqrt(23)   25 1/3    3
             2 3                9 (-------- + --)
                                       3/2    54
                                    2 3
(%o10)                  [%t8, %t9, %t10]
@end group
@end example

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{dimension}
@deffn  {Function} dimension @
@fname{dimension} (@var{eqn}) @
@fname{dimension} (@var{eqn_1}, @dots{}, @var{eqn_n})

@code{dimen} is a package for dimensional analysis.
@code{load ("dimen")} loads this package.
@code{demo ("dimen")} displays a short demonstration.
@c I GUESS THIS SHOULD BE EXPANDED TO COVER EACH FUNCTION IN THE PACKAGE

@opencatbox{Categories:}
@category{Share packages}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{dispflag}
@defvr {Option variable} dispflag
Default value: @code{true}

@c WHAT DOES THIS MEAN ??
If set to @code{false} within a @code{block} will inhibit the display of output
generated by the solve functions called from within the @code{block}.
Termination of the @code{block} with a dollar sign, @code{$}, sets @code{dispflag} to
@code{false}.

@opencatbox{Categories:}
@category{Algebraic equations}
@category{Display flags and variables}
@closecatbox
@end defvr

@c THIS COULD BENEFIT FROM REPHRASING

@c -----------------------------------------------------------------------------
@anchor{funcsolve}
@deffn {Function} funcsolve (@var{eqn}, @var{g}(@var{t}))

Returns @code{[@var{g}(@var{t}) = ...]}  or @code{[]}, depending on whether
or not there exists a rational function @code{@var{g}(@var{t})} satisfying
@var{eqn}, which must be a first order, linear polynomial in (for this case)
@code{@var{g}(@var{t})} and @code{@var{g}(@var{t}+1)}

@c ===beg===
@c eqn: (n + 1)*f(n) - (n + 3)*f(n + 1)/(n + 1) =
@c      (n - 1)/(n + 2);
@c funcsolve (eqn, f(n));
@c ===end===
@example maxima
@group
(%i1) eqn: (n + 1)*f(n) - (n + 3)*f(n + 1)/(n + 1) =
     (n - 1)/(n + 2);
                            (n + 3) f(n + 1)   n - 1
(%o1)        (n + 1) f(n) - ---------------- = -----
                                 n + 1         n + 2
@end group
@group
(%i2) funcsolve (eqn, f(n));
solve: dependent equations eliminated: (4 3)
                                   n
(%o2)                f(n) = ---------------
                            (n + 1) (n + 2)
@end group
@end example

Warning: this is a very rudimentary implementation -- many safety checks
and obvious generalizations are missing.

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{globalsolve}
@defvr {Option variable} globalsolve
Default value: @code{false}

When @code{globalsolve} is @code{true}, solved-for variables are assigned the
solution values found by @code{linsolve}, and by @mref{solve} when solving two
or more linear equations.

When @code{globalsolve} is @code{false}, solutions found by @mref{linsolve} and
by @code{solve} when solving two or more linear equations are expressed as
equations, and the solved-for variables are not assigned.

When solving anything other than two or more linear equations, @code{solve}
ignores @code{globalsolve}.  Other functions which solve equations (e.g.,
@mref{algsys}) always ignore @code{globalsolve}.

Examples:

@c ===beg===
@c globalsolve: true$
@c solve ([x + 3*y = 2, 2*x - y = 5], [x, y]);
@c x;
@c y;
@c globalsolve: false$
@c kill (x, y)$
@c solve ([x + 3*y = 2, 2*x - y = 5], [x, y]);
@c x;
@c y;
@c ===end===
@example maxima
(%i1) globalsolve: true$
@group
(%i2) solve ([x + 3*y = 2, 2*x - y = 5], [x, y]);
                             17        1
(%o2)                  [[x : --, y : - -]]
                             7         7
@end group
@group
(%i3) x;
                               17
(%o3)                          --
                               7
@end group
@group
(%i4) y;
                                 1
(%o4)                          - -
                                 7
@end group
(%i5) globalsolve: false$
(%i6) kill (x, y)$
@group
(%i7) solve ([x + 3*y = 2, 2*x - y = 5], [x, y]);
                             17        1
(%o7)                  [[x = --, y = - -]]
                             7         7
@end group
@group
(%i8) x;
(%o8)                           x
@end group
@group
(%i9) y;
(%o9)                           y
@end group
@end example

@opencatbox{Categories:}
@category{Linear equations}
@closecatbox
@end defvr

@c THIS DESCRIPTION NEEDS WORK AND EXAMPLES
@c MERGE IN TEXT FROM share/integequations/inteqn.usg
@c AND EXAMPLES FROM .../intexs.mac

@c --- I'm not sure that all examples from share/integequations/intexs.mac
@c are handled correctly by ieqn.

@c -----------------------------------------------------------------------------
@anchor{ieqn}
@deffn {Function} ieqn (@var{ie}, @var{unk}, @var{tech}, @var{n}, @var{guess})

@code{inteqn} is a package for solving integral equations.
@code{load ("inteqn")} loads this package.

@var{ie} is the integral equation; @var{unk} is the unknown function;
@var{tech} is the technique to be tried from those given in the lists
below; (@var{tech} = @code{first} means: try the first technique which
finds a solution; @var{tech} = @code{all} means: try all applicable
techniques); @var{n} is the maximum number of terms to take for
@code{taylor}, @code{neumann}, @code{firstkindseries}, or
@code{fredseries} (it is also the maximum depth of recursion for the
differentiation method); @var{guess} is the initial guess for
@code{neumann} or @code{firstkindseries}.

Two types of equations are considered. A second-kind equation of the
following form,
@ifnottex
@example
                           b(x)
                          /
                          [
        p(x) = q(x, p(x), I     w(x, u, p(x), p(u)) du)
                          ]
                          /
                           a(x)
@end example
@end ifnottex
@tex
$$p\left(x\right)=q\left(x, p\left(x\right) , \int_{a\left(x\right)}
^{b\left(x\right)}{w\left(x, u, p\left(x\right), p\left(u\right)\right)
\;du}\right)$$
@end tex

and a first-kind equation with the form
@ifnottex
@example
                         b(x)
                        /
                        [
                 f(x) = I     w(x, u, p(u)) du
                        ]
                        /
                         a(x)
@end example
@end ifnottex
@tex
$$f\left(x\right)=\int_{a\left(x\right)}^{b\left(x\right)}
{w\left(x, u, p\left(u\right)\right)\;du}$$
@end tex

The different solution techniques used require particular forms of the
expressions @var{q} and @var{w}. The techniques available are the following:

@b{Second-kind equations}
@itemize  @bullet
@item @code{flfrnk2nd}: For fixed-limit, finite-rank integrands.
@item @code{vlfrnk}: For variable-limit, finite-rank integrands.
@item @code{transform}: Laplace transform for convolution types.
@item @code{fredseries}: Fredholm-Carleman series for linear equations.
@item @code{tailor}: Taylor series for quasi-linear variable-limit equations.
@item @code{neumann}: Neumann series for quasi-second kind equations.
@item @code{collocate}: Collocation using a power series form for p(x)
evaluated at equally spaced points.
@end itemize

@b{First-kind equations}
@itemize  @bullet
@item @code{flfrnk1st}: For fixed-limit, finite-rank integrands.
@item @code{vlfrnk}: For variable-limit, finite-rank integrands.
@item @code{abel}: For singular integrands
@item @code{transform}: See above
@item @code{collocate}: See above
@item @code{firstkindseries}: Iteration technique similar to neumann series.
@end itemize

The default values for the 2nd thru 5th parameters in the calling form
are:

@var{unk}: @code{@var{p}(@var{x})}, where @var{p} is the first function
encountered in an integrand which is unknown to Maxima and @var{x} is the
variable which occurs as an argument to the first occurrence of @var{p} found
outside of an integral in the case of @code{secondkind} equations, or is the
only other variable besides the variable of integration in @code{firstkind}
equations. If the attempt to search for @var{x} fails, the user will be asked
to supply the independent variable. @var{tech}: @code{first}. @var{n}: 1.
@var{guess}: @code{none} which will cause @code{neumann} and
@code{firstkindseries} to use @code{@var{f}(@var{x})} as an initial guess.

Examples:
@example
(%i1) load("inteqn")$

(%i2) e: p(x) - 1 -x + cos(x) + 'integrate(cos(x-u)*p(u),u,0,x)$

(%i3) ieqn(e, p(x), 'transform);
default 4th arg, number of iterations or coll. parms.:  1 
default 5th arg, initial guess:  none 

(%t3)                           [x, transform]
(%o3)                               [%t3]
(%i4) e: 2*'integrate(p(x*sin(u)), u, 0, %pi/2) - a*x - b$

(%i5) ieqn(e, p(x), 'firstkindseries);
default 4th arg, number of iterations or coll. parms.:  1 
default 5th arg, initial guess:  none 

(%t5)          [2 a x + %pi b, firstkindseries, 1, approximate]
(%o5)                               [%t5]
@end example

@opencatbox{Categories:}
@category{Integral equations}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{ieqnprint}
@defvr {Option variable} ieqnprint
Default value: @code{true}

@code{ieqnprint} governs the behavior of the result returned by the
@mref{ieqn} command.  When @code{ieqnprint} is @code{false}, the lists returned
by the @code{ieqn} function are of the form

   [@var{solution}, @var{technique used}, @var{nterms}, @var{flag}]

where @var{flag} is absent if the solution is exact.

Otherwise, it is the word @code{approximate} or @code{incomplete} corresponding
to an inexact or non-closed form solution, respectively.  If a series method was
used, @var{nterms} gives the number of terms taken (which could be less than
the n given to @code{ieqn} if an error prevented generation of further terms).

@opencatbox{Categories:}
@category{Integral equations}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{lhs}
@deffn {Function} lhs (@var{expr})

Returns the left-hand side (that is, the first argument) of the expression
@var{expr}, when the operator of @var{expr} is one of the relational operators
@code{< <= = # equal notequal >= >},
@c MENTION -> (MARROW) IN THIS LIST IF/WHEN THE PARSER RECOGNIZES IT
one of the assignment operators @code{:= ::= : ::}, or a user-defined binary
infix operator, as declared by @mrefdot{infix}

When @var{expr} is an atom or its operator is something other than the ones
listed above, @code{lhs} returns @var{expr}.

See also @mrefdot{rhs}

Examples:

@c ===beg===
@c e: aa + bb = cc;
@c lhs (e);
@c rhs (e);
@c [lhs (aa < bb), lhs (aa <= bb), lhs (aa >= bb), 
@c        lhs (aa > bb)];
@c [lhs (aa = bb), lhs (aa # bb), lhs (equal (aa, bb)), 
@c        lhs (notequal (aa, bb))];
@c e1: '(foo(x) := 2*x);
@c e2: '(bar(y) ::= 3*y);
@c e3: '(x : y);
@c e4: '(x :: y);
@c [lhs (e1), lhs (e2), lhs (e3), lhs (e4)];
@c infix ("][");
@c lhs (aa ][ bb);
@c ===end===
@example maxima
@group
(%i1) e: aa + bb = cc;
(%o1)                     bb + aa = cc
@end group
@group
(%i2) lhs (e);
(%o2)                        bb + aa
@end group
@group
(%i3) rhs (e);
(%o3)                          cc
@end group
@group
(%i4) [lhs (aa < bb), lhs (aa <= bb), lhs (aa >= bb),
       lhs (aa > bb)];
(%o4)                   [aa, aa, aa, aa]
@end group
@group
(%i5) [lhs (aa = bb), lhs (aa # bb), lhs (equal (aa, bb)),
       lhs (notequal (aa, bb))];
(%o5)                   [aa, aa, aa, aa]
@end group
@group
(%i6) e1: '(foo(x) := 2*x);
(%o6)                     foo(x) := 2 x
@end group
@group
(%i7) e2: '(bar(y) ::= 3*y);
(%o7)                    bar(y) ::= 3 y
@end group
@group
(%i8) e3: '(x : y);
(%o8)                         x : y
@end group
@group
(%i9) e4: '(x :: y);
(%o9)                        x :: y
@end group
@group
(%i10) [lhs (e1), lhs (e2), lhs (e3), lhs (e4)];
(%o10)               [foo(x), bar(y), x, x]
@end group
@group
(%i11) infix ("][");
(%o11)                         ][
@end group
@group
(%i12) lhs (aa ][ bb);
(%o12)                         aa
@end group
@end example

@opencatbox{Categories:}
@category{Expressions}
@closecatbox
@end deffn

@c REVISIT -- THERE'S PROBABLY MORE TO SAY HERE

@c -----------------------------------------------------------------------------
@anchor{linsolve}
@deffn {Function} linsolve ([@var{expr_1}, @dots{}, @var{expr_m}], [@var{x_1}, @dots{}, @var{x_n}])

Solves the list of simultaneous linear equations for the list of variables.
The expressions must each be polynomials in the variables and may be equations.
If the length of the list of variables doesn't match the number of
linearly-independent equations to solve the result will be an empty list.

When @mref{globalsolve} is @code{true}, each solved-for variable is bound to
its value in the solution of the equations.

When @mref{backsubst} is @code{false}, @code{linsolve} does not carry out back
substitution after the equations have been triangularized.  This may be
necessary in very big problems where back substitution would cause the
generation of extremely large expressions.

When @mref{linsolve_params} is @code{true}, @code{linsolve} also generates the
@code{%r} symbols used to represent arbitrary parameters described in the manual
under @mrefdot{algsys}  Otherwise, @code{linsolve} solves an under-determined
system of equations with some variables expressed in terms of others.

When @mref{programmode} is @code{false}, @code{linsolve} displays the solution
with intermediate expression (@code{%t}) labels, and returns the list of labels.

See also @mrefcomma{algsys} @mrefdot{eliminate} and @mrefdot{solve}

Examples:
@c ===beg===
@c e1: x + z = y;
@c e2: 2*a*x - y = 2*a^2;
@c e3: y - 2*z = 2;
@c [globalsolve: false, programmode: true];
@c linsolve ([e1, e2, e3], [x, y, z]);
@c [globalsolve: false, programmode: false];
@c linsolve ([e1, e2, e3], [x, y, z]);
@c ''%;
@c [globalsolve: true, programmode: false];
@c linsolve ([e1, e2, e3], [x, y, z]);
@c ''%;
@c [x, y, z];
@c [globalsolve: true, programmode: true];
@c linsolve ([e1, e2, e3], '[x, y, z]);
@c [x, y, z];
@c ===end===
@example maxima
@group
(%i1) e1: x + z = y;
(%o1)                       z + x = y
@end group
@group
(%i2) e2: 2*a*x - y = 2*a^2;
                                       2
(%o2)                   2 a x - y = 2 a
@end group
@group
(%i3) e3: y - 2*z = 2;
(%o3)                      y - 2 z = 2
@end group
@group
(%i4) [globalsolve: false, programmode: true];
(%o4)                     [false, true]
@end group
@group
(%i5) linsolve ([e1, e2, e3], [x, y, z]);
(%o5)            [x = a + 1, y = 2 a, z = a - 1]
@end group
@group
(%i6) [globalsolve: false, programmode: false];
(%o6)                    [false, false]
@end group
@group
(%i7) linsolve ([e1, e2, e3], [x, y, z]);
Solution:

(%t7)                       z = a - 1

(%t8)                        y = 2 a

(%t9)                       x = a + 1
(%o9)                    [%t7, %t8, %t9]
@end group
@group
(%i10) ''%;
(%o10)           [z = a - 1, y = 2 a, x = a + 1]
@end group
@group
(%i11) [globalsolve: true, programmode: false];
(%o11)                    [true, false]
@end group
@group
(%i12) linsolve ([e1, e2, e3], [x, y, z]);
Solution:

(%t12)                      z : a - 1

(%t13)                       y : 2 a

(%t14)                      x : a + 1
(%o14)                 [%t12, %t13, %t14]
@end group
@group
(%i15) ''%;
(%o15)           [z : a - 1, y : 2 a, x : a + 1]
@end group
@group
(%i16) [x, y, z];
(%o16)                 [a + 1, 2 a, a - 1]
@end group
@group
(%i17) [globalsolve: true, programmode: true];
(%o17)                    [true, true]
@end group
@group
(%i18) linsolve ([e1, e2, e3], '[x, y, z]);
(%o18)           [x : a + 1, y : 2 a, z : a - 1]
@end group
@group
(%i19) [x, y, z];
(%o19)                 [a + 1, 2 a, a - 1]
@end group
@end example

@opencatbox{Categories:}
@category{Linear equations}
@closecatbox
@end deffn

@c DO ANY FUNCTIONS OTHER THAN linsolve RESPECT linsolvewarn ??

@c -----------------------------------------------------------------------------
@anchor{linsolvewarn}
@defvr {Option variable} linsolvewarn
Default value: @code{true}

When @code{linsolvewarn} is @code{true}, @mref{linsolve} prints a message
"Dependent equations eliminated".

@opencatbox{Categories:}
@category{Linear equations}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{linsolve_params}
@defvr {Option variable} linsolve_params
Default value: @code{true}

When @code{linsolve_params} is @code{true}, @mref{linsolve} also generates
the @code{%r} symbols used to represent arbitrary parameters described in
the manual under @mrefdot{algsys}  Otherwise, @code{linsolve} solves an
under-determined system of equations with some variables expressed in terms of
others.

@opencatbox{Categories:}
@category{Linear equations}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{multiplicities}
@defvr {System variable} multiplicities
Default value: @code{not_set_yet}

@code{multiplicities} is set to a list of the multiplicities of the individual
solutions returned by @mref{solve} or @mrefdot{realroots}
@c NEED AN EXAMPLE HERE

@opencatbox{Categories:}
@category{Algebraic equations}
@category{Polynomials}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{nroots}
@deffn {Function} nroots (@var{p}, @var{low}, @var{high})

Returns the number of real roots of the real univariate polynomial @var{p} in
the half-open interval @code{(@var{low}, @var{high}]}.  The endpoints of the
interval may be @code{minf} or @code{inf}.

@code{nroots} uses the method of Sturm sequences.

@c ===beg===
@c p: x^10 - 2*x^4 + 1/2$
@c nroots (p, -6, 9.1);
@c ===end===
@example maxima
(%i1) p: x^10 - 2*x^4 + 1/2$
@group
(%i2) nroots (p, -6, 9.1);
(%o2)                           4
@end group
@end example

@opencatbox{Categories:}
@category{Polynomials}
@category{Numerical methods}
@closecatbox
@end deffn

@c NEEDS WORK

@c -----------------------------------------------------------------------------
@anchor{nthroot}
@deffn {Function} nthroot (@var{p}, @var{n})

where @var{p} is a polynomial with integer coefficients and @var{n} is a
positive integer returns @code{q}, a polynomial over the integers, such that
@code{q^n = p} or prints an error message indicating that @var{p} is not a
perfect nth power.  This routine is much faster than @mref{factor} or even
@mrefdot{sqfr}

@opencatbox{Categories:}
@category{Polynomials}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{polyfactor}
@defvr {Option variable} polyfactor
Default value: @code{false}

The option variable @code{polyfactor} when @code{true} causes
@mref{allroots} and @mref{bfallroots} to factor the polynomial over the real
numbers if the polynomial is real, or over the complex numbers, if the
polynomial is complex.

See @code{allroots} for an example.

@opencatbox{Categories:}
@category{Polynomials}
@category{Numerical methods}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{programmode}
@defvr {Option variable} programmode
Default value: @code{true}

When @code{programmode} is @code{true}, @mrefcomma{solve}@w{}
@mrefcomma{realroots} @mrefcomma{allroots} and @mref{linsolve} return solutions
as elements in a list.
@c WHAT DOES BACKSUBSTITUTION HAVE TO DO WITH RETURN VALUES ??
(Except when @mref{backsubst} is set to @code{false}, in which case
@code{programmode: false} is assumed.)

When @code{programmode} is @code{false}, @code{solve}, etc. create intermediate
expression labels @code{%t1}, @code{%t2}, etc., and assign the solutions to them.
@c NEED AN EXAMPLE HERE

@opencatbox{Categories:}
@category{Algebraic equations}
@category{Polynomials}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{realonly}
@defvr {Option variable} realonly
Default value: @code{false}

When @code{realonly} is @code{true}, @mref{algsys} returns only those solutions
which are free of @code{%i}.

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{realroots}
@deffn  {Function} realroots @
@fname{realroots} (@var{expr}, @var{bound}) @
@fname{realroots} (@var{eqn}, @var{bound}) @
@fname{realroots} (@var{expr}) @
@fname{realroots} (@var{eqn})

Computes rational approximations of the real roots of the polynomial @var{expr}
or polynomial equation @var{eqn} of one variable, to within a tolerance of
@var{bound}.  Coefficients of @var{expr} or @var{eqn} must be literal numbers;
symbol constants such as @code{%pi} are rejected.

@code{realroots} assigns the multiplicities of the roots it finds
to the global variable @mrefdot{multiplicities}

@code{realroots} constructs a Sturm sequence to bracket each root, and then
applies bisection to refine the approximations.  All coefficients are converted
to rational equivalents before searching for roots, and computations are carried
out by exact rational arithmetic.  Even if some coefficients are floating-point
numbers, the results are rational (unless coerced to floats by the
@mref{float} or @mref{numer} flags).

When @var{bound} is less than 1, all integer roots are found exactly.
When @var{bound} is unspecified, it is assumed equal to the global variable
@mrefdot{rootsepsilon}

When the global variable @mref{programmode} is @code{true}, @code{realroots}
returns a list of the form @code{[x = @var{x_1}, x = @var{x_2}, ...]}.
When @code{programmode} is @code{false}, @code{realroots} creates intermediate
expression labels @code{%t1}, @code{%t2}, @dots{},
assigns the results to them, and returns the list of labels.

See also @mrefcomma{allroots} @mrefcomma{bfallroots} @mrefcomma{guess_exact_value}
and @mrefdot{lhs}

Examples:

@c ===beg===
@c realroots (-1 - x + x^5, 5e-6);
@c ev (%[1], float);
@c ev (-1 - x + x^5, %);
@c ===end===
@example maxima
@group
(%i1) realroots (-1 - x + x^5, 5e-6);
                               612003
(%o1)                     [x = ------]
                               524288
@end group
@group
(%i2) ev (%[1], float);
(%o2)                x = 1.1673030853271484
@end group
@group
(%i3) ev (-1 - x + x^5, %);
(%o3)                - 7.396496210176906e-6
@end group
@end example

@c ===beg===
@c realroots (expand ((1 - x)^5 * (2 - x)^3 * (3 - x)), 1e-20);
@c multiplicities;
@c ===end===
@example maxima
@group
(%i1) realroots (expand ((1 - x)^5 * (2 - x)^3 * (3 - x)), 1e-20);
(%o1)                 [x = 1, x = 2, x = 3]
@end group
@group
(%i2) multiplicities;
(%o2)                       [5, 3, 1]
@end group
@end example

@opencatbox{Categories:}
@category{Polynomials}
@category{Numerical methods}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{rhs}
@deffn {Function} rhs (@var{expr})

Returns the right-hand side (that is, the second argument) of the expression
@var{expr}, when the operator of @var{expr} is one of the relational operators
@code{< <= = # equal notequal >= >},
@c MENTION -> (MARROW) IN THIS LIST IF/WHEN THE PARSER RECOGNIZES IT
one of the assignment operators @code{:= ::= : ::}, or a user-defined binary
infix operator, as declared by @mrefdot{infix}

When @var{expr} is an atom or its operator is something other than the ones
listed above, @code{rhs} returns 0.

See also @mrefdot{lhs}

Examples:

@c ===beg===
@c e: aa + bb = cc;
@c lhs (e);
@c rhs (e);
@c [rhs (aa < bb), rhs (aa <= bb), rhs (aa >= bb), 
@c        rhs (aa > bb)];
@c [rhs (aa = bb), rhs (aa # bb), rhs (equal (aa, bb)), 
@c        rhs (notequal (aa, bb))];
@c e1: '(foo(x) := 2*x);
@c e2: '(bar(y) ::= 3*y);
@c e3: '(x : y);
@c e4: '(x :: y);
@c [rhs (e1), rhs (e2), rhs (e3), rhs (e4)];
@c infix ("][");
@c rhs (aa ][ bb);
@c ===end===
@example maxima
@group
(%i1) e: aa + bb = cc;
(%o1)                     bb + aa = cc
@end group
@group
(%i2) lhs (e);
(%o2)                        bb + aa
@end group
@group
(%i3) rhs (e);
(%o3)                          cc
@end group
@group
(%i4) [rhs (aa < bb), rhs (aa <= bb), rhs (aa >= bb),
       rhs (aa > bb)];
(%o4)                   [bb, bb, bb, bb]
@end group
@group
(%i5) [rhs (aa = bb), rhs (aa # bb), rhs (equal (aa, bb)),
       rhs (notequal (aa, bb))];
(%o5)                   [bb, bb, bb, bb]
@end group
@group
(%i6) e1: '(foo(x) := 2*x);
(%o6)                     foo(x) := 2 x
@end group
@group
(%i7) e2: '(bar(y) ::= 3*y);
(%o7)                    bar(y) ::= 3 y
@end group
@group
(%i8) e3: '(x : y);
(%o8)                         x : y
@end group
@group
(%i9) e4: '(x :: y);
(%o9)                        x :: y
@end group
@group
(%i10) [rhs (e1), rhs (e2), rhs (e3), rhs (e4)];
(%o10)                  [2 x, 3 y, y, y]
@end group
@group
(%i11) infix ("][");
(%o11)                         ][
@end group
@group
(%i12) rhs (aa ][ bb);
(%o12)                         bb
@end group
@end example

@opencatbox{Categories:}
@category{Expressions}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{rootsconmode}
@defvr {Option variable} rootsconmode
Default value: @code{true}

@code{rootsconmode} governs the behavior of the @code{rootscontract} command.
See @mref{rootscontract} for details.

@opencatbox{Categories:}
@category{Expressions}
@category{Simplification flags and variables}
@closecatbox
@end defvr

@c NEEDS WORK

@c -----------------------------------------------------------------------------
@anchor{rootscontract}
@deffn {Function} rootscontract (@var{expr})

Converts products of roots into roots of products.  For example,
@code{rootscontract (sqrt(x)*y^(3/2))} yields @code{sqrt(x*y^3)}.

When @mref{radexpand} is @code{true} and @mref{domain} is @code{real},
@code{rootscontract} converts @mref{abs} into @mrefcomma{sqrt}  e.g.,
@code{rootscontract (abs(x)*sqrt(y))} yields @code{sqrt(x^2*y)}.

There is an option @mref{rootsconmode} affecting @code{rootscontract} as
follows:

@example
Problem            Value of        Result of applying
                  rootsconmode        rootscontract
      
x^(1/2)*y^(3/2)      false          (x*y^3)^(1/2)
x^(1/2)*y^(1/4)      false          x^(1/2)*y^(1/4)
x^(1/2)*y^(1/4)      true           (x*y^(1/2))^(1/2)
x^(1/2)*y^(1/3)      true           x^(1/2)*y^(1/3)
x^(1/2)*y^(1/4)      all            (x^2*y)^(1/4)
x^(1/2)*y^(1/3)      all            (x^3*y^2)^(1/6)
@end example

When @code{rootsconmode} is @code{false}, @code{rootscontract} contracts only
with respect to rational number exponents whose denominators are the same.  The
key to the @code{rootsconmode: true} examples is simply that 2 divides into 4
but not into 3.  @code{rootsconmode: all} involves taking the least common
multiple of the denominators of the exponents.

@code{rootscontract} uses @mref{ratsimp} in a manner similar to
@mrefdot{logcontract}

Examples:

@c ===beg===
@c rootsconmode: false$
@c rootscontract (x^(1/2)*y^(3/2));
@c rootscontract (x^(1/2)*y^(1/4));
@c rootsconmode: true$
@c rootscontract (x^(1/2)*y^(1/4));
@c rootscontract (x^(1/2)*y^(1/3));
@c rootsconmode: all$
@c rootscontract (x^(1/2)*y^(1/4));
@c rootscontract (x^(1/2)*y^(1/3));
@c rootsconmode: false$
@c rootscontract (sqrt(sqrt(x) + sqrt(1 + x))
@c                     *sqrt(sqrt(1 + x) - sqrt(x)));
@c rootsconmode: true$
@c rootscontract (sqrt(5 + sqrt(5)) - 5^(1/4)*sqrt(1 + sqrt(5)));
@c ===end===
@example maxima
(%i1) rootsconmode: false$
@group
(%i2) rootscontract (x^(1/2)*y^(3/2));
                                   3
(%o2)                      sqrt(x y )
@end group
@group
(%i3) rootscontract (x^(1/2)*y^(1/4));
                                   1/4
(%o3)                     sqrt(x) y
@end group
(%i4) rootsconmode: true$
@group
(%i5) rootscontract (x^(1/2)*y^(1/4));
(%o5)                    sqrt(x sqrt(y))
@end group
@group
(%i6) rootscontract (x^(1/2)*y^(1/3));
                                   1/3
(%o6)                     sqrt(x) y
@end group
(%i7) rootsconmode: all$
@group
(%i8) rootscontract (x^(1/2)*y^(1/4));
                              2   1/4
(%o8)                       (x  y)
@end group
@group
(%i9) rootscontract (x^(1/2)*y^(1/3));
                             3  2 1/6
(%o9)                      (x  y )
@end group
(%i10) rootsconmode: false$
@group
(%i11) rootscontract (sqrt(sqrt(x) + sqrt(1 + x))
                    *sqrt(sqrt(1 + x) - sqrt(x)));
(%o11)                          1
@end group
(%i12) rootsconmode: true$
@group
(%i13) rootscontract (sqrt(5 + sqrt(5)) - 5^(1/4)*sqrt(1 + sqrt(5)));
(%o13)                          0
@end group
@end example

@opencatbox{Categories:}
@category{Simplification functions}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{rootsepsilon}
@defvr {Option variable} rootsepsilon
Default value: 1.0e-7

@code{rootsepsilon} is the tolerance which establishes the confidence interval
for the roots found by the @mref{realroots} function.
@c IS IT GUARANTEED THAT |ACTUAL - ESTIMATE| < rootepsilon OR IS IT SOME OTHER
@c NOTION ?? NEED EXAMPLE HERE

@opencatbox{Categories:}
@category{Polynomials}
@category{Numerical methods}
@closecatbox
@end defvr

@c NEEDS WORK

@c -----------------------------------------------------------------------------
@anchor{solve}
@deffn  {Function} solve @
@fname{solve} (@var{expr}, @var{x}) @
@fname{solve} (@var{expr}) @
@fname{solve} ([@var{eqn_1}, @dots{}, @var{eqn_n}], [@var{x_1}, @dots{}, @var{x_n}])

Solves the algebraic equation @var{expr} for the variable @var{x} and returns a
list of solution equations in @var{x}.  If @var{expr} is not an equation, the
equation @code{@var{expr} = 0} is assumed in its place.
@var{x} may be a function (e.g. @code{f(x)}), or other non-atomic expression
except a sum or product.  @var{x} may be omitted if @var{expr} contains only one
variable.  @var{expr} may be a rational expression, and may contain
trigonometric functions, exponentials, etc.

The following method is used:

Let @var{E} be the expression and @var{X} be the variable.  If @var{E} is linear
in @var{X} then it is trivially solved for @var{X}.  Otherwise if @var{E} is of
the form @code{A*X^N + B} then the result is @code{(-B/A)^1/N)} times the
@code{N}'th roots of unity.

If @var{E} is not linear in @var{X} then the gcd of the exponents of @var{X} in
@var{E} (say @var{N}) is divided into the exponents and the multiplicity of the
roots is multiplied by @var{N}.  Then @code{solve} is called again on the
result.  If @var{E} factors then @code{solve} is called on each of the factors.
Finally @code{solve} will use the quadratic, cubic, or quartic formulas where
necessary.

In the case where @var{E} is a polynomial in some function of the variable to be
solved for, say @code{F(X)}, then it is first solved for @code{F(X)} (call the
result @var{C}), then the equation @code{F(X)=C} can be solved for @var{X}
provided the inverse of the function @var{F} is known.

@mref{breakup} if @code{false} will cause @code{solve} to express the solutions
of cubic or quartic equations as single expressions rather than as made
up of several common subexpressions which is the default.

@mref{multiplicities} - will be set to a list of the multiplicities of the
individual solutions returned by @code{solve}, @mrefcomma{realroots} or
@mrefdot{allroots}  Try @code{apropos (solve)} for the switches which affect
@code{solve}.  @mref{describe} may then by used on the individual switch names
if their purpose is not clear.

@code{solve ([@var{eqn_1}, ..., @var{eqn_n}], [@var{x_1}, ..., @var{x_n}])}
solves a system of simultaneous (linear or non-linear) polynomial equations by
calling @mref{linsolve} or @mref{algsys} and returns a list of the solution
lists in the variables.  In the case of @mref{linsolve} this list would contain
a single list of solutions.  It takes two lists as arguments.  The first list
represents the equations to be solved; the second list is a
list of the unknowns to be determined.  If the total number of
variables in the equations is equal to the number of equations, the
second argument-list may be omitted.

@c I think this is not true --hgeyer
@c 
@c if no unique
@c solution exists, then @code{singular} will be displayed.

When @mref{programmode} is @code{false}, @code{solve} displays solutions with
intermediate expression (@code{%t}) labels, and returns the list of labels.

When @mref{globalsolve} is @code{true} and the problem is to solve two or more
linear equations, each solved-for variable is bound to its value in the solution
of the equations.

Examples:

@c FOLLOWING ADAPTED FROM example (solve)
@c ===beg===
@c solve (asin (cos (3*x))*(f(x) - 1), x);
@c ev (solve (5^f(x) = 125, f(x)), solveradcan);
@c [4*x^2 - y^2 = 12, x*y - x = 2];
@c solve (%, [x, y]);
@c solve (1 + a*x + x^3, x);
@c solve (x^3 - 1);
@c solve (x^6 - 1);
@c ev (x^6 - 1, %[1]);
@c expand (%);
@c x^2 - 1;
@c solve (%, x);
@c ev (%th(2), %[1]);
@c ===end===
@example maxima
@group
(%i1) solve (asin (cos (3*x))*(f(x) - 1), x);
solve: using arc-trig functions to get a solution.
Some solutions will be lost.
                            %pi
(%o1)                  [x = ---, f(x) = 1]
                             6
@end group
@group
(%i2) ev (solve (5^f(x) = 125, f(x)), solveradcan);
                                log(125)
(%o2)                   [f(x) = --------]
                                 log(5)
@end group
@group
(%i3) [4*x^2 - y^2 = 12, x*y - x = 2];
                      2    2
(%o3)             [4 x  - y  = 12, x y - x = 2]
@end group
@group
(%i4) solve (%, [x, y]);
(%o4) [[x = 2, y = 2], [x = 0.5202594388652008 %i
 - 0.1331240357358706, y = 0.07678378523787788
 - 3.608003221870287 %i], [x = - 0.5202594388652008 %i
 - 0.1331240357358706, y = 3.608003221870287 %i
 + 0.07678378523787788], [x = - 1.733751846381093, 
y = - 0.15356757100196963]]
@end group
@group
(%i5) solve (1 + a*x + x^3, x);
                                       3
            - 1   sqrt(3) %i   sqrt(4 a  + 27)   1 1/3
(%o5) [x = (--- - ----------) (--------------- - -)
             2        2               3/2        2
                                   2 3
       sqrt(3) %i   - 1
      (---------- + ---) a
           2         2
 - --------------------------, x = 
              3
      sqrt(4 a  + 27)   1 1/3
   3 (--------------- - -)
             3/2        2
          2 3
                            3
 sqrt(3) %i   - 1   sqrt(4 a  + 27)   1 1/3
(---------- + ---) (--------------- - -)
     2         2           3/2        2
                        2 3
       - 1   sqrt(3) %i
      (--- - ----------) a
        2        2
 - --------------------------, x = 
              3
      sqrt(4 a  + 27)   1 1/3
   3 (--------------- - -)
             3/2        2
          2 3
         3
 sqrt(4 a  + 27)   1 1/3               a
(--------------- - -)    - --------------------------]
        3/2        2                  3
     2 3                      sqrt(4 a  + 27)   1 1/3
                           3 (--------------- - -)
                                     3/2        2
                                  2 3
@end group
@group
(%i6) solve (x^3 - 1);
             sqrt(3) %i - 1        sqrt(3) %i + 1
(%o6)   [x = --------------, x = - --------------, x = 1]
                   2                     2
@end group
@group
(%i7) solve (x^6 - 1);
           sqrt(3) %i + 1      sqrt(3) %i - 1
(%o7) [x = --------------, x = --------------, x = - 1, 
                 2                   2
                     sqrt(3) %i + 1        sqrt(3) %i - 1
               x = - --------------, x = - --------------, x = 1]
                           2                     2
@end group
@group
(%i8) ev (x^6 - 1, %[1]);
                                      6
                      (sqrt(3) %i + 1)
(%o8)                 ----------------- - 1
                             64
@end group
@group
(%i9) expand (%);
(%o9)                           0
@end group
@group
(%i10) x^2 - 1;
                              2
(%o10)                       x  - 1
@end group
@group
(%i11) solve (%, x);
(%o11)                  [x = - 1, x = 1]
@end group
@group
(%i12) ev (%th(2), %[1]);
(%o12)                          0
@end group
@end example

The symbols @code{%r} are used to denote arbitrary constants in a solution.

@c ===beg===
@c solve([x+y=1,2*x+2*y=2],[x,y]);
@c ===end===
@example maxima
@group
(%i1) solve([x+y=1,2*x+2*y=2],[x,y]);
solve: dependent equations eliminated: (2)
(%o1)               [[x = 1 - %r1, y = %r1]]
@end group
@end example

See @mref{algsys} and @mref{%rnum_list} for more information.

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{solvedecomposes}
@defvr {Option variable} solvedecomposes
Default value: @code{true}

When @code{solvedecomposes} is @code{true}, @code{solve} calls
@mref{polydecomp} if asked to solve polynomials.
@c OTHERWISE WHAT HAPPENS -- CAN'T SOLVE POLYNOMIALS, OR SOME OTHER METHOD IS USED ??

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{solveexplicit}
@defvr {Option variable} solveexplicit
Default value: @code{false}

When @code{solveexplicit} is @code{true}, inhibits @mref{solve} from returning
implicit solutions, that is, solutions of the form @code{F(x) = 0} where
@code{F} is some function.
@c NEED AN EXAMPLE HERE

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{solvefactors}
@defvr {Option variable} solvefactors
Default value: @code{true}

@c WHAT IS THIS ABOUT EXACTLY ??
When @code{solvefactors} is @code{false}, @mref{solve} does not try to factor
the expression.  The @code{false} setting may be desired in some cases where
factoring is not necessary.
@c NEED AN EXAMPLE HERE

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{solvenullwarn}
@defvr {Option variable} solvenullwarn
Default value: @code{true}

When @code{solvenullwarn} is @code{true}, @mref{solve} prints a warning message
if called with either a null equation list or a null variable list.  For
example, @code{solve ([], [])} would print two warning messages and return
@code{[]}.

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{solveradcan}
@defvr {Option variable} solveradcan
Default value: @code{false}

When @code{solveradcan} is @code{true}, @mref{solve} calls @mref{radcan}@w{}
which makes @code{solve} slower but will allow certain problems containing
exponentials and logarithms to be solved.
@c NEED AN EXAMPLE HERE

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{solvetrigwarn}
@defvr {Option variable} solvetrigwarn
Default value: @code{true}

@c MAYBE THIS CAN BE CLARIFIED
When @code{solvetrigwarn} is @code{true}, @mref{solve} may print a message
saying that it is using inverse trigonometric functions to solve the equation,
and thereby losing solutions.
@c NEED AN EXAMPLE HERE

@opencatbox{Categories:}
@category{Algebraic equations}
@closecatbox
@end defvr

@c =============================================================================
@node Examples for algsys, References for equations, Functions and Variables for Equations, Equations
@section Examples for algsys

@var{algsys} often fails to solve problems that have solutions.  The following examples
provide some solution strategies.

@subsection Strategies

Many users try to solve the most general problem imaginable, with multiple
free parameters. Unfortunately the size and complexity of individual solutions
increases rapidly with
the number of parameters, as can be seen in the examples below.
This 'expression swell' makes it difficult for a computer
algebra system to confirm symbolically that solutions satisfy the
input equations so solutions can be incorrectly rejected by a solver.
Every effort should be made to reduce the complexity of, and number of
parameters in, the equations to be solved.

@subsection Example 1: Intersection of two circles

We wish to find the intersection points of two circles: one centered
at (a,b) with radius r
and the second centered at (c,d) with radius s.

@var{algsys} does not find a solution to the original problem.
@c ===beg===
@c eq1: (x-a)^2+(y-b)^2-r^2;
@c eq2: (x-c)^2+(y-d)^2-s^2;
@c algsys([eq1,eq2],[x,y]);
@c ===end===
@example maxima
@group
(%i1) eq1: (x-a)^2+(y-b)^2-r^2;
                           2          2    2
(%o1)               (y - b)  + (x - a)  - r
@end group
@group
(%i2) eq2: (x-c)^2+(y-d)^2-s^2;
                           2          2    2
(%o2)               (y - d)  + (x - c)  - s
@end group
@group
(%i3) algsys([eq1,eq2],[x,y]);
(%o3)                          []
@end group
@end example

@c -----------------------------------------------------------------------------
@subsubheading Simplify the problem

This problem can be transformed to eliminate parameters by:
translating the center of the first circle to the origin;
scaling so that the first circle has radius 1;
and, rotating about the new origin so that
the center of the second circle is located on the positive x-axis.

@c ===beg===
@c eq1a:x^2+y^2-1;
@c eq2a:(x-C)^2+y^2-S^2;
@c algsys([eq1a,eq2a],[x,y]);
@c ===end===
@example maxima
@group
(%i1) eq1a:x^2+y^2-1;
                            2    2
(%o1)                      y  + x  - 1
@end group
@group
(%i2) eq2a:(x-C)^2+y^2-S^2;
                        2          2    2
(%o2)                  y  + (x - C)  - S
@end group
@group
(%i3) algsys([eq1a,eq2a],[x,y]);
               2    2
              S  - C  - 1
(%o3) [[x = - -----------, y = 
                  2 C
          4       2       2    4      2
  sqrt(- S  + (2 C  + 2) S  - C  + 2 C  - 1)
- ------------------------------------------], 
                     2 C
        2    2
       S  - C  - 1
[x = - -----------, y = 
           2 C
        4       2       2    4      2
sqrt(- S  + (2 C  + 2) S  - C  + 2 C  - 1)
------------------------------------------]]
                   2 C
@end group
@end example

It is not necessary to rescale these equations to obtain
a solution.

@c ===beg===
@c eq1b:x^2+y^2-r^2;
@c eq2b:(x-C)^2+y^2-s^2;
@c algsys([eq1b,eq2b],[x,y]);
@c ===end===
@example maxima
@group
(%i1) eq1b:x^2+y^2-r^2;
                           2    2    2
(%o1)                     y  + x  - r
@end group
@group
(%i2) eq2b:(x-C)^2+y^2-s^2;
                        2          2    2
(%o2)                  y  + (x - C)  - s
@end group
@group
(%i3) algsys([eq1b,eq2b],[x,y]);
               2    2    2
              s  - r  - C
(%o3) [[x = - ------------, y = 
                  2 C
          4       2      2   2    4      2  2    4
  sqrt(- s  + (2 r  + 2 C ) s  - r  + 2 C  r  - C )
- -------------------------------------------------], 
                         2 C
        2    2    2
       s  - r  - C
[x = - ------------, y = 
           2 C
        4       2      2   2    4      2  2    4
sqrt(- s  + (2 r  + 2 C ) s  - r  + 2 C  r  - C )
-------------------------------------------------]]
                       2 C
@end group
@end example

@c -----------------------------------------------------------------------------
@subsubheading Simplify the equations

Another strategy is to simplify the equations. 
The expression @var{eq1-eq2} is linear in unknowns @var{x} and @var{y}.
@var{algsys} can solve the simpler system of equations @var{[eq1,eq1-eq2]}.

Note the complexity of the solution at (%o4).  

@c ===beg===
@c eq1: (x-a)^2+(y-b)^2-r^2;
@c eq2: (x-c)^2+(y-d)^2-s^2;
@c eq3: expand(eq1-eq2);
@c soln:algsys([eq1,eq3],[x,y]);
@c ratsimp(subst(soln[1],[eq1,eq2]));
@c ratsimp(subst(soln[2],[eq1,eq2]));
@c ===end===
@example maxima
@group
(%i1) eq1: (x-a)^2+(y-b)^2-r^2;
                           2          2    2
(%o1)               (y - b)  + (x - a)  - r
@end group
@group
(%i2) eq2: (x-c)^2+(y-d)^2-s^2;
                           2          2    2
(%o2)               (y - d)  + (x - c)  - s
@end group
@group
(%i3) eq3: expand(eq1-eq2);
                                       2    2    2    2    2    2
(%o3) 2 d y - 2 b y + 2 c x - 2 a x + s  - r  - d  - c  + b  + a
@end group
@group
(%i4) soln:algsys([eq1,eq3],[x,y]);
                               4
(%o4) [[x = - ((d - b) sqrt(- s
       2      2              2              2      2   2    4
 + (2 r  + 2 d  - 4 b d + 2 c  - 4 a c + 2 b  + 2 a ) s  - r
       2              2              2      2   2    4        3
 + (2 d  - 4 b d + 2 c  - 4 a c + 2 b  + 2 a ) r  - d  + 4 b d
         2              2      2   2
 + (- 2 c  + 4 a c - 6 b  - 2 a ) d
         2                3      2         4        3
 + (4 b c  - 8 a b c + 4 b  + 4 a  b) d - c  + 4 a c
         2      2   2         2      3       4      2  2    4
 + (- 2 b  - 6 a ) c  + (4 a b  + 4 a ) c - b  - 2 a  b  - a )
            2            2              2
 + (c - a) s  + (a - c) r  + (- c - a) d  + (2 b c + 2 a b) d
    3      2     2    2         2    3
 - c  + a c  + (a  - b ) c - a b  - a )
     2              2              2      2
/(2 d  - 4 b d + 2 c  - 4 a c + 2 b  + 2 a ), 
                     4       2      2              2
y = ((c - a) sqrt(- s  + (2 r  + 2 d  - 4 b d + 2 c  - 4 a c
      2      2   2    4       2              2              2
 + 2 b  + 2 a ) s  - r  + (2 d  - 4 b d + 2 c  - 4 a c + 2 b
      2   2    4        3         2              2      2   2
 + 2 a ) r  - d  + 4 b d  + (- 2 c  + 4 a c - 6 b  - 2 a ) d
         2                3      2         4        3
 + (4 b c  - 8 a b c + 4 b  + 4 a  b) d - c  + 4 a c
         2      2   2         2      3       4      2  2    4
 + (- 2 b  - 6 a ) c  + (4 a b  + 4 a ) c - b  - 2 a  b  - a )
            2            2    3      2     2            2    2
 + (b - d) s  + (d - b) r  + d  - b d  + (c  - 2 a c - b  + a ) d
      2              3    2        2              2
 + b c  - 2 a b c + b  + a  b)/(2 d  - 4 b d + 2 c  - 4 a c
      2      2                          4
 + 2 b  + 2 a )], [x = ((d - b) sqrt(- s
       2      2              2              2      2   2    4
 + (2 r  + 2 d  - 4 b d + 2 c  - 4 a c + 2 b  + 2 a ) s  - r
       2              2              2      2   2    4        3
 + (2 d  - 4 b d + 2 c  - 4 a c + 2 b  + 2 a ) r  - d  + 4 b d
         2              2      2   2
 + (- 2 c  + 4 a c - 6 b  - 2 a ) d
         2                3      2         4        3
 + (4 b c  - 8 a b c + 4 b  + 4 a  b) d - c  + 4 a c
         2      2   2         2      3       4      2  2    4
 + (- 2 b  - 6 a ) c  + (4 a b  + 4 a ) c - b  - 2 a  b  - a )
            2            2            2
 + (a - c) s  + (c - a) r  + (c + a) d  + (- 2 b c - 2 a b) d
    3      2     2    2         2    3
 + c  - a c  + (b  - a ) c + a b  + a )
     2              2              2      2
/(2 d  - 4 b d + 2 c  - 4 a c + 2 b  + 2 a ), 
                       4       2      2              2
y = - ((c - a) sqrt(- s  + (2 r  + 2 d  - 4 b d + 2 c  - 4 a c
      2      2   2    4       2              2              2
 + 2 b  + 2 a ) s  - r  + (2 d  - 4 b d + 2 c  - 4 a c + 2 b
      2   2    4        3         2              2      2   2
 + 2 a ) r  - d  + 4 b d  + (- 2 c  + 4 a c - 6 b  - 2 a ) d
         2                3      2         4        3
 + (4 b c  - 8 a b c + 4 b  + 4 a  b) d - c  + 4 a c
         2      2   2         2      3       4      2  2    4
 + (- 2 b  - 6 a ) c  + (4 a b  + 4 a ) c - b  - 2 a  b  - a )
            2            2    3      2
 + (d - b) s  + (b - d) r  - d  + b d
       2            2    2         2              3    2
 + (- c  + 2 a c + b  - a ) d - b c  + 2 a b c - b  - a  b)
     2              2              2      2
/(2 d  - 4 b d + 2 c  - 4 a c + 2 b  + 2 a )]]
@end group
@group
(%i5) ratsimp(subst(soln[1],[eq1,eq2]));
(%o5)                        [0, 0]
@end group
@group
(%i6) ratsimp(subst(soln[2],[eq1,eq2]));
(%o6)                        [0, 0]
@end group
@end example

@c -----------------------------------------------------------------------------
@subsubheading Simplify the equations using poly_reduced_grobner

Sometimes the system of equations can be solved after preprocessing
with the function
@mref{poly_reduced_grobner} from the @var{grobner} package.

The reduced Gröbner basis returned at (%o4) consists of two polynomials
in unknowns @var{x} and @var{y}:
the first is bilinear in the unknowns;
the second is quadratic in @var{y} only.  This confirms there
are two (perhaps multiple) solutions, as we know geometrically.

@c ===beg===
@c eq1: (x-a)^2+(y-b)^2-r^2;
@c eq2: (x-c)^2+(y-d)^2-s^2;
@c /* load grobner package */
@c  load("grobner")$
@c poly_reduced_grobner([eq1,eq2],[x,y]);
@c soln:algsys(%,[x,y]);
@c ratsimp(subst(soln[1],[eq1,eq2]));
@c ratsimp(subst(soln[2],[eq1,eq2]));
@c ===end===
@example maxima
@group
(%i1) eq1: (x-a)^2+(y-b)^2-r^2;
                           2          2    2
(%o1)               (y - b)  + (x - a)  - r
@end group
@group
(%i2) eq2: (x-c)^2+(y-d)^2-s^2;
                           2          2    2
(%o2)               (y - d)  + (x - c)  - s
@end group
@group
(%i3) /* load grobner package */
 load("grobner")$
@end group
@group
(%i4) poly_reduced_grobner([eq1,eq2],[x,y]);
                                        2    2    2    2    2
(%o4) [(2 d - 2 b) y + (2 c - 2 a) x + s  - r  - d  - c  + b
    2      2              2              2      2   2
 + a , (4 d  - 8 b d + 4 c  - 8 a c + 4 b  + 4 a ) y
          2      2      2          2      2       3        2
 + (d (4 s  - 4 r  + 4 b ) + b (4 r  - 4 s ) - 4 d  + 4 b d
                      2                  2                    3
 + a c (8 d + 8 b) + c  (- 4 d - 4 b) + a  (- 4 d - 4 b) - 4 b )
      4            2      2      2      2       3
 y + s  + c (a (4 s  + 4 r  - 4 d  - 4 b ) - 4 a )
    2     2      2       2  2    2       2      2      2
 + b  (2 s  - 2 r ) - 2 r  s  + d  (- 2 s  + 2 r  - 2 b )
    2       2      2      2      2      2
 + c  (- 2 s  - 2 r  + 2 d  + 2 b  + 6 a )
    2       2      2      2      2     4    4    4        3    4
 + a  (- 2 s  - 2 r  + 2 d  + 2 b ) + r  + d  + c  - 4 a c  + b
    4
 + a ]
@end group
@group
(%i5) soln:algsys(%,[x,y]);
                               4
(%o5) [[x = - ((d - b) sqrt(- s
       2      2              2              2      2   2    4
 + (2 r  + 2 d  - 4 b d + 2 c  - 4 a c + 2 b  + 2 a ) s  - r
       2              2              2      2   2    4        3
 + (2 d  - 4 b d + 2 c  - 4 a c + 2 b  + 2 a ) r  - d  + 4 b d
         2              2      2   2
 + (- 2 c  + 4 a c - 6 b  - 2 a ) d
         2                3      2         4        3
 + (4 b c  - 8 a b c + 4 b  + 4 a  b) d - c  + 4 a c
         2      2   2         2      3       4      2  2    4
 + (- 2 b  - 6 a ) c  + (4 a b  + 4 a ) c - b  - 2 a  b  - a )
            2            2              2
 + (c - a) s  + (a - c) r  + (- c - a) d  + (2 b c + 2 a b) d
    3      2     2    2         2    3
 - c  + a c  + (a  - b ) c - a b  - a )
     2              2              2      2
/(2 d  - 4 b d + 2 c  - 4 a c + 2 b  + 2 a ), 
                     4       2      2              2
y = ((c - a) sqrt(- s  + (2 r  + 2 d  - 4 b d + 2 c  - 4 a c
      2      2   2    4       2              2              2
 + 2 b  + 2 a ) s  - r  + (2 d  - 4 b d + 2 c  - 4 a c + 2 b
      2   2    4        3         2              2      2   2
 + 2 a ) r  - d  + 4 b d  + (- 2 c  + 4 a c - 6 b  - 2 a ) d
         2                3      2         4        3
 + (4 b c  - 8 a b c + 4 b  + 4 a  b) d - c  + 4 a c
         2      2   2         2      3       4      2  2    4
 + (- 2 b  - 6 a ) c  + (4 a b  + 4 a ) c - b  - 2 a  b  - a )
            2            2    3      2     2            2    2
 + (b - d) s  + (d - b) r  + d  - b d  + (c  - 2 a c - b  + a ) d
      2              3    2        2              2
 + b c  - 2 a b c + b  + a  b)/(2 d  - 4 b d + 2 c  - 4 a c
      2      2                          4
 + 2 b  + 2 a )], [x = ((d - b) sqrt(- s
       2      2              2              2      2   2    4
 + (2 r  + 2 d  - 4 b d + 2 c  - 4 a c + 2 b  + 2 a ) s  - r
       2              2              2      2   2    4        3
 + (2 d  - 4 b d + 2 c  - 4 a c + 2 b  + 2 a ) r  - d  + 4 b d
         2              2      2   2
 + (- 2 c  + 4 a c - 6 b  - 2 a ) d
         2                3      2         4        3
 + (4 b c  - 8 a b c + 4 b  + 4 a  b) d - c  + 4 a c
         2      2   2         2      3       4      2  2    4
 + (- 2 b  - 6 a ) c  + (4 a b  + 4 a ) c - b  - 2 a  b  - a )
            2            2            2
 + (a - c) s  + (c - a) r  + (c + a) d  + (- 2 b c - 2 a b) d
    3      2     2    2         2    3
 + c  - a c  + (b  - a ) c + a b  + a )
     2              2              2      2
/(2 d  - 4 b d + 2 c  - 4 a c + 2 b  + 2 a ), 
                       4       2      2              2
y = - ((c - a) sqrt(- s  + (2 r  + 2 d  - 4 b d + 2 c  - 4 a c
      2      2   2    4       2              2              2
 + 2 b  + 2 a ) s  - r  + (2 d  - 4 b d + 2 c  - 4 a c + 2 b
      2   2    4        3         2              2      2   2
 + 2 a ) r  - d  + 4 b d  + (- 2 c  + 4 a c - 6 b  - 2 a ) d
         2                3      2         4        3
 + (4 b c  - 8 a b c + 4 b  + 4 a  b) d - c  + 4 a c
         2      2   2         2      3       4      2  2    4
 + (- 2 b  - 6 a ) c  + (4 a b  + 4 a ) c - b  - 2 a  b  - a )
            2            2    3      2
 + (d - b) s  + (b - d) r  - d  + b d
       2            2    2         2              3    2
 + (- c  + 2 a c + b  - a ) d - b c  + 2 a b c - b  - a  b)
     2              2              2      2
/(2 d  - 4 b d + 2 c  - 4 a c + 2 b  + 2 a )]]
@end group
@group
(%i6) ratsimp(subst(soln[1],[eq1,eq2]));
(%o6)                        [0, 0]
@end group
@group
(%i7) ratsimp(subst(soln[2],[eq1,eq2]));
(%o7)                        [0, 0]
@end group
@end example

@c -----------------------------------------------------------------------------
@subsection Example 2: Equations with irrational coefficients

The presence of irrational coefficients can prevent @var{algsys}
from finding solutions.  Replacing the constant with a symbol
allows a solution to be found.

@c ===beg===
@c eq1: %pi*y + x - 1;
@c eq2: 1 - x^2*y;
@c algsys([eq1,eq2],[x,y]);
@c /* Substitute p for %p and magically algsys finds solutions */
@c  eq1a:subst(p,%pi,eq1);
@c s:algsys([eq1a,eq2],[x,y]);
@c /* substitute %pi for p */
@c  s:subst(%pi,p,s)$
@c /* Check the solution */
@c  ratsimp(subst(s[1],[eq1,eq2]));
@c ratsimp(subst(s[2],[eq1,eq2]));
@c ratsimp(subst(s[3],[eq1,eq2]));
@c /* numerical values of solution */
@c  rectform(float(s));
@c ===end===
@example maxima
@group
(%i1) eq1: %pi*y + x - 1;
(%o1)                     %pi y + x - 1
@end group
@group
(%i2) eq2: 1 - x^2*y;
                                 2
(%o2)                       1 - x  y
@end group
@group
(%i3) algsys([eq1,eq2],[x,y]);
(%o3)                          []
@end group
@group
(%i4) /* Substitute p for %p and magically algsys finds solutions */
 eq1a:subst(p,%pi,eq1);
(%o4)                      p y + x - 1
@end group
@group
(%i5) s:algsys([eq1a,eq2],[x,y]);
                 5/3               5/3
(%o5) [[x = - ((2    sqrt(3) %i + 2   )
   3/2          2                   1/3
 (3    sqrt(27 p  - 4 p) - 27 p + 2)
     3/2          2                   2/3
 + (3    sqrt(27 p  - 4 p) - 27 p + 2)
      1/3       1/3  3/2           2
 ((9 2    %i - 2    3   ) sqrt(27 p  - 4 p)
     1/3  7/2          1/3       4/3               4/3
 + (2    3    %i - 27 2   ) p - 2    sqrt(3) %i + 2   ) - 8)/24, 
       5/3               5/3
y = ((2    sqrt(3) %i + 2   )
   3/2          2                   1/3
 (3    sqrt(27 p  - 4 p) - 27 p + 2)
     3/2          2                   2/3
 + (3    sqrt(27 p  - 4 p) - 27 p + 2)
      1/3       1/3  3/2           2
 ((9 2    %i - 2    3   ) sqrt(27 p  - 4 p)
     1/3  7/2          1/3       4/3               4/3
 + (2    3    %i - 27 2   ) p - 2    sqrt(3) %i + 2   ) + 16)
                  5/3               5/3
/(24 p)], [x = ((2    sqrt(3) %i - 2   )
   3/2          2                   1/3
 (3    sqrt(27 p  - 4 p) - 27 p + 2)
     3/2          2                   2/3
 + (3    sqrt(27 p  - 4 p) - 27 p + 2)
      1/3       1/3  3/2           2
 ((9 2    %i + 2    3   ) sqrt(27 p  - 4 p)
     1/3  7/2          1/3       4/3               4/3
 + (2    3    %i + 27 2   ) p - 2    sqrt(3) %i - 2   ) + 8)/24, 
         5/3               5/3
y = - ((2    sqrt(3) %i - 2   )
   3/2          2                   1/3
 (3    sqrt(27 p  - 4 p) - 27 p + 2)
     3/2          2                   2/3
 + (3    sqrt(27 p  - 4 p) - 27 p + 2)
      1/3       1/3  3/2           2
 ((9 2    %i + 2    3   ) sqrt(27 p  - 4 p)
     1/3  7/2          1/3       4/3               4/3
 + (2    3    %i + 27 2   ) p - 2    sqrt(3) %i - 2   ) - 16)
                     5/3   3/2          2                   1/3
/(24 p)], [x = - (- 2    (3    sqrt(27 p  - 4 p) - 27 p + 2)
     3/2          2                   2/3
 + (3    sqrt(27 p  - 4 p) - 27 p + 2)
   1/3  3/2          2              1/3      4/3
 (2    3    sqrt(27 p  - 4 p) + 27 2    p - 2   ) - 4)/12, 
        5/3   3/2          2                   1/3
y = (- 2    (3    sqrt(27 p  - 4 p) - 27 p + 2)
     3/2          2                   2/3
 + (3    sqrt(27 p  - 4 p) - 27 p + 2)
   1/3  3/2          2              1/3      4/3
 (2    3    sqrt(27 p  - 4 p) + 27 2    p - 2   ) + 8)/(12 p)]]
@end group
@group
(%i6) /* substitute %pi for p */
 s:subst(%pi,p,s)$
@end group
@group
(%i7) /* Check the solution */
 ratsimp(subst(s[1],[eq1,eq2]));
(%o7)                        [0, 0]
@end group
@group
(%i8) ratsimp(subst(s[2],[eq1,eq2]));
(%o8)                        [0, 0]
@end group
@group
(%i9) ratsimp(subst(s[3],[eq1,eq2]));
(%o9)                        [0, 0]
@end group
@group
(%i10) /* numerical values of solution */
 rectform(float(s));
(%o10) [[x = 1.0980298583288306 - 1.1920356507617584 %i, 
y = 0.37943673232099623 %i - 0.031203873047263193], 
[x = 1.1920356507617584 %i + 1.0980298583288306, 
y = - 0.37943673232099623 %i - 0.031203873047263193], 
[x = - 1.1960597166576612, y = 0.6990275184621078]]
@end group
@end example

@c -----------------------------------------------------------------------------
@subsection Example 3: Assumptions on parameters

@var{algsys} may require assumptions on parameters to obtain a solution.
No general guidance can be provided.  Users may be able to use their knowledge
of the problem to restrict the range of parameters appropriately.

@c ===beg===
@c eqs:[y-x=0, g*x*y-h=0, z+(x+1)/y-x-1=0];
@c /* without assumptions no solution is found */
@c  algsys(eqs,[x,y,z]);
@c assume(h>0);
@c algsys(eqs,[x,y,z]);
@c /* With a different assumption the solution has a different form */
@c  (forget(h>0),assume(h<0));
@c algsys(eqs,[x,y,z]);
@c ===end===
@example maxima
@group
(%i1) eqs:[y-x=0, g*x*y-h=0, z+(x+1)/y-x-1=0];
                                       x + 1
(%o1)   [y - x = 0, g x y - h = 0, z + ----- - x - 1 = 0]
                                         y
@end group
@group
(%i2) /* without assumptions no solution is found */
 algsys(eqs,[x,y,z]);
(%o2)                          []
@end group
@group
(%i3) assume(h>0);
(%o3)                        [h > 0]
@end group
@group
(%i4) algsys(eqs,[x,y,z]);
            sqrt(h)      sqrt(h)           h - g
(%o4) [[x = -------, y = -------, z = ---------------], 
            sqrt(g)      sqrt(g)      sqrt(g) sqrt(h)
                  sqrt(h)        sqrt(h)             h - g
           [x = - -------, y = - -------, z = - ---------------]]
                  sqrt(g)        sqrt(g)        sqrt(g) sqrt(h)
@end group
@group
(%i5) /* With a different assumption the solution has a different form */
 (forget(h>0),assume(h<0));
(%o5)                        [h < 0]
@end group
@group
(%i6) algsys(eqs,[x,y,z]);
              %i sqrt(- h)        %i sqrt(- h)
(%o6) [[x = - ------------, y = - ------------, 
                sqrt(g)             sqrt(g)
      sqrt(- h) (%i h - %i g)
z = - -----------------------], 
             sqrt(g) h
     %i sqrt(- h)      %i sqrt(- h)
[x = ------------, y = ------------, 
       sqrt(g)           sqrt(g)
    sqrt(- h) (%i h - %i g)
z = -----------------------]]
           sqrt(g) h
@end group
@end example

@c -----------------------------------------------------------------------------
@subsection Example 4: Preproccess equations with poly_reduced_grobner

In this example the direct solution of the system of equations
using @var{algsys} finds four real solutions.
After preprocessing with @mref{poly_reduced_grobner}, ten
solutions are found.

Inspection of the reduced Gröbner basis returned at (%o5) shows that it
comprises a degree-10 polynomial in @var{y} and an expression
linear in @var{x} and of degree-8 in @var{y}. There can be at most
10 solutions for y, and exactly one @var{x} solution for each @var{y}
solution, for a maximum of ten solutions overall.

@c ===beg===
@c p1:-x*y^3+y^2+x^4-9*x/8;
@c p2:y^4-x^3*y-9*y/8+x^2;
@c algsys([p1,p2],[x,y]);
@c /* load grobner package */
@c  load("grobner")$
@c eqs:poly_reduced_grobner([p1,p2],[x,y]);
@c algsys(eqs,[x,y]);
@c ===end===
@example maxima
@group
(%i1) p1:-x*y^3+y^2+x^4-9*x/8;
                          3    2    4   9 x
(%o1)                - x y  + y  + x  - ---
                                         8
@end group
@group
(%i2) p2:y^4-x^3*y-9*y/8+x^2;
                       4    3     9 y    2
(%o2)                 y  - x  y - --- + x
                                   8
@end group
@group
(%i3) algsys([p1,p2],[x,y]);
            1               9      9               1
(%o3) [[x = -, y = 1], [x = -, y = -], [x = 1, y = -], 
            2               8      8               2
                                                  [x = 0, y = 0]]
@end group
@group
(%i4) /* load grobner package */
 load("grobner")$
@end group
@group
(%i5) eqs:poly_reduced_grobner([p1,p2],[x,y]);
                 8           5           2
(%o5) [- 200704 y  + 437832 y  - 263633 y  + 53010 x, 
                                 10          7         4
                           4096 y   - 10440 y  + 7073 y  - 729 y]
@end group
@group
(%i6) algsys(eqs,[x,y]);
                                   1        9      9
(%o6) [[x = 0, y = 0], [x = 1, y = -], [x = -, y = -], 
                                   2        8      8
     1               sqrt(3) %i - 1        sqrt(3) %i + 1
[x = -, y = 1], [x = --------------, y = - --------------], 
     2                     4                     2
       sqrt(3) %i + 1      sqrt(3) %i - 1
[x = - --------------, y = --------------], 
             4                   2
      5/2                5/2
     3    %i - 9        3    %i + 9
[x = -----------, y = - -----------], 
         16                 16
        5/2              5/2
       3    %i + 9      3    %i - 9
[x = - -----------, y = -----------], 
           16               16
     sqrt(3) %i - 1        sqrt(3) %i + 1
[x = --------------, y = - --------------], 
           2                     4
       sqrt(3) %i + 1      sqrt(3) %i - 1
[x = - --------------, y = --------------]]
             2                   4
@end group
@end example

@subsection Example 5: Intersection of a sphere with two paraboloids

This problem is the intersection of a sphere with two paraboloids
  (@ref{allgower,,Allgower et al 1992}, Example 2, p841).

There are two real solutions y = z = (sqrt(5)-1)/2,
x = +/- sqrt(z-y^2) = +/- sqrt(sqrt(5)-2).

@c ===beg===
@c algsys([x^2+y^2+z^2-1,z-x^2-y^2,y-x^2-z^2],[x,y,z]);
@c ===end===
@example maxima
@group
(%i1) algsys([x^2+y^2+z^2-1,z-x^2-y^2,y-x^2-z^2],[x,y,z]);
                            sqrt(5) - 1        sqrt(5) + 1
(%o1) [[x = sqrt(2) %i, y = -----------, z = - -----------], 
                                 2                  2
                       sqrt(5) + 1      sqrt(5) - 1
[x = sqrt(2) %i, y = - -----------, z = -----------], 
                            2                2
                       sqrt(5) - 1        sqrt(5) + 1
[x = - sqrt(2) %i, y = -----------, z = - -----------], 
                            2                  2
                         sqrt(5) + 1      sqrt(5) - 1
[x = - sqrt(2) %i, y = - -----------, z = -----------], 
                              2                2
                                sqrt(5) + 1        sqrt(5) + 1
[x = sqrt(- sqrt(5) - 2), y = - -----------, z = - -----------], 
                                     2                  2
                                  sqrt(5) + 1
[x = - sqrt(- sqrt(5) - 2), y = - -----------, 
                                       2
      sqrt(5) + 1                               sqrt(5) - 1
z = - -----------], [x = sqrt(sqrt(5) - 2), y = -----------, 
           2                                         2
    sqrt(5) - 1                                 sqrt(5) - 1
z = -----------], [x = - sqrt(sqrt(5) - 2), y = -----------, 
         2                                           2
    sqrt(5) - 1
z = -----------]]
         2
@end group
@end example

@c =============================================================================
@node References for equations, , Examples for algsys, Equations
@section References for equations

@itemize

@item @anchor{beyer}
(Beyer 1984) Beyer, William A.,
   Solution of Simultaneous Polynomial Equations by Elimination in MACSYMA,
   @url{ http://udspace.udel.edu/handle/19716/1399 ,
   Proceedings of the 1984 MACSYMA Users' Conference}, pp 110-120
   

@item @anchor{allgower}
(Allgower et al 1992) Eugene L. Allgower, Kurt Georg and Rick Miranda,
   The Method of
   Resultants for Computing Real Solutions of Polynomial Systems, 
   SIAM Journal on Numerical Analysis, Vol 29 No 3, Jun 1992, pp 831-844
   @url{https://doi.org/10.1137/0729051, doi:10.1137/0729051}

@end itemize
