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

\begin{lidia_man}
\markright{\BF{order}}

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

\NAME
\BF{order} \dotfill orders in algebraic number fields.

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

\ABSTRACT
\BF{order} is a class for representing orders of algebraic
number fields and for computing elementary invariants like the
discriminant and for maximizing the order at a given prime.

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

\DESCRIPTION \label{order_description}

An \BF{order}, exactly like a \BF{number\_field}, consists of its
\MATH{\Z}--basis. This basis is stored using the internal class \BF{nf\_base}.

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

\CONS
\fcode{ct}{order}{const nf\_base * base1 = nf\_base::current\_base}
{
  initializes with the base represented by \TT{base1}. If no pointer to an
  \BF{nf\_base} is given, the current base is used, which is the base of
  the \BF{number\_field} or the \BF{order} that was 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 order.}

\fcode{ct}{order}{const polynomial\TEMPL{bigint} \&p\k const
  base\_matrix\TEMPL{bigint} \& T = bigint\_matrix()\k const bigint \& d = 1}{
  if the second and third argument are omitted, this constructor
  initializes an order with the equation order of the polynomial
  \MATH{p}. If this polynomial is not irreducible or not monic, this
  results in undefined behaviour. If \MATH{T} and \MATH{d} are given also,
  this constructs an order with basis 
  \MATH{(1,x,\dots,x^\TT{p.degree()})\cdot T\cdot 1/d}.}

\fcode{ct}{order}{const bigint\_matrix \& A}
{
initializes with the given matrix \MATH{A} as multiplication table.
\MATH{A} must be in the format described in the section Input/Output of the
documentation for class \BF{number\_field} (see page \pageref{order_io}) .}

\fcode{ct}{order}{const bigint\_matrix \& A\k const bigint \& d\k nf\_base
  * base = nf\_base::current\_base}{
initializes with the order generated by the columns of
\MATH{\FRAC{1}{d} \CDOT B \CDOT A},
where \MATH{B} is the base pointed to by \TT{base}. Note that due to the
automatic casts you may also use an \BF{order} or a \BF{number\_field} as
third argument. If no third argument is given, the current base is used,
which is the base of the \BF{number\_field} or the \BF{order} that was
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}{order}{const number\_field \& F}
{
initializes with the maximal \BF{order} of the \BF{number\_field} \MATH{F}.}

\fcode{ct}{order}{const order \& O}
{
initializes with a copy of the order \MATH{O}.}

\fcode{dt}{{\MATH{\sim}order}}{}{}

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

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


\fcode{void}{O.assign}{const order \& Q}
{
\MATH{O = Q}.}

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

\ACCS
Let \MATH{O} be an order in \MATH{\Z[X] / (p)} for a polynomial \MATH{p}
and let 
\latex{
\[(w_1,\dots,w_n):=\frac{1}{d}(1,x,\dots,x^{n-1})\cdot T \]
}\html{
(w_1,...,w_n):= 1/d (1,x,\dots,x^{n-1}) T
}
be the basis of \MATH{O}, where \MATH{d} is a \BF{bigint} and \MATH{T} is a
\BF{bigint\_matrix}. Then \MATH{MT} 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}}
is the multiplication table of the order.

\cfcode{const bigint \&}{O.MT}{long i\k long j\k long k}
{
returns \MATH{MT(i,j,k)}.}

\cfcode{const bigint\_matrix \&}{O.base\_numerator}{}
{
returns the \BF{bigint\_matrix} \MATH{T} described above, if \MATH{T} has
been computed. Otherwise it returns a \MATH{1}\TIMES\MATH{1}--matrix
containing \MATH{0}.}

\fcode{const bigint\_matrix \&}{base\_numerator}{const order \& O}
{
returns the \BF{bigint\_matrix} \MATH{T} described above, if \MATH{T} has
been computed. Otherwise it returns a \MATH{1}\TIMES\MATH{1}--matrix
containing \MATH{0}.}

\cfcode{const bigint \&}{O.base\_denominator}{}
{
returns the \BF{bigint} \MATH{d} described above, if \MATH{T} has been
computed. Otherwise it returns \MATH{1}.}

\fcode{const bigint \& }{base\_denominator}{const order \& O}
{
returns the \BF{bigint} \MATH{d} described above, if \MATH{T} has been
computed. Otherwise it returns \MATH{1}.}

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

\fcode{nf\_base *}{which\_base}{const order \& O}
{
returns the pointer to the \BF{nf\_base} used to describe \MATH{O}.}

\cfcode{const polynomial\TEMPL{bigint} \&}{O.which\_polynomial}{}{
returns the polynomial \MATH{p} described above.}

\fcode{const polynomial\TEMPL{bigint} \&}{which\_polynomial}{const order \& O}{
returns the polynomial \MATH{p} described above.}

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

\COMP 
The binary operators \TT{==}, \TT{!=}, \TT{<=}, \TT{<} (true subset),
\TT{>=}, and \TT{>} are overloaded and can be used in exactly the
same way as in the programming language C if the orders to be
compared happen to be represented using the same polynomial. If this is not
the case the \TT{lidia\_error\_handler} will be invoked.

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

