%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  field.tex      LiDIA documentation
%%
%%  This file contains the documentation of the class number_field
%%
%%  Copyright (c) 1995 by the LiDIA Group
%%
%%  Authors: Stefan Neis
%%

\begin{lidia_man}
\markright{\BF{number\_field}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\NAME
\BF{number\_field} \DOTFILL algebraic number fields.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ABSTRACT
\BF{number\_field} is a class for representing algebraic number
fields \MATH{\Q(b)}, where \MATH{b} is a root of a monic irreducible
polynomial with coefficients in the rational integers.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\DESCRIPTION   
A \BF{number\_field} consists of a \MATH{\Z}--basis of an algebraic number
field. This basis is stored using the internal class
\BF{nf\_base}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\CONS
\fcode{ct}{number\_field}{}
{
initializes with the number field generated by the current
\BF{nf\_base}. This is the base of the \BF{number\_field} or the \BF{order}
that was either constructed or read the last before invoking this
constructor. If no \BF{number\_field} or \BF{order} has been used so far,
this defaults to a (mostly useless) dummy field.}

\fcode{ct}{number\_field}{const polynomial\TEMPL{bigint} \&}
{
  initializes with the given polynomial. If the given polynomial
  is not irreducible or not monic, this results in undefined
  behaviour.}

\fcode{ct}{number\_field}{const bigint * v\k lidia\_size\_t deg}
{
initializes the field by the number field \MATH{\Q(b)}, where
\MATH{b} is a root of 
\latex{
\[ \sum_{i=0}^{deg} v[i]x^i.\]
}
\html{\begin{verbatim}
  deg
 -----
 \          i
  ) v[i] * x .
 /
 -----
 i = 0
\end{verbatim}}
% If this polynomial is not irreducible or not monic, the
% \TT{lidia\_error\_handler} will be invoked.}
If this polynomial is not irreducible or not monic, this results in
undefined behaviour.}

\fcode{ct}{number\_field}{const order \& O}
{
initializes with the quotient field of the order \MATH{O}.}

\fcode{ct}{number\_field}{const number\_field \& F}
{
initializes with a copy of the field \MATH{F}.}

\fcode{dt}{{\SIM number\_field}}{}{}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ASGN
Let \MATH{F} be of type \BF{number\_field}. The operator \TT{=} is
overloaded. For consistency reasons, the following function is also
implemented: 
\vspace*{1ex}

