% This file was created automatically from rings.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  rings.msk                    GAP documentation              Thomas Breuer
%%
%A  @(#)$Id: rings.msk,v 1.20.2.1 2005/07/20 09:48:16 stefan Exp $
%%
%Y  (C) 1998 School Math and Comp. Sci., University of St.  Andrews, Scotland
%Y  Copyright (C) 2002 The GAP Group
%%
\Chapter{Rings}

This chapter deals with domains that are additive groups closed under
multiplication `\*'.
Such a domain, if `\*' and `+' are distributive,
is called a *ring* in {\GAP}.
Each division ring, field (see~"Fields and Division Rings"),
or algebra (see~"Algebras") is a ring,
important examples are the integers (see~"Integers") and matrix rings.
%(see~"???").

% residue class rings ?

In the case of a *ring-with-one*, additional multiplicative structure is
present, see~"IsRingWithOne".

Several functions for ring elements, such as `IsPrime' ("IsPrime") and
`Factors' ("Factors"), are defined only relative to a ring <R>,
which can be entered as an optional argument;
if <R> is omitted then a *default ring* is formed from the ring elements
given as arguments, see~"DefaultRing".


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Generating Rings}

\>IsRing( <R> ) P

A *ring* in {\GAP} is an additive group (see~"IsAdditiveGroup")
that is also a magma (see~"IsMagma"),
such that addition `+' and multiplication `\*' are distributive.

The multiplication need *not* be associative (see~"IsAssociative").
For example, a Lie algebra (see~"Lie Algebras") is regarded as a
ring in {\GAP}.



\>Ring( <r> , <s>, ... ) F
\>Ring( <coll> ) F

In the first form `Ring' returns the smallest ring that
contains all the elements <r>, <s>... etc.
In the second form `Ring' returns the smallest ring that
contains all the elements in the collection <coll>.
If any element is not an element of a ring or if the elements lie in no
common ring an error is raised.

`Ring' differs from `DefaultRing' (see~"DefaultRing") in that it returns
the smallest ring in which the elements lie, while `DefaultRing' may
return a larger ring if that makes sense.



\beginexample
gap> Ring( 2, E(4) );
<ring with 2 generators>
\endexample

\>DefaultRing( <r> , <s>, ... ) F
\>DefaultRing( <coll> ) F

In the first form `DefaultRing' returns a ring that contains
all the elements <r>, <s>, ... etc.
In the second form `DefaultRing' returns a ring that contains
all the elements in the collection <coll>.
If any element is not an element of a ring or if the elements lie in no
common ring an error is raised.

The ring returned by `DefaultRing' need not be the smallest ring in which
the elements lie.
For example for elements from cyclotomic fields,
`DefaultRing' may return the ring of integers of the smallest cyclotomic
field in which the elements lie, which need not be the smallest ring
overall, because the elements may in fact lie in a smaller number field
which is itself not a cyclotomic field.

(For the exact definition of the default ring of a certain type of
elements, look at the corresponding method installation.)

`DefaultRing' is used by the ring functions like `Quotient', `IsPrime',
`Factors', or `Gcd' if no explicit ring is given.

`Ring' (see~"Ring") differs from `DefaultRing' in that it returns the
smallest ring in which the elements lie, while `DefaultRing' may return
a larger ring if that makes sense.



\beginexample
gap> DefaultRing( 2, E(4) );
GaussianIntegers
\endexample

\>RingByGenerators( <C> ) O

`RingByGenerators' returns the ring generated by the elements in the
collection <C>,
i.~e., the closure of <C> under addition, multiplication,
and taking additive inverses.



\beginexample
gap> RingByGenerators([ 2, E(4) ]);
<ring with 2 generators>
\endexample

\>DefaultRingByGenerators( <coll> ) O



\beginexample
gap> DefaultRingByGenerators([ 2, E(4) ]);
GaussianIntegers
\endexample


\>GeneratorsOfRing( <R> ) A

`GeneratorsOfRing' returns a list of elements such that the ring <R> is
the closure of these elements under addition, multiplication,
and taking additive inverses.



\beginexample
gap> R:=Ring( 2, 1/2 );
<ring with 2 generators>
gap> GeneratorsOfRing( R );
[ 2, 1/2 ]
\endexample

\>AsRing( <C> ) A

If the elements in the collection <C> form a ring then `AsRing' returns
this ring, otherwise `fail' is returned.





\>Subring( <R>, <gens> ) F
\>SubringNC( <R>, <gens> ) F

returns the ring with parent <R> generated by the elements in
<gens>. When the second form, `SubringNC' is used, it is *not* checked
whether all elements in <gens> lie in <R>. 



