% This file was created automatically from ratfun.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  ratfun.msk                  GAP documentation            Alexander Hulpke
%A                                                           Frank Celler
%%
%A  @(#)$Id: ratfun.msk,v 1.42 2002/04/15 10:02:33 sal Exp $
%%
%Y  (C) 1998 School Math and Comp. Sci., University of St.  Andrews, Scotland
%Y  Copyright (C) 2002 The GAP Group
%%
\Chapter{Polynomials and Rational Functions}

Let $R$ be a commutative ring-with-one. We call a free associative
algebra $A$ over $R$ a *polynomial ring* over $R$. The free generators of
$A$ are called *indeterminates*, they are usually denoted by
$x_1,x_2,\ldots$. The number of indeterminates is called the *rank* of $A$.
The elements of $A$ are called *polynomials*. Products of
indeterminates are called *monomials*, every
polynomial can be expressed as a finite sum of products of monomials with
ring elements in a form like
$r_{1,0}x_1+r_{1,1}x_1x_2+r_{0,1}x_2+\cdots$ with $r_{i,j}\in R$.

A polynomial ring of rank 1 is called an *univariate* polynomial ring, its
elements are *univariate polynomials*.

Polynomial rings of smaller rank
naturally embed in rings of higher rank; if $S$ is a subring of $R$ then a
polynomial ring over $S$ naturally embeds in a polynomial ring over $R$ of
the same rank.

Internally, indeterminates are represented by positive integers, but it is
possible to give names to them to have them printed in a nicer way. Beware,
however that there is not necessarily any relation between the way an
indeterminate is called and the way it is printed. See section
"Indeterminates" for details.

If $R$ is an integral domain, the polynomial ring $A$ over $R$ is an integral domain as well and one can
therefore form its quotient field $Q$. This field is called a *field of
rational functions*. Again $A$ embeds naturally into $Q$ and {\GAP} will
perform this embedding implicitly. (In fact it implements the ring of rational
functions over $R$.) To avoid problems with leading
coefficients, however, $R$ must be a unique factorization domain.

%%  The operations for rational functions were implemented by Frank Celler and
%%  Alexander Hulpke with help from Werner Nickel and Andrew Solomon.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Indeterminates}

{\GAP} implements a polynomial ring with countably many indeterminates.
These indeterminates can be referred to by positive integers. If only a
number <num> of indeterminates is required they default to `[1..<num>]'.

It is possible to assign names to indeterminates. These names only
provide a means for printing the indeterminates in a nice way, but have
not necessary any relations to variable names. Indeterminates that have
not been assigned a name will be printed as ``{`x_<nr>'}''.

It is possible to assign
the *same* name to *different* indeterminates (though it is probably not
a good idea to do so). Asking *twice* for an indeterminate with the name
<nam> will produce *two different* indeterminates!

When asking for indeterminates with certain
names, {\GAP} usually will take the first indeterminates that are not
yet named, name these accordingly and return them. Thus when asking for
named indeterminates, no relation between names and indeterminate
numbers can be guaranteed. The attribute
`IndeterminateNumberOfLaurentPolynomial(<indet>)' will return
the number of the indeterminate <indet>.


\>Indeterminate( <R>, [<nr>] ) O
\>Indeterminate( <R>, [<avoid>] ) O
\>Indeterminate( <R>, <name>[, <avoid>] ) O
\>Indeterminate( <fam>, <nr> ) O

returns indeterminate number <nr> over the ring <R>. If <nr> is not
given it defaults to 1. If the number is not specified a list <avoid> of
indeterminates may be given. The function will return an indeterminate
that is guaranteed to be different from all the indeterminates in
<avoid>. The third usage returns an indeterminate called <name> (also
avoiding the indeterminates in <avoid> if given).

\beginexample 
gap> a:=Indeterminate(GF(3));
x_1
gap> x:=Indeterminate(GF(3),"x");
x
gap> Indeterminate(GF(3),"x")=x;
false
gap> y:=Indeterminate(GF(3),"y");z:=Indeterminate(GF(3),"X");
y
X
gap> Indeterminate(GF(3),3);
y
gap> Indeterminate(GF(3),[y,z]);
x
\endexample

\>IndeterminateNumberOfUnivariateRationalFunction( <rfun> ) A

returns the number of the indeterminate in which the univariate rational
function <rfun> is expressed. (This also provides a way to obtain the
number of a given indeterminate.)

A constant rational function might not possess an indeterminate number. In
this case `IndeterminateNumberOfUnivariateRationalFunction' will
default to a value of 1.
Therefore two univariate polynomials may be considered to be in the same
univariate polynomial ring if their indeterminates have the same number
or one if of them is constant.  (see also~"CIUnivPols"
and~"IsLaurentPolynomialDefaultRep").

\>IndeterminateOfUnivariateRationalFunction( <rfun> ) A

returns the indeterminate in which the univariate rational
function <rfun> is expressed. (cf.
"IndeterminateNumberOfUnivariateRationalFunction".)

\beginexample 
gap> IndeterminateNumberOfUnivariateRationalFunction(z);
4
gap> IndeterminateOfUnivariateRationalFunction(z^5+z);
X
\endexample

\>IndeterminateName( <fam>, <nr> ) O
\>HasIndeterminateName( <fam>, <nr> ) O
\>SetIndeterminateName( <fam>, <nr>, <name> ) O

`SetIndeterminateName' assigns the name <name> to indeterminate <nr>
in the rational functions family <fam>. It issues an error if the
indeterminate was already named.

`IndeterminateName' returns the name of the <nr>-th indeterminate (and
returns `fail' if no name has been assigned).

`HasIndeterminateName' tests whether indeterminate <nr> has already been
assigned a name 

\beginexample 
gap> IndeterminateName(FamilyObj(x),3);
"y"
gap> HasIndeterminateName(FamilyObj(x),5);
false
gap> SetIndeterminateName(FamilyObj(x),10,"bla");
gap> Indeterminate(GF(3),10);
bla
\endexample

