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

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

\NAME

\CLASS{number_field} \dotfill algebraic number fields.


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

\ABSTRACT

\code{number_field} is a class for representing algebraic number fields $\bbfQ(b)$, where $b$ is
a root of a monic irreducible polynomial with coefficients in the rational integers.


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

\DESCRIPTION

A \code{number_field} consists of a $\bbfZ$-basis of an algebraic number field.  This basis is
stored using the internal class \code{nf_base}.


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

\CONS

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

\begin{fcode}{ct}{number_field}{const polynomial< bigint > &}
  initializes with the given polynomial.  If the given polynomial is not irreducible or not
  monic, this results in undefined behaviour.
\end{fcode}

\begin{fcode}{ct}{number_field}{const bigint * $v$, lidia_size_t $\mathit{deg}$}
  initializes the field by the number field $\bbfQ(b)$, where $b$ is a root of
  \begin{displaymath}
    \sum_{i=0}^{\mathit{deg}} v[i]x^i \enspace.
  \end{displaymath}
% If this polynomial is not irreducible or not monic, the
% \LEH will be invoked.
  If this polynomial is not irreducible or not monic, this results in undefined behaviour.
\end{fcode}

\begin{fcode}{ct}{number_field}{const order & $\Or$}
  initializes with the quotient field of the order $\Or$.
\end{fcode}

\begin{fcode}{ct}{number_field}{const number_field & $F$}
  initializes with a copy of the field $F$.
\end{fcode}

\begin{fcode}{dt}{{~number_field}}{}
\end{fcode}


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

\ASGN

Let $F$ be of type \code{number_field}.  The operator \code{=} is overloaded.  For consistency
reasons, the following function is also implemented:

\begin{fcode}{void}{$F$.assign}{const number_field & $K$}
  $F \assign K$.
\end{fcode}


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

\ACCS

\begin{cfcode}{nf_base *}{$F$.which_base}{}
  returns the pointer to the \code{nf_base} used to describe $F$.
\end{cfcode}

\begin{fcode}{nf_base *}{which_base}{const number_field & $F$}
  returns the pointer to the \code{nf_base} used to describe $F$.
\end{fcode}

\begin{cfcode}{const polynomial< bigint > &}{$F$.which_polynomial}{}
  returns the generating polynomial of $F$.
\end{cfcode}

\begin{fcode}{const polynomial< bigint > &}{which_polynomial}{const number_field & $F$}
  returns the generating polynomial of $F$.
\end{fcode}


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

\BASIC

Let $F$ be an instance of type \code{number_field}.

\begin{cfcode}{lidia_size_t}{$F$.degree}{}
  returns the degree of the field $F$ over $\bbfQ$.
\end{cfcode}

\begin{fcode}{lidia_size_t}{degree}{const number_field & $F$}
  returns the degree of the field $F$ over $\bbfQ$.
\end{fcode}

\begin{cfcode}{operator}{nf_base *}{}
  cast operator which implicitly converts a \code{number_field} to a pointer to the
  representation of its base.
\end{cfcode}

\begin{cfcode}{lidia_size_t}{$F$.no_of_real_embeddings}{}
  returns the number of embeddings of the field $F$ into $\bbfR$.
\end{cfcode}

\begin{fcode}{lidia_size_t}{no_of_real_embeddings}{const number_field & $F$}
  returns the number of embeddings of the field $F$ into $\bbfR$.
\end{fcode}


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

\HIGH

Let $F$ be an instance of type \code{number_field}.

\begin{cfcode}{const bigfloat &}{$F$.get_conjugate}{lidia_size_t $i$, lidia_size_t $j$}
  for $0 \leq i < \deg(F)$ and $0 < j \leq \deg(F)$ this functions returns the $j$-th conjugate
  of the $i$-th element of the basis representing $F$.  If $i$ or $j$ are not within the
  indicated bounds, the \LEH will be invoked.  Note that the order of the conjugates is randomly
  determined, but once it is determined, it remains fixed.  The first
  \code{$F$.no_of_real_embeddings()} conjugates always correspond to the real embeddings of $F$.
\end{cfcode}

\begin{cfcode}{const math_matrix< bigfloat > &}{$F$.get_conjugates}{}
  returns a reference to the matrix that is used internally to store the conjugates.  The $i$-th
  column of the matrix contains the conjugates of the $i$-th element of the basis representing
  $F$.
\end{cfcode}


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