\beginexample
gap> R:= Integers;
Integers
gap> S:= Subring( R, [ 4, 6 ] );
<ring with 2 generators>
gap> Parent( S );
Integers
\endexample

\>ClosureRing( <R>, <r> ) O
\>ClosureRing( <R>, <S> ) O

For a ring <R> and either an element <r> of its elements family or a ring
<S>, `ClosureRing' returns the ring generated by both arguments.



\beginexample
gap> ClosureRing( Integers, E(4) );
<ring-with-one, with 2 generators>
\endexample

\>Quotient( <R>, <r>, <s> ) O
\>Quotient( <r>, <s> ) O

In the first form `Quotient' returns the quotient of the two ring
elements <r> and <s> in the ring <R>.
In the second form `Quotient' returns the quotient of the two ring
elements <r> and <s> in their default ring.
It returns `fail' if the quotient does not exist in the respective ring.

(To perform the division in the quotient field of a ring, use the
quotient operator `/'.)



\beginexample
gap> Quotient( 2, 3 );
fail
gap> Quotient( 6, 3 );
2
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Ideals in Rings}

A *left ideal* in a ring $R$ is a subring of $R$
that is closed under multiplication with elements of $R$ from the left.

A *right ideal* in a ring $R$ is a subring of $R$
that is closed under multiplication with elements of $R$ from the right.

A *two-sided ideal* or simply *ideal* in a ring $R$ is both a left ideal
and a right ideal in $R$.

So being a (left/right/two-sided) ideal is not a property of a domain
but refers to the acting ring(s).
Hence we must ask, e.~g., `IsIdeal( <R>, <I> )' if we want to know
whether the ring <I> is an ideal in the ring <R>.
The property `IsIdealInParent' can be used to store whether a ring is an
ideal in its parent.

(Whenever the term `Ideal' occurs without specifying prefix `Left' or
`Right', this means the same as `TwoSidedIdeal'. Conversely, any 
occurrence of `TwoSidedIdeal' can be substituted by `Ideal'.)

For any of the above kinds of ideals, there is a notion of generators,
namely `GeneratorsOfLeftIdeal', `GeneratorsOfRightIdeal', and
`GeneratorsOfTwoSidedIdeal'.
The acting rings can be accessed as `LeftActingRingOfIdeal' and
`RightActingRingOfIdeal', respectively.
Note that ideals are detected from known values of these attributes,
especially it is assumed that whenever a domain has both a left and a
right acting ring then these two are equal.

Note that we cannot use `LeftActingDomain' and `RightActingDomain' here,
since ideals in algebras are themselves vector spaces, and such a space
can of course also be a module for an action from the right.
In order to make the usual vector space functionality automatically
available for ideals, we have to distinguish the left and right module
structure from the additional closure properties of the ideal.

Further note that the attributes denoting ideal generators and acting
ring are used to create ideals if this is explicitly wanted, but the
ideal relation in the sense of `IsIdeal' is of course independent of the
presence of the attribute values.

Ideals are constructed with `LeftIdeal', `RightIdeal', `TwoSidedIdeal'.
Principal ideals of the form $x * R$, $R * x$, $R * x * R$ can also be
constructed with a simple multiplication.

Currently many methods for dealing with ideals need linear algebra to
work, so they are mainly applicable to ideals in algebras.




\>TwoSidedIdeal( <R>, <gens>[, "basis"] ) F
\>Ideal( <R>, <gens>[, "basis"] ) F
\>LeftIdeal( <R>, <gens>[, "basis"] ) F
\>RightIdeal( <R>, <gens>[, "basis"] ) F

Let <R> be a ring, and <gens> a list of collection of elements in <R>.
`TwoSidedIdeal', `LeftIdeal', and `RightIdeal' return the two-sided,
left, or right ideal, respectively, $I$ in <R> that is generated by
<gens>.
The ring <R> can be accessed as `LeftActingRingOfIdeal' or
`RightActingRingOfIdeal'
(or both) of $I$.

If <R> is a left $F$-module then also $I$ is a left $F$-module,
in particular the `LeftActingDomain' (see~"LeftActingDomain") values of
<R> and $I$ are equal.

If the optional argument `\"basis\"' is given then <gens> are assumed to
be a list of basis vectors of $I$ viewed as a free $F$-module.
(This is mainly applicable to ideals in algebras.)
In this case, it is *not* checked whether <gens> really is linearly
independent and whether <gens> is a subset of <R>.

`Ideal' is simply a synonym of `TwoSidedIdeal'.



\beginexample
gap> R:= Integers;;
gap> I:= Ideal( R, [ 2 ] );
<two-sided ideal in Integers, (1 generators)>
\endexample

\>TwoSidedIdealNC( <R>, <gens>[, "basis"] ) F
\>IdealNC( <R>, <gens>[, "basis"] ) F
\>LeftIdealNC( <R>, <gens>[, "basis"] ) F
\>RightIdealNC( <R>, <gens>[, "basis"] ) F

The effects of `TwoSidedIdealNC', `LeftIdealNC', and `RightIdealNC' are
the same as `TwoSidedIdeal', `LeftIdeal', and `RightIdeal', respectively
(see~"TwoSidedIdeal"), but they do not check whether all entries
of <gens> lie in <R>.



\>IsTwoSidedIdeal( <R>, <I> ) O
\>IsLeftIdeal( <R>, <I> ) O
\>IsRightIdeal( <R>, <I> ) O
\>IsTwoSidedIdealInParent( <I> ) P
\>IsLeftIdealInParent( <I> ) P
\>IsRightIdealInParent( <I> ) P

The properties `IsTwoSidedIdealInParent' etc., are attributes of the
ideal, and once known they are stored in the ideal. 



\beginexample
gap> A:= FullMatrixAlgebra( Rationals, 3 );
( Rationals^[ 3, 3 ] )
gap> I:= Ideal( A, [ Random( A ) ] );
<two-sided ideal in ( Rationals^[ 3, 3 ] ), (1 generators)>
gap> IsTwoSidedIdeal( A, I );
true
\endexample

\>TwoSidedIdealByGenerators( <R>, <gens> ) O
\>IdealByGenerators( <R>, <gens> ) O

`TwoSidedIdealByGenerators' returns the ring that is generated by the
elements of the collection <gens> under addition, multiplication, and
multiplication with elements of the ring <R> from the left and from the
right.

<R> can be accessed by `LeftActingRingOfIdeal' or
`RightActingRingOfIdeal',
<gens> can be accessed by `GeneratorsOfTwoSidedIdeal'.



\>LeftIdealByGenerators( <R>, <gens> ) O

`LeftIdealByGenerators' returns the ring that is generated by the
elements of the collection <gens> under addition, multiplication, and
multiplication with elements of the ring <R> from the left.

<R> can be accessed by `LeftActingRingOfIdeal',
<gens> can be accessed by `GeneratorsOfLeftIdeal'.



\>RightIdealByGenerators( <R>, <gens> ) O

`RightIdealByGenerators' returns the ring that is generated by the
elements of the collection <gens> under addition, multiplication, and
multiplication with elements of the ring <R> from the right.

<R> can be accessed by `RightActingRingOfIdeal',
<gens> can be accessed by `GeneratorsOfRightIdeal'.



\>GeneratorsOfTwoSidedIdeal( <I> ) A
\>GeneratorsOfIdeal( <I> ) A

is a list of generators for the bi-ideal <I>, with respect to the action of
`LeftActingRingOfIdeal( <I> )' from the left and the action of
`RightActingRingOfIdeal( <I> )'from the right.

Note that `LeftActingRingOfIdeal(<I>)' and `RightActingRingOfIdeal(<I>)'
coincide if <I> is a two-sided ideal.



\beginexample
gap> A:= FullMatrixAlgebra( Rationals, 3 );;
gap> I:= Ideal( A, [ One( A ) ] );;
gap> GeneratorsOfIdeal( I );
[ [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ] ]
\endexample

\>GeneratorsOfLeftIdeal( <I> ) A

is a list of generators for the left ideal <I>, with respect to the 
action of
`LeftActingRingOfIdeal( <I> )' from the left.



\>GeneratorsOfRightIdeal( <I> ) A

is a list of generators for the right ideal <I>, with respect to the 
action of
`RightActingRingOfIdeal( <I> )' from the right.



\>LeftActingRingOfIdeal( <I> ) A
\>RightActingRingOfIdeal( <I> ) A



\>AsLeftIdeal( <R>, <S> ) O
\>AsRightIdeal( <R>, <S> ) O
\>AsTwoSidedIdeal( <R>, <S> ) O

Let <S> be a subring of <R>.

If <S> is a left ideal in <R> then `AsLeftIdeal' returns this left ideal,
otherwise `fail' is returned.
If <S> is a right ideal in <R> then `AsRightIdeal' returns this right
ideal, otherwise `fail' is returned.
If <S> is a two-sided ideal in <R> then `AsTwoSidedIdeal' returns this
two-sided ideal, otherwise `fail' is returned.



\beginexample
gap> A:= FullMatrixAlgebra( Rationals, 3 );;
gap> B:= DirectSumOfAlgebras( A, A );
<algebra over Rationals, with 6 generators>
gap> C:= Subalgebra( B, Basis( B ){[1..9]} );
<algebra over Rationals, with 9 generators>
gap> I:= AsTwoSidedIdeal( B, C );
<two-sided ideal in <algebra of dimension 18 over Rationals>, (9 generators)>
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Rings With One}