As a convenience there is a special method installed for `SetName' that will
assign a name to an indeterminate.
\beginexample 
gap> a:=Indeterminate(GF(3),5);
x_5
gap> SetName(a,"ah");
gap> a^5+a;
ah+ah^5
\endexample

\>CIUnivPols( <upol>, <upol> ) F

This function (whose name stands for
``CommonIndeterminateOfUnivariatePolynomials'') takes two univariate
polynomials as arguments. If both polynomials are given in the same
indeterminate number <indnum> (in this case they are ``compatible'' as
univariate polynomials) it returns <indnum>. In all other cases it
returns `fail'.
`CIUnivPols' also accepts if either polynomial is constant but
formally expressed in another indeterminate, in this situation the
indeterminate of the other polynomial is selected.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Operations for Rational Functions}

The rational functions form a field,
therefore all arithmetic operations are applicable to rational functions.

\>`<f> + <g>'{addition!rational functions}
\>`<f> - <g>'{subtraction!rational functions}
\>`<f> * <g>'{product!rational functions}
\>`<f> / <g>'{quotient!rational functions}

\beginexample 
gap> x:=Indeterminate(Rationals,1);;y:=Indeterminate(Rationals,2);;
gap> f:=3+x*y+x^5;;g:=5+x^2*y+x*y^2;;
gap> a:=g/f;
(5+x_1^2*x_2+x_1*x_2^2)/(3+x_1*x_2+x_1^5)
\endexample

Note that the quotient `<f>/<g>' of two polynomials might be represented as
a rational function again. If <g> is known to divide <f> the call
`Quotient(<f>,<g>)' (see~"Quotient") should be used instead.

\>`<f> mod <g>'{mod!Laurent polynomials}
%\>`<f> mod <int>'{mod!integer polynomial}

For two Laurent polynomials <f> and <g>, `<f> mod <g>' is the Euclidean
remainder (see~"EuclideanRemainder") of <f> modulo <g>.
% For a polynomial <f> over the integers and an integer <int>, `<f> mod <int>'
% is the polynomial over the integers obtained by reducing the coefficients
% of <f> modulo <int>.
% Just a remark:
% These two methods would not be compatible if integers would be regarded
% as constant polynomials.
% Therefore, I leave the second method undocumented.

At the moment {\GAP} does not contain a proper multivariate Gcd algorithm.
Therefore it cannot be guaranteed that rational functions will always be
represented as a quotient of coprime polynomials. In certain unfortunate
situations this might lead to a degree explosion.

All polynomials as well as all the univariate polynomials in the same
indeterminate form subrings of this field. If two rational functions are
known to be in the same subring, the result will be expressed as element in
this subring.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Comparison of Rational Functions}

\>`<f> = <g>'{comparison!rational functions}

Two rational functions <f> and <g> are equal if the product
$`Numerator'(<f>)*`Denominator'(<g>)$ equals
$`Numerator'(<g>)*`Denominator'(<f>)$.

\beginexample 
gap> x:=Indeterminate(Rationals,"x");;y:=Indeterminate(Rationals,"y");;
gap> f:=3+x*y+x^5;;g:=5+x^2*y+x*y^2;;
gap> a:=g/f;
(5+x^2*y+x*y^2)/(3+x*y+x^5)
gap> b:=(g*f)/(f^2);
(15+5*x*y+3*x^2*y+3*x*y^2+5*x^5+x^3*y^2+x^2*y^3+x^7*y+x^6*y^2)/(9+6*x*y+x^2*y^\
2+6*x^5+2*x^6*y+x^10)
gap> a=b;
true
\endexample

\>`<f> \< <g>'{smaller!rational functions}

The ordering of rational functions is defined in several steps. Monomials
(products of indeterminates) are sorted first by total-degree and then
lexicographically (see~"MonomialTotalDegreeLess"). Products of monomials
with ring elements (``terms'') are compared first by their monomials and
then by their coefficients.

\beginexample 
gap> x<y;
true
gap> x^2*y<x*y^2;
true
gap> x*y<x^2*y;
true
gap> x^2*y < 5* y*x^2;
true
\endexample
Polynomials are compared by comparing the largest terms in turn until they
differ.
\beginexample 
gap> x+y<y;
false
gap> x<x+1;
true
\endexample
Rational functions are compared by comparing the polynomial
$`Numerator'(<f>)*`Denominator'(<g>)$ with the polynomial
$`Numerator'(<g>)*`Denominator'(<f>)$. (As the ordering of monomials used by
{\GAP} is invariant under multiplication this is independent of common
factors in numerator and denominator.)
\beginexample 
gap> f/g<g/f;
false
gap> f/g<(g*g)/(f*g);
false
\endexample

For univariate polynomials this reduces to an ordering first by total degree
and then lexicographically on the coefficients.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Properties and Attributes of Rational Functions}

\>IsRationalFunction( <obj> ) C

A rational function is an element of the quotient field of a polynomial
ring over an UFD. It is represented as a quotient of two polynomials,
its numerator (see~"NumeratorOfRationalFunction") and
its denominator (see~"DenominatorOfRationalFunction")


\>NumeratorOfRationalFunction( <ratfun> ) A

returns the nominator of the rational function <ratfun>.

As no proper multivariate gcd has been implemented yet, numerators and
denominators are not guaranteed to be reduced!


\>DenominatorOfRationalFunction( <ratfun> ) A

returns the denominator of the rational function <ratfun>.

As no proper multivariate gcd has been implemented yet, numerators and
denominators are not guaranteed to be reduced!


\beginexample 
gap> x:=Indeterminate(Rationals,1);;y:=Indeterminate(Rationals,2);;
gap> DenominatorOfRationalFunction((x*y+x^2)/y);
y
gap> NumeratorOfRationalFunction((x*y+x^2)/y);
x^2+x*y
\endexample

\>IsPolynomial( <ratfun> ) P

A polynomial is a rational functions whose  denominator is one. (If the
coefficients family forms a field this is equivalent to the denominator
being constant.)

If the base family is not a field, it may be impossible to represent the
quotient of a polynomial by a ring element as a polynomial again, but it
will have to be represented as a rational function.


\beginexample 
gap> IsPolynomial((x*y+x^2*y^3)/y);
true
gap> IsPolynomial((x*y+x^2)/y);
false
\endexample

\>AsPolynomial( <poly> ) A

