%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%   gf2n.tex           LiDIA documentation
%%
%%   This file contains the documentation of the class gf2n    
%%
%%   Copyright  (c)   1996  LiDIA-Group 
%%
%%   Authors: Patric Kirsch, Franz-Dieter Berger
%%            Volker Mueller, 8/5/96
%%

\begin{lidia_man}
\markright{\BF{gf2n}}

\NAME
\BF{gf2n} \DOTFILL \MATH{GF(2^n)} arithmetic

\ABSTRACT \BF{gf2n} is a class for doing arithmetic in \MATH{GF(2^n)},
the finite field with \MATH{2^n} elements.  It supports for example
arithmetic operations, comparisons, I/O of \MATH{GF(2^n)}-elements and
basic operations like computing a generator of the multiplicative
group. We use a polynomial representation for \MATH{GF(2^n)} with a
precomputed sparse modulus.

\DESCRIPTION

We use the polynomial representation for elements in the finite field
\MATH{GF(2^n)}.  A \BF{gf2n} element is represented by an array of
\TT{unsigned longs} and a global modulus. This modulus must be set by
the procedure \BF{gf2n\_init}, before any variable of type \BF{gf2n} can
be declared. The modulus can be chosen from a given database or you
can select it yourself. For a detailed description of the different
inputs of this initialization procedure, see section initialization.

Each equivalence class modulo the global modulus is represented by a
polynomial over \MATH{GF(2)}, whose degree is smaller than the degree
of the modulus. This polynomial is internally stored in the bit field
given by the array of \TT{unsigned longs}.

The format of the input/output of \BF{gf2n} elements is handled with a
special class \BF{gf2nIO}. Available choices are described in section
Input/Output.


\CONS

  \fcode{ct }{gf2n}{}{initialize variable with 0.}
  \fcode{ct }{gf2n}{const gf2n \& x}{initialize variable with \MATH{x}.}
  
  \fcode{ct }{gf2n}{unsigned long ul}{initialize variable with the
    binary representation of \MATH{ui}, i.e.~if $ul=\sum_{i=0}^k
    b_i\,2^i$ with $b_i\in\{0,1\}$, then initialize the variable with the
    equivalence class represented by the polynomial $\sum_{i=0}^k
    b_i\,x^i$. If \MATH{ul} is greater or equal than the number of elements
    in \MATH{GF(2^n)}, the \TT{lidia\_error\_handler} is invoked.}
  
  \fcode{ct }{gf2n}{const bigint \& b}{initializes the declared
    variable with the binary representation of \MATH{b}, i.e.~if
    $b=\sum_{i=0}^k b_i\,2^i$ with $b_i\in\{0,1\}$, then initialize
    variable with the equivalence class represented by the polynomial
    $\sum_{i=0}^k b_i\,x^i$. If \MATH{b} is greater or equal than the
    number of elements in \MATH{GF(2^n)}, the 
    \TT{lidia\_error\_handler} is invoked.}
 
 \fcode{dt }{\MATH{\sim}gf2n}{}{}


\INIT

One of the two following initialization routines must be called before
any object of type \BF{gf2n} can be declared. Note that because of this
fact it is not possible to use static or global variables of type
\BF{gf2n}.


\fcode{void}{gf2n\_init}{unsigned int d \k gf2nIO::base base =
  GF2nIO::Dec} {the function selects a sparse irreducible polynomial
  of degree \TT{d} over \MATH{GF(2)} in a precomputed database and
  initializes the global modulus with this polynomial.  Per default
  the database is read from the file
  \TT{LIDIA\_INSTALL\_DIR/lib/LiDIA/GF2n.database}, where
  \TT{LIDIA\_INSTALL\_DIR} denotes the directory where \LiDIA\ was
  installed by the installation procedure. If you want to use another
  location for the database, you can set the environment variable
  \TT{LIDIA\_GF2N} to point to this location. Furthermore the
  initialization function sets the output base of \BF{gf2nIO} 
  to \TT{base}, for a detailed description of \BF{gf2nIO} see the
  section on Input/Output.}

