% This file was created automatically from fieldfin.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  fieldfin.msk                  GAP documentation             Thomas Breuer
%%
%A  @(#)$Id: fieldfin.msk,v 1.24.2.1 2005/04/13 11:45:38 gap Exp $
%%
%Y  (C) 1998 School Math and Comp. Sci., University of St.  Andrews, Scotland
%Y  Copyright (C) 2002 The GAP Group
%%
\Chapter{Finite Fields}

This chapter describes the special functionality which exists in {\GAP} for
finite fields and their elements.
Of course the general functionality for fields
(see Chapter~"Fields and Division Rings") also applies to finite fields.

In the following, the term *finite field element* is used to denote {\GAP}
objects in the category `IsFFE' (see~"IsFFE"), and *finite field* means a
field consisting of such elements.
Note that in principle we must distinguish these fields from (abstract)
finite fields.
For example, the image of the embedding of a finite field into a field of
rational functions in the same characteristic is of course a finite field
but its elements are not in `IsFFE', and in fact {\GAP} does currently not
support such fields.

Special representations exist for row vectors and matrices over small finite
fields (see sections~"Row Vectors over Finite Fields"
and~"Matrices over Finite Fields").


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Finite Field Elements}

\>IsFFE( <obj> ) C
\>IsFFECollection( <obj> ) C
\>IsFFECollColl( <obj> ) C


Objects in the category `IsFFE' are used to implement elements of finite
fields.  In this manual, the term *finite field element* always means an
object in `IsFFE'.
All finite field elements of the same characteristic form a family in
{\GAP} (see~"Families").
Any collection of finite field elements (see~"IsCollection") lies in
`IsFFECollection', and a collection of such collections
(e.g., a matrix) lies in `IsFFECollColl'.



\>Z( <p>^<d> ) F

For creating elements of a finite field the function `Z' can be used.
The call `Z( <p>^<d> )' returns  the designated generator of  the 
multiplicative
group of the finite field with `<p>^<d>' elements.  <p>  must be a prime
and `<p>^<d>' must be less than or equal to $2^{16} = 65536$.

The  root returned by `Z' is  a generator of  the multiplicative group of
the finite field with $p^d$ elements, which  is cyclic.  The order of the
element is  of course $p^d-1$.  The $p^d-1$  different powers of the root
are exactly the nonzero elements of the finite field.

Thus  all nonzero elements of the  finite field  with `<p>^<d>' elements
can  be entered  as `Z(<p>^<d>)^<i>'.  Note that this is  also the form
that {\GAP} uses to output those elements.

The additive neutral element  is `0\*Z(<p>)'.  It  is  different from the
integer `0' in subtle ways.  First `IsInt( 0\*Z(<p>)  )' (see "IsInt") is
`false' and `IsFFE( 0\*Z(<p>) )'  (see "IsFFE") is  `true', whereas it is
just the other way around for the integer `0'.

The multiplicative neutral element is `Z(<p>)^0'.   It is different from
the integer `1' in subtle ways.  First `IsInt( Z(<p>)^0 )' (see "IsInt")
is `false' and `IsFFE( Z(<p>)^0 )' (see  "IsFFE") is  `true', whereas it
is just the  other  way around for the  integer `1'.  Also `1+1' is `2',
whereas, e.g., `Z(2)^0 + Z(2)^0' is `0\*Z(2)'.

The  various  roots  returned  by  `Z'  for  finite  fields  of the  same
characteristic  are  compatible  in  the  following  sense.  If the field
$GF(p^n)$ is a  subfield of the  field  $GF(p^m)$, i.e., $n$ divides $m$,
then $Z(p^n) = Z(p^m)^{(p^m-1)/(p^n-1)}$.  Note that this is the simplest
relation that may  hold  between a generator of $GF(p^n)$ and  $GF(p^m)$,
since $Z(p^n)$ is an element of order $p^m-1$ and $Z(p^m)$  is an element
of order  $p^n-1$.  This is achieved  by choosing $Z(p)$ as  the smallest
primitive  root modulo $p$  and  $Z(p^n)$ as a root of the $n$-th *Conway
polynomial* (see~"ConwayPolynomial") of characteristic $p$.
Those polynomials were defined by J.~H.~Conway, and many of them were
computed by R.~A.~Parker.

Elements of prime fields of order larger than $2^{16}$ can be handled
using the machinery of Residue Class Rings
(see section~"Residue Class Rings").



\beginexample
gap> a:= Z( 32 );
Z(2^5)
gap> a+a;
0*Z(2)
gap> a*a;
Z(2^5)^2
\endexample

Elements of finite fields can be compared using the operators `=' and
`\<'. The call `<a> = <b>' returns `true' if and only if the finite
field elements <a> and <b> are equal. Furthermore `<a> \< <b>' tests
whether <a> is smaller than <b>. Finite field elements are ordered in
the following way. If the two elements lie in fields of different
characteristics the one that lies in the field with the smaller
characteristic is smaller.  If the two elements lie in different
fields of the same characteristic the one that lies in the smaller
field is smaller.  If the two elements lie in the same field and one
is the zero and the other is not, the zero element is smaller.  If the
two elements lie in the same field and both are nonzero, and are
represented as $Z(p^d)^{i_1}$ and $Z(p^d)^{i_2}$ respectively, then
the one with the smaller $i$ is smaller.

For the comparison of finite field elements with other {\GAP} objects,
see~"Comparisons".

\beginexample
gap> Z( 16 )^10 = Z( 4 )^2;  # this illustrates the embedding of GF(4) in GF(16)
true
gap> 0 < 0*Z(101);
true
gap> Z(256) > Z(101);
false
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Operations for Finite Field Elements}

Since finite field elements are scalars, the operations `Characteristic',
`One', `Zero', `Inverse', `AdditiveInverse', `Order' can be applied to
then (see~"Attributes and Properties of Elements").
Contrary to the situation with other scalars, `Order' is defined also for
the zero element in a finite field, with value `0'.
% mainly for {\GAP}~3 compatibility ...