\BASIC
Let \MATH{O} be an instance of type \BF{order}.\vspace*{1ex}


\cfcode{long}{O.degree}{}
{
returns the rank of \MATH{O} as module over \MATH{\Z}.}

\fcode{long}{degree}{const order \& O}
{
returns the rank of \MATH{O} as module over \MATH{\Z}.}

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

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

\fcode{void}{swap}{order \& O\k order \& Q}
{
swaps \MATH{O} and \MATH{Q}.}

\cfcode{operator}{ideal}{}
{
cast operator, which implicitly converts an \BF{order} to an
\BF{ideal} over this \BF{order}.}



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

\HIGH
Let \MATH{O} be an instance of type \BF{order}.\vspace*{1ex}

\cfcode{const bigfloat \&}{O.get\_conjugate}{lidia\_size\_t i\k
  lidia\_size\_t j}{
  for \MATH{0}\LEQ\MATH{i}\LT\TT{O.degree()} and
  \MATH{0}\LT\MATH{j}\LEQ\TT{O.degree()} this functions returns the
  \MATH{j}-th conjugate of the \MATH{i}-th element of the basis
  representing \MATH{O}. 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{O.no\_of\_real\_embeddings()}
  conjugates always correspond to the real embeddings of \MATH{O}.}

\cfcode{const math\_matrix\TEMPL{bigfloat} \&}{O.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{O}.}

\cfcode{const math\_vector\TEMPL{bigint} \&}{O.get\_one}{}
{
returns the representation of the rational number \MATH{1} in \MATH{O}.}

%\cfcode{bigint\_matrix}{O.get\_trace\_matrix}{}
%{
%returns the matrix of the traces of \MATH{w_i \CDOT w_j},
%\MATH{1}\LE\MATH{i,j}\LE\MATH{n}, i.e.~\MATH{({\rm Tr}(w_i \CDOT
%w_j))_{i,j}}.} 

\fcode{bigint}{disc}{const order \& O}
{
returns the discriminant of \MATH{O}.}

\cfcode{module}{O.pseudo\_radical}{const bigint \& p}
{
returns the \MATH{p}-radical, if \MATH{p} is a prime
number. Otherwise, this routine returns the so-called pseudo-radical
(see~\cite{BuLe}).}

\cfcode{int}{O.dedekind}{const bigint \&p, polynomial\TEMPL{bigint} \& h}
{
returns \MATH{1}, if \MATH{p} is an index divisor of the equation
order of the polynomial used to describe the base of \MATH{O}. In this case
\MATH{h(x)} and \MATH{p} generate the \MATH{p}-radical, where \MATH{x} is a
root of the generating polynomial of the field. If \MATH{p} is not a prime
number the behaviour of this function is undefined.} 

\cfcode{order}{O.maximize}{const bigint \&m}
{
returns an order which is maximized at all primes which divide \MATH{m} but
whose squares don't divide \MATH{m}.}

\cfcode{order}{O.maximize}{}
{
returns the maximal order containing \MATH{O}. Since this involves
factoring the discriminant of the order, this might take a fairly long time.}
%which is maximized at all primes with less than 6
%digits and at all factors of the discriminant with at most \MATH{10}
%digits, that where found by ECM (see \BF{rational\_factorization}, page
%\pageref{rational_fact_class}).}

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

\IO
\BF{istream} operator \TT{>>} and \BF{ostream} operator \TT{<<} are
overloaded. Input and output of an \BF{order} support exactly the same
formats as input and output of a \BF{number\_field}, so see the description
of \BF{number\_field} for the (lengthy) description of these formats (page \pageref{order_io}).

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

\WARNINGS

Some of the functions and arguments described as const in this
documentation are only const, if your compiler supports the new
ANSI--keyword ``\BF{mutable}''. Otherwise you might get some warnings while
compiling your own programs. For more detailed information which functions
are concerned have a look at \TT{LiDIA/alg\_number.h} and look for the
\TT{NO\_MUTABLE} -- ifdefs.

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

\SEEALSO
\BF{bigint}, \BF{base\_vector}, \BF{module}, \BF{alg\_number},
\BF{polynomial\TEMPL{bigint}}

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

\EXAMPLES

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

int main()
{

  order O;                             // a dummy order
  number_field F;                      // a dummy field
  cin >> O;                            // Now the base of O is current_base
  alg_number a = bigint(1);
  cout << O;
  O = O.maximize();                    // Now the current_base is the base
                                       // of the maximal order!

  for (long zaehl=1;zaehl<=2;zaehl++){
    alg_number one = bigint(1);
    cout << "one = " << one << endl;
    cout << "one + 1 = " << (one + 1) << endl;

    alg_number two = bigint(2);
    cout << "two = " << two << "\n";

    if(zaehl !=2){
      cin >> F;                       // now the base of F is the current_base
      O.assign(order(F));             // O is the maximal order of F;
      // The numbers used in the next iteration will be numbers in order(F)!!
    }
    else cout<<endl;
  }
  return 0;
}
\end{verbatim}

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

\AUTHOR
Stefan Neis
\end{lidia_man}
