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

\begin{lidia_man}
\markright{\BF{alg\_number}}

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

\NAME
\BF{alg\_number} \DOTFILL arithmetic for algebraic numbers

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

\ABSTRACT
\BF{alg\_number} is a class  for doing multiprecision arithmetic
for algebraic numbers. It supports for example arithmetic operations,
comparisons, and computations of norm and trace.

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

\DESCRIPTION
An \BF{alg\_number} consists of a triple \MATH{(num, den, O)},
where the nu\-me\-ra\-tor \\ \MATH{num=(num_0, \dots, num_{n-1})} is a
\BF{math\_vector\TEMPL{bigint}} of length \MATH{n}, the  denominator
\MATH{den} is a \BF{bigint}, and \MATH{O} is a pointer to the
\BF{nf\_base}, that is used to represent the number. The
\BF{alg\_number} \MATH{(num, den, O)} represents the algebraic
number
\latex{
\[ \FRAC{1}{den}\sum_{i=0}^{n-1}num_iw_i, \]
}
\html{\begin{verbatim}
 n - 1
 -----
 \
  )      num_i  w_i ,
 /
 -----
 i = 0

      \end{verbatim}}
where \MATH{w_i} are the base elements described by the \BF{nf\_base}
pointed to by \MATH{O}. The components of the numerator \MATH{num} and the
denominator \MATH{den} of an \BF{alg\_number} are always coprime,
the denominator \MATH{den} is positive.

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

\CONS
In the following constructors there is an optional pointer to an
\BF{nf\_base}. Instead of this pointer, a \BF{number\_field} or an
\BF{order} may be given, since there are suitable automatic casts.
If however, this argument is completely omitted, the number is generated
with respect to \TT{nf\_base::current\_base}, which is the base of the
\BF{number\_field} or \BF{order} that was constructed or read last. If no
\BF{number\_field} or \BF{order} has been constructed or read so far, this
defaults to a dummy base. Computations with algebraic numbers over this
dummy base will lead to unpredictable results or errors, if you do not
assign meaningful values to such algebraic numbers before using them.

\fcode{ct}{alg\_number}{nf\_base * O = nf\_base::current\_base}
{
initializes with zero with respect to the given base.
}

\fcode{ct}{alg\_number}{const bigint \&\k nf\_base * O1 = nf\_base::current\_base}
{
lifts the given bigint algebraic number field described by the given nf\_base.
}

\fcode{ct}{alg\_number}{const base\_vector\TEMPL{bigint} \& v\k const bigint \& d=1\k nf\_base * O1 = nf\_base::current\_base}
{
initializes with the algebraic number \FRAC{1}{d}\SUM{i=0}{n-1}{v[i]w_i}
if \MATH{v} has exactly \MATH{n} components. Otherwise the 
\TT{lidia\_error\_handler} will be invoked.
}

\fcode{ct}{alg\_number}{const bigint * \& v\k const bigint \& d=1\k nf\_base * O1 = nf\_base::current\_base}
{
initializes with the algebraic number \FRAC{1}{d}\SUM{i=0}{n-1}{v[i]w_i}. 
The behaviour of this constructor is undefined if the array \MATH{v} 
has less than \MATH{n} components.
}

\fcode{ct}{alg\_number}{const alg\_number \& a}
{
initializes with a copy of the algebraic number \MATH{a}.
}

\fcode{dt}{{\SIM alg\_number}}{}{}

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

\ASGN
Let \MATH{a} be of type \BF{alg\_number}.  The operator \TT{=} is
overloaded. For efficiency reasons, the following functions are also
implemented:\vspace*{1ex}

\fcode{void}{a.assign\_zero}{}
{
\MATH{a = 0}. Note that this embedds zero into the number field which
\MATH{a} is a member of.
}

\fcode{void}{a.assign\_one}{}
{
\MATH{a = 1}. Note that this embedds one into the number field which
\MATH{a} is a member of.
}