\>IsRingWithOne( <R> ) P

A *ring-with-one* in {\GAP} is a ring (see~"IsRing")
that is also a magma-with-one (see~"IsMagmaWithOne").

Note that the identity and the zero of a ring-with-one need *not* be
distinct.
This means that a ring that consists only of its zero element can be
regarded as a ring-with-one.

This is especially useful in the case of finitely presented rings,
in the sense that each factor of a ring-with-one is again a
ring-with-one.



\>RingWithOne( <r>, <s>, ... ) F
\>RingWithOne( <C> ) F

In the first form `RingWithOne' returns the smallest ring with one that
contains all the elements <r>, <s>... etc.
In the second form `RingWithOne' returns the smallest ring with one that
contains all the elements in the collection <C>.
If any element is not an element of a ring or if the elements lie in no
common ring an error is raised.



\beginexample
gap> RingWithOne( [ 4, 6 ] );
<ring-with-one, with 2 generators>
\endexample

\>RingWithOneByGenerators( <coll> ) O

`RingWithOneByGenerators' returns the ring-with-one generated by the
elements in the collection <coll>, i.~e., the closure of <coll> under
addition, multiplication, taking additive inverses,
and taking the identity of an element.


\>GeneratorsOfRingWithOne( <R> ) A

`GeneratorsOfRingWithOne' returns a list of elements
such that the ring <R> is the closure of these elements
under addition, multiplication, taking additive inverses, and taking
the identity element `One( <R> )'.

<R> itself need *not* be known to be a ring-with-one.



\beginexample
gap> R:= RingWithOne( [ 4, 6 ] );
<ring-with-one, with 2 generators>
gap> GeneratorsOfRingWithOne( R );
[ 4, 6 ]
\endexample

\>SubringWithOne( <R>, <gens> ) F
\>SubringWithOneNC( <R>, <gens> ) F

returns the ring with one with parent <R> generated by the elements in
<gens>. When the second form, `SubringNC' is used, it is *not* checked
whether all elements in <gens> lie in <R>. 