\fcode{void}{F.assign}{const number\_field \& K}
{
\MATH{F = K}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ACCS
\cfcode{nf\_base *}{F.which\_base}{}
{
returns the pointer to the \BF{nf\_base} used to describe \MATH{F}.}

\fcode{nf\_base *}{which\_base}{const number\_field \& F}
{
returns the pointer to the \BF{nf\_base} used to describe \MATH{F}.}

\cfcode{const polynomial\TEMPL{bigint} \&}{F.which\_polynomial}{}
{
returns the generating polynomial of \MATH{F}.}

\fcode{const polynomial\TEMPL{bigint} \&}{which\_polynomial}{const number\_field
  \& F}{
returns the generating polynomial of \MATH{F}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\BASIC

Let \MATH{F} be an instance of type \BF{number\_field}.\vspace*{1ex}

\cfcode{lidia\_size\_t}{F.degree}{}
{
returns the degree of the field \MATH{F} over \MATH{\Q}.}

\fcode{lidia\_size\_t}{degree}{const number\_field \& F}
{
returns the degree of the field \MATH{F} over \MATH{\Q}.}

\cfcode{operator}{nf\_base *}{}{
  cast operator which implicitly converts a \BF{number\_field} to a
  pointer to the representation of its base.}

\cfcode{lidia\_size\_t}{F.no\_of\_real\_embeddings}{}
{
returns the number of embeddings of the field \MATH{F} into \MATH{\R}.}

\fcode{lidia\_size\_t}{no\_of\_real\_embeddings}{const number\_field \& F}
{
returns the number of embeddings of the field \MATH{F} into \MATH{\R}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\HIGH
Let \MATH{F} be an instance of type \BF{number\_field}.\vspace*{1ex}

\cfcode{const bigfloat \&}{F.get\_conjugate}{lidia\_size\_t i\k
  lidia\_size\_t j}{
  for \MATH{0}\LEQ\MATH{i}\LT\TT{F.degree()} and
  \MATH{0}\LT\MATH{j}\LEQ\TT{F.degree()} this functions returns the
  \MATH{j}-th conjugate of the \MATH{i}-th element of the basis
  representing \MATH{F}. If \MATH{i} or \MATH{j} are not within the
  indicated bounds, the \TT{lidia\_error\_handler} will be invoked. Note
  that the order of the conjugates is randomly determined, but once it is
  determined, it remains fixed. The first \TT{F.no\_of\_real\_embeddings()}
  conjugates always correspond to the real embeddings of \MATH{F}.}

\cfcode{const math\_matrix\TEMPL{bigfloat} \&}{F.get\_conjugates}{}{
  returns a reference to the matrix that is used internally to store the
  conjugates. The \MATH{i}-th column of the matrix contains the conjugates
  of the \MATH{i}-th element of the basis representing \MATH{F}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\IO \label{order_io}
\BF{istream} operator \TT{>>} and \BF{ostream} operator \TT{<<} are
overloaded. We support four formats for the input of a \BF{number\_field}:
\begin{itemize}
\item You may input the generating polynomial of the \BF{number\_field};
  however -- due to the limitations of the class \BF{istream} -- only the
  verbose format for polynomials is supported and the polynomial has to
  start with the variable, e.g.
  \begin{center}
    \MATH{x^n + \cdots + a_1 x + a_0}
  \end{center}
  This represents the field \MATH{\Q[b]} where \MATH{b} is a root of the
  given polynomial, which must be monic and irreducible. The powers
  \MATH{\{1, b, b^2, \dots, b^{n-1}\}} of \MATH{b} will be used as the
  basis of the \BF{number\_field}.

\item You may give a pair of a (monic and irreducible) generating
  polynomial \MATH{f} and a transformation matrix \MATH{T} in the form
  \begin{center}
    \MATH{(f\SQCUP T)}.
  \end{center}
  Any format supported by \BF{polynomial\TEMPL{bigint}} may be used to give
  the polynomial. Since any matrix over the rationals would be an
  acceptable transformation matrix we use a \BF{bigint\_matrix} (supporting
  any format supported by \BF{bigint\_matrix}) that is optionally followed
  by a common denominator in the form ``\MATH{/ d}'' to give the
  transformation matrix.

  This also represents the field generated by the given polynomial, however
  in contrast to the previous format \MATH{\{1, b, b^2, \dots,
    b^{n-1}\}\CDOT T} will be used as the basis of the \BF{number\_field}.

\item You may only input a transformation matrix. This will be interpreted
  as a transformation with respect to the current \BF{nf\_base}. This is
  the base of the \BF{number\_field} or the \BF{order} that was constructed
  or read the last before invoking this operator. If there is no current
  \BF{nf\_base}, the \TT{lidia\_error\_handler} will be invoked. Any format
  supported by \BF{bigint\_matrix} optionally followed by a common
  denominator in the form ``\MATH{/ d}'' can be used to give this
  transformation matrix.

\item Finally, you may input a multiplication table, describing the basis
  of the \BF{number\_field}: A basis \MATH{\{w_1,\dots, w_n\}} is uniquely
  determined by constants \MATH{MT(i,j,k)} with
\latex{
\[ w_i \cdot w_j=\sum_{k=1}^{n}MT(i,j,k)w_k.\] 

}
\html{\begin{verbatim}
               n
             -----
             \
 w_i w_j  =   )      MT(i,j,k) w_k .
             /
             -----
             k = 1

        \end{verbatim}}

Since the multiplication table
\latex{
\begin{center}
\[\begin{array}{ccccc}
(& (MT(1,1,1),\dots,MT(1,1,n)) & \ldots & (MT(1,n,1),\dots,MT(1,n,n))&)\\ 
(& \vdots & \vdots & \vdots &)\\
(& (MT(n,1,1),\dots,MT(n,1,n)) & \ldots & (MT(n,n,1),\dots,MT(n,n,n))&)\\ 
\end{array}\],
\end{center}
}
\html{\begin{verbatim}
 ( (MT(1,1,1),...,MT(1,1,n)) ..... (MT(1,n,1),...,MT(1,n,n)) )
 (      :             :                 :             :      )
 ( (MT(n,1,1),...,MT(n,1,n)) ..... (MT(n,n,1),...,MT(n,n,n)) )
\end{verbatim}}
  is symmetric, we represent such a table by its lower left part, i.e.~by the
  following \BF{bigint\_matrix} 
\latex{
\begin{center}
\[\begin{array}{ccccc}
(& MT(1,1,1) & \ldots & MT(1,1,n)&)\\ 
(& MT(2,1,1) & \ldots & MT(2,1,n)&)\\ 
(& MT(2,2,1) & \ldots & MT(2,2,n)&)\\ 
(& \vdots & \vdots & \vdots &)\\
(& MT(i,1,1) & \ldots & MT(i,1,n)&)\\ 
(& \vdots & \vdots & \vdots &)\\
(& MT(i,i,1) & \ldots & MT(i,i,n)&)\\ 
(& MT(i+1,1,1) & \ldots & MT(i+1,1,n)&)\\ 
(& \vdots & \vdots & \vdots &)\\
(& MT(i+1,i+1,1) & \ldots & MT(i+1,i+1,n)&)\\
(& \vdots & \vdots & \vdots &)\\
(& MT(n,1,1) & \ldots & MT(n,1,n)&)\\ 
(& \vdots & \vdots & \vdots &)\\
(& MT(n,n,1) & \ldots & MT(n,n,n)&)\\ 
\end{array}\]
\end{center}
}
\html{\begin{verbatim}
 (   MT(1,1,1)   ...   MT(1,1,n)  )
 (   MT(2,1,1)   ...   MT(2,1,n)  )
 (   MT(2,2,1)   ...   MT(2,2,n)  )
 (       :                 :      )
 (   MT(i,1,1)   ...   MT(i,1,n)  )
 (       :                 :      )
 (   MT(i,i,1)   ...   MT(i,i,n)  )
 (  MT(i+1,1,1)  ...  MT(i+1,1,n) )
 (       :                 :      )
 ( MT(i+1,i+1,1) ... MT(i+1,i+1,n))
 (       :                 :      )
 (   MT(n,1,1)   ...   MT(n,1,n)  )
 (       :       ...       :      )
 (   MT(n,n,1)   ...   MT(n,n,n)  )
\end{verbatim}}
  As for the previous formats, any format supported by \BF{bigint\_matrix}
  can be used.
\end{itemize}

The output of a \BF{number\_field} always uses either the first or the
second format, depending on whether a transformation matrix is necessary to
describe the base of the \BF{number\_field} or not.

Note that you have to manage by yourself that successive
\BF{order}s may have to be separated by blanks, depending on what
format you are using for reading and writing matrices.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\NOTES
Due to the automatic casts to and from \BF{nf\_base *} there should be no
need to use this (undocumented) internal class, although -- for the sake of
completeness -- it has been mentioned several times.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SEEALSO
\BF{order}, \BF{polynomial\TEMPL{bigint}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\EXAMPLES
see the documentation of ``\BF{order}'' for an example.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\AUTHOR
Stefan Neis

\end{lidia_man}