If <poly> is a rational function that is a polynomial this attribute
returns an equal rational function <p> such that <p> is equal to its
numerator and the denominator of <p> is one.


\beginexample 
gap> AsPolynomial((x*y+x^2*y^3)/y);
x+x^2*y^2
\endexample

\>IsUnivariateRationalFunction( <ratfun> ) P

A rational function is univariate if its numerator and its denominator
are both polynomials in the same one indeterminate. The attribute
`IndeterminateNumberOfUnivariateRationalFunction' can be used to obtain
the number of this common indeterminate.

\>CoefficientsOfUnivariateRationalFunction( <rfun> ) A

if <rfun> is a univariate rational function, this attribute
returns a list [<ncof>,<dcof>,<val>] where <ncof> and <dcof> are
coefficient lists of univariate polynomials <n> and <d> and a valuation
<val> such that $<rfun>=x^{<val>}\cdot<n>/<d>$ where $x$ is the variable
with the number given by
"IndeterminateNumberOfUnivariateRationalFunction". Numerator and
Denominator are guaranteed to be cancelled.


\>IsUnivariatePolynomial( <ratfun> ) P

A univariate polynomial is a polynomial in only one indeterminate.

\>CoefficientsOfUnivariatePolynomial( <pol> ) A

`CoefficientsOfUnivariatePolynomial'  returns  the     coefficient   list
of the polynomial <pol>, sorted in ascending order.



\>IsLaurentPolynomial( <ratfun> ) P

A Laurent polynomial is a univariate rational function whose denominator
is a monomial. Therefore every univariate polynomial is a
Laurent polynomial.


The attribute `CoefficientsOfLaurentPolynomial'
(see~"CoefficientsOfLaurentPolynomial") gives a compact representation as
Laurent polynomial.

\>IsConstantRationalFunction( <ratfun> ) P

A  constant  rational   function is  a    function  whose  numerator  and
denominator are polynomials of degree 0.



All these tests are applicable to *every* rational function. Depending on the
internal representation of the rational function, however some of these
tests (in particular, univariateness) might be expensive in some cases.

For reasons of performance within algorithms it can be useful to use other
attributes, which give a slightly more technical representation. See
section~"The Representations of Rational Functions" for details.

\>IsPrimitivePolynomial( <F>, <pol> ) O

For a univariate polynomial <pol> of degree $d$ in the indeterminate $X$,
with coefficients in a finite field <F> with $q$ elements, say,
`IsPrimitivePolynomial' returns `true' if
\beginlist%ordered
\item{1.}
    <pol> divides $X^{q^d-1} - 1$, and
\item{2.}
    for each prime divisor $p$ of $q^d - 1$, <pol> does not divide
    $X^{(q^d-1)/p} - 1$,
\endlist
and `false' otherwise.


\>SplittingField( <f> ) A

returns the smallest field which contains the coefficients of <f> and
the roots of <f>.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Univariate Polynomials}

Some of the operations are actually defined on the larger domain of Laurent
polynomials (see "Laurent Polynomials"). For this section you can simply
ignore the word ``Laurent'' if it occurs in a description.

\>UnivariatePolynomial( <ring>, <cofs>[, <ind>] ) O

constructs an univariate polynomial over the ring <ring> in the
indeterminate <ind> with the coefficients given by <coefs>.

\>UnivariatePolynomialByCoefficients( <fam>, <cofs>, <ind> ) O

constructs an univariate polynomial over the coefficients family
<fam> and in the indeterminate <ind> with the coefficients given by
<coefs>. This function should be used in algorithms to create
polynomials as it avoids overhead associated with
`UnivariatePolynomial'.

\>DegreeOfLaurentPolynomial( <pol> ) A

The degree of a univariate (Laurent) polynomial <pol> is the largest
exponent $n$ of a monomial $x^n$ of <pol>.

\beginexample 
gap> p:=UnivariatePolynomial(Rationals,[1,2,3,4],1);
1+2*x+3*x^2+4*x^3
gap> UnivariatePolynomialByCoefficients(FamilyObj(1),[9,2,3,4],73);
9+2*x_73+3*x_73^2+4*x_73^3
gap> CoefficientsOfUnivariatePolynomial(p);
[ 1, 2, 3, 4 ]
gap> DegreeOfLaurentPolynomial(p);
3
gap> IndeterminateNumberOfLaurentPolynomial(p);
1
gap> IndeterminateOfLaurentPolynomial(p);
x
\endexample

We remark that some functions for multivariate polynomials (which will be
defined in the following sections) permit a different syntax for univariate
polynomials which drops the requirement to specify the indeterminate.
Examples are `Value', `Discriminant', `Derivative', `LeadingCoefficient' and
`LeadingMonomial':
\beginexample 
gap> Value(p,Z(5));
Z(5)^2
gap> LeadingCoefficient(p);
4
gap> Derivative(p);
2+6*x+12*x^2
\endexample

\>RootsOfUPol( <upol> ) F
\>RootsOfUPol( <field>, <upol> ) F
\>RootsOfUPol( "split", <upol> ) F

This function returns a list of all roots of the univariate polynomial
<upol> in its default domain. If <field> is given the roots over <field>
are taken, if the first parameter is the string `"split"' the field is
taken to be the splitting field of the polynomial.


\beginexample 
gap> RootsOfUPol(50-45*x-6*x^2+x^3);
[ 10, 1, -5 ]
\endexample

\>UnivariatenessTestRationalFunction( <f> ) F

takes a rational function <f> and tests whether it is univariate or even
a Laurent polynomial. It returns a list
`[<isunivariate>, <indet>, <islaurent>, <cofs>]' where <indet> is the
indeterminate number and <cofs> (if applicable) the coefficients lists.
The list <cofs> is the `CoefficientsOfLaurentPolynomial' if <islaurent>
is `true' and the `CoefficientsOfUnivariateRationalFunction' if
<islaurent> is `false' and <isunivariate> `true'.
As there is no proper multivariate gcd, it might return `fail' for
<isunivariate>.


The info class for univariate polynomials is `InfoPoly'.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Polynomials as Univariate Polynomials in one Indeterminate}

\>DegreeIndeterminate( <pol>, <ind> ) O
\>DegreeIndeterminate( <pol>, <inum> ) O