\beginexample
gap> R:= SubringWithOne( Integers, [ 4, 6 ] );
<ring-with-one, with 2 generators>
gap> Parent( R );
Integers
\endexample



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Properties of Rings}

\>IsIntegralRing( <R> ) P

A ring-with-one <R> is integral if it is commutative, contains no
nontrivial zero divisors,
and if its identity is distinct from its zero.



\beginexample
gap> IsIntegralRing( Integers );
true
\endexample

\>IsUniqueFactorizationRing( <R> ) C

A ring <R> is called a *unique factorization ring* if it is an integral
ring (see~"IsIntegralRing"),
and every element has a unique factorization into irreducible elements,
i.e., a  unique representation as product  of irreducibles (see
"IsIrreducibleRingElement").
Unique in this context means unique up to permutations of the factors and
up to multiplication of the factors by units (see~"Units").

Mathematically, a field should therefore also be a  unique factorization
ring, since every element is a unit. In {\GAP}, however, at least at present
fields do not lie in the filter `IsUniqueFactorizationRing' 
(see~"IsUniqueFactorizationRing"), since 
Operations such as `Factors', `Gcd', `StandardAssociate' and so on do
not apply to fields (the results would be trivial, and not
especially useful) and Methods which require their arguments to
lie in `IsUniqueFactorizationRing' expect these Operations to work.

(Note that we cannot install a subset maintained method for this category
since the factorization of an element needs not exist in a subring.
As an example, consider the subring $4 \N + 1$ of the ring $4 \Z + 1$;
in the subring, the element $3 \cdot 3 \cdot 11 \cdot 7$ has the two
factorizations $33 \cdot 21 = 9 \cdot 77$, but in the large ring there
is the unique factorization $(-3) \cdot (-3) \cdot (-11) \cdot (-7)$,
and it is easy to see that every element in $4 \Z + 1$ has a unique
factorization.)