\beginexample
gap> Characteristic( Z( 16 )^10 );  Characteristic( Z( 9 )^2 );
2
3
gap> Characteristic( [ Z(4), Z(8) ] );
2
gap> One( Z(9) );  One( 0*Z(4) );
Z(3)^0
Z(2)^0
gap> Inverse( Z(9) );  AdditiveInverse( Z(9) );
Z(3^2)^7
Z(3^2)^5
gap> Order( Z(9)^7 );
8
\endexample

\>DegreeFFE( <z> ) O
\>DegreeFFE( <vec> ) O
\>DegreeFFE( <mat> ) O

`DegreeFFE'  returns  the   degree of  the   smallest  finite field
<F> containing the element <z>, respectively all elements of the vector
<vec> over a finite field (see~"Row Vectors"), or matrix  <mat> over a
finite field (see~"Matrices").


\beginexample
gap> DegreeFFE( Z( 16 )^10 );
2
gap> DegreeFFE( Z( 16 )^11 );
4
gap> DegreeFFE( [ Z(2^13), Z(2^10) ] );
130
\endexample

\>LogFFE( <z>, <r> ) O

`LogFFE' returns the discrete  logarithm of the element <z> in  a  finite
field with  respect  to  the  root <r>.
An  error is signalled if <z> is zero, or if <z> is not a power of <r>.

The *discrete logarithm* of an element $z$ with  respect to a root $r$ is
the smallest nonnegative integer $i$ such that $r^i = z$.


\beginexample
gap> LogFFE( Z(409)^116, Z(409) );  LogFFE( Z(409)^116, Z(409)^2 );
116
58
\endexample

\>IntFFE( <z> ) O

`IntFFE' returns the integer corresponding to the element <z>, which must
lie in  a finite  prime field.   That is  `IntFFE' returns  the  smallest
nonnegative integer <i> such that `<i> \*\ One( <z> ) = <z>'.

The  correspondence between elements from a finite prime field of
characteristic <p> (for $p\< 2^{16}$) and the integers between $0$ and $p-1$ is defined by
choosing `Z(<p>)' the element corresponding to the smallest primitive
root mod <p> (see~"PrimitiveRootMod").

`IntFFE' is installed as a method for the operation `Int' (see~"Int")
with argument a finite field element.


\beginexample
gap> IntFFE( Z(13) );  PrimitiveRootMod( 13 );
2
2
gap> IntFFE( Z(409) );
21
gap> IntFFE( Z(409)^116 );  21^116 mod 409;
311
311
\endexample

\>IntFFESymm( <z> ) O
\>IntFFESymm( <vec> ) O

For a finite prime field element <z>, `IntFFESymm' returns the corresponding
integer of smallest absolute value. That is `IntFFESymm' returns the integer
<i> of smallest absolute value that `<i> \*\ One( <z> ) = <z>'.

For a vector <vec>, the operation returns the result if applying
`IntFFESymm' to every entry of the vector.