returns the degree of the polynomial <pol> in the indeterminate <ind>
(respectively indeterminate number <inum>).


\beginexample 
gap> f:=x^5+3*x*y+9*y^7+4*y^5*x+3*y+2;
2+3*y+3*x*y+x^5+4*x*y^5+9*y^7
gap> DegreeIndeterminate(f,1);
5
gap> DegreeIndeterminate(f,y);
7
\endexample

\>PolynomialCoefficientsOfPolynomial( <pol>, <ind> ) O
\>PolynomialCoefficientsOfPolynomial( <pol>, <inum> ) O

`PolynomialCoefficientsOfPolynomial' returns the coefficient list
(whose entries are polynomials not involving the indeterminate <ind>)
describing the polynomial <pol> viewed as a polynomial in <ind>. 
Instead of <ind> also the indeterminate number <inum> can be given.


\beginexample 
gap> PolynomialCoefficientsOfPolynomial(f,2);
[ 2+x^5, 3+3*x, 0, 0, 0, 4*x, 0, 9 ]
\endexample

\>LeadingCoefficient( <pol> ) O

returns the leading coefficient (that is the coefficient of the leading
monomial, see~"LeadingMonomial") of the polynomial <pol>.


\>LeadingMonomial( <pol> ) F

returns the leading monomial (with respect to the ordering given by
"MonomialTotalDegreeLess" of the polynomial <pol> as a list
containing indeterminate numbers and exponents.


\beginexample 
gap> LeadingCoefficient(f,1);
1
gap> LeadingCoefficient(f,2);
9
gap> LeadingMonomial(f);
[ 2, 7 ]
gap> LeadingCoefficient(f);
9
\endexample

\>Derivative( <ufun> ) O
\>Derivative( <ratfun>, <ind> ) O

returns the derivative $<upoly>'$ of the univariate rational function
<ufun> by its indeterminant. The second version returns the derivative
of <ratfun> by the indeterminate <ind> (respectively indeterminate
number <ind>) when viewing <ratfun> as univariate in <ind>.


\beginexample 
gap> Derivative(f,2);
3+3*x+20*x*y^4+63*y^6
\endexample
\>Discriminant( <upol> ) O
\>Discriminant( <pol>, <ind> ) O

returns the discriminant disc($<upoly>$) of the univariate polynomial
<upoly> by its indeterminant. The second version returns the
discriminant of <pol> by the indeterminate <ind> (respectively
indeterminate number <ind>).


\beginexample 
gap> Discriminant(f,1);
50000+300000*y+675000*y^2+675000*y^3+253125*y^4+62208*y^5+900000*y^7+4050000*y\
^8+6489720*y^9+3037500*y^10+1105920*y^13+6075000*y^14+18225000*y^15+13668750*y\
^16+1474560*y^17+19208040*y^21+27337500*y^22+262144*y^25+20503125*y^28
\endexample

\>Resultant( <pol1>, <pol2>, <inum> ) O
\>Resultant( <pol1>, <pol2>, <ind> ) O

computes the resultant of the polynomials <pol1> and <pol2> with respect
to the indeterminate <ind> or indeterminate number <inum>.
The resultant considers <pol1> and <pol2> as univariate in <ind> and
returns an element of the corresponding base ring (which might be a
polynomial ring).

\beginexample 
gap> Resultant(x^4+y,y^4+x,1);
y+y^16
gap> Resultant(x^4+y,y^4+x,2);
x+x^16
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Multivariate Polynomials}

\>Value( <ratfun>, <indets>, <vals>[, <one>] ) O
\>Value( <upol>, <value>[, <one>] ) O

The first variant takes a rational function <ratfun> and specializes the
indeterminates given in <indets> to the values given in <vals>,
replacing the $i$-th indeterminate $<indets>_i$ by $<vals>_i$. If this
specialization results in a constant polynomial, an element of the
coefficient ring is returned. If the specialization would specialize
the denominator of <ratfun> to zero, an error is raised.

A variation is the evaluation at elements of another ring $R$, for which
a multiplication with elements of the coefficient ring of <ratfun> are
defined. In this situation the identity element of $R$ may be given by a
further argument <one> which will be used for $x^0$ for any specialized
indeterminate $x$.

The second version takes an univariate rational function and specializes
the value of its indeterminate to <val>. Again, an optional argument
<one> may be given.

\beginexample 
gap> Value(x*y+y+x^7,[x,y],[5,7]);
78167
\endexample
Note that the default values for `one' can lead to different results than
one would expect: For example for a matrix $M$, the values $M+M^0$ and $M+1$
are *different*. As `Value' defaults to the one of the coefficient ring,
when evaluating Matrices in polynomials always the correct `one' should be
given!

\>OnIndeterminates( <poly>, <perm> ) F

A permutation <perm> acts on the multivariate polynomial <poly> by
permuting the indeterminates as it permutes points.

\beginexample 
gap> OnIndeterminates(x^7*y+x*y^4,(1,17)(2,28));
x_17*x_28^4+x_17^7*x_28
gap> Stabilizer(Group((1,2,3,4),(1,2)),x*y,OnIndeterminates);
Group([ (1,2), (3,4) ])
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Minimal Polynomials}

\indextt{MinimalPolynomial!over a ring}
\>MinimalPolynomial( <R>, <elm>[ , <ind>] ) O

returns the *minimal polynomial* of <elm> over the ring <R>,
expressed in the indeterminate number <ind>.
If <ind> is not given, it defaults to 1.

The minimal polynomial is the monic polynomial of smallest degree with
coefficients in <R> that has value zero at <elm>.


\beginexample 
gap> MinimalPolynomial(Rationals,[[2,0],[0,2]]);
-2+x
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Cyclotomic Polynomials}

\>CyclotomicPolynomial( <F>, <n> ) F

is the <n>-th cyclotomic polynomial over the ring <F>.


\beginexample 
gap> CyclotomicPolynomial(Rationals,5);
1+x+x^2+x^3+x^4
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Polynomial Factorization}

At the moment {\GAP} provides only methods to factorize univariate
polynomials over finite fields (see Chapter~"Finite Fields") and
over subfields of cyclotomic fields (see Chapter~"Abelian Number Fields").