\beginexample
gap> IsUniqueFactorizationRing( PolynomialRing( Rationals, 1 ) );
true
\endexample

\>IsLDistributive( <C> ) P

is `true' if the relation $a * ( b + c ) = ( a * b ) + ( a * c )$
holds for all elements $a$, $b$, $c$ in the collection <C>,
and `false' otherwise.


\>IsRDistributive( <C> ) P

is `true' if the relation $( a + b ) * c = ( a * c ) + ( b * c )$
holds for all elements $a$, $b$, $c$ in the collection <C>,
and `false' otherwise.


\>IsDistributive( <C> ) P

is `true' if the collection <C> is both left and right distributive,
and `false' otherwise.



\beginexample
gap> IsDistributive( Integers );
true
\endexample


\>IsAnticommutative( <R> ) P

is `true' if the relation $a * b = - b * a$
holds for all elements $a$, $b$ in the ring <R>,
and `false' otherwise.



\>IsZeroSquaredRing( <R> ) P

is `true' if $a * a$ is the zero element of the ring <R>
for all $a$ in <R>, and `false' otherwise.



\>IsJacobianRing( <R> ) P

is `true' if the Jacobi identity holds in <R>, and `false' otherwise.
The Jacobi identity means that $x \* (y \* z) + z \* (x \* y) + 
y \* (z \* x)$
is the zero element of <R>, for all elements $x$, $y$, $z$ in <R>.



\beginexample
gap> L:= FullMatrixLieAlgebra( GF( 5 ), 7 );
<Lie algebra over GF(5), with 13 generators>
gap> IsJacobianRing( L );
true
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Units and Factorizations}

\>IsUnit( <R>, <r> ) O
\>IsUnit( <r> ) O

In the first form `IsUnit' returns `true' if <r> is a unit in the ring
<R>.
In the second form `IsUnit' returns `true' if the ring element <r> is a
unit in its default ring (see "DefaultRing").

An element $r$ is called a *unit* in a ring $R$, if $r$ has an inverse in
$R$.

`IsUnit' may call `Quotient'.


\>Units( <R> ) A