\IO \label{order_io}

\code{istream} operator \code{>>} and \code{ostream} operator \code{<<} are overloaded.  We
support four formats for the input of a \code{number_field}:
\begin{itemize}
\item You may input the generating polynomial of the \code{number_field}; however ---- due to
  the limitations of the class \code{istream} --- only the verbose format for polynomials is
  supported and the polynomial has to start with the variable, e.g.
  \begin{displaymath}
    x^n + \dots + a_1 x + a_0 \enspace.
  \end{displaymath}
  This represents the field $\bbfQ[b]$ where $b$ is a root of the given polynomial, which must
  be monic and irreducible.  The powers $\{1, b, b^2, \dots, b^{n-1}\}$ of $b$ will be used as
  the basis of the \code{number_field}.
  
\item You may give a pair of a (monic and irreducible) generating polynomial $f$ and a
  transformation matrix $T$ in the form
  \begin{displaymath}
    (f \sqcup T) \enspace.
  \end{displaymath}
  Any format supported by \code{polynomial< bigint >} may be used to give the polynomial.  Since
  any matrix over the rationals would be an acceptable transformation matrix we use a
  \code{bigint_matrix} (supporting any format supported by \code{bigint_matrix}) that is
  optionally followed by a common denominator in the form ``$/ d$'' to give the transformation
  matrix.
  
  This also represents the field generated by the given polynomial, however in contrast to the
  previous format $\{ 1, b, b^2, \dots, b^{n-1} \} \cdot T$ will be used as the basis of the
  \code{number_field}.
  
\item You may only input a transformation matrix.  This will be interpreted as a transformation
  with respect to the current \code{nf_base}.  This is the base of the \code{number_field} or
  the \code{order} that was constructed or read the last before invoking this operator.  If
  there is no current \code{nf_base}, the \LEH will be invoked.  Any format supported by
  \code{bigint_matrix} optionally followed by a common denominator in the form ``$/ d$'' can be
  used to give this transformation matrix.
  
\item Finally, you may input a multiplication table, describing the basis of the
  \code{number_field}: A basis $\{ w_1, \dots, w_n \}$ is uniquely determined by constants
  $MT(i,j,k)$ with
  \begin{displaymath}
    w_i \cdot w_j=\sum_{k=1}^{n} MT(i,j,k) w_k \enspace.
  \end{displaymath}
  Since the multiplication table
  \begin{displaymath}
    \begin{array}{ccccc}
      (& (MT(1,1,1),\dots,MT(1,1,n)) & \dots & (MT(1,n,1),\dots,MT(1,n,n))&)\\
      (& \vdots & \vdots & \vdots &)\\
      (& (MT(n,1,1),\dots,MT(n,1,n)) & \dots & (MT(n,n,1),\dots,MT(n,n,n))&)\\
    \end{array}\enspace,
  \end{displaymath}
  is symmetric, we represent such a table by its lower left part, i.e.~by the following
  \code{bigint_matrix}
  \begin{displaymath}
    \begin{array}{ccccc}
      (& MT(1,1,1) & \dots & MT(1,1,n)&)\\
      (& MT(2,1,1) & \dots & MT(2,1,n)&)\\
      (& MT(2,2,1) & \dots & MT(2,2,n)&)\\
      (& \vdots & \vdots & \vdots &)\\
      (& MT(i,1,1) & \dots & MT(i,1,n)&)\\
      (& \vdots & \vdots & \vdots &)\\
      (& MT(i,i,1) & \dots & MT(i,i,n)&)\\
      (& MT(i+1,1,1) & \dots & MT(i+1,1,n)&)\\
      (& \vdots & \vdots & \vdots &)\\
      (& MT(i+1,i+1,1) & \dots & MT(i+1,i+1,n)&)\\
      (& \vdots & \vdots & \vdots &)\\
      (& MT(n,1,1) & \dots & MT(n,1,n)&)\\
      (& \vdots & \vdots & \vdots &)\\
      (& MT(n,n,1) & \dots & MT(n,n,n)&)\\
    \end{array}\enspace.
  \end{displaymath}
  As for the previous formats, any format supported by \code{bigint_matrix} can be used.
\end{itemize}

The output of a \code{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 \code{number_field}
or not.

Note that you have to manage by yourself that successive \code{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 \code{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

\SEE{order}, \SEE{polynomial< bigint >}


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

\EXAMPLES

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


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

\AUTHOR

Stefan Neis