The  correspondence between elements from a finite prime field of
characteristic <p> (for $p\< 2^{16}$) and the integers between $-p/2$ and $p/2$ is defined by
choosing `Z(<p>)' the element corresponding to the smallest positive
primitive
root mod <p> (see~"PrimitiveRootMod") and reducing results to the
$-p/2..p/2$ range.


\beginexample
gap> IntFFE(Z(13)^2);IntFFE(Z(13)^3);
4
8
gap> IntFFESymm(Z(13)^2);IntFFESymm(Z(13)^3);
4
-5
\endexample

\>IntVecFFE( <vecffe> ) O

is the list of integers corresponding to the vector <vecffe> of finite
field elements in a prime field (see~"IntFFE").




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Creating Finite Fields}

\indextt{DefaultField!for finite field elements}
\indextt{DefaultRing!for finite field elements}
`DefaultField' (see~"DefaultField") and `DefaultRing' (see~"DefaultRing")
for finite field elements are defined to return the *smallest* field
containing the given elements.


\beginexample
gap> DefaultField( [ Z(4), Z(4)^2 ] );  DefaultField( [ Z(4), Z(8) ] );
GF(2^2)
GF(2^6)
\endexample

\>GaloisField( <p>^<d> ) F
\>GF( <p>^<d> ) F
\>GaloisField( <p>, <d> ) F
\>GF( <p>, <d> ) F
\>GaloisField( <subfield>, <d> ) F
\>GF( <subfield>, <d> ) F
\>GaloisField( <p>, <pol> ) F
\>GF( <p>, <pol> ) F
\>GaloisField( <subfield>, <pol> ) F
\>GF( <subfield>, <pol> ) F

`GaloisField' returns a finite field.  It takes two arguments.
The form `GaloisField( <p>, <d> )', where <p>, <d> are integers,
can also be given as `GaloisField( <p>^<d> )'.
`GF' is an abbreviation for `GaloisField'.

The first argument specifies the subfield <S> over which the new field
<F> is to be taken.
It can be a prime or a finite field.
If it is a prime <p>, the subfield is the prime field of this
characteristic.

The second argument specifies the extension.
It can be an integer or an irreducible polynomial over the field <S>.
If it is an integer <d>, the new field is constructed as the
polynomial extension with the Conway polynomial (see~"ConwayPolynomial")
of degree <d> over the subfield <S>.
If it is an irreducible polynomial <pol> over <S>,
the new field is constructed as polynomial extension of the subfield <S>
with this polynomial;
in this case, <pol> is accessible as the value of `DefiningPolynomial'
(see~"DefiningPolynomial") for the new field,
and a root of <pol> in the new field is accessible as the value of
`RootOfDefiningPolynomial' (see~"RootOfDefiningPolynomial").