\fcode{void}{a.assign}{const bigint \& b}
{
\MATH{a = b}. Note that this embedds \MATH{b} into the number field which
\MATH{a} is a member of.
}

\fcode{void}{a.assign}{const alg\_number \& b}
{
\MATH{a = b}.
}

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

\ACCS
Let \MATH{a} be of type \BF{alg\_number} with \MATH{a = (num, den, O)}.

\cfcode{const math\_vector\TEMPL{bigint} \&}{a.coeff\_vector}{}
{
returns the coefficient vector \MATH{num} of \MATH{a}.
}

\fcode{const math\_vector\TEMPL{bigint} \&}{coeff\_vector}{const alg\_number \& a}
{
returns the coefficient vector \MATH{num} of \MATH{a}.
}

\cfcode{alg\_number}{a.numerator}{}
{
returns the \BF{alg\_number} \MATH{(num, 1, O)}.
}

\fcode{alg\_number}{numerator}{const alg\_number \& a}
{
returns the \BF{alg\_number} \MATH{(num, 1, O)}.
}

\cfcode{const bigint \&}{a.denominator}{}
{
returns the denominator \MATH{den} of \MATH{a}.
}

\fcode{const bigint \&}{denominator}{const alg\_number \& a}
{
returns the denominator \MATH{den} of \MATH{a}.
}

\cfcode{nf\_base *}{a.which\_base}{}
{
returns the pointer \MATH{O}.
}

\fcode{nf\_base *}{which\_base}{const alg\_number \& a}
{
returns the pointer \MATH{O}.
}

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

\ARTH
The following operators are overloaded and can be used in exactly 
the same way as in the programming language C. If you use the binary 
operators on two algebraic numbers \MATH{a} and \MATH{b}, this is 
only successful if \TT{a.which\_order() = b.which\_order()}, 
otherwise the \TT{lidia\_error\_handler} will be invoked.

\begin{tabular}{|c|rcl|l|}\hline
unary & & \MATH{op} & alg\_number & \MATH{op\IN\{\TT{-}\}} \\\hline
binary & alg\_number & \MATH{op} & alg\_number 
& \MATH{op\IN\{\TT{+},\TT{-},\TT{*},\TT{/}\}}\\\hline
binary with & alg\_number & \MATH{op} & alg\_number
& \MATH{op\IN\{\TT{+=},\TT{-=},\TT{*=},\TT{/=}\}}\\
assignment & & & &\\\hline
binary & alg\_number & \MATH{op} & bigint
& \MATH{op \IN\{\TT{+},\TT{-},\TT{*},\TT{/}\}}\\\hline
binary & bigint & \MATH{op} & alg\_number
& \MATH{op \IN\{\TT{+},\TT{-},\TT{*},\TT{/}\}}\\\hline
binary with & alg\_number & \MATH{op} & bigint
& \MATH{op \IN\{\TT{+=},\TT{-=},\TT{*=},\TT{/=}\}}\\
assignment & & & &\\\hline
\end{tabular}

To avoid copying all operators also exist as functions.\vspace*{1ex}

\fcode{void}{add}{alg\_number \& c\k const alg\_number \& a\k const alg\_number \& b}
{
\MATH{c = a + b} if \MATH{a} and \MATH{b} are members of the same
order. Otherwise the \TT{lidia\_error\_handler}
will be invoked.
}

\fcode{void}{add}{alg\_number \& c\k const alg\_number \& a\k const bigint \& i}
{
\MATH{c = a + i}.
}

\fcode{void}{add}{alg\_number \& c\k const bigint \& i\k const alg\_number \& b}
{
\MATH{c = i + b}.
}

\fcode{void}{subtract}{alg\_number \& c\k const alg\_number \& a\k const alg\_number \& b}
{
\MATH{c = a - b} if \MATH{a} and \MATH{b} are members of the same
order. Otherwise the \TT{lidia\_error\_handler} will be invoked.
}

