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

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

\NAME

\CLASS{prime_ideal} \dotfill prime ideals in algebraic number fields

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

\ABSTRACT

\code{prime_ideal} is a class for representing prime ideals in algebraic number fields.  Since
each prime ideal obviously is an ideal, you can do everything you can do with an
\code{alg_ideal} also with a \code{prime_ideal}.  This is realised by a cast operator, which
implicitly converts a \code{prime_ideal} to an \code{alg_ideal}.  Note especially, that
operations on \code{prime_ideal}s always have an \code{alg_ideal} as result.

However this class offers some additional functionality which either makes no sense for a
general \code{alg_ideal} or would be of much less interest in the general case.


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

\DESCRIPTION

A \code{prime_ideal} consists of a prime $p$ (represented by a \code{bigint}) and an
\code{alg_number} $a$ which especially contains the pointer to an \code{nf_base} $B$, such that
$B$ is the basis of the \code{order} $O$ over which the prime ideal is defined and that $p$ and
$a$ generate the prime ideal as $O$-ideal.  Additionaly the \code{lidia_size_t}s $e$ and $f$
contain the ramification index and the degree of inertia of the prime ideal, respectively.  An
additional \code{alg_number} contains information needed to compute valuations.


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

\CONS

\begin{fcode}{ct}{prime_ideal}{}
  constructs a dummy prime ideal initialized with useless values.  Don't try to do any
  computation with such a prime ideal!
\end{fcode}

\begin{fcode}{ct}{prime_ideal}{const bigint & $p$, const alg_number & $a$,
    lidia_size_t $e$ = 0, lidia_size_t $f$ = 0}%
  initializes with the prime ideal generated by the prime $p$ and the algebraic number $a$.  If
  $e$ and $f$ are not given, their values are computed.  If incorrect data is given to this
  constructor (e.g. if $p$ and $a$ do not generate a prime ideal or if the values given for $e$
  and $f$ are wrong), this will result in unpredictable behaviour.
\end{fcode}

\begin{fcode}{ct}{prime_ideal}{const bigint & $p$, const nf_base * $\Or$ = nf_base::current_base}
  initializes with a prime $p$ that is inert over the order generated by the \code{nf_base}
  pointed to by $\Or$.  If $p$ is not an inert prime, this will result in unpredictable behaviour.
\end{fcode}

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


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

\ACCS

Let $P$ be of type \code{prime_ideal} with $P = (p, a, \Or)$.

\begin{cfcode}{const bigint &}{$P$.first_generator}{}
  returns the prime $p$ of the description of $P$.
\end{cfcode}

\begin{cfcode}{const alg_number &}{$P$.second_generator}{}
  returns the algebraic number $a$ of the description of $P$.
\end{cfcode}

\begin{cfcode}{lidia_size_t}{$P$.ramification_index}{}
  returns the ramification index of the prime ideal $P$.
\end{cfcode}

\begin{cfcode}{lidia_size_t}{$P$.degree_of_inertia}{}
  returns the degree of inertia of the prime ideal $P$.
\end{cfcode}

\begin{cfcode}{const bigint &}{$P$.base_prime}{}
  returns the prime $p$ which is divided by $P$, i.e. the function returns the first generator.
\end{cfcode}


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

\BASIC

\begin{cfcode}{operator}{alg_ideal}{}
  cast operator, which implicitly converts a \code{prime_ideal} to an \code{alg_ideal} over the
  same \code{order}.
\end{cfcode}

\begin{fcode}{void}{swap}{prime_ideal & $a$, prime_ideal & $b$}
  exchanges the values of $a$ and $b$.
\end{fcode}


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

\HIGH

\begin{fcode}{long}{ord}{const prime_ideal & $P$, const alg_ideal & $M$}
  returns $\ord_P(M)$, i.e. the maximal power of $P$ which divides $M$.
\end{fcode}

\begin{fcode}{long}{ord}{const prime_ideal & $P$, const alg_number & $a$}
  returns $\ord_P(a)$, i.e. the maximal power of $P$ which divides the principal ideal generated
  by $a$.
\end{fcode}


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

\IO

\code{istream} operator \code{>>} and \code{ostream} operator \code{<<} are overloaded.  Input
and output of a \code{prime_ideal} have the following format: $< p, a >,$ where $p$ and $a$ are
the generators of the prime ideal.  In this representation $p$ is a \code{bigint} and $a$ is an
\code{alg_number}.  If $a$ is $0$, output will be simplified to the format $< p >$.


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

\WARNINGS

Due to a last minute redesign, this class lacks several functions that it should have for
compatibility with the class \code{alg_ideal}.  This will be fixed in the next version.


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

\SEEALSO

\SEE{alg_number}, \SEE{alg_ideal}, \SEE{order}


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

\AUTHOR

Stefan Neis