\>Factors([<R>,]<upoly>[,<opt>])!{of univariate polynomial}

returns a list of the irreducible factors of the univariate polynomial
<upoly> in the polynomial ring <R>. (That is factors over the
`CoefficientsRing' of <R>.)

It is possible to pass a record <opt> as a third
argument. This record can contain the following components:
\beginitems
`onlydegs'&is a set of positive integers. The factorization assumes
that all irreducible factors have a degree in this set.

`stopdegs'&is a set of positive integers. The factorization will stop once a
factor of degree in `stopdegs' has been found and will return the
factorization found so far.
\enditems

\beginexample 
gap> f:= CyclotomicPolynomial( GF(2), 7 );
Z(2)^0+x_1+x_1^2+x_1^3+x_1^4+x_1^5+x_1^6
gap> Factors( f );
[ Z(2)^0+x_1+x_1^3, Z(2)^0+x_1^2+x_1^3 ]
gap> Factors( PolynomialRing( GF(8) ), f );
[ Z(2^3)+x_1, Z(2^3)^2+x_1, Z(2^3)^3+x_1, Z(2^3)^4+x_1, Z(2^3)^5+x_1, 
  Z(2^3)^6+x_1 ]
gap> f:= MinimalPolynomial( Rationals, E(4) );
1+x^2
gap> Factors( f );
[ 1+x^2 ]
gap> Factors( PolynomialRing( Rationals ), f );
[ 1+x^2 ]
gap> Factors( PolynomialRing( CF(4) ), f );
[ -E(4)+x, E(4)+x ]
\endexample

\>FactorsSquarefree( <pring>, <upol>, <opt> ) O

returns a factorization of the squarefree, monic, univariate polynomial
<upoly> in the polynomial ring <pring>;
<opt> must be a (possibly empty) record of options.
<upol> must not have zero as a root.
This function is used by the factoring algorithms.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Polynomials over the Rationals}

The following functions are only available to polynomials with rations
coefficients:

\>PrimitivePolynomial( <f> ) F

takes a polynomial <f> with rational coefficients and computes a new
polynomial with integral coefficients, obtained by multiplying with the
Lcm of the denominators of the coefficients and casting out the content
(the Gcd of the coefficients). The operation returns a list
[<newpol>,<coeff>] with rational <coeff> such that
`<coeff>\*<newpol>=<f>'.



The following operations are used by {\GAP} inside the factorization algorithm
but might be of interest also in other contexts.
\>BombieriNorm( <pol> ) F

computes weighted Norm [pol]_2 of <pol> which is a good measure for
factor coeffietients (see \cite{BTW93}).


\>MinimizedBombieriNorm( <f> ) A

This function applies linear Tschirnhaus transformations 
($x \mapsto x + i$) to the
polynomial <f>, trying to get the Bombieri norm of <f> small. It returns a
list `[<new_polynomial>, <i_of_transformation>]'.


\>HenselBound( <pol>, [<minpol>, <den>] ) F

returns the Hensel bound of the polynomial <pol>.
If the computation takes place over an algebraic extension, then
the minimal polynomial <minpol> and denominator <den> must be given.


\>OneFactorBound( <pol> ) F

returns the coefficient bound for a single factor of the rational 
polynomial <pol>.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Laurent Polynomials}

A univariate polynomial can be written in the form $r_0+r_1x+\cdots+r_nx^n$
with $r_i\in R$.  Formally, there is no reason to start with 0, if $m$ is an
integer, we can consider objects of the form
$r_mx^m+r_{m+1}x^{m+1}+\cdots+r_nx^n$. We call these *Laurent polynomials*.
Laurent polynomials also can be considered as quotients of a univariate
polynomial by a power of the indeterminate.  The addition and multiplication
of univariate polynomials extends to Laurent polynomials (though it might be
impossible to interpret a Laurent polynomial as a function) and many
functions for univariate polynomials extend to Laurent polynomials (or
extended versions for Laurent polynomials exist).

\>LaurentPolynomialByCoefficients( <fam>, <cofs>, <val> [, <ind>] ) O

constructs a Laurent polynomial over the coefficients
family <fam> and in the indeterminate <ind> (defaulting to 1) with
the coefficients given by <coefs> and valuation <val>.

\>CoefficientsOfLaurentPolynomial( <laurent> ) A

For a Laurent polynomial this function returns a pair `[<cof>, <val>]',
consisting of the coefficient list (in ascending order) <cof> and the
valuation <val> of the Laurent polynomial <laurent>.


\beginexample 
gap> p:=LaurentPolynomialByCoefficients(FamilyObj(1),
> [1,2,3,4,5],-2);
x^-2+2*x^-1+3+4*x+5*x^2
gap> NumeratorOfRationalFunction(p);DenominatorOfRationalFunction(p);
1+2*x+3*x^2+4*x^3+5*x^4
x^2
gap> CoefficientsOfLaurentPolynomial(p*p);
[ [ 1, 4, 10, 20, 35, 44, 46, 40, 25 ], -4 ]
\endexample

\>IndeterminateNumberOfLaurentPolynomial( <pol> ) F

Is a synonym for `IndeterminateNumberOfUnivariateRationalFunction'
(see~"IndeterminateNumberOfUnivariateRationalFunction").


\>QuotRemLaurpols( <left>, <right>, <mode> ) F

takes two Laurent polynomials <left> and <right> and computes their
quotient. Depending on the integer variable <mode> it returns:
\beginlist%ordered
\item{1.}
the quotient (there might be some remainder),

\item{2.}
the remainder,

\item{3.}
a list [<q>,<r>] of quotient and remainder,