`Units' returns the group of units of the ring <R>.
This may either be returned as a list or as a group.

An element $r$ is called a *unit* of a ring $R$, if $r$ has an inverse in
$R$.
It is easy to see that the set of units forms a multiplicative group.



\beginexample
gap> Units( GaussianIntegers );
[ -1, 1, -E(4), E(4) ]
gap> Units( GF( 16 ) );
<group with 1 generators>
\endexample

\>IsAssociated( <R>, <r>, <s> ) O
\>IsAssociated( <r>, <s> ) O

In the first form `IsAssociated' returns `true' if the two ring elements
<r> and <s> are associated in the ring <R> and `false' otherwise.
In the second form `IsAssociated' returns `true' if the two ring elements
<r> and <s> are associated in their default ring (see "DefaultRing") and
`false' otherwise.

Two elements $r$ and $s$ of a ring $R$ are called *associated* if there
is a unit $u$ of $R$ such that $r u = s$.


\>Associates( <R>, <r> ) O
\>Associates( <r> ) O

In the first form `Associates' returns the set of associates of <r> in
the ring <R>.
In the second form `Associates' returns the set of associates of the
ring element <r> in its default ring (see "DefaultRing").

Two elements $r$ and $s$ of a ring $R$ are called *associated* if there
is a unit $u$ of $R$ such that $r u = s$.



\beginexample
gap> Associates( Integers, 2 );
[ -2, 2 ]
gap> Associates( GaussianIntegers, 2 );
[ -2, 2, -2*E(4), 2*E(4) ]
\endexample

\>StandardAssociate( <R>, <r> ) O
\>StandardAssociate( <r> ) O

In the first form `StandardAssociate' returns the standard associate of
the ring element <r> in the ring <R>.
In the second form `StandardAssociate' returns the standard associate of
the ring element <r> in its default ring (see "DefaultRing").

The *standard associate* of a ring element $r$ of $R$ is an associated
element of $r$ which is, in a ring dependent way, distinguished among the
set of associates of $r$.
For example, in the ring of integers the standard associate is the
absolute value.



\beginexample
gap> x:= Indeterminate( Rationals, "x" );;
gap> StandardAssociate( -x^2-x+1 );
x^2+x-1
\endexample

\>IsIrreducibleRingElement( <R>, <r> ) O
\>IsIrreducibleRingElement( <r> ) O

In the first form `IsIrreducibleRingElement' returns `true' if the ring
element <r> is irreducible in the ring <R> and `false' otherwise.
In the second form `IsIrreducibleRingElement' returns `true' if the ring
element <r> is irreducible in its default ring (see "DefaultRing") and
`false' otherwise.

An element $r$ of a ring $R$ is called *irreducible* if $r$ is not a
unit in $R$ and if there is no nontrivial factorization of $r$ in $R$,
i.e., if there is no representation of $r$ as product $s t$ such that
neither $s$ nor $t$ is a unit (see "IsUnit").
Each prime element (see "IsPrime") is irreducible.



\beginexample
gap> IsIrreducibleRingElement( Integers, 2 );
true
\endexample


\>IsPrime( <R>, <r> ) O
\>IsPrime( <r> ) O

In the first form `IsPrime' returns `true' if the ring element <r> is a
prime in the ring <R> and `false' otherwise.
In the second form `IsPrime' returns `true' if the ring element <r> is a
prime in its default ring (see "DefaultRing") and `false' otherwise.

An element $r$ of a ring $R$ is called *prime* if for each pair $s$ and
$t$ such that $r$ divides $s t$ the element $r$ divides either $s$ or
$t$.
Note that there are rings where not every irreducible element
(see "IsIrreducibleRingElement") is a prime.


\>Factors( <R>, <r> ) O
\>Factors( <r> ) O

In the first form `Factors' returns the factorization of the ring
element <r> in the ring <R>.
In the second form `Factors' returns the factorization of the ring
element <r> in its default ring (see "DefaultRing").
The factorization is returned as a list of primes (see "IsPrime").
Each element in the list is a standard associate (see
"StandardAssociate") except the first one, which is multiplied by a unit
as necessary to have `Product( Factors( <R>, <r> )  )  = <r>'.
This list is usually also sorted, thus smallest prime factors come first.
If <r> is a unit or zero, `Factors( <R>, <r> ) = [ <r> ]'.




\beginexample
gap> x:= Indeterminate( GF(2), "x" );;
gap> pol:= x^2+x+1;
x^2+x+Z(2)^0
gap> Factors( pol );
[ x^2+x+Z(2)^0 ]
gap> Factors( PolynomialRing( GF(4) ), pol );
[ x+Z(2^2), x+Z(2^2)^2 ]
\endexample

\>PadicValuation( <r>, <p> ) O

`PadicValuation' is the operation to compute the <p>-adic valuation of
a ring element <r>.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Euclidean Rings}

\>IsEuclideanRing( <R> ) C

A ring $R$ is called a Euclidean ring if it is an integral ring and
there exists a function $\delta$, called the Euclidean degree, from
$R-\{0_R\}$ to the nonnegative integers, such that for every pair $r \in
R$ and $s \in  R-\{0_R\}$ there exists an element $q$ such that either
$r - q s = 0_R$ or $\delta(r - q s) \< \delta( s )$. In {\GAP} the
Euclidean degree $\delta$ is implicitly built into an ring and cannot be
changed.  The existence of this division with remainder implies that the
Euclidean algorithm can be applied to compute a greatest common divisor
of two elements, which in turn implies that $R$ is a unique
factorization ring.




\beginexample
gap> IsEuclideanRing( GaussianIntegers );
true
\endexample

\>EuclideanDegree( <R>, <r> ) O
\>EuclideanDegree( <r> ) O

In the first form `EuclideanDegree' returns the Euclidean degree of the
ring element in the ring <R>.
In the second form `EuclideanDegree' returns the Euclidean degree of the
ring element <r> in its default ring.
<R> must of course be a Euclidean ring (see "IsEuclideanRing").



\beginexample
gap> EuclideanDegree( GaussianIntegers, 3 );
9
\endexample

\>EuclideanQuotient( <R>, <r>, <m> ) O
\>EuclideanQuotient( <r>, <m> ) O

In the first form `EuclideanQuotient' returns the Euclidean quotient of
the ring elements <r> and <m> in the ring <R>.
In the second form `EuclideanQuotient' returns the Euclidean quotient of
the ring elements <r> and <m> in their default ring.
The ring <R> must be a Euclidean ring (see "IsEuclideanRing") otherwise
an error is signalled.



\beginexample
gap> EuclideanQuotient( 8, 3 );
2
\endexample