\fcode{void}{gf2n\_init}{char * m \k gf2nIO::base base = gf2nIO::Dec}
{the global modulus of \BF{gf2n} is initialized with the polynomial,
  which is described in the string \TT{m}.  This string must contain
  the exponents of 1-coefficients of the polynomial, separated by a
  blank (example: the string "123 45 0" represents the polynomial
  \MATH{x^{123}+x^{45}+x^0}). Note that the irreducibility of the
  modulus is not checked.  The output base of \BF{gf2nIO} is set to
  \TT{base}, for a detailed description of \BF{gf2nIO} see the section
  on Input/Output.}


\ASGN

The assignment operator \TT{=} is overloaded. Furthermore there exist
the following assignment functions:

\fcode{void}{x.assign\_zero}{}{
  \MATH{x = 0}.}
\fcode{void}{x.assign\_one}{}{
  \MATH{x = 1}.}
\fcode{void}{ x.assign}{const gf2n \& a}{
  \MATH{x = a}.}


\ARTH

The following operators are overloaded and can be used in exactly the same
way as in C (note that addition and subtraction are the same in fields
of characteristic 2, but nevertheless we support both operators).

  \begin{center}
    \TT{(binary) +, -, *, /} \\
    \TT{(binary with assignment) +=, -=, *=, /=} 
  \end{center}

To avoid copying, all operators also exist as functions:

\fcode{void}{add}{gf2n \& x \k const gf2n \& y \k const gf2n \& z}{
  \MATH{x = y + z}.}
\fcode{void}{subtract}{gf2n \& x \k const gf2n \& y \k const gf2n \& z}{
  \MATH{x = y - z}.}
\fcode{void}{multiply}{gf2n \& x \k const gf2n \& y \k const gf2n \& z}{
  \MATH{x = y * z}.}
\fcode{void}{divide}{gf2n \& x \k const gf2n \& y \k const gf2n \& z}{
  \MATH{x = y / z}. If $z=0$, the \TT{lidia\_error\_handler} is invoked.}
\fcode{void}{square}{gf2n \& x \k const gf2n \& y}{
  \MATH{x = y^{2}}.}
\fcode{void}{sqrt}{gf2n \& x \k const gf2n \& y}{
  compute $x$ with $x^2=y$.}
\fcode{gf2n}{sqrt}{const gf2n \& y}{return \MATH{x} such that
  \MATH{x^2=y}.}
\fcode{void}{x.invert}{}
 {set \MATH{x = x^{-1}}.  If \MATH{x=0}, the \TT{lidia\_error\_handler} is 
  invoked.}
\fcode{void}{invert}{gf2n \& x \k const gf2n \& y}{
  \MATH{x = y^{-1}}. If \MATH{y=0}, the \TT{lidia\_error\_handler} is
 invoked.}
\fcode{gf2n}{inverse}{const gf2n \& y}{
  return \MATH{y^{-1}}. If \MATH{y=0},the \TT{lidia\_error\_handler} is 
 invoked.}
\fcode{void}{power}{gf2n \& x \k const gf2n \& y \k const \& bigint i }{
  \MATH{x = y^{i}}. If \MATH{y=0} and \MATH{i<0},  the \TT{lidia\_error\_handler} s invoked.}
\fcode{void}{power}{gf2n \& x \k const gf2n \& y \k long l}{
  \MATH{x = y^{l}}. If \MATH{y=0} and \MATH{l<0},  the \TT{lidia\_error\_handler} s invoked.}


\COMP

\BF{gf2n} supports the binary operators \MATH{==} and \MATH{!=}. Let
\MATH{a} be an instance of type \BF{gf2n}. 

\cfcode{void}{a.is\_zero}{}{  
  returns \TRUE\ if \MATH{a=0}, \FALSE\ otherwise.}