\item{4.}
the quotient if there is no remainder and `fail' otherwise.
\endlist


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Univariate Rational Functions}

\>UnivariateRationalFunctionByCoefficients( <fam>, <ncof>, <dcof>, <val>[, <ind>] ) O

constructs a univariate rational function over the coefficients
family <fam> and in the indeterminate <ind> (defaulting to 1) with
numerator and denominator coefficients given by <ncof> and <dcof> and
valuation <val>.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Polynomial Rings}

While polynomials depend only on the family of the coefficients, polynomial
rings $A$ are defined over a base ring $R$. A polynomial is an element of
$A$ if and only if all its coefficients are contained in $R$. Besides
providing domains and an easy way to create polynomials, polynomial rings
can affect the behavior of operations like factorization into irreducibles.

\>PolynomialRing( <ring>, <rank>, [<avoid>] ) O
\>PolynomialRing( <ring>, <names>, [<avoid>] ) O
\>PolynomialRing( <ring>, <indets> ) O

creates a polynomial ring over <ring>. If a positive integer <rank> is
given, this creates the polynomial ring in <rank> indeterminates
(differing from the indeterminates contained in <avoid> if given). The
second usage takes a list <names> of strings and returns a polynomial
ring in indeterminates labelled by <names>. In the third use, a list of
positive integers <indets> is given. This creates the polynomial ring in
the indeterminates labelled by <indets>.

\>IndeterminatesOfPolynomialRing( <pring> ) A

returns a list of the indeterminates of the polynomial ring <pring>

\>CoefficientsRing( <pring> ) A

returns the ring of coefficients of the polynomial ring <pring>, that is
the ring over which <pring> was defined.

\beginexample 
gap> r:=PolynomialRing(GF(7));
PolynomialRing(..., [ x_1 ])
gap>  r:=PolynomialRing(GF(7),3);
PolynomialRing(..., [ x_1, x_2, x_3 ])
gap> IndeterminatesOfPolynomialRing(r);
[ x_1, x_2, x_3 ]
gap> r2:=PolynomialRing(GF(7),[5,7,12]);
PolynomialRing(..., [ x_5, x_7, x_12 ])
gap> CoefficientsRing(r);
GF(7)
gap> r:=PolynomialRing(GF(7),3);
PolynomialRing(..., [ x_1, x_2, x_3 ])
gap> r2:=PolynomialRing(GF(7),3,IndeterminatesOfPolynomialRing(r));
PolynomialRing(..., [ x_4, x_5, x_6 ])
gap> r:=PolynomialRing(GF(7),["x","y","z","z2"]);
PolynomialRing(..., [ x, y, z, z2 ])
\endexample

As {\GAP} objects polynomials can exist without a polynomial ring being
defined and polynomials cannot be associated to a particular polynomial
ring. (For example dividing a polynomial which is in a polynomial ring over
the integers by another integer will result in a polynomial over the
rationals, not in a rational function over the integers.)

\>IsPolynomialRing( <pring> ) C

is the category of polynomial rings


\>IsFiniteFieldPolynomialRing( <pring> ) C

is the category of polynomial rings over a finite field
(see Chapter~"Finite Fields").


\>IsAbelianNumberFieldPolynomialRing( <pring> ) C

is the category of polynomial rings over a field of cyclotomics
(see the chapters~"Cyclotomic Numbers" and "Abelian Number Fields").


\>IsRationalsPolynomialRing( <pring> ) C

is the category of polynomial rings over the rationals
(see Chapter~"Rational Numbers").



\beginexample 
gap> IsPolynomialRing(r);
true
gap> IsFiniteFieldPolynomialRing(r);
true
gap> IsRationalsPolynomialRing(r);
false
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Univariate Polynomial Rings}

\>UnivariatePolynomialRing( <R> [, <nr>] ) O
\>UnivariatePolynomialRing( <R> [, <avoid>] ) O
\>UnivariatePolynomialRing( <R>, <name> [, <avoid>] ) O

returns a univariate polynomial ring in the indeterminate <nr> over the
base ring <R>. if <nr> is not given it defaults to 1.  If the number is
not specified a list <avoid> of indeterminates may be given. The
function will return a ring in an indeterminate that is guaranteed to be
different from all the indeterminates in <avoid>. The third usage
returns a ring in an indeterminate called <name> (also avoiding the
indeterminates in <avoid> if given).

\>IsUnivariatePolynomialRing( <pring> ) C

is the category of polynomial rings with one indeterminate.

\beginexample 
gap> r:=UnivariatePolynomialRing(Rationals,"x");
PolynomialRing(..., [ x ])
gap> r2:=PolynomialRing(Rationals,["q"]);
PolynomialRing(..., [ q ])
gap> IsUnivariatePolynomialRing(r);
true
gap> IsUnivariatePolynomialRing(r2);
true
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Polynomial Reduction}

The functions described in this section and their syntax might be subject to
change in future releases.

\>PolynomialReduction( <poly>, <gens>, <order> )!{function} F

reduces the polynomial <poly> by the ideal generated by the polynomials
in <gens>, using the order <order> of monomials.  Unless <gens> is a
Gr{\accent127 o}bner basis the result is not guaranteed to be unique.

The operation returns a list of length two, the first entry is the
remainder after the reduction. The second entry is a list of quotients
corresponding to <gens>.


The polynomial reduction requires an ordering on monomials. This must be a
function that takes two monomials without coefficients (in the form of lists
as described in "The Defining Attributes of Rational Functions", for example
`[3,1,4,1,5,9]') and returns whether one is smaller than the other.

Normally the ordering chosen should be *admissible*, i.e. it
must be compatible with products: If $a\<b$ then $ca\<cb$ for all monomials
$a,b$ and $c$.

Currently two admissible orderings are available:
\>MonomialTotalDegreeLess( <a>, <b> ) F

implements comparison of monomial by the total degree order. This is
the order {\GAP} naturally puts on monomials. The function takes two
monomials <a> and <b> in expanded form and returns whether the first is
smaller than the second. (This ordering is also used by {\GAP}
internally for representing polynomials as a linear combination of
monomials.)

See section~"The Defining Attributes of Rational Functions" for details
on the expanded form of monomials.

\>MonomialRevLexicoLess( <a>, <b> ) F

implements comparison of monomials by the position/lexicographic
order.
The function takes two
monomials <a> and <b> in expanded form and returns whether the first is
smaller than the second.

See section~"The Defining Attributes of Rational Functions" for details
on the expanded form of monomials.


\beginexample 
gap> x:=X(Rationals,"x");;y:=X(Rationals,"y");;z:=X(Rationals,"z");;
gap> bas:=[x^3*y*z,x*y^2*z,z*y*z^3+x];
[ x^3*y*z, x*y^2*z, x+y*z^4 ]
gap> PolynomialReduction(x^7*z*bas[1]+y^5*bas[3]+x*z,bas,
> MonomialTotalDegreeLess);
[ x*z, [ x^7*z, 0, y^5 ] ]
\endexample