Note that the subfield over which a field was constructed determines over
which  field  the  Galois  group,  conjugates,   norm,   trace,   minimal
polynomial, and trace polynomial are  computed  (see~"GaloisGroup!of field",
"Conjugates", "Norm", "Trace!for field elements", "MinimalPolynomial!over
a field", "TracePolynomial").

The field is regarded as a vector space (see~"Vector Spaces") over the
given subfield, so this determines the dimension and the canonical basis
of the field.


\beginexample
gap> f1:= GF( 2^4 );
GF(2^4)
gap> Size( GaloisGroup ( f1 ) );
4
gap> BasisVectors( Basis( f1 ) );
[ Z(2)^0, Z(2^4), Z(2^4)^2, Z(2^4)^3 ]
gap> f2:= GF( GF(4), 2 );
AsField( GF(2^2), GF(2^4) )
gap> Size( GaloisGroup( f2 ) );
2
gap> BasisVectors( Basis( f2 ) );
[ Z(2)^0, Z(2^4) ]
\endexample

\>PrimitiveRoot( <F> ) A

A *primitive root* of a finite field is a generator of its multiplicative
group.
A primitive root is always a primitive element (see~"PrimitiveElement"),
the converse is in general not true.
% For example, `Z(9)^2' is a primitive element for `GF(9)' but not a
% primitive root.


\beginexample
gap> f:= GF( 3^5 );
GF(3^5)
gap> PrimitiveRoot( f );
Z(3^5)
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{FrobeniusAutomorphism}\nolabel

\atindex{homomorphisms!Frobenius, field}{@homomorphisms!Frobenius, field}
\atindex{field homomorphisms!Frobenius}{@field homomorphisms!Frobenius}
\indextt{Image!for Frobenius automorphisms}
\indextt{CompositionMapping!for Frobenius automorphisms}

\>FrobeniusAutomorphism( <F> ) A

returns the Frobenius automorphism of the finite
field <F> as a field homomorphism (see~"Ring Homomorphisms").

\atindex{Frobenius automorphism}{@Frobenius automorphism}
The *Frobenius automorphism* $f$ of a finite field $F$ of characteristic
$p$ is the function that takes each element $z$ of $F$ to its $p$-th
power.
Each automorphism of $F$ is a power of $f$.
Thus $f$ is a generator for the Galois group of $F$ relative to the prime
field of $F$,
and an appropriate power of $f$ is a generator of the Galois group of $F$
over a subfield (see~"GaloisGroup!of field").

\beginexample
gap> f := GF(16);
GF(2^4)
gap> x := FrobeniusAutomorphism( f );
FrobeniusAutomorphism( GF(2^4) )
gap> Z(16) ^ x;
Z(2^4)^2
gap> x^2;
FrobeniusAutomorphism( GF(2^4) )^2
\endexample

The image of an element $z$ under the $i$-th power of $f$ is computed
as the $p^i$-th power of $z$.
The product of the $i$-th power and the $j$-th power of $f$ is the $k$-th
power of $f$, where $k$ is $i j \pmod{`Size(<F>)'-1}$.
The zeroth power of $f$ is `IdentityMapping( <F> )'.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Conway Polynomials}

\>ConwayPolynomial( <p>, <n> ) F

is the Conway polynomial of the finite field $GF(p^n)$ as
polynomial over the prime field in characteristic <p>.

The *Conway polynomial* $\Phi_{n,p}$ of $GF(p^n)$ is defined by the
following properties.

First define an ordering of polynomials of degree $n$ over $GF(p)$ as
follows.  $f = \sum_{i=0}^n (-1)^i f_i x^i$ is smaller than
$g = \sum_{i=0}^n (-1)^i g_i x^i$ if and only if there is an index
$m \leq n$ such that $f_i = g_i$ for all $i > m$, and
$\tilde{f_m} \< \tilde{g_m}$, where $\tilde{c}$ denotes the integer
value in $\{ 0, 1, \ldots, p-1 \}$ that is mapped to $c\in GF(p)$ under
the canonical epimorphism that maps the integers onto $GF(p)$.

$\Phi_{n,p}$ is *primitive* over $GF(p)$ (see~"IsPrimitivePolynomial").
That is, $\Phi_{n,p}$ is irreducible, monic,
and is the minimal polynomial of a primitive root of $GF(p^n)$.

For all divisors $d$ of $n$ the compatibility condition
$\Phi_{d,p}( x^{\frac{p^n-1}{p^m-1}} ) \equiv 0 \pmod{\Phi_{n,p}(x)}$
holds. (That is, the appropriate power of a zero of $\Phi_{n,p}$ is a
zero of the Conway polynomial $\Phi_{d,p}$.)

With respect to the ordering defined above, $\Phi_{n,p}$ shall be
minimal.

The computation of Conway polynomials can be time consuming. Therefore,
{\GAP} comes with a list of precomputed polynomials. If a requested
polynomial is not stored then {\GAP} prints a warning and computes it by
checking all polynomials in the order defined above for the defining
conditions. If $n$ is not a prime this is probably a very long computation.
(Some previously known polynomials with prime $n$ are not stored in
{\GAP} because they are quickly recomputed.) Use the function 
"IsCheapConwayPolynomial" to check in advance if `ConwayPolynomial' will
give a result after a short time.

Note that primitivity of a polynomial can only be checked if {\GAP} can
factorize $p^n-1$. A sufficiently new version of the \package{FactInt}
package contains many precomputed factors of such numbers from various
factorization projects.

See~\cite{L03} for further information on known Conway polynomials.

If <pol> is a result returned by `ConwayPolynomial' the command
`Print( InfoText( <pol> ) );' will print some info on the origin of that
particular polynomial.

For some purposes it may be enough to have any primitive polynomial for
an extension of a finite field instead of the Conway polynomial, 
see~"ref:RandomPrimitivePolynomial" below.


\beginexample
gap> ConwayPolynomial( 2, 5 );  ConwayPolynomial( 3, 7 );
x_1^5+x_1^2+Z(2)^0
x_1^7-x_1^2+Z(3)^0
\endexample

\>IsCheapConwayPolynomial( <p>, <n> ) F

Returns `true' if `ConwayPolynomial( <p>, <n> )' will give a result in
*reasonable* time. This is either the case when this polynomial is
pre-computed, or if <n> is a not too big prime.



\>RandomPrimitivePolynomial( <F>, <n>[, <i> ] ) F

For a finite field <F> and a positive integer <n> this function
returns a primitive polynomial of degree <n> over <F>, that is a zero of 
this polynomial has maximal multiplicative order $|<F>|^n-1$. 
If <i> is given then the polynomial is written in variable number <i>
over <F> (see~"ref:Indeterminate"), the default for <i> is 1.

Alternatively, <F> can be a prime power q, then <F> = GF(q) is assumed.
And <i> can be a univariate polynomial over <F>, then the result is a
polynomial in the same variable.

This function can work for much larger fields than those for which
Conway polynomials are available, of course {\GAP} must be able to
factorize $|<F>|^n-1$.



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