\fcode{void}{subtract}{alg\_number \& c\k const alg\_number \& a\k const bigint \& i}
{
\MATH{c = a - i}.
}

\fcode{void}{subtract}{alg\_number \& c\k const bigint \& i\k const alg\_number \& b}
{
\MATH{c = i - b}.
}

\fcode{void}{multiply}{alg\_number \& c\k const alg\_number \& a\k const alg\_number \& b}
{
\MATH{c = a * b} if \MATH{a} and \MATH{b} are members of the same
order. Otherwise the \TT{lidia\_error\_handler} will be invoked.
}

\fcode{void}{multiply}{alg\_number \& c\k const alg\_number \& a\k const bigint \& i}
{
\MATH{c = a * i}.
}

\fcode{void}{multiply}{alg\_number \& c\k const bigint \& i\k const alg\_number \& b}
{
\MATH{c = i * b}.
}

\fcode{void}{divide}{alg\_number \& c\k const alg\_number \& a\k const alg\_number \& b}
{
\MATH{c = a / b} if \MATH{b \NEQ 0} and if \MATH{a} and \MATH{b} 
are members of the same order. Otherwise the \TT{lidia\_error\_handler} 
will be invoked.
}

\fcode{void}{divide}{alg\_number \& c\k const alg\_number \& a\k const bigint \& i}
{
\MATH{c = a / i} if \MATH{i \NEQ 0}. Otherwise the 
\TT{lidia\_error\_handler} will be invoked.
}

\fcode{void}{divide}{alg\_number \& c\k const bigint \& i\k const alg\_number \& b}
{
\MATH{c = i / b} if \MATH{b \NEQ 0}. Otherwise the 
\TT{lidia\_error\_handler} will be invoked.
}

\fcode{void}{a.negate}{}
{
\MATH{a = -a}.
}

\fcode{void}{negate}{alg\_number \& a\k const alg\_number \& b}
{
\MATH{a = -b}.
}

\fcode{void}{a.multiply\_by\_2}{}
{
\MATH{a = 2 * a} (done by shifting).
}

\fcode{void}{a.divide\_by\_2}{}
{
\MATH{a = a / 2} (done by shifting).
}

\fcode{void}{a.invert}{}
{
\MATH{a = 1 / a} if \MATH{a \NEQ 0}. Otherwise the
\TT{lidia\_error\_handler} will be invoked.
}

\fcode{void}{invert}{alg\_number \& c\k const alg\_number \& a}
{
\MATH{c = 1 / a} if \MATH{a \NEQ 0}. Otherwise the 
\TT{lidia\_error\_handler} will be invoked.
}

\fcode{alg\_number}{inverse}{const alg\_number \& a}
{
returns \MATH{1 / a} if \MATH{a \NEQ 0}. Otherwise the 
\TT{lidia\_error\_handler} will be invoked.
}

\fcode{void}{square}{alg\_number \& c\k const alg\_number \& a}
{
\MATH{c = a^2}.
}

\fcode{void}{power}{alg\_number \& c\k const alg\_number \& a\k const bigint \& i}
{
\MATH{c = a^i}.
}

\fcode{void}{power\_mod\_p}{alg\_number \& c\k const alg\_number \& a\k    const bigint \& i\k const bigint \& p}
{
\MATH{c = a^i \mbox{ mod } p}, i.e.~every component of the result 
is reduced modulo \MATH{p}. We assume, that \MATH{a} has denominator 
\MATH{1}.
}

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

\COMP 
The binary operators \TT{==}, \TT{!=}, and the unary operator \TT{!}
(comparison with zero) are overloaded and can be used in exactly the
same way as in the  programming language C if the numbers to be
compared are members of the same order. Otherwise the
\TT{lidia\_error\_handler} will be invoked.

In addition we offer the following functions for frequently needed special
cases.