\>LeadingMonomialPosExtRep( <fam>, <ext>, <order> ) F

This function takes an external representation <ext> of a polynomial in
family <fam> and returns the position of the leading monomial in <ext>
with respect to the monomial order implemented by the function <order>.

See section~"The Defining Attributes of Rational Functions" for details
on the external representation.


At the moment {\GAP} does not contain any facilities to compute
Gr{\accent127 o}bner bases.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Rational Function Families}

All rational functions defined over a ring lie in the same family, the
rational functions family over this ring.

In {\GAP} therefore the family of a polynomial depends only on the family of
the coefficients, all polynomials whose coefficients lie in the same family
are ``compatible''.

\>RationalFunctionsFamily( <fam> ) A

creates a   family  containing rational functions  with   coefficients
in <fam>. This family <fam> *must* be a UFD, that is to say, there are no
zero divisors, the family must have a one, be commutative and the
factorisation of an  elements into irreducible  elements of the  family
must be unique (up to units and order).
All elements of the `RationalFunctionsFamily' are rational functions
(see~"IsRationalFunction").

\>IsRationalFunctionsFamily( <obj> ) C

Is the category of a family of rational functions.



\begintt
gap> fam:=RationalFunctionsFamily(FamilyObj(1));
NewFamily( "RationalFunctionsFamily(...)", [ 618, 620 ],
[ 82, 85, 89, 93, 97, 100, 103, 107, 111, 618, 620 ] )
\endtt

\>CoefficientsFamily( <rffam> ) A

If <rffam> has been created as `RationalFunctionsFamily(<cfam>)' this
attribute holds the coefficients family <cfam>.


{\GAP} does *not* embed the base ring in the polynomial ring. While
multiplication and addition of base ring elements to rational functions
return the expected results, polynomials and rational functions are not
equal.
\beginexample 
gap> 1=Indeterminate(Rationals)^0;
false
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{The Representations of Rational Functions}

{\GAP} uses four representations of rational functions: Rational
functions given by numerator and denominator, polynomials, univariate
rational functions (given by coefficient lists for numerator and denominator
and valuation) and
Laurent polynomials (given by coefficient list and valuation).

These representations do not necessarily reflect mathematical properties:
While an object in the Laurent polynomials representation must be a
Laurent polynomial it might turn out that a rational function given by
numerator and denominator is actually a Laurent polynomial and the property
tests in section~"Properties and Attributes of Rational Functions" will find
this out.

Each representation is associated one or several ``defining attributes''
that give an ``external'' representation
(see~"The Defining Attributes of Rational Functions")
of the representation in the form of lists and are the defining information
that tells a rational function what it is.

{\GAP} also implements methods to compute these attributes for rational
functions in *other* representations, provided it would be possible to
express an *mathematically equal* rational function in the representation
associated with the attribute. (That is one can always get a
numerator/denominator representation of a polynomial while an arbitrary
function of course can compute a polynomial representation only if it is a
polynomial.)

Therefore these attributes can be thought of as ``conceptual''
representations that allow us -- as far as possible --
to consider an object as a rational function, a polynomial or a Laurent
polynomial, regardless of the way it is represented in the computer.

Functions thus usually do not need to care about the representation of
a rational function. Depending on its (known in the context or determined)
properties, they can access the attribute representing the rational function
in the desired way.

Consequentially, methods for rational functions are installed for properties
and not for representations.

When *creating* new rational functions however they must be created in one
of the three representations. In most cases this will be the representation
for which the ``conceptual'' representation in which the calculation was done
is the defining attribute.

Iterated operations (like forming the product over a list) therefore will
tend to stay in the most suitable representation and the calculation of
another conceptual representation (which may be comparatively expensive in
certain circumstances) is not necessary.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{The Defining Attributes of Rational Functions}

In general, rational functions are given in terms of monomials. They are
represented by lists, using numbers (see~"Indeterminates") for the
indeterminates.

\index{Expanded form of monomials}
A monomial is a product of powers of indeterminates. A monomial is
stored as a list (we call this the *expanded form* of the monomial)
of the form `[<inum>,<exp>,<inum>,<exp>,...]' where each <inum>
is the number of an indeterminate and <exp> the corresponding exponent.
The list must be sorted according to the numbers of the indeterminates.
Thus for example, if $x$, $y$ and $z$ are the first three indeterminates,
the expanded form of the monomial $x^5z^8=z^8x^5$ is `[1,5,3,8]'.

\index{External representation of polynomials}
The representation of a polynomials is a list of the form
`[<mon>,<coeff>,<mon>,<coeff>,...]' where <mon> is a monomial in
expanded form (that is given as list) and <coeff> its coefficient. The
monomials must be sorted according to the total degree/lexicographic
order (implemented by the function `MonomialTotalDegreeLess'). We call
this the *external representation* of a polynomial. (The
reason for ordering is that addition of polynomials becomes linear in
the number of monomials instead of quadratic; the reason for the
particular ordering chose is that it is compatible with multiplication
and thus gives acceptable performance for quotient calculations.)


\>IsRationalFunctionDefaultRep( <obj> ) R

is the default representation of rational functions. A rational function
in this representation is defined by the attributes
`ExtRepNumeratorRatFun' and `ExtRepDenominatorRatFun' where
`ExtRepNumeratorRatFun' and `ExtRepDenominatorRatFun' are
both external representations of a polynomial.

\>ExtRepNumeratorRatFun( <ratfun> ) A

returns the external representation of the numerator polynomial of the
rational function <ratfun>. Numerator and Denominator are not guaranteed
to be cancelled against each other.

\>ExtRepDenominatorRatFun( <ratfun> ) A

returns the external representation of the denominator polynomial of the
rational function <ratfun>. Numerator and Denominator are not guaranteed
to be cancelled against each other.

\>ZeroCoefficientRatFun( <ratfun> ) O

returns the zero of the coefficient ring. This might be needed to
represent the zero polynomial for which the external representation of
the numerator is the empty list.


\>IsPolynomialDefaultRep( <obj> ) R

