% This file was created automatically from fieldfin.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  fieldfin.msk                  GAP documentation             Thomas Breuer
%%
%A  @(#)$Id: fieldfin.msk,v 1.20 2002/04/15 10:02:28 sal 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> 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

\>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
\>GaloisField( <p>, <d> ) F
\>GaloisField( <S>, <d> ) F
\>GaloisField( <p>, <pol> ) F
\>GaloisField( <S>, <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.

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


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


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