\>EuclideanRemainder( <R>, <r>, <m> ) O
\>EuclideanRemainder( <r>, <m> ) O

In the first form `EuclideanRemainder' returns the remainder of the ring
element <r> modulo the ring element <m> in the ring <R>.
In the second form `EuclideanRemainder' returns the remainder of the ring
element <r> modulo the ring element <m> in their default ring.
The ring <R> must be a Euclidean ring (see "IsEuclideanRing") otherwise
an error is signalled.



\beginexample
gap> EuclideanRemainder( 8, 3 );
2
\endexample

\>QuotientRemainder( <R>, <r>, <m> ) O
\>QuotientRemainder( <r>, <m> ) O

In the first form `QuotientRemainder' returns the Euclidean quotient
and the Euclidean remainder of the ring elements <r> and <m> in the ring
<R>.
In the second form `QuotientRemainder' returns the Euclidean quotient and
the Euclidean remainder of the ring elements <r> and <m> in their default
ring as pair of ring elements.
The ring <R> must be a Euclidean ring (see "IsEuclideanRing") otherwise
an error is signalled.



\beginexample
gap> QuotientRemainder( GaussianIntegers, 8, 3 );
[ 3, -1 ]
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Gcd and Lcm}

\>Gcd( <R>, <r1>, <r2>, ... ) F
\>Gcd( <R>, <list> ) F
\>Gcd( <r1>, <r2>, ... ) F
\>Gcd( <list> ) F

In the first two forms `Gcd' returns the greatest common divisor of the
ring elements `<r1>, <r2>, ...' resp. of the ring elements in the list
<list> in the ring <R>.
In the second two forms `Gcd' returns the greatest common divisor of the
ring elements `<r1>, <r2>, ...' resp. of the ring elements in the list
<list> in their default ring (see "DefaultRing").
<R> must be a Euclidean ring (see "IsEuclideanRing") so that
`QuotientRemainder' (see "QuotientRemainder") can be applied to its
elements.
`Gcd' returns the standard associate (see "StandardAssociate") of the
greatest common divisors.

A greatest common divisor of the elements $r_1, r_2, \ldots$ of the
ring $R$ is an element of largest Euclidean degree (see
"EuclideanDegree") that is a divisor of $r_1, r_2, \ldots$ .

We define 
`Gcd( <r>, $0_{<R>}$ ) = Gcd( $0_{<R>}$, <r> ) = StandardAssociate( <r> )'
and `Gcd( $0_{<R>}$, $0_{<R>}$ ) = $0_{<R>}$'.



\beginexample
gap> Gcd( Integers, [ 10, 15 ] );
5
\endexample

\>GcdOp( <R>, <r>, <s> ) O
\>GcdOp( <r>, <s> ) O

`GcdOp' is the operation to compute the greatest common divisor of
two ring elements <r>, <s> in the ring <R> or in their default ring.


\>GcdRepresentation( <R>, <r1>, <r2>, ... ) F
\>GcdRepresentation( <R>, <list> ) F
\>GcdRepresentation( <r1>, <r2>, ... ) F
\>GcdRepresentation( <list> ) F

In the first two forms `GcdRepresentation' returns the representation of
the greatest common divisor of the ring elements `<r1>, <r2>, ...' resp.
of the ring elements in the list <list> in the ring <R>.
In the second two forms `GcdRepresentation' returns the representation of
the greatest common divisor of the ring elements `<r1>, <r2>, ...' resp.
of the ring elements in the list <list> in their default ring
(see "DefaultRing").
<R> must be a Euclidean ring (see "IsEuclideanRing") so that
`Gcd' (see "Gcd") can be applied to its elements.

The representation of the gcd  $g$ of  the elements $r_1, r_2, \ldots$
of a ring $R$ is a list of ring elements $s_1, s_2, \ldots$ of $R$,
such that $g = s_1 r_1 + s_2  r_2 + \cdots$.
That this representation exists can be shown using the Euclidean
algorithm, which in fact can compute those coefficients.



\beginexample
gap> x:= Indeterminate( Rationals, "x" );;
gap> GcdRepresentation( x^2+1, x^3+1 );
[ -1/2*x^2-1/2*x+1/2, 1/2*x+1/2 ]
\endexample

\>GcdRepresentationOp( <R>, <r>, <s> ) O
\>GcdRepresentationOp( <r>, <s> ) O