is the default representation of polynomials. A polynomial
in this representation is defined by the components
and `ExtRepNumeratorRatFun' where `ExtRepNumeratorRatFun' is the
external representation of the polynomial.

\>ExtRepPolynomialRatFun( <polynomial> ) A

returns the external representation of a polynomial. The difference to
`ExtRepNumeratorRatFun' is that rational functions might know to be a
polynomial but can still have a non-vanishing denominator. In this case
`ExtRepPolynomialRatFun' has to call a quotient routine.


\>IsLaurentPolynomialDefaultRep( <obj> ) R

This representation is used for Laurent polynomials and univariate
polynomials. It represents a Laurent polynomial via the attributes
`CoefficientsOfLaurentPolynomial'
(see~"CoefficientsOfLaurentPolynomial") and
`IndeterminateNumberOfLaurentPolynomial'
(see~"IndeterminateNumberOfLaurentPolynomial").

The attributes that give a representation of a a rational function as a Laurent polynomial are
`CoefficientsOfLaurentPolynomial' (see~"CoefficientsOfLaurentPolynomial")
and `IndeterminateNumberOfUnivariateRationalFunction'
(see~"IndeterminateNumberOfUnivariateRationalFunction").

Algorithms should use only the attributes `ExtRepNumeratorRatFun',
`ExtRepDenominatorRatFun',
`ExtRepPolynomialRatFun', `CoefficientsOfLaurentPolynomial' and -- if
the univariate function is not constant --
`IndeterminateNumberOfUnivariateRationalFunction' as the low-level
interface to work with a polynomial. They should not refer to the actual
representation used.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Creation of Rational Functions}

The operations `LaurentPolynomialByCoefficients'
(see~"LaurentPolynomialByCoefficients"),
`PolynomialByExtRep' and `RationalFunctionByExtRep' are used to
construct objects in the three basic representations for rational
functions.


\>RationalFunctionByExtRep( <rfam>, <num>, <den> ) F

constructs a rational function (in the representation
`IsRationalFunctionDefaultRep') in the rational function family <rfam>,
the rational function itself is given by the external representations
<num> and <den> for numerator and denominator.
No test for validity of the arguments is performed and no cancellation
takes place.

\>PolynomialByExtRep( <rfam>, <extrep> ) F

constructs a polynomial (in the representation `IsPolynomialDefaultRep')
in the rational function family <rfam>, the polynomial itself is given
by the external representation <extrep>.
No test for validity of the arguments is performed.

\beginexample 
gap> fam:=RationalFunctionsFamily(FamilyObj(1));;
gap> p:=PolynomialByExtRep(fam,[[1,2],1,[2,1,9,7],3]);
x^2+3*y*x_9^7
gap> q:=p/(p+1);
(x^2+3*y*x_9^7)/(1+x^2+3*y*x_9^7)
gap> ExtRepNumeratorRatFun(q);
[ [ 1, 2 ], 1, [ 2, 1, 9, 7 ], 3 ]
gap> ExtRepDenominatorRatFun(q);
[ [  ], 1, [ 1, 2 ], 1, [ 2, 1, 9, 7 ], 3 ]
\endexample
\>LaurentPolynomialByExtRep( <fam>, <cofs>, <val> , <ind> ) F

creates a Laurent polynomial in the family <fam> with [<cofs>,<val>] as
value of `CoefficientsOfLaurentPolynomial'. No coefficient shifting is
performed.  This is the lowest level function to create a Laurent
polynomial but will rely on the coefficients being shifted properly and
will not perform any tests. Unless this is guaranteed for the
parameters, `LaurentPolynomialByCoefficients'
(see~"LaurentPolynomialByCoefficients") should be used.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Arithmetic for External Representations of Polynomials}

The following operations are used internally to perform the arithmetic for
polynomials in their ``external'' representation
(see~"The Defining Attributes of Rational Functions")
as lists.
\>ZippedSum( <z1>, <z2>, <czero>, <funcs> ) O

computes the sum of two external representations of polynomials <z1> and
<z2>. <czero> is the appropriate coefficient zero and <funcs> a list 
[ <monomial less>, <coefficient sum> ] containing a monomial comparison
and a coefficient addition function. This list can be found in the
component `<fam>!.zippedSum' of the rational functions family.


\>ZippedProduct( <z1>, <z2>, <czero>, <funcs> ) O

computes the product of two external representations of polynomials <z1>
and <z2>. <czero> is the appropriate coefficient zero and <funcs> a list
`[<monomial_prod>, <monomial_less>, <coefficient_sum>, <coefficient_prod>]'
containing functions to multiply and compare monomials, to add and to
multiply coefficients.  This list can be found in the component
`<fam>!.zippedProduct' of the rational functions family.


\>QuotientPolynomialsExtRep( <fam>, <a>, <b> ) F

Let <a> and <b> the external representations of two polynomials in the
rational functions family <fam>. This function computes the external
representation of the quotient of both polynomials, it returns `fail' if
<b> does not divide <a>.


Functions to perform arithmetic with the coefficient lists of Laurent
polynomials are described in section~"Coefficient List Arithmetic".

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Cancellation Tests for Rational Functions}

{\GAP} does not contain a multivariate GCD algorithm. The following
operations are used internally to try to keep the denominators as small as
possible

\>RationalFunctionByExtRepWithCancellation( <rfam>, <num>, <den> ) F

constructs a rational function as `RationalFunctionByExtRep' does but
tries to cancel out common factors of numerator and denominator, calling
`TryGcdCancelExtRepPolynomials'.

\>TryGcdCancelExtRepPolynomials( <fam>, <a>, <b> ) F

Let <f> and <g> be two polynomials given by the ext reps <a> and <b>.
This function tries to cancel common factors between <a> and <b> and
returns a list [<ac>,<bc>] of cancelled numerator and denominator ext
rep. As there is no proper multivariate GCD cancellation is not
guaranteed to be optimal.

\>HeuristicCancelPolynomials( <fam>, <ext1>, <ext2> ) O

is called by `TryGcdCancelExtRepPol' to perform the actual work. It will
return either `fail' or a new list [<num>,<den>] of cancelled numerator
and denominator. The cancellation performed is not necessarily optimal.