\cfcode{void}{a.is\_one}{}{
  returns \TRUE\ if \MATH{a=1}, \FALSE\ otherwise.}


\BASIC

Let \MATH{x} be of type \BF{gf2n}.

\fcode{static unsigned int}{extension\_degree}{}{return the extension
  degree \MATH{n} of the current field \MATH{GF(2^n)} over
  \MATH{GF(2)}.}

\fcode{void}{swap}{gf2n \& a \k gf2n \& b}{ 
  exchange the values of \MATH{a} and \MATH{b}.}

\fcode{udigit}{hash}{const gf2n \& a}{
  return a hash value for \MATH{a}.}

\fcode{void}{randomize}{gf2n \& a}{
  set $\MATH{a}$ to a random element in \MATH{GF(2^n)}.}



\HIGH

\fcode{bigint}{compute\_order}{const gf2n \& a}{compute the order of \MATH{a}.
  Note that computing the order of an element might imply factoring
  the order of the multiplicative group of \MATH{GF(2^n)} which can
  take a while for extension degrees bigger than 150.}

\fcode{gf2n}{get\_generator}{}{return a generator of the
  multiplicative group of \MATH{GF(2^n)}. Note that computing a
  generator might imply factoring the order of the multiplicative
  group of \MATH{GF(2^n)} which can take a while for extension degrees
  bigger than 150.}  



\IO

The \BF{istream} operator \MATH{>>} and the \BF{ostream} operator
\MATH{<<} are implemented. The format of the I/O of \BF{gf2n} elements
can be chosen with the help of the class \BF{gf2nIO}. Note that the
I/O-format stored in \BF{gf2nIO} is valid for all variables of type
\BF{gf2n}. 

Input of \BF{gf2n} elements is per default expected as decimal
number. Moreover one of the two prefixes \TT{dec:}, \TT{hex:} can be
used to denote decimal, hexadecimal interpretation of the input,
respectively. Example: you can input the ``polynomial'' $x^4+x+1$ as either
\TT{19}, \TT{dec:19} or \TT{hex:a4}.

At the moment, the class \BF{gf2nIO} allows you to choose a base for Output and
an output prefix. Available bases are given as \BF{enum base \{Dec,
  Hex\}}. Output of an \BF{gf2n} variable is then done as decimal,
hexadecimal number with the chosen prefix, respectively.  This Output
format can be chosen during initialization with the functions
\BF{gf2n\_init} or it can be changed at any time with the help of the
following functions.


\fcode{gf2nIO::void}{setbase}{gf2nIO::base b}{set \TT{gf2nIO::base} to
  base \MATH{b}. If \MATH{b} is no valid base, the
  \TT{lidia\_error\_handler} is invoked.}

\fcode{gf2nIO::base}{showbase}{}{return \TT{gf2nIO::base}.}

\fcode{gf2nIO::void}{setprefix}{gf2nIO::base b}
{set the output-prefix to the standard prefix for base \MATH{b}.}

\fcode{gf2nIO::void}{setprefix}{char * p}
{set the output prefix to \MATH{p}.}

\fcode{gf2nIO::void}{noprefix}{}
{set the output prefix to the empty string.}

\fcode{char *}{showprefix}{}{ returns the actual output prefix.}

 
\EXAMPLES

The following program computes a generator of a given field \MATH{GF(2^n)}.

\begin{verbatim}
        #include <LiDIA/gf2n.h>

        main()
        { 
          unsigned int degree;
          
          cout << "Degree: ";  cin >> degree;

          gf2n_init(degree);

          gf2n a;
           
          a = get_generator();

          cout << "Generator of GF(2^"<< n <<") = " << a;
        }
  \end{verbatim}

\NOTES

The classes \BF{gf2n} and \BF{gf2nIO} are not yet complete. In future
we will add more different input/output formats and make the I/O of
\BF{gf2n} elements easier.



\AUTHOR
  Franz-Dieter Berger, Patric Kirsch, Volker M\"uller

\end{lidia_man}