`GcdRepresentationOp' is the operation to compute the representation of
the greatest common divisor of two ring elements <r>, <s> in the ring
<R> or in their default ring, respectively.


\>Lcm( <R>, <r1>, <r2>, ... ) F
\>Lcm( <R>, <list> ) F
\>Lcm( <r1>, <r2>, ... ) F
\>Lcm( <list> ) F


In the first two forms `Lcm' returns the least common multiple of the
ring elements `<r1>, <r2>, ...' resp. of the ring elements in the list
<list> in the ring <R>.
In the second two forms `Lcm' returns the least common multiple of the
ring elements `<r1>, <r2>, ...' resp. of the ring elements in the list
<list> in their default ring (see~"DefaultRing").

<R> must be a Euclidean ring (see~"IsEuclideanRing") so that `Gcd'
(see~"Gcd") can be applied to its elements.
`Lcm' returns the standard associate (see~"StandardAssociate") of the
least common multiples.

A least common multiple of the elements $r_1, r_2, \ldots$ of the
ring $R$ is an element of smallest Euclidean degree
(see~"EuclideanDegree") that is a multiple of $r_1, r_2, \ldots$ .

We define 
`Lcm( <r>, $0_{<R>}$ ) = Lcm( $0_{<R>}$, <r> ) = StandardAssociate( <r> )'
and `Lcm( $0_{<R>}$, $0_{<R>}$ ) = $0_{<R>}$'.

`Lcm' uses the equality $lcm(m,n) = m\*n / gcd(m,n)$ (see~"Gcd").



\>LcmOp( <R>, <r>, <s> ) O
\>LcmOp( <r>, <s> ) O

`LcmOp' is the operation to compute the least common multiple of
two ring elements <r>, <s> in the ring <R> or in their default ring,
respectively.



\>QuotientMod( <R>, <r>, <s>, <m> ) O
\>QuotientMod( <r>, <s>, <m> ) O

In the first form `QuotientMod' returns the quotient of the ring
elements <r> and <s> modulo the ring element <m> in the ring <R>.
In the second form `QuotientMod' returns the quotient of the ring elements
<r> and  <s> modulo the ring element <m> in their default ring (see
"DefaultRing").
<R> must be a Euclidean ring (see "IsEuclideanRing") so that
`EuclideanRemainder' (see "EuclideanRemainder") can be applied.
If the modular quotient does not exist, `fail' is returned.

The quotient $q$ of $r$ and $s$ modulo $m$ is an element of $R$ such that
$q s = r$ modulo $m$, i.e., such that $q s - r$ is divisible by $m$ in
$R$ and that $q$ is either 0 (if $r$ is divisible by $m$) or the
Euclidean degree of $q$ is strictly smaller than the Euclidean degree of
$m$.



\beginexample
gap> QuotientMod( 7, 2, 3 );
2
\endexample

\>PowerMod( <R>, <r>, <e>, <m> ) O
\>PowerMod( <r>, <e>, <m> ) O

In the first form `PowerMod' returns the <e>-th power of the ring
element <r> modulo the ring element <m> in the ring <R>.
In the second form `PowerMod' returns the <e>-th power of the ring
element <r> modulo the ring element <m> in their default ring (see
"DefaultRing").
<e> must be an integer.
<R> must be a Euclidean ring (see "IsEuclideanRing") so that
`EuclideanRemainder' (see "EuclideanRemainder") can be applied to its
elements.

If $e$ is positive the result is $r^e$ modulo $m$.
If $e$ is negative then `PowerMod' first tries to find the inverse of $r$
modulo $m$, i.e., $i$ such that $i r = 1$ modulo $m$.
If the inverse does not exist an error is signalled.
If the inverse does exist `PowerMod' returns
`PowerMod( <R>, <i>, -<e>, <m> )'.

`PowerMod' reduces the intermediate values modulo $m$, improving
performance drastically when <e> is large and <m> small.



\beginexample
gap> PowerMod( 12, 100000, 7 );
2
\endexample


\>InterpolatedPolynomial( <R>, <x>, <y> ) O

`InterpolatedPolynomial' returns, for given lists <x>, <y> of elements in
a ring <R> of the same length $n$, say, the unique  polynomial of  degree
less than $n$ which has value <y>[$i$] at <x>[$i$], 
for all $i\in\{1,\ldots,n\}$. 
Note that the elements in <x> must be distinct.



\beginexample
gap>  InterpolatedPolynomial( Integers, [ 1, 2, 3 ], [ 5, 7, 0 ] );
-9/2*x^2+31/2*x-6
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E