Let \MATH{a} be an instance of type \BF{alg\_number}.\vspace*{1ex}

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

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

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

\BASIC
Let \MATH{a = (num, den, O)} be an instance of type \BF{alg\_number}.
\vspace*{1ex}

\cfcode{lidia\_size\_t}{a.degree}{}
{
returns the degree of the number field described by the base pointed to by
\MATH{O}.
}

\fcode{lidia\_size\_t}{degree}{const alg\_number \& a}
{
  returns the degree of the number field described by the base pointed to by
  \MATH{O}.
}

\fcode{void}{a.normalize}{}
{
  normalizes the \BF{alg\_number} \MATH{a} such that the \MATH{\gcd} 
  of the elements representing the numerator and the denominator is 
  \MATH{1} and that the denominator is positive.
}

\fcode{void}{swap}{alg\_number \& a\k alg\_number \& b}
{
  exchanges the values of \MATH{a} and \MATH{b}.
}

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

\HIGH
Let \MATH{a} be an instance of type \BF{alg\_number}.\vspace*{1ex}

\cfcode{bigfloat}{a.get\_conjugate}{lidia\_size\_t j}{
  for \MATH{0}\LT\MATH{j}\LEQ\TT{O.degree()} this functions returns the
  \MATH{j}-th conjugate of \MATH{a}. If \MATH{j} is not within the
  indicated bounds, the \TT{lidia\_error\_handler} will be invoked.}

\cfcode{math\_vector\TEMPL{bigfloat}}{a.get\_conjugates}{}{
  returns the vector of conjugates of \MATH{a}.}

\fcode{bigint\_matrix}{rep\_matrix}{const alg\_number \& a}
{
returns the representation matrix of the numerator of \MATH{a}, 
i.e.~the matrix of the endomorphism \MATH{K \RIGHTARROW K, x 
\mapsto a*{\rm den}(a)*x} with respect to the basis of the number field
\MATH{K} pointed to by \MATH{O}.
}

\fcode{bigrational}{norm}{const alg\_number \& a}
{
returns the norm of \MATH{a}.
}

\fcode{bigrational}{trace}{const alg\_number \& a}
{
returns the trace of \MATH{a}.
}

\fcode{polynomial\TEMPL{bigint}}{charpoly}{const alg\_number \& a}
{
returns the characteristic polynomial of \MATH{a}.
}

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

\IO
\BF{istream} operator \TT{>>} and \BF{ostream} operator \TT{<<} are
overloaded. Input and output of an \BF{alg\_number} have the following
format:
\MATH{[a_0\ \dots\ a_{n-1}] / den.}

If the denominator is \MATH{1} we omit it, i.e.~in this case the
format is
\MATH{[a_0\ \dots\ a_{n-1}].}

Note that you have to manage by yourself that successive \BF{alg\_number}s
may have to be separated by blanks. 

Since we didn't want to read the \MATH{O}--component of each number, we
always assume, that we are reading a representation with coefficients
relative to the base pointed to by \TT{nf\_base::current\_base}. By
default, \TT{nf\_base::current\_base} points to the basis of the last
number field or order that was read or constructed, but you may set it to
previously defined bases,e.g.~by calling an constructor of the class
\BF{order} with suitable arguments.
If \TT{nf\_base::current\_base} was not set before, the number will
use some useless dummy base, which will produce unpredictable results, if
you use such a number in a computation before assigning a meaningful value
to it.
(Note: Exactly the same mechanism using the same variables is used for
reading and writing modules and ideals).


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

\SEEALSO
\BF{bigint}, \BF{vector}, \BF{module}, \BF{ideal}, \BF{number\_field},
\BF{order}

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

\EXAMPLES
For an example please refer to\\
\TT{LiDIA/src/packages/alg\_number/alg\_number\_appl.c}

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

\AUTHOR
Stefan Neis

\end{lidia_man}
