\chapter{Functions and Operations available in PARI and GP}
\label{se:functions}

The functions and operators available in PARI and in the GP/PARI calculator
are numerous and everexpanding. Here is a description of the ones available
in version \vers. It should be noted that many of these functions accept
quite different types as arguments, but others are more restricted. The list
of acceptable types will be given for each function or class of functions.
Except when stated otherwise, it is understood that a function or operation
which should make natural sense is legal.
In this chapter, we will describe the functions according to a rough
classification. For the functions in alphabetical order, see the general 
index. The general entry looks something like:

\teb{foo}$(x,\{flag=0\})$: short description.

The library syntax is {\tt foo}$(x,flag)$.

This means that GP function {\tt foo}, has one mandatory argument $x$, and an
optional one, $flag$, whose default value is 0 (the $\{\}$ should never be
typed, it is just a notation we will use throughout). That is, you can type
{\tt foo(x,2)}, or {\tt foo(x)}, which is then understood to mean {\tt
foo(x,0)}. As well, a comma or closing parenthesis, where an optional
argument should have been, signals to GP it should use the default. Thus, the
syntax {\tt foo(x,)} is also accepted as a synonym for our last expression.
When a function has more than one optional argument, the argument list is
filled with user supplied values, in order. And when none are left, the
defaults are used instead. Thus, assuming {\tt foo} prototype had been:

{\tt foo}$(\{x=1\},\{y=2\},\{z=3\})$: typing in {\tt foo(6,4)}, would give
you {\tt foo(6,4,3)}. In the rare case when you want to set some far off
flag, and leave the defaults as they stand in between, you can use the
``empty arg'' trick alluded to above: {\tt foo(6,,1)} would yield
{\tt foo(6,2,1)}. By the way, {\tt foo()} by itself yields
{\tt foo(1,2,3)} as was to be expected. In this rather special case of a
function having no mandatory argument, you can even omit the $()$: a
standalone {\tt foo} would be enough (though we don't really recommend it in
your scripts, for the sake of clarity). In defining GP syntax, we strove
to put optional arguments at the end of the argument list (of course, since
they would not make sense otherwise), and in order of decreasing usefulness
so that, most of the time, you will be able to ignore them.

For some of these optional flags, we adopted the customary binary notation as
a compact way to represent many toggles with just one number. Let
$(p_0,\dots,p_n)$ a list of switches (that is properties that can be assumed
to take the values $0$ or $1$), the number $2^3 + 2^5=40$ means that $p_3$
and $p_5$ have been set (that is, set to $1$), and none of the others were
(that is, they were set to 0). This will usually be announced as ``The binary
digits of {\it flag} mean 1: $p_0$, 2: $p_1$, 4: $p_2$'', and so on, using the
available consecutive powers of $2$.

To finish with our generic simple-minded example, the {\it library} function
{\tt foo}, as defined above, is indicated to have two mandatory arguments, $x$
and $flag$ (no PARI mathematical function has been implemented so as to
accept a variable number of arguments). When not mentioned otherwise, the
result and arguments of a function is assumed implicitly to be a \kbd{GEN}.
Most other functions return an object of type {\tt long integer} in C (see
Chapter~4). $prec$ and $flag$ always denote {\tt long} integers.

\section{Standard monadic or dyadic operators.}
\def\subsecop#1{\subsec{\tt #1}}

\subsecop{+$/$-}: The expressions {\tt +}$x$ and {\tt -}$x$ refer
to monadic operators (the first does nothing, the second negates $x$).

The library syntax is $\teb{gneg}(x)$ for {\tt -}$x$.

\subsecop{+}, {\tt -} : The expression $x$ {\tt +} $y$ is the \idx{sum} and
$x$ {\tt -} $y$ is the \idx{difference} of $x$ and $y$. Among the prominent
impossibilities are addition/subtraction between a scalar type and a vector
or a matrix, between vector/matrices of incompatible sizes and between an
integermod and a real number.

The library syntax is $\teb{gadd}(x,y)$ for $x$ {\tt +} $y$, $\teb{gsub}(x,y)$
for $x$ {\tt -} $y$.

\subsecop{*} : The expression $x$ {\tt *} $y$ is the \idx{product} of $x$ 
and $y$. Among the prominent impossibilities are multiplication between
vector/matrices of incompatible sizes, between an integermod and a real
number. Note that because of vector and matrix operations, {\tt *} is not
necessarily commutative. Note also that since multiplication between two
column or two row vectors is not allowed, to obtain the \idx{scalar product}
of two vectors of the same length, you must multiply a line vector by a
column vector, if necessary by transposing one of the vectors (using 
{\tt\til} or {\tt trans$(\,)$}, see \secref{se:linear_algebra}).

If $x$ and $y$ are binary quadratic forms, compose them. See also
{\tt qfbnucomp} and {\tt qfbnupow}.

The library syntax is $\teb{gmul}(x,y)$ for $x$ {\tt *} $y$. Also available is
$\teb{gsqr}(x)$ for $x$ {\tt *} $x$ (faster of course !).

\subsecop{/} : The expression $x$ {\tt /} $y$ is the \idx{quotient} of $x$
and $y$. In addition to the impossibilities for multiplication, note that if
the divisor is a matrix, it must be an invertible square matrix, and in that
case the result is $x*y^{-1}$. Furthermore note that the result is as exact
as possible: in particular, division of two integers always gives a rational
number (which may be an integer if the quotient is exact) and {\it not\/} the
Euclidean quotient (see $x$ {\tt \bs} $y$ for that), and similarly the
quotient of two polynomials is a rational function in general. To obtain the
approximate real value of the quotient of two integers, add {\tt 0.} to the
result; to obtain the approximate $p$-adic value of the quotient of two
integers, add {\tt O(p\pow k)} to the result; finally, to obtain the
\idx{Taylor series} expansion of the quotient of two polynomials, add 
{\tt O(X\pow k)} to the result or use the {\tt taylor} function 
(see \secref{se:taylor}). \label{se:gdiv}

The library syntax is $\teb{gdiv}(x,y)$ for $x$ {\tt /} $y$.

\subsecop{\bs} : The expression $x$ {\tt\bs} $y$ is the \idx{Euclidean
quotient} of $x$ and $y$. The types must be either both integer or both
polynomials. The result is the Euclidean quotient. In the case of integer
division, the quotient is such that the corresponding remainder is
non-negative.

The library syntax is $\teb{gdivent}(x,y)$ for $x$ {\tt\bs} $y$.

\subsecop{\bs/} : The expression $x$ \b{/} $y$ is the Euclidean
quotient of $x$ and $y$.  The types must be either both integer or both
polynomials. The result is the rounded Euclidean quotient. In the case of
integer division, the quotient is such that the corresponding remainder is
smallest in absolute value and in case of a tie the quotient closest to
$+\infty$ is chosen.

The library syntax is $\teb{gdivround}(x,y)$ for $x$ \b{/} $y$.

\subsecop{\%} : The expression $x$ {\tt \%} $y$ is the \idx{Euclidean
remainder} of $x$ and $y$. The modulus $y$ must be of type integer or
polynomial. The result is the remainder, always non-negative in the case of
integers. Allowed dividend types are scalar exact types when the modulus is
an integer, and polynomials, polmods and rational functions when the modulus
is a polynomial.

The library syntax is $\teb{gmod}(x,y)$ for $x$ {\tt \%} $y$.

\subsecidx{divrem}$(x,y)$: creates a column vector with two components,
the first being the Euclidean quotient, the second the Euclidean remainder,
of the division of $x$ by $y$. This avoids the need to do two divisions if
one needs both the quotient and the remainder. The arguments must be both
integers or both polynomials, and in the case of integers the remainder is of
the sign of the dividend.

The library syntax is $\teb{gdiventres}(x,y)$.

\subsecop{\pow} : The expression $x${\tt\pow}$y$ is \idx{powering}. If the
exponent is an integer, then exact operations are performed using binary
powering techniques. In particular, in this case the first argument cannot be
a vector or matrix unless it is a square matrix (and moreover invertible if
the exponent is negative). If the exponent is not of type integer, this is
treated as a transcendental function (see Section~3), and in particular has
the effect of componentwise powering on vector or matrices.

The library syntax is $\teb{gpui}(x,y,prec)$ for $x${\tt\pow}$y$ where the
precision parameter $prec$ must be given only if $y$ is not integral but $x$
is an exact (real or complex) type.

In addition, there are two shift functions (i.e.~multiplication and division
by powers of 2) which are faster than the general multiplication or division
routines:

\subsecidx{shift}$(x,n)$ or $x$ {\tt <<} $n$ (= $x$ {\tt >>} $(-n)$): shift
$x$ componentwise left by $n$ bits if $n\ge0$ and right by $-n$ bits if
$n<0$. A left shift by $n$ corresponds to multiplication by $2^n$. A right
shift by $-n$ corresponds to a Euclidean division of $x$ by $2^{-n}$ with a
remainder of the same sign as $x$, hence is not the same (in general) as
$x$ {\tt\bs} $2^n$.

The library syntax is $\teb{gshift}(x,n)$ where $n$ is a C-long integer.

\subsecidx{shiftmul}$(x,n)$: multiply $x$ by $2^n$. The difference with {\tt
shift} is that when $n<0$, the ordinary division takes place, hence for
example if $x$ is an integer the result may be a fraction, while for {\tt
shift} Euclidean division takes place when $n<0$ hence if $x$ is an integer
the result is still an integer.

The library syntax is $\teb{gmul2n}(x,n)$ where $n$ is a C-long integer.

\subsec{Comparison and \idx{boolean operators}}. 
The six standard \idx{comparison operators} \kbd{<=}, \kbd{<}, \kbd{>=},
\kbd{>}, \kbd{==}, \kbd{!=} are available in GP, and in library mode under
the names {\bf \idx{gle}, \idx{glt}, \idx{gge}, \idx{ggt}, \idx{geq},
\idx{gne}} respectively. The library syntax is ${\bf co}(x,y)$, where co is
the comparison operator. The result is 1 (as a \kbd{GEN}) if the comparison
is true, 0 (as a \kbd{GEN}) if it is false.

The standard boolean functions  \kbd{||} (\idx{inclusive or}), \kbd{\&\&}
(\idx{and})\sidx{or} and \kbd{!} (\idx{not}) are also available, and the
library syntax is $\teb{gor}(x,y)$, $\teb{gand}(x,y)$ and $\teb{gnot}(x)$
respectively.

In library mode, it is in fact usually preferable to use the two basic
functions which are $\teb{gcmp}(x,y)$ which gives the sign (1, 0, or -1) of
$x-y$, where $x$ and $y$ must be in $\R$, and $\teb{gegal}(x,y)$ which
can be applied to any two PARI objects $x$ and $y$ and gives 1 (i.e.~true) if
they are equal (but not necessarily identical), 0 (i.e.~false) otherwise.
Particular cases of {\bf gegal} which should be used are $\teb{gcmp0}(x)$
($x==0$ ?), $\teb{gcmp1}(x)$ ($x==1$ ?), and \sidx{gcmp\string\_1} {\bf
gcmp\_1}$(x)$ ($x==-1$ ?).

Note that $\teb{gcmp0}(x)$ tests whether $x$ is equal to zero, even if $x$ is
not an exact object. To test whether $x$ is an exact object which is equal to
zero, one must use $\teb{isexactzero}$.

Also note that the {\tt gcmp}$x$ and {\tt gegal} functions return a C-integer,
and {\it not\/} a \kbd{GEN} like {\tt gle} etc.

\smallskip
GP accepts the following synonyms for some of the above functions: since
there is no bitwise \kbd{and} or bitwise \kbd{or}, \kbd{|} and \kbd{\&} are
accepted as\sidx{bitwise and} \sidx{bitwise or} synonyms of \kbd{||} and
\kbd{\&\&} respectively. Also, \kbd{<>} is accepted as a synonym for
\kbd{!=}. On the other hand, \kbd{=} is definitely {\it not} a synonym for
\kbd{==} since it is the assignment statement.

\subsecidx{lex}$(x,y)$: gives the result of a lexicographic comparison between
$x$ and $y$. This is to be interpreted in quite a wide sense. For example,
the vector $[1,3]$ will be considered smaller than the longer vector
$[1,3,-1]$ (but of course larger than $[1,2,5]$), i.e.
\kbd{lex([1,3],[1,3,-1])} will give $-1$ as a result.

The library syntax is $\teb{lexcmp}(x,y)$.

\subsecidx{sign}$(x)$: \idx{sign} of $x$, which must be of type
integer, real or fraction. The result (0, 1 or -1) is a C-long integer.

The library syntax is $\teb{gsigne}(x)$.

\subsecidx{max}$(x,y)$ and {\bf \idx{min}}$(x,y)$: create the
maximum and minimum of $x$ and $y$ when they can be compared.

The library syntax is $\teb{gmax}(x,y)$ and $\teb{gmin}(x,y)$.

\subsecidx{vecmax}$(x)$: if $x$ is a vector or a matrix, returns the maximum
of the elements of $x$, otherwise returns a copy of $x$. Returns $-\infty$
in the form of $-(2^{31}-1)$ (or $-(2^{63}-1)$ for 64-bit machines) if $x$ is
empty.

The library syntax is $\teb{vecmax}(x)$.

\subsecidx{vecmin}$(x)$: if $x$ is a vector or a matrix, returns the minimum
of the elements of $x$, otherwise returns a copy of $x$. Returns $+\infty$
in the form of $2^{31}-1$ (or $2^{63}-1$ for 64-bit machines) if $x$ is empty.

The library syntax is $\teb{vecmin}(x)$.

\subsectitle{Important remark.} In all the above library syntaxes, we have
given only the basic names of the functions. For example ${\tt gadd}(x,y)$
assumes that $x$ and $y$ are PARI objects (the \kbd{GEN} type) and {\it
creates} the result $x+y$ on the PARI stack. From most of these basic names,
the names and effects of other functions can be obtained in the following
way. We give the example for {\tt gadd}, but the same is true for all the
other functions above, and a few more that we have not given:

$\teb{gaddgs}(x,y)$: here $x$ is a \kbd{GEN}, $y$ is an ordinary C-long integer.

$\teb{gaddsg}(x,y)$: here $x$ is an ordinary C-long integer, $y$ is a \kbd{GEN}.

$\teb{gaddz}(x,y,z),\ \teb{gaddgsz}(x,y,z),\ \teb{gaddsgz}(x,y,z)$: here $z$
is a preexisting \kbd{GEN} and the result of the corresponding operation is put in
$z$. The size of the PARI stack does not change.

As simplification to programming, for many functions beginning with a 
{\tt g}, such as {\tt gadd}, one can replace the {\tt g} by an {\tt l} to
obtain a \kbd{long} result instead of a \kbd{GEN} (i.e.~pointer to long)
result. For instance ${\tt \idx{ladd}}(x,y)$ is identical to
$({\tt (long)gadd}(x,y))$. These macros are written in the file
\kbd{\idx{cast.h}} (see also \secref{se:typecast}). Note that {\tt ldiv} is
an ANSI C function name which is used to mean {\tt (long)gdiv} in PARI.

\section{Conversions and similar elementary functions or commands}

Many of the conversion functions are rounding or truncating operations. In
this case, if the argument is a rational function, the result is the
Euclidean quotient of the numerator by the denominator, and if the argument
is a vector or a matrix, the operation is done componentwise. This will not
be restated for every function.

\subsecidx{List}$({x=[\,]})$: transform a (row or column) vector $x$
into a list. The only other way to create a \typ{LIST} is to use the
function {\tt listcreate}.

This is useless in library mode.

\subsecidx{Mat}$({x=[\,]})$: transform the object $x$ into a matrix.
If $x$ is not a vector or a matrix, this creates a $1\times 1$ matrix.
If $x$ is a row (resp. column) vector, this creates a 1-row (resp.
1-column) matrix. If $x$ is already a matrix, a copy of $x$ is created.

This function can be useful in connection with the function {\tt concat}
(see below).

The library syntax is $\teb{gtomat}(x)$.

\subsecidx{Mod}$(x,y,\{flag=0\})$:\label{se:Mod} creates the PARI object
$(x \mod y)$, i.e.~an integermod or a polmod. $y$ must be an integer or a
polynomial. If $y$ is an integer, $x$ must be an integer. If $y$ is a
polynomial, $x$ must be a scalar or a polynomial. The result is put on the
PARI stack.

This function is not the same as $x$ \kbd{\%} $y$, the result of which is an
integer or a polynomial.

If $flag$ is equal to $1$, the modulus of the created result is put on the
heap and not on the stack, and hence becomes a permanent copy which cannot be
erased later by garbage collecting (see \secref{se:garbage}). In particular,
care should be taken to avoid creating too many such objects, since the heap
is very small (typically a few thousand objects at most).

The library syntax is $\teb{Mod0}(x,y,flag)$. Also available are 

$\bullet$ for $flag=1$: $\teb{gmodulo}(x,y)$.

$\bullet$ for $flag=0$: $\teb{gmodulcp}(x,y)$, $\teb{gmodulsg}(s,y)$ (where
$s$ is a \kbd{long}) and $\teb{gmodulss}(s,t)$ (where both $s$ and $t$ are
{\tt long} integers).

\subsecidx{Pol}$(x,\{v=x\})$: transform the object $x$ into a polynomial with
main variable $v$. If $x$ is a scalar, this gives a constant polynomial. If
$x$ is a power series, the effect is identical to {\tt truncate} (see below),
i.e.~it chops off the $O(X^k)$. If $x$ is a vector, this function creates
the polynomial whose coefficients are given in $x$, with $x[1]$ being the
leading coefficient (which can be zero).

Warning: this is {\it not} a substitution function. It is intended to be
quick and dirty. So if you try {\tt Pol(a,y)} on the polynomial {\tt a=x+y},
you will get {\tt y+y}, which is not a valid PARI/GP object.

The library syntax is $\teb{gtopoly}(x,v)$, where $v$ is a variable number.

\subsecidx{Polrev}$(x,\{v=x\})$: transform the object $x$ into a polynomial
with main variable $v$. If $x$ is a scalar, this gives a constant polynomial.
If $x$ is a power series, the effect is identical to {\tt truncate} (see
below), i.e.~it chops off the $O(X^k)$. If $x$ is a vector, this function
creates the polynomial whose coefficients are given in $x$, with $x[1]$ being
the constant term. Note that this is the reverse of {\tt Pol} if $x$ is a
vector, otherwise it is identical to {\tt Pol}.

The library syntax is $\teb{gtopolyrev}(x,v)$, where $v$ is a variable number.

\subsecidx{Ser}$(x,\{v=x\})$: transform the object $x$ into a power series
with main variable $v$ ($x$ by default). If $x$ is a scalar, this gives a
constant power series with precision given by the default {\tt serieslength}
(corresponding to the C global variable {\tt precdl}). If $x$ is a
polynomial, the precision is the greatest of {\tt precdl} and the degree of
the polynomial. If $x$ is a vector, the precision is similarly given, and the
coefficients of the vector are understood to be the coefficients of the power
series starting from the constant term (i.e.~the reverse of the function
{\tt Pol}, see above).

The warning given for {\tt Pol} applies here: this is not a substitution
function.

The library syntax is $\teb{gtoser}(x,v)$, where $v$ is a variable number
(i.e.~a C integer).

\subsecidx{Set}$(\{x=[\,]\})$: convert $x$ into a set, i.e.~into a row vector
with strictly increasing entries. $x$ can be of any type, but is most useful
when $x$ is already a vector. The components of $x$ are put in canonical form
(type \typ{STR}) so as to be easily sorted. To recover an ordinary \kbd{GEN}
from such an element, you can apply {\tt \idx{eval}} to it.

The library syntax is $\teb{gtoset}(x)$.

\subsecidx{Str}$(\{x={\tt ""}\})$: convert $x$ into a character string (the
empty string if $x$ is omitted). To recover an ordinary \kbd{GEN} from a string,
apply {\tt eval} to it.

The library syntax is $\teb{gtostr}(x)$.

\subsecidx{Vec}$({x=[\,]})$: transform the object $x$ into a row vector. The
vector will be with one component only, except when $x$ is a vector/matrix or
a quadratic form (in which case the resulting vector is simply the initial
object considered as a row vector), but more importantly when $x$ is a
polynomial or a power series. In the case of a polynomial, the coefficients
of the vector starts with the leading coefficient of the polynomial, while
for power series only the significant coefficients are taken into account,
but this time by increasing order of degree.

The library syntax is $\teb{gtovec}(x)$.

\subsecidx{binary}$(x)$: outputs the vector of the binary digits of $|x|$.
Here $x$ can be an integer, a real number (in which case the result has two
components, one for the integer part, one for the fractional part) or a
vector/matrix.

The library syntax is $\teb{binaire}(x)$.

\subsecidx{bittest}$(x,n)$: outputs the $n^{\text{th}}$ bit of $|x|$ starting
from the right (i.e.~the coefficient of $2^n$ in the binary expansion of $x$).
The result is 0 or 1.

The library syntax is $\teb{bittest}(x,n)$, where $n$ as well as the result
are C-long integers.

\subsecidx{ceil}$(x)$: ceiling of $x$. When $x$ is in $\R$,
the result is the smallest integer greater than or equal to $x$.

The library syntax is $\teb{gceil}(x)$.

\subsecidx{centerlift}$(x)$: lifts an element $x=a \bmod n$ of $\Z/n\Z$ to
$a$ in $\Z$, and similarly lifts a polmod to a polynomial. This is the
same as {\tt lift} except that in the particular case of elements of $\Z/n\Z$,
the lift $y$ is such that $-n/2<y\le n/2$. If $x$ is of type
fraction, complex, quadratic, polynomial, power series, rational function,
vector or matrix, the lift is done for each coefficient. Forbidden types for
$x$ are reals and $p$-adics.

The library syntax is $\teb{centerlift}(x)$.

\subsecidx{changevar}$(x,y)$: create a copy of the object $x$ where its
variables are modified according to the permutation specified by the vector
$y$. For example, assume that the variables have been introduced in the
order {\tt x}, {\tt a}, {\tt b}, {\tt c}. Then, if $y$ is the vector {\tt
[x,c,a,b]}, the variable {\tt a} will be replaced by {\tt c}, {\tt b} by {\tt
a}, and {\tt c} by {\tt b}, {\tt x} being unchanged. Note that the
permutation must be completely specified, e.g. {\tt [c,a,b]} would not work,
since this would replace {\tt x} by {\tt c}, and leave {\tt a} and {\tt b}
unchanged (as well as {\tt c} which is the fourth variable of the initial
list). In particular, the new variable names must be distinct.

The library syntax is $\teb{changevar}(x,y)$.

\subsec{\idx{components} of a PARI object}: 

There are essentially three ways to extract the components from a PARI object.

The first and most general, is the function $\teb{component}(x,n)$ which
extracts the $n^{\text{th}}$-component of $x$. This is to be understood as
follows: every PARI type has one or two initial \idx{code words}. The
components are counted, starting at 1, after these code words. In particular
if $x$ is a vector, this is indeed the $n^{\text{th}}$-component of $x$, if
$x$ is a matrix, the $n^{\text{th}}$ column, if $x$ is a polynomial, the
$n^{\text{th}}$ coefficient (i.e.~of degree $n-1$), and for power series, the
$n^{\text{th}}$ significant coefficient. The use of the function
{\tt component} implies the knowledge of the structure of the different PARI
types, which can be recalled by typing \b{t} under GP.

The library syntax is $\teb{compo}(x,n)$, where $n$ is a C-long integer.

The two other methods are more natural but more restricted. First, the
function $\teb{polcoeff}(x,n)$ gives the coefficient of degree $n$ of the
polynomial or power series $x$, with respect to the main variable of $x$ (to
see the order of the variables or to change it, use the function {\tt
reorder}, see Section~11). In particular if $n$ is less than the valuation of
$x$ or in the case of a polynomial, greater than the degree, the result is
zero (contrary to {\tt compo} which would send an error message). If $x$ is a
power series and $n$ is greater than the largest significant degree, then an
error message is issued.

For greater flexibility, vector or matrix types are also accepted for $x$,
and the meaning is then identical with that of {\tt compo}.

Finally note that a scalar type is considered by {\tt polcoeff} as a polynomial
of degree zero.

The library syntax is $\teb{truecoeff}(x,n)$.

The third method is specific to vectors or matrices under GP. If $x$ is a
(row or column) vector, then {\tt \idx{x[n]}} represents the $n^{\text{th}}$
component of $x$, i.e.~{\tt compo(x,n)}. It is more natural and shorter to
write. If $x$ is a matrix, {\tt \idx{x[m,n]}} represents the coefficient of
row {\tt m} and column {\tt n} of the matrix, {\tt \idx{x[m,]}} represents
the $m^{\text{th}}$ {\it row\/} of $x$, and {\tt \idx{x[,n]}} represents
the $n^{\text{th}}$ {\it column\/} of $x$.

Finally note that in library mode, the macros \teb{coeff} and \teb{mael}
are available to deal with the non-recursivity of the {\tt GEN} type from the
compiler's point of view. See the discussion on typecasts in Chapter 4.

\subsecidx{conj}$(x)$: conjugate of $x$. The meaning of this
is clear, except that for real quadratic numbers, it means conjugation in the
real quadratic field. This function has no effect on integers, reals,
integermods, fractions or $p$-adics. The only forbidden type is polmod
(see {\tt conjvec} for this).

The library syntax is $\teb{gconj}(x)$.

\subsecidx{conjvec}$(x)$: conjugate vector representation of $x$. If $x$ is a
polmod, equal to {\tt Mod}$(a,q)$, this gives a vector of length
$\text{degree}(q)$ containing the complex embeddings of the polmod if $q$ has
integral or rational coefficients, and the conjugates of the polmod if $q$
has some integermod coefficients. The order is the same as that of the {\tt
roots} functions. If $x$ is an integer or a rational number, the result
is~$x$. If $x$ is a (row or column) vector, the result is a matrix whose
columns are the conjugate vectors of the individual elements of $x$.

The library syntax is $\teb{conjvec}(x,prec)$, where $prec$ is a C-long 
integer.

\subsecidx{denominator}$(x)$: lowest denominator of $x$. The meaning of this
is clear when $x$ is a rational number or function. When $x$ is an integer
or a polynomial, the result is equal to 1. When $x$ is a vector or a matrix,
the lowest common denominator of the components of $x$ is computed. All other
types are forbidden.

The library syntax is $\teb{denom}(x)$.

\subsecidx{floor}$(x)$: floor of $x$. When $x$ is in $\R$,
the result is the largest integer smaller than or equal to $x$.

The library syntax is $\teb{gfloor}(x)$.

\subsecidx{frac}$(x)$: fractional part of $x$. Identical to
$x-\text{floor}(x)$. If $x$ is real, the result is in $[0,1[$.

The library syntax is $\teb{gfrac}(x)$.

\subsecidx{imag}$(x)$: imaginary part of $x$. When
$x$ is a quadratic number, this is the coefficient of $\omega$ in
the ``canonical'' integral basis $(1, \omega)$.

The library syntax is $\teb{gimag}(x)$.

\subsecidx{length}$(x)$: number of non-code words in $x$ really used (i.e.
the effective length minus 2 for integers and polynomials). In particular,
the degree of a polynomial is equal to its length minus 1.

The library syntax is $\teb{glength}(x)$.

\subsecidx{lift}$(x)$: lifts an element $x=a \bmod n$ of $\Z/n\Z$ to
$a$ in $\Z$, and similarly lifts a polmod to a polynomial. If $x$ is of
type fraction, complex, quadratic, polynomial, power series, rational
function, vector or matrix, the lift is done for each coefficient. Forbidden
types for $x$ are reals and $p$-adics.

The library syntax is $\teb{lift}(x)$.

\subsecidx{norm}$(x)$: algebraic norm of $x$, i.e.~the product of $x$ with
its conjugate (no square roots are taken), or conjugates for polmods. For
vectors and matrices, the norm is taken componentwise and hence is not the
$L^2$-norm (see {\tt norml2} below). Note that the norm of an element of
$\R$ is its square, so as to be compatible with the complex norm.

The library syntax is $\teb{gnorm}(x)$.

\subsecidx{norml2}$(x)$: square of the $L^2$-norm of $x$. $x$ must
be a (row or column) vector.

The library syntax is $\teb{gnorml2}(x)$.

\subsecidx{numerator}$(x)$: numerator of $x$. When $x$ is a rational number
or function, the meaning is clear. When $x$ is an integer or a polynomial,
the result is $x$ itself. When $x$ is a vector or a matrix, then {\tt
numerator(x)} is defined to be {\tt denominator(x)*x}. All other types are
forbidden.

The library syntax is $\teb{numer}(x)$.

\subsecidx{numtoperm}$(n,k)$: generates the $k$-th permutation (as a 
row vector of length $n$) of the numbers $1$ to $n$. The number $k$ is taken 
modulo $n!\,$.

The library syntax is $\teb{permute}(n,k)$, where $n$ is a C-long integer.

\subsecidx{padicprec}$(x,p)$: absolute $p$-adic precision of the object $x$.
This is the minimum precision of the components of $x$. The result is
{\tt VERYBIGINT} ($2^{31}-1$ for 32-bit machines or $2^{63}-1$ for 64-bit
machines) if $x$ is an exact object.

The library syntax is $\teb{padicprec}(x,p)$ and the result is a C-long
integer.

\subsecidx{permtonum}$(x)$: given a permutation $x$ on $n$ elements,
gives the number $k$ such that $x=${\tt permtonum(n,k)}, i.e.~inverse
function of {\tt permtonum}.

The library syntax is $\teb{permuteInv}(x)$.

\subsecidx{precision}$(x,\{n\})$: gives the precision in decimal digits of the
PARI object $x$. If $x$ is an exact object, the largest single precision integer
is returned. If $n$ is not omitted, creates a new object equal to $x$ with a
new precision $n$. This is to be understood as follows:

For exact types, no change. For $x$ a vector or a matrix, the operation
is done componentwise.

For real $x$, $n$ is the number of desired significant {\it decimal} digits.
If $n$ is smaller than the precision of $x$, $x$ is truncated, otherwise $x$
is extended with zeros.

For $x$ a $p$-adic or a power series, $n$ is the desired number of
significant $p$-adic or $X$-adic digits, where $X$ is the main variable of
$x$.

Note that the function {\tt precision} never changes the type of the result.
In particular it is not possible to use it to obtain a polynomial from a
power series. For that, see {\tt truncate} (see below).

The library syntax is $\teb{precision0}(x,n)$, where $n$ is a C-long integer.
Also available are $\teb{ggprecision}(x)$ (result is a \kbd{GEN}) and
$\teb{gprec}(x,n)$, where $n$ is a C-long integer.

\subsecidx{random}$(\{N=2^{31}\})$: gives a random integer between 0 and
$N-1$. The maximal value of $N$ is the default one $2^31$ (in the case of
64-bit machines this can be changed at compilation time to $2^{63}$). This is
an internal PARI function and does not depend on the system's random number
generator. Note that this integer is obtained by means of linear congruences
and will not be well distributed in arithmetic progressions.

The library syntax is $\teb{genrand}(N)$.

\subsecidx{real}$(x)$: real part of $x$. In the case where $x$ is a quadratic
number, this is the coefficient of $1$ in the ``canonical'' integral basis
$(1, \omega)$.

The library syntax is $\teb{greal}(x)$.

\subsecidx{round}$(x,\{flag=0\})$: If $x$ is in $\R$, rounds $x$ to the
nearest integer. If the exponent of $x$ is too large compared to its
precision, the result is undefined and an error occurs, unless $flag$ is
non-zero.

Important remark: note that, contrary to the other truncation functions, this
function operates on every coefficient at every level of a PARI object. For
example
$$\text{truncate}\left(\dfrac{2.4*X^2-1.7}{X}\right)=2.4*X,$$ whereas
$$\text{round}\left(\dfrac{2.4*X^2-1.7}{X}\right)=\dfrac{2*X^2-2}{X}.$$
An important use of {\tt round} is to get exact results after a long
approximate computation, when theory tells you that the coefficients
must be integers.

The library syntax is $\teb{round0}\,(x,flag)$. Also available are
$\teb{ground}(x) = \teb{round0}\,(x,0)$ and $\teb{grndtoi}(x,\&e)$ which
emulates $\teb{round0}\,(x,0)$, but for the C-long integer $e$. If no digits
are lost, this second argument $e$ contains the negative of the number of
significant bits of the fractional part.

\subsecidx{rounderror}$(x)$: maximum error in decimal digits observed when
rounding $x$. This functions allows the user to easily check the precision of
the rounding of a result whose components are supposed to be integers.

The library syntax is $\teb{rounderror}(x)$ and the result is a C-long integer.

\subsecidx{simplify}$(x)$: this function tries to simplify the object $x$ as
much as it can. The simplifications do not concern rational functions (which
PARI automatically tries to simplify), but type changes. Specifically, a 
complex or quadratic number whose imaginary part is exactly equal to 0 
(i.e.~not a real zero) is converted to its real part, and a polynomial of degree 
zero is converted to its constant term. For all types, this of course occurs
recursively. This function is useful in any case, but in particular before
the use of arithmetic functions which expect integer arguments, and not for
example a complex number of 0 imaginary part and integer real part (which is
however printed as an integer).

The library syntax is $\teb{simplify}(x)$.

\subsecidx{sizebyte}$(x)$: outputs the total number of bytes occupied by the
tree representing the PARI object $x$.

The library syntax is $\teb{taille2}(x)$ which returns a C-long integer. The
function {\bf taille} returns the number of {\it words} instead.

\subsecidx{sizedigit}$(x)$: output a quick bound for the number of decimal
digits of (the components of) $x$, off by at most $1$.

The library syntax is $\teb{gsize}(x)$ which returns a C-long integer.

\subsecidx{truncate}$(x,\{flag=0\})$: truncation of $x$. When $x$ is in $\R$,
this means that the part after the decimal point is chopped away. If the
result is not significant because the exponent is too large compared to the
precision, an error occurs unless $flag$ is non-zero.

Note a very special use of {\tt truncate}: when applied to a power series, it
transforms it into a polynomial or a rational function with denominator
a power of $X$, by chopping away the $O(X^k)$. Similarly, when applied to
a $p$-adic number, it transforms it into an integer or a rational number
by chopping away the $O(p^k)$.

The library syntax is $\teb{trunc0}\,(x,flag)$. Also available are
$\teb{gtrunc}(x) = \teb{trunc0}\,(x,0)$ and $\teb{gcvtoi}(x,\&e)$ which
emulates $\teb{trunc0}\,(x,0)$, but for the C-long integer $e$. If no digits
are lost, this second argument $e$ contains the negative of the number of
significant bits of the fractional part.

\subsecidx{valuation}$(x,p)$: Computes the highest exponent of $p$
dividing $x$. If $p$ is of type integer, $x$ must be an integer,
an integermod whose modulus is divisible by $p$, a fraction, a
$q$-adic number with $q=p$, or a polynomial or power series 
in which case the valuation is the minimum of the valuation of the coefficients.

If $p$ is of type polynomial, $x$ must be of type polynomial or rational
function, and also a power series if $x$ is a monomial. If $x=0$, an error is
issued except in case of $p$-adic numbers and power series, in which case the
result is the exponent of the zero. Finally, the valuation of a vector,
complex or quadratic number is the minimum of the component valuations. Any
other type combinations gives an error.

The library syntax is $\teb{ggval}(x)$, and the result is a C-long integer.

\subsecidx{variable}$(x)$: gives the main variable of the object $x$, and
$p$ if $x$ is a $p$-adic number. Gives an error if $x$ has no variable
associated to it. Note that this function is useful only in GP, since
in library mode the function {\tt gvar} is more useful.

The library syntax is $\teb{gpolvar}(x)$. However, in library mode,
this function should not be used. Instead, test whether $x$ is a $p$-adic
(type \typ{PADIC}), in which case $p$ is in $x[2]$, or call the function 
{\tt gvar(x)} which returns the variable {\it number\/} of $x$ if it 
exists, BIGINT otherwise.

\section{Transcendental functions.}

As a general rule, which of course in some cases may have exceptions,
transcendental functions operate in the following way:

$\bullet$ If the argument is either an integer, a real, a rational, a complex
or a quadratic number, it is, if necessary, first converted to a real (or
complex) number using the current \idx{precision} held in the default {\tt
realprecision}. Note that only exact arguments are converted, while inexact
arguments such as reals are not.

Under GP this is transparent to the user, but when programming
in library mode, care must be taken to supply a parameter {\tt prec} as 
the last argument of the function if the first argument is an exact object
(see~1.2.5.), otherwise disasters will occur.

   Note that in library mode the precision argument {\tt prec} is a word
count including codewords, i.e.~represents the length in words of a real
number, while under GP the precision (which is changed by the metacommand
\b{p} or using {\tt default(realprecision,...)}) is the number of significant
decimal digits.

Note that some accuracies attainable on 32-bit machines cannot be attained
on 64-bit machines for parity reasons. For example the default GP
accuracy is 28 decimal digits on 32-bit machines, corresponding to
{\tt prec} having the value 5, but this cannot be attained on 64-bit
machines. \smallskip

After possible conversion, the function is computed. Note that even if the
argument is real, the result may be complex (e.g. $\text{acos}(2.0)$ or
$\text{acosh}(0.0)$). Note also that the principal branch is always chosen.

$\bullet$ If the argument is an integermod or a $p$-adic, at present only a
few functions like {\tt sqrt} (square root), {\tt sqr} (square), {\tt log},
{\tt exp}, powering, {\tt teichmuller} (Teichm\"uller character) and {\tt
agm} (arithmetic-geometric mean) are implemented. Note that in the case of a
$2$-adic number, ${\tt sqr}(x)$ is not identical to $x*x$: for example if $x
= 1+O(2^5)$ then $x*x = 1+O(2^5)$ while ${\tt sqr}(x) = 1+O(2^6)$. (Remark:
note that if we wanted to be strictly consistent with the PARI philosophy, we
should have $x*y= (4 \mod 8)$ when both $x$ and $y$ are congruent to $2$
modulo $4$, or ${\tt sqr}(x)=(4\mod 32)$ when $x$ is congruent to $2$ modulo
$4$. However, since an integermod is an exact object, PARI assumes that the
modulus must not change, and the result is hence $0\, \mod\, 4$ in both
cases. On the other hand, $p$-adics are not exact objects, hence are treated
differently.)

$\bullet$ If the argument is a polynomial, power series or rational function,
it is, if necessary, first converted to a power series using the current
precision held in the variable {\tt\idx{precdl}}. Under GP this again is
transparent to the user. When programming in library mode, however, the
global variable {\tt precdl} must be set before calling the function if the
argument has an exact type (i.e.~not a power series). Here {\tt precdl} is
not an argument of the function, but a global variable.

Then the Taylor series expansion of the function around $X=0$ (where $X$ is
the main variable) is computed to a number of terms depending on the number
of terms of the argument and the function being computed.

$\bullet$ If the argument is a vector or a matrix, the result is
componentwise evaluation of the function. In particular, transcendental
functions on square matrices, which are not implemented in the present
version \vers{} (see Appendix C however), will have a slightly different name
if they are implemented some day.

\subsecop{\pow} : If $y$ is not of type integer, $x$\pow$y$ has the same effect
as {\tt exp($y$*ln($x$))}. It can be applied to $p$-adic numbers as well as
to the more usual types.\sidx{powering}

The library syntax is $\teb{gpui}(x,y,prec)$.

\subsecidx{Euler}: Euler's constant $0.57721\cdots$. Note that {\tt Euler}
is one of the few special reserved names which cannot be used for variables
(the others are {\tt I} and {\tt Pi}, as well as all function names).
\label{se:euler}

The library syntax is $\teb{mpeuler}(prec)$ where $prec$ {\it must} be
given. Note that this creates $\gamma$ on the PARI stack. If one does not
want to create it on that stack but be able to use it later under the global
name {\bf \idx{geuler}} (with no parentheses) use instead
$\teb{consteuler}(prec)$.

\subsecidx{I}: The complex number $\sqrt{-1}$

The library syntax is the global variable {\tt gi} (of type {\tt GEN}).

\subsecidx{Pi}: the constant $\pi$ ($3.14159\cdots$).\label{se:pi}

The library syntax is $\teb{mppi}(prec)$ where $prec$ {\it must} be given.
Note that this creates $\pi$ on the PARI stack. If one does not want to
create it on that stack but be able to use it later under the global
name {\bf \idx{gpi}} (with no parentheses) use instead $\teb{constpi}(prec)$.

\subsecidx{abs}$(x)$: absolute value of $x$ (modulus if $x$ is complex).
Polynomials, power series and rational functions are not allowed. 
Contrary to most transcendental functions, an integer is {\it not\/}
converted to a real number before applying {\tt abs}.

The library syntax is $\teb{gabs}(x,prec)$, where the second argument
$prec$ is necessary only in the complex or imaginary quadratic case.

\subsecidx{acos}$(x)$: principal branch of $\text{cos}^{-1}(x)$,
i.e.~such that $\text{Re(acos}(x))\in [0,\pi]$. If
$x\in \R$ and $|x|>1$, then $\text{acos}(x)$ is complex.

The library syntax is $\teb{gacos}(x,prec)$.

\subsecidx{acosh}$(x)$: principal branch of $\text{cosh}^{-1}(x)$,
i.e.~such that $\text{Im(acosh}(x))\in [0,\pi]$. If
$x\in \R$ and $x<1$, then $\text{acosh}(x)$ is complex.

The library syntax is $\teb{gach}(x,prec)$.

\subsecidx{agm}$(x,y)$: arithmetic-geometric mean of $x$ and $y$. In the
case of complex or negative numbers, the principal square root is always
chosen. $p$-adic or power series arguments are also allowed. Note that
a $p$-adic agm exists only if $x/y$ is congruent to 1 modulo $p$ (modulo
16 for $p=2$). $x$ and $y$ cannot both be vectors or matrices.

The library syntax is $\teb{agm}(x,y,prec)$.

\subsecidx{arg}$(x)$: argument of the complex number $x$, such that
$-\pi<\text{arg}(x)\le\pi$.

The library syntax is $\teb{garg}(x,prec)$.

\subsecidx{asin}$(x)$: principal branch of $\text{sin}^{-1}(x)$,
i.e.~such that $\text{Re(asin}(x))\in [-\pi/2,\pi/2]$. If
$x\in \R$ and $|x|>1$ then $\text{asin}(x)$ is complex.

The library syntax is $\teb{gasin}(x,prec)$.

\subsecidx{asinh}$(x)$: principal branch of $\text{sinh}^{-1}(x)$,
i.e.~such that $\text{Im(asinh)}(x)\in [-\pi/2,\pi/2]$.

The library syntax is $\teb{gash}(x,prec)$.

\subsecidx{atan}$(x)$: principal branch of $\text{tan}^{-1}(x)$,
i.e.~such that $\text{Re(atan}(x))\in ]-\pi/2,\pi/2[$.

The library syntax is $\teb{gatan}(x,prec)$.

\subsecidx{atanh}$(x)$: principal branch of $\text{tanh}^{-1}(x)$.
i.e.~such that $\text{Im(atanh}(x))\in ]-\pi/2,\pi/2]$. If
$x\in \R$ and $|x|>1$ then $\text{atanh}(x)$ is complex.

The library syntax is $\teb{gath}(x,prec)$.

\subsecidx{bernreal}$(x)$: Bernoulli number $B_x$, where $B_0=1$, $B_1=-1/2$,
$B_2=1/6$,\dots, expressed as a real number with the current precision.
The argument $x$ should be of type integer.

The library syntax is $\teb{bernreal}(x,prec)$.

\subsecidx{bernvec}$(x)$: creates a vector containing, as rational numbers, the
Bernoulli numbers $B_0$, $B_2$,\dots, $B_{2x}$. These Bernoulli numbers can
then be used as follows. Assume that this vector has been put into a variable,
say {\tt bernint}. Then you can define under GP:

{\obeylines\tt\parskip=0pt
$\{$
\quad bern(x) = 
\qquad  if (x==1, return(-1/2));
\qquad  if ((x<0) || (x\%2), return(0));
\qquad  bernint[x/2+1]
$\}$}

\noindent and then {\tt bern(k)} gives the Bernoulli number of index $k$ as a
rational number, exactly as {\tt bernreal(k)} gives it as a real number.

The library syntax is $\teb{bernvec}(x)$.

\subsecidx{besseljh}$(n,x)$: $J$-Bessel function of half integral index.
More precisely, {\tt besseljh}(n,x) computes $J_{n+1/2}(x)$ where $n$
must be of type integer, and $x$ is any element of $\C$. In the
present version \vers, this function is not very accurate when $x$ is
small.

The library syntax is $\teb{jbesselh}(n,x,prec)$.

\subsecidx{besselk}$(nu,x,\{flag=0\})$: K-Bessel function of index $nu$
(which can be complex) and argument $x$. Only real and positive arguments
$x$ are allowed in the present version \vers. If $flag$ is equal to 1,
use another implementation of this function which is often faster.

The library syntax is $\teb{kbessel}(nu,x,prec)$ and
$\teb{kbessel2}(nu,x,prec)$ respectively.

\subsecidx{cos}$(x)$: cosine of $x$.

The library syntax is $\teb{gcos}(x,prec)$.

\subsecidx{cosh}$(x)$: hyperbolic cosine of $x$.

The library syntax is $\teb{gch}(x,prec)$.

\subsecidx{dilog}$(x)$: principal branch of the dilogarithm of $x$, i.e.
analytic continuation of the power series $\log_2(x)=\sum_{n\ge1}x^n/n^2$.

The library syntax is $\teb{dilog}(x,prec)$.

\subsecidx{eint1}$(x)$: exponential integral 
$\int_x^\infty \dfrac{e^{-t}}{t}\,dt$.

The library syntax is $\teb{eint1}(x,prec)$.

\subsecidx{erfc}$(x)$: complementary error function
$(2/\sqrt\pi)\int_x^\infty e^{-t^2}\,dt$.

The library syntax is $\teb{erfc}(x,prec)$.

\subsecidx{eta}$(x,\{flag=0\})$: Dedekind's $\eta$ function, without the
$q^{1/24}$. The meaning is this. If $x$ is a complex number with positive
imaginary part, the result is $\prod_{n=1}^\infty(1-q^n)$, where 
$q=e^{2i\pi x}$. If $x$ is a power series (or can be converted to a power
series) with positive valuation, the result is $\prod_{n=1}^\infty(1-x^n)$.

If $flag=1$ and $x$ can be converted to a complex number (i.e.~is not a power
series), compute the true $\eta$ function, with the leading $q^{1/24}$.

The library syntax is $\teb{eta}(x,prec)$.

\subsecidx{exp}$(x)$: exponential of $x$.
$p$-adic arguments with positive valuation are accepted.

The library syntax is $\teb{gexp}(x,prec)$.

\subsecidx{gammah}$(x)$: gamma function evaluated at the argument
$x+1/2$. When $x$ is an integer, this is much faster than using
{\tt gamma}$(x+1/2)$.

The library syntax is $\teb{ggamd}(x,prec)$.

\subsecidx{gamma}$(x)$: gamma function of $x$. In the present version
\vers{} the $p$-adic gamma function is not implemented.

The library syntax is $\teb{ggamma}(x,prec)$.

\subsecidx{hyperu}$(a,b,x)$: U-confluent hypergeometric function with
parameters $a$ and $b$.

The library syntax is $\teb{hyperu}(a,b,x,prec)$.

\subsecidx{incgam}$(s,x,{y})$: incomplete gamma function.

The arguments $s$ and $x$ must be positive. The result returned is
$\int_x^\infty e^{-t}t^{s-1}\,dt$. When y is given, assume (of course
without checking !) that $y=\Gamma(s)$. For small $x$, this will tremendously
speed up the computation.

The library syntax is $\teb{incgam}(s,x,prec)$ and
$\teb{incgam4}(s,x,y,prec)$, respectively.

Note: in addition, there exist also the functions
{\tt \idx{incgam1} and \idx{incgam2}} which are used for internal purposes.

\subsecidx{incgamc}$(s,x)$: complementary incomplete gamma function.

The arguments $s$ and $x$ must be positive. The result returned is
$\int_0^x e^{-t}t^{s-1}\,dt$, when $x$ is not too large.

The library syntax is $\teb{incgam3}(s,x,prec)$.

\subsecidx{log}$(x,\{flag=0\})$: principal branch of the natural logarithm of
$x$, i.e.~such that $\text{Im(ln}(x))\in ]-\pi,\pi]$. The result is complex
(with imaginary part equal to $\pi$) if $x\in \R$ and $x<0$.

$p$-adic arguments are also accepted for $x$, with the convention that
$\ln(p)=0$. Hence in particular $\exp(\ln(x))/x$ will not in general be
equal to 1 but to a $p-1$-th root of unity (or $\pm1$ if $p=2$)
times a power of $p$.

If $flag$ is equal to 1, use an agm formula suggested by Mestre, when $x$ is
real, otherwise identical to {\tt log}.

The library syntax is $\teb{glog}(x,prec)$ or $\teb{glogagm}(x,prec)$.

\subsecidx{lngamma}$(x)$: principal branch of the logarithm of the gamma
function of $x$. Can have much larger arguments than {\tt gamma} itself.
In the present version \vers{} the $p$-adic {\tt lngamma} function is not 
implemented.

The library syntax is $\teb{glngamma}(x,prec)$.

\subsecidx{polylog}$(m,x,{flag=0})$: One of the different polylogarithms,
depending on $flag$:

If $flag=0$ or is omitted: $m^\text{th}$ polylogarithm of $x$, i.e.~analytic
continuation of the power series $\log_m(x)=\sum_{n\ge1}x^n/n^m$. The
program uses the power series when $|x|^2\le1/2$, and the power series
expansion in $\log(x)$ otherwise. It is valid in a large domain (at least
$|x|<230$), but should not be used too far away from the unit circle since it
is then better to use the functional equation linking the value at $x$ to the
value at $1/x$, which takes a trivial form for the variant below. Power
series, polynomial, rational and vector/matrix arguments are allowed.

For the variants to follow we need a notation: let $\Re_m$
denotes $\Re$ or $\Im$ depending whether $m$ is odd or even.

If $flag=1$: modified $m^\text{th}$ polylogarithm of $x$, called
$\tilde D_m(x)$ in Zagier, defined for $|x|\le1$ by
$$\Re_m\left(\sum_{k=0}^{m-1} \dfrac{(-\log|x|)^k}{k!}\log_{m-k}(x)
+\dfrac{(-\log|x|)^{m-1}}{m!}\log|1-x|\right).$$

If $flag=2$: modified $m^\text{th}$ polylogarithm of $x$,
called $D_m(x)$ in Zagier, defined for $|x|\le1$ by
$$\Re_m\left(\sum_{k=0}^{m-1}\dfrac{(-\log|x|)^k}{k!}\log_{m-k}(x)
-\dfrac{1}{2}\dfrac{(-\log|x|)^m}{m!}\right).$$

If $flag=3$: another modified $m^\text{th}$
polylogarithm of $x$, called $P_m(x)$ in Zagier, defined for $|x|\le1$ by
$$\Re_m\left(\sum_{k=0}^{m-1}\dfrac{2^kB_k}{k!}(\log|x|)^k\log_{m-k}(x)
-\dfrac{2^{m-1}B_m}{m!}(\log|x|)^m\right).$$

These three functions satisfy the functional equation
$f_m(1/x)=(-1)^{m-1}f_m(x)$, where $f_m$ is any one of $D_m$, $\tilde D_m$
or $P_m$.

The library syntax is \teb{polylog0}$(m,x,flag,prec)$.

\subsecidx{psi}$(x)$: the $\psi$-function of $x$, i.e.~the
logarithmic derivative $\Gamma'(x)/\Gamma(x)$.

The library syntax is $\teb{gpsi}(x,prec)$.

\subsecidx{sin}$(x)$: sine of $x$.

The library syntax is $\teb{gsin}(x,prec)$.

\subsecidx{sinh}$(x)$: hyperbolic sine of $x$.

The library syntax is $\teb{gsh}(x,prec)$.

\subsecidx{sqr}$(x)$: square of $x$. Not identical to $x*x$ in
the case of $2$-adics (see above).

The library syntax is $\teb{gsqr}(x)$.

\subsecidx{sqrt}$(x)$: principal branch of the square root of $x$,
i.e.~such that $\text{Arg(sqrt}(x))\in ]-\pi/2,\pi/2]$, or in other words
such that $\text{Re(sqrt}(x))>0$ or $\text{Re(sqrt}(x))=0$ and
$\text{Im(sqrt}(x))\ge0$.
If $x\in \R$ and $x<0$, then the result is complex with positive 
imaginary part.

Integermod a prime and $p$-adics are allowed as arguments. In that case,
the square root (if it exists) which is returned is the one whose 
first $p$-adic digit (or its unique $p$-adic digit in the case of
integermods) is in the interval $[0,p/2]$.

The library syntax is $\teb{gsqrt}(x,prec)$.

\subsecidx{tan}$(x)$: tangent of $x$.

The library syntax is $\teb{gtan}(x,prec)$.

\subsecidx{tanh}$(x)$: hyperbolic tangent of $x$.

The library syntax is $\teb{gth}(x,prec)$.

\subsecidx{teichmuller}$(x)$: Teichmuller character of the $p$-adic number
$x$.

The library syntax is $\teb{teich}(x)$.

\subsecidx{theta}$(q,z)$: Jacobi sine theta-function.

The library syntax is $\teb{theta}(q,z,prec)$.

\subsecidx{thetanullk}$(q,k)$: $k$' th derivative at $z=0$ of {\tt
theta}$(q,z)$.

The library syntax is $\teb{thetanullk}(q,k,prec)$, where $k$ is a {\tt long}
integer.

\subsecidx{weber}$(x,\{flag=0\})$: One of Weber's $f$ function. If $flag=0$,
return $f(x)=\exp(-i\pi/24)\eta((x+1)/2)/\eta(x)$ such that 
$j=(f^{24}-16)^3/f^{24}$, where $j$ is the elliptic $j$-invariant 
(see the function {\tt ellj} below). If $flag=1$,
return $f_1(x)=\eta(x/2)/\eta(x)$ such that 
$j=(f_1^{24}+16)^3/f_1^{24}$. Finally, if $flag=2$,
return $f_2(x)=\sqrt{2}\eta(2x)/\eta(x)$ such that 
$j=(f_2^{24}+16)^3/f_2^{24}$. Note the identities $f^8=f_1^8+f_2^8$
and $ff_1f_2=\sqrt2$.

The library syntax is $\teb{weber0}(x,flag,prec)$, or 
$\teb{wf}(x,prec)$, $\teb{wf1}(x,prec)$ or $\teb{wf2}(x,prec)$.

\subsecidx{zeta}$(s)$: Riemann's zeta function $\zeta(s)=\sum_{n\ge1}n^{-s}$,
computed using the Euler-Maclaurin summation formula, except when $s$ is of
type integer, in which case it is computed using Bernoulli numbers for
$s\le0$ or $s>0$ and even, and using modular forms for $s>0$ and odd.

The library syntax is $\teb{gzeta}(s,prec)$.

\section{Arithmetic functions.}

These functions are by definition functions whose natural domain of
definition is either $\Z$ (or $\Z_{>0}$), or sometimes polynomials
over a base ring. Functions which concern polynomials exclusively will be
explained in the next section. The way these functions are used is
completely different from transcendental functions: in general only the types
integer and polynomial are accepted as arguments. If a vector or matrix type
is given, the function will be applied on each coefficient independently.

In the present version \vers{} a primitive but useful version of the
\idx{ECM} factoring method has been implemented. Also, numbers found to be
pseudo-primes after 10 successful trials of the \idx{Rabin-Miller} test are
declared primes.

\bigskip
\subsecidx{Qfb}$(a,b,c,\{D=0.\})$: creates the binary quadratic form
$ax^2+bxy+cy^2$. If $b^2-4ac>0$, initialize Shanks's distance function to $D$.

The library syntax is $\teb{Qfb0}(a,b,c,D,prec)$. Also available are
$\teb{qfi}(a,b,c)$ (when $b^2-4ac<0$), and
$\teb{qfr}(a,b,c,d)$ (when $b^2-4ac>0$).
\sidx{binary quadratic form}

\subsecidx{addprimes}$(\{x=[\,]\})$: add the primes contained in the vector
$x$ (or the single integer $x$) to the table computed upon GP initialization
(by {\tt pari\_init} in library mode), and 
return a row vector whose first entries contain all primes added by the user
and whose last entries have been filled up with 1's. In total the returned row 
vector has 100 components. Whenever {\tt factor} or {\tt smallfact} is 
subsequently called, first the primes in the table computed by {\tt pari\_init} 
will be checked, and then the additional primes in this table. If $x$ is empty or 
omitted, just return the current list of extra primes.

The entries in $x$ are not checked for primality. They only need be positive
integers not divisible by any of the pre-computed primes. It's in fact a nice
trick to add composite numbers, which for example the function {\tt
factor}$(x,0)$ was not able to factor. In case the message ``impossible
inverse modulo $<${\it some integermod}$>$'' shows up afterwards, you just
stumbled over one non-trivial factor.

The present PARI version \vers{} allows up to 100 user-specified
primes to be appended to the table. This limit may be changed
by altering {\tt NUMPRTBELT} in file {\tt init.c}. To remove primes from the
list use {\tt removeprimes}.

The library syntax is $\teb{addprimes}(x)$.

\subsecidx{bestappr}$(x,k)$: if $x\in\R$, finds the best rational
approximation to $x$ with denominator at most equal to $k$ using continued
fractions.

The library syntax is $\teb{bestappr}(x,k)$.

\subsecidx{bezout}$(x,y)$: finds $u$ and $v$ minimal in a
natural sense such that $x*u+y*v=\text{gcd}(x,y)$. The arguments
must be both integers or both polynomials, and the result is a
row vector with three components $u$, $v$, and $\text{gcd}(x,y)$.

The library syntax is either $\teb{vecbezout}(x,y)$ to get the
vector, or $\teb{gbezout}(x,y, \& u, \& v)$ which gives as result the
address of the created gcd, and puts in $u$ and $v$ the addresses of the
corresponding created objects.

\subsecidx{bezoutres}$(x,y)$: as above, with the resultant of $x$ and
$y$ replacing the gcd.

The library syntax is either $\teb{vecbezoutres}(x,y)$ to get the
vector, or $\teb{subresext}(x,y, \& u, \& v)$ which gives as result the
address of the created gcd, and puts in $u$ and $v$ the addresses of the
corresponding created objects.

\subsecidx{bigomega}$(x)$: number of prime
divisors of $x$ counted with multiplicity. $x$ must be an integer,
and the result is a C-long integer.

The library syntax is $\teb{bigomega}(x)$.

\subsecidx{binomial}$(x,y)$: \idx{binomial coefficient} $\binom x y$.
Here $y$ must be an integer, but $x$ can be any PARI object.

The library syntax is $\teb{binome}(x,y)$, where $y$ must be a C-long integer.

\subsecidx{chinese}$(x,y)$: If $x$ and $y$ are both integermods or both
polmods, creates (with the same type) a $z$ in the same residue class
as $x$ and in the same residue class as $y$, if it is possible.

This function also allows vector and matrix arguments, in which case the
operation is recursively applied to each component of the vector or matrix.
For polynomial arguments, it is applied to each coefficient. Finally
{\tt chinese}$(x,x) = x$ regardless of the type of $x$; this allows vector
inputs to contain other data types, if this data is identical in both
vectors.

The library syntax is $\teb{chinois}(x,y)$.

\subsecidx{content}$(x)$: computes the gcd of all the coefficients of $x$,
when this gcd makes sense. If $x$ is a scalar, this simply gives $x$. If $x$
is a polynomial (and by extension a power series), it gives the usual content
of $x$. If $x$ is a rational function, it gives the ratio of the contents of
the numerator and the denominator. Finally, if $x$ is a vector or a matrix,
it gives the gcd of all the entries.

The library syntax is $\teb{content}(x)$.

\subsecidx{contfrac}$(x,\{b\},\{lmax\})$: creates the row vector whose
components are the partial quotients of the \idx{continued fraction}
expansion of $x$, the number of partial quotients being limited to $lmax$.
If $x$ is a real number, the expansion stops at the last significant partial
quotient if $lmax$ is omitted. $x$ can also be a rational function or a power
series.

If a vector $b$ is supplied, the numerators will be equal to the coefficients
of $b$. The length of the result is then equal to the length of $b$, unless a
partial remainder is encountered which is equal to zero. In which case the
expansion stops. In the case of real numbers, the stopping criterion in thus
different from the one mentionned above since, if $b$ is too long, some partial
quotients may not be significant.

The library syntax is $\teb{contfrac0}(x,b,lmax)$. Also available are
$\teb{gboundcf}(x,lmax)$, $\teb{gcf}(x)$, or $\teb{gcf2}(b,x)$, where $lmax$
is a C integer.

\subsecidx{contfracpnqn}$(x)$: When $x$ is a vector or a one-row matrix, $x$
is considered as the list of partial quotients $[a_0,a_1,\dots,a_n]$ of a
rational number, and the result is the 2 by 2 matrix
$[p_n,p_{n-1};q_n,q_{n-1}]$ in the standard notation of continued fractions,
so $p_n/q_n=a_0+1/(a_1+\dots+1/a_n)\dots)$. If $x$ is a matrix with two rows
$[b_0,b_1,\dots,b_n]$ and $[a_0,a_1,\dots,a_n]$, this is then considered as a
generalized continued fraction and we have similarly
$p_n/q_n=1/b_0(a_0+b_1/(a_1+\dots+b_n/a_n)\dots)$. Note that in this case one
usually has $b_0=1$.

The library syntax is $\teb{pnqn}(x)$.

\subsecidx{core}$(n,\{flag=0\})$: if $n$ is a non-zero integer written as
$n=df^2$ with $d$ squarefree, returns $d$. If $flag$ is non-zero,
returns the two-element row vector $[d,f]$.

The library syntax is $\teb{core0}(n,flag)$.
Also available are
$\teb{core}(n)$ (=\teb{core}$(n,0)$) and
$\teb{core2}(n)$ (=\teb{core}$(n,1)$).

\subsecidx{coredisc}$(n,\{flag\})$: if $n$ is a non-zero integer written as
$n=df^2$ with $d$ fundamental discriminant (including 1), returns $d$. If
$flag$ is non-zero, returns the two-element row vector $[d,f]$. Note that if
$n$ is not congruent to 0 or 1 modulo 4, $f$ will be a half integer and not
an integer.

The library syntax is $\teb{coredisc0}(n,flag)$.
Also available are
$\teb{coredisc}(n)$ (=\teb{coredisc}$(n,0)$) and
$\teb{coredisc2}(n)$ (=\teb{coredisc}$(n,1)$).

\subsecidx{dirdiv}$(x,y)$: $x$ and $y$ being vectors of perhaps different
lengths but with $y[1]\neq 0$ considered as Dirichlet series, computes the
quotient of $x$ by $y$, again as a vector.

The library syntax is $\teb{dirdiv}(x,y)$.

\subsecidx{direuler}$(p=a,b,expr)$: computes the Dirichlet series to $b$
terms of the Euler product of expression $expr$ as $p$ ranges through the
primes from $a$ to $b$. $expr$ must be a polynomial or rational function in
another variable than $p$ (say $X$) and $expr(X)$ is understood as the
Dirichlet series (or more precisely the local factor) $expr(p^{-s})$.

The library syntax is \tec{direuler}{(entree *ep, GEN a, GEN b, char *ch)}
(see the section on sums and products for explanations of this).

\subsecidx{dirmul}$(x,y)$: $x$ and $y$ being vectors of perhaps different
lengths considered as Dirichlet series, computes the product of $x$ by $y$,
again as a vector.

The library syntax is $\teb{dirmul}(x,y)$.

\subsecidx{divisors}$(x)$: creates a row vector whose components are the
positive divisors of the integer $x$ in increasing order.

The library syntax is $\teb{divisors}(x)$.

\subsecidx{eulerphi}$(x)$: Euler's $\phi$-function of $x$. $x$ must be of
type integer.

The library syntax is $\teb{phi}(x)$.

\subsecidx{factor}$(x,\{lim=-1\})$: general factorization function. If $x$ is of
type integer, rational, polynomial or rational function, the result is a
two-column matrix, the first column being the irreducibles dividing $x$
(prime numbers or polynomials), and the second the exponents. If $x$ is a
vector or a matrix, the factoring is done componentwise (hence the result is
a vector or matrix of two-column matrices).

   If $x$ is of type integer or rational, an argument $lim$ can be added,
meaning that we look only for factors up to $lim$, or to {\tt primelimit},
whichever is lowest (except when $lim=0$ where the effect is identical to
setting $lim={\tt primelimit}$). In this case, the remaining part is hence
not necessarily prime. 

   The polynomials or rational functions to be factored must have scalar
coefficients. In particular PARI does {\it not} yet know how to factor
multivariate polynomials.

   Note that PARI tries to guess in a sensible way over which ring you want
to factor. Note also that for the moment, the content of a polynomial or
rational function is discarded and not included in the factorization. Hence
the user should either first divide by this content, or simply be aware of
this. See also {\tt \idx{factornf}}.

The library syntax is $\teb{factor0}(x,lim)$, where $lim$ is a C integer.
Also available are 
$\teb{factor}(x)$ ( = $\teb{factor0}(x,-1)$),
$\teb{smallfact}(x)$ ( = $\teb{factor0}(x,0)$).

\subsecidx{factorback}$(f,\{nf\})$: $f$ being any factorisation, gives back
the factored object. If a second argument $nf$ is supplied, $f$ is assumed to
be a prime ideal factorisation in the number field $nf$. The resulting
ideal is the given in HNF form.

The library syntax is $\teb{factorback}(f,nf)$, where an omitted $nf$ is
entered as {\tt NULL}.

\subsecidx{factorcantor}$(x,p)$: factorization mod $p$ of the polynomial $x$
using distinct degree plus Cantor-Zassenhaus. The coefficients of $x$ must be
operation-compatible with $\Z/p\Z$. The result is a two-column
matrix, the first column being the irreducible polynomials dividing $x$, and
the second the exponents.  If you want only the {\it degrees} of the
irreducible polynomials (for example for computing an $L$-function), use
{\tt factormod}$(x,p,1)$. Note that the {\tt factormod} algorithm is usually
faster than {\tt factorcantor}.

The library syntax is $\teb{factcantor}(x,p)$.

\subsecidx{factorff}$(x,p,a)$: factorization in the field $\F_q$ defined
by the irreducible polynomial $a$ over $\F_p$ of the polynomial $x$. The
coefficients of $x$ must be operation-compatible with $\Z/p\Z$. The
result is a two-column matrix, the first column being the irreducible
polynomials dividing $x$, and the second the exponents. It is advised to use
for the variable of $a$ (which will be used as variable of a polmod), a name
distinct from the other variables used, so that a {\tt lift()} of the result
will be legible.

The library syntax is $\teb{factmod9}(x,p,a)$.

\subsecidx{factorial}$(x)$ or $x!$: factorial of $x$. The expression $x!$
gives a result which is an integer, while {\tt fact}$(x)$ gives a real
number.

The library syntax is $\teb{mpfact}(x)$ for $x!$ and $\teb{mpfactr}(x,prec)$
for {\tt fact}$(x)$. $x$ must be a C-long integer and not a PARI integer.

\subsecidx{factormod}$(x,p,\{flag=0\})$: factor mod $p$ the polynomial $x$,
using Berlekamp. The coefficients of $x$ must be operation-compatible with
$\Z/p\Z$. The result is a two-column matrix, the first column being
the irreducible polynomials dividing $x$, and the second the exponents. If
$flag$ is non-zero, output only the {\it degrees} of the irreducible
polynomials (for example, for computing an $L$-function). A different
algorithm for computing the mod $p$ factorization is {\tt factorcantor} which
is sometimes faster.

The library syntax is $\teb{factormod}(x,p,flag)$. Also available are
$\teb{factmod}(x,p)$ (which is equivalent to $\teb{factormod}(x,p,0)$) and
$\teb{simplefactmod}(x,p)$ (= $\teb{factormod}(x,p,1)$).

\subsecidx{fibonacci}$(x)$: $x^{\text{th}}$ Fibonacci number.

The library syntax is $\teb{fibo}(x)$. $x$ must be a
C-long integer and not a PARI integer.

\subsecidx{gcd}$(x,y,\{flag=0\})$: creates the greatest common divisor of $x$
and $y$. $x$ and $y$ can be of quite general types; for instance both
rational numbers. Vector/matrix types are also accepted, in which case
the GCD is taken recursively on each component. Note that for these
types, {\tt gcd} is not commutative.

If $flag=0$, use Euclid's algorithm.

If $flag=1$, use the modular gcd algorithm ($x$ and $y$ have to be
polynomials, with integer coefficients).

If $flag=2$, use the subresultant algorithm.

The library syntax is $\teb{gcd0}(x,y,flag)$. Also available are
$\teb{ggcd}(x,y)$ ( = $\teb{gcd0}(x,y,0)$),
$\teb{modulargcd}(x,y)$ ( = $\teb{gcd0}(x,y,1)$),
$\teb{srgcd}(x,y)$ ( = $\teb{gcd0}(x,y,2)$).

\subsecidx{hilbert}$(x,y,\{p\})$: \idx{Hilbert symbol} of $x$ and $y$ modulo
$p$. If $x$ and $y$ are of type integer or fraction, an explicit third
parameter $p$ must be supplied, $p=0$ meaning the place at infinity.
Otherwise, $p$ need not be given, and $x$ and $y$ can be of compatible types
integer, fraction, real, integermod or $p$-adic.

The library syntax is $\teb{hil}(x,y,p)$.

\subsecidx{isfundamental}$(x)$: true (1) if $x$ is equal to 1 or to the
discriminant of a quadratic field, false (0) otherwise.

The library syntax is $\teb{gisfundamental}(x)$, but the
simpler function $\teb{isfundamental}(x)$ which returns a C-long
should be used if $x$ is known to be of type integer.

\subsecidx{isprime}$(x)$: true (1) if $x$ is a strong pseudo-prime
for 10 randomly chosen bases, false (0) otherwise.

The library syntax is $\teb{gisprime}(x)$, but the
simpler function $\teb{isprime}(x)$ which returns a C-long
should be used if $x$ is known to be of type integer.

\subsecidx{ispseudoprime}$(x)$: true (1) if $x$ is a strong 
pseudo-prime for a randomly chosen base, false (0) otherwise.

The library syntax is $\teb{gispsp}(x)$, but the
simpler function $\teb{ispsp}(x)$ which returns a C-long
should be used if $x$ is known to be of type integer.

\subsecidx{issquare}$(x)$: true (1) if $x$ is square, false if not. $x$
can be of any type.

The library syntax is $\teb{gcarreparfait}(x)$. In the case where $x$ is
known to be of type integer, the function $\teb{carrecomplet}(x,\&r)$
which returns a C-long should be used, since not only does it give the
answer (true or false), but in the case where $x$ is indeed a square, puts
the integer square root in $r$.

\subsecidx{issquarefree}$(x)$: true (1) if $x$ is squarefree, false if not.
Here $x$ can be an integer or a polynomial.

The library syntax is $\teb{gissquarefree}(x)$, but the
simpler function $\teb{issquarefree}(x)$ which returns a C-long
should be used if $x$ is known to be of type integer.

\subsecidx{kronecker}$(x,y)$: Kronecker \sidx{Legendre symbol}
(i.e.~generalized Legendre) symbol $\left(\dfrac{x}{y}\right)$. $x$ and $y$
must be of type integer and the result ($0$ or $\pm 1$) is a C-long integer.

The library syntax is $\teb{kronecker}(x,y)$.

\subsecidx{lcm}$(x,y)$: least common multiple of $x$ and $y$, i.e.
such that $\text{lcm}(x,y)*\text{gcd}(x,y)=\text{abs}(x*y)$.

The library syntax is $\teb{glcm}(x,y)$.

\subsecidx{moebius}$(x)$: M\"obius $\mu$-function of $x$. $x$ must be of type
integer and the result ($0$ or $\pm 1$) is a C-long integer.

The library syntax is $\teb{mu}(x)$.

\subsecidx{nextprime}$(x)$: finds the smallest prime greater than or
equal to $x$. $x$ must be of type integer. Note that if $x$ is a prime,
this function returns $x$ and not the smallest prime strictly larger than $x$.

The library syntax is $\teb{nextprime}(x)$.

\subsecidx{numdiv}$(x)$: number of divisors of $x$. $x$ must be of type
integer, and the result is a C-long integer.

The library syntax is $\teb{numbdiv}(x)$.

\subsecidx{omega}$(x)$: number of distinct prime divisors of $x$. $x$ must be
of type integer, and the result is a C-long integer.

The library syntax is $\teb{omega}(x)$.

\subsecidx{precprime}$(x)$: finds the largest prime less than or equal to
$x$. $x$ must be of type integer. Returns 0 if $x\le1$.
Note that if $x$ is a prime, this function returns $x$ and not the largest
prime strictly smaller than $x$.


The library syntax is $\teb{precprime}(x)$.

\subsecidx{prime}$(x)$: the $x^{\text{th}}$ prime number, which must be among
the precalculated primes.

The library syntax is $\teb{prime}(x)$. $x$ must be a C-long integer.

\subsecidx{primes}$(x)$: creates a row vector whose components
are the first $x$ prime numbers, which must be among the precalculated primes.

The library syntax is $\teb{primes}(x)$. $x$ must be a C-long integer.

\subsecidx{qfbclassno}$(x,\{flag=0\})$: class number of the quadratic field
of discriminant $x$. In the present version \vers, a simple algorithm is used
for $x>0$, so $x$ should not be too large (say $x<10^7$) for the time to be
reasonable. On the other hand, for $x<0$ one can reasonably compute
classno($x$) for $|x|<10^{25}$, since the method used is Shanks' method which
is in $O(|x|^{1/4})$. For larger values of $|D|$, see {\tt quadclassunit}.

If $flag=1$, compute the class number using Euler products and the functional
equation. However, it is in $O(|x|^{1/2})$.

{\bf Important warning.} For $D<0$, this function often gives incorrect results
when the class group is non-cyclic, because the authors were too lazy to implement
completely Shanks's method. It is therefore strongly advised to use either the 
version with $flag=1$, the function {\tt qfhclassno(-x)} if $x$ is known to be
a fundamental discriminant, or the function {\tt quadclassunit}.

The library syntax is $\teb{qfbclassno0}(x,flag)$. Also available are
$\teb{classno}(x)$ ( = $\teb{qfbclassno}(x)$),
$\teb{classno2}(x)$ ( = $\teb{qfbclassno}(x,1)$), and finally
there exists the function {\tt \idx{classno3}(x)} which computes the class
number of an imaginary quadratic field by counting reduced forms, a $O(|x|)$
algorithm. See also {\tt qfbhclassno} below.

\subsecidx{qfbcompraw}$(x,y)$ composition of the binary quadratic forms $x$
and $y$, without reduction of the result. This is useful e.g. to compute a
generating element of an ideal.

The library syntax is $\teb{compraw}(x,y)$.

\subsecidx{qfbhclassno}$(x)$: \idx{Hurwitz class number} of $x$, where $x$ is
non-negative and congruent to 0 or 3 modulo 4. See also {\tt qfbclassno}
above.

The library syntax is $\teb{hclassno}(x)$.

\subsecidx{qfbnucomp}$(x,y,l)$ composition of the primitive positive definite
binary quadratic forms $x$ and $y$ using the NUCOMP and NUDUPL algorithms of
Shanks (\`a la Atkin). $l$ is any positive constant, but for optimal speed,
one should take $l=|D|^{1/4}$, where $D$ is the common discriminant of $x$
and $y$.

The library syntax is $\teb{nucomp}(x,y,l)$. The auxiliary function
$\teb{nudupl}(x,l)$ should be used instead for speed when $x=y$.

\subsecidx{qfbnupow}$(x,n)$: $n$-th power of the primitive positive definite
binary quadratic form $x$ using the NUCOMP and NUDUPL algorithms (see
{\tt qfbnucomp} above).

The library syntax is $\teb{nupow}(x,n)$.

\subsecidx{qfbpowraw}$(x,n)$ $n$-th power of the binary quadratic form
$x$, computed without doing any reduction (i.e.~using {\tt qfbcompraw}
above). Here $n$ must be non-negative and $n<2^{31}$.

The library syntax is $\teb{powraw}(x,n)$ where $n$ must be a C-long
integer.

\subsecidx{qfbprimeform}$(x,p)$: prime binary quadratic form of discriminant
$x$ whose first coefficient is the prime number $p$. Error if $x$ is not a
quadratic residue mod $p$. In the case where $x>0$, the ``distance''
component of the form is set equal to zero according to the current
precision.

\subsecidx{qfbred}$(x,\{flag=0\},\{D\},\{isqrtD\},\{sqrtD\})$: reduce the
 binary quadratic form $x$. $flag$ can be any of $0$: default behaviour, uses
Shanks's distance function $d$, $1$: use $d$, but perform only a single
reduction step, $2$: do not compute the distance function $d$, or $3$: do not
use $d$, single reduction step.

  $D$, $isqrtD$, $sqrtD$, if present, supply the values of the discriminant,
$\lfloor \sqrt{D}\rfloor$, and $\sqrt{D}$ respectively (no checking is done
of these facts). If $D<0$ these values are useless, and all references to
Shanks's distance are irrelevant whatsoever.

The library syntax is $\teb{qfbred0}(x,flag,D,isqrtD,sqrtD)$. Use NULL
to omit any of $D$, $isqrtD$, $sqrtD$.

\noindent Also available are

 $\teb{redimag}(x)$ ( = $\teb{qfbred}(x)$ where $x$ is definite),

\noindent and for indefinite forms:

$\teb{redreal}(x)$ ( = $\teb{qfbred}(x)$),

$\teb{rhoreal}(x)$ ( = $\teb{qfbred}(x,1)$,

$\teb{redrealnod}(x,sq)$ ( = $\teb{qfbred}(x,2,,isqrtD)$),

$\teb{rhorealnod}(x,sq)$ ( = $\teb{qfbred}(x,3,,isqrtD)$).

The library syntax is $\teb{primeform}(x,p,prec)$, where the third
variable $prec$ is a C-long integer, but is necessary only when $x>0$.

\subsecidx{quadclassunit}$(D,\{flag=0\},\{tech=[]\})$: Buchmann-McCurley's
sub-exponential algorithm for computing the class group of a
quadratic field of discriminant $D$. Should be used instead of
{\tt qfbclassno} or {\tt quadregula} when $D<-10^{25}$, $D>10^{10}$, or when
the {\it structure} is wanted. If $flag$ is non-zero {\it and} $D>0$, compute
the narrow class group and regulator, instead of the ordinary (or wide) ones.
$tech$ is a row vector of the form $[c_1,c_2]$, where $c_1$ and $c_2$ are
positive real numbers which control the execution time and the stack size. To
get maximum speed, set $c_2=c$. To get a rigorous result (under GRH) you must
take $c_2=6$. Reasonable values for $c$ are between $0.1$ and $2$. 

The result of this function is a vector with 4 components if $D<0$, and $5$
otherwise. The first is the class number, the second is a vector giving the
structure of the class group as a product of cyclic groups, and the third is
a vector giving as binary quadratic forms generators of those cyclic groups.
If $D>0$, the fourth component is the regulator, computed to an accuracy
which is the maximum of an internal accuracy determined by the program and
the current default (note that once the regulator is known to a small
accuracy it is trivial to compute it to very high accuracy. I leave this as
an exercise to the reader, or see the tutorial). The last component is a
measure of the correctness of the result. If it is close to 1, the result is
correct (under GRH). If it is close to a larger integer, this shows that the
class number is off by a factor equal to this integer, and you must start
again with a larger value for $c_1$ or a different random seed. In this case,
a warning message is printed.

The library syntax is $quadclassunit0(D,flag,tech)$. Also available are
$\teb{buchimag}(D,c_1,c_2)$ and $\teb{buchreal}(D,flag,c_1,c_2)$.

\subsecidx{quaddisc}$(x)$: discriminant of the quadratic field
$\Q(\sqrt{x})$, where $x\in\Q$. Up to trivial 2-factors, this function
can also be used to compute the squarefree part of $x$.

The library syntax is $\teb{quaddisc}(x)$.

\subsecidx{quadhilbert}$(D,\{flag=0\})$: relative equation for the Hilbert
class field of the quadratic field of discriminant $D$. If flag is non-zero
and $D<0$, output $[form,root(form)]$ (to be used for constructing subfields).
Uses complex multiplication in the imaginary case and Stark units in the real
case.

The library syntax is $\teb{quadhilbert}(D,flag,prec)$.

\subsecidx{quadgen}$(x)$: creates the quadratic number \sidx{omega}
$\omega=(a+\sqrt{x})/2$ where $a=0$ if $x\equiv0\mod4$, 
$a=1$ if $x\equiv1\mod4$, so that $(1,\omega)$ is an integral basis for
the quadratic order of discriminant $x$. $x$ must be an integer congruent to 
0 or 1 modulo 4.

The library syntax is $\teb{quadgen}(x)$.

\subsecidx{quadpoly}$(x)$: creates the ``canonical'' quadratic
polynomial corresponding to the discriminant $x$, i.e.~the minimal polynomial
of {\tt quadgen(x)}. $x$ must be an integer congruent to 0 or 1 modulo 4.

The library syntax is $\teb{quadpoly}(x)$.

\subsecidx{quadregulator}$(x)$: regulator of the quadratic field of positive
discriminant $x$. Error if $x$ is not a discriminant (fundamental or not) or
if $x$ is a square. See also {\tt quadclassunit} if $x$ is large.

The library syntax is $\teb{regula}(x,prec)$.

\subsecidx{quadunit}$(x)$: \idx{fundamental unit} of the real quadratic field
$\Q(\sqrt x)$ where  $x$ is the positive discriminant of the field. If
$x$ is not a fundamental discriminant, this probably gives the fundamental
unit of the corresponding order. $x$ must be of type integer, and the result
is a quadratic number.

The library syntax is $\teb{fundunit}(x)$.

\subsecidx{removeprimes}$(\{x=[\,]\})$: remove the primes listed in $x$ from
the prime number table. $x$ can also be a single integer. List the current
extra primes if $x$ is omitted.

The library syntax is $\teb{removeprimes}(x)$.

\subsecidx{sigma}$(x,\{k=1\})$: sum of the $k^{\text{th}}$ powers of the
positive divisors of $x$. $x$ must be of type integer.

The library syntax is $\teb{sumdiv}(x)$ ( = $\teb{sigma}(x)$) or
$\teb{gsumdivk}(x,k)$ ( = $\teb{sigma}(x,k)$), where $k$ is a C long integer.

\subsecidx{sqrtint}$(x)$: integer square root of $x$, which must be of PARI
type integer. The result is non-negative and rounded towards zero. A
negative $x$ is allowed, and the result in that case is {\tt I*sqrtint(-x)}. 

The library syntax is $\teb{racine}(x)$.

\subsecidx{znorder}$(x)$: $x$ must be an integer mod $n$, and the result is the
order of $x$ in the multiplicative group $(\Z/n\Z)^*$. Error if $x$
is not invertible.

The library syntax is $\teb{order}(x)$.

\subsecidx{znprimroot}$(x)$: returns a primitive root of $x$, where $x$
is a prime power.

The library syntax is $\teb{gener}(x)$.

\subsecidx{znstar}$(n)$: gives the structure of the multiplicative group
$(\Z/n\Z)^*$ as a 3-component row vector $v$, where $v[1]=\phi(n)$ is the
order of that group, $v[2]$ is a $k$-component row-vector $d$ of integers
$d[i]$ such that $d[i]>1$ and $d[i]\mid d[i-1]$ for $i\ge2$ and
$(\Z/n\Z)^*\simeq\prod_{i=1}^k(\Z/d[i]\Z)$, and $v[3]$ is a $k$-component row
vector giving generators of the image of the cyclic groups $\Z/d[i]\Z$.

The library syntax is $\teb{znstar}(n)$.

\section{Functions related to elliptic curves.}

We have implemented a number of functions which are useful for number
theorists working on elliptic curves. We always use Tate's notations.

The functions assume that the curve is given by a general Weierstrass model

$$y^2+a_1xy+a_3y=x^3+a_2x^2+a_4x+a_6,$$

where a priori the $a_i$ can be of any scalar type. This curve can be
considered as a five component vector {\tt E=[a1,a2,a3,a4,a6]}, but for most
functions it is useful to have at one's disposal more information. This is
given by the function {\tt ellinit} (see below), which usually gives a 19
component vector (which we will call a long vector in this section). If a
specific flag is added, a vector with only 13 component will be output (which
we will call a medium vector). A medium vector just gives the first 13
components of the long vector corresponding to the same curve, but is of
course faster to compute.

\noindent The following \idx{member functions} are available to deal with the
output of {\tt ellinit}:
\settabs\+xxxxxxxxxxxxxxxxxx& : &\cr

\+ {\tt a1}--{\tt a6}, {\tt b2}--{\tt b8}, {\tt c4}--{\tt c6} & : &
coefficients of the elliptic curve.\cr

\+ {\tt \idx{area}} & : &  volume of the complex lattice defining $E$.\cr

\+ {\tt \idx{disc}} & : & discriminant of the curve.\cr

\+ {\tt \idx{j}}    & : & $j$-invariant of the curve.\cr

\+ {\tt \idx{omega}} & : & $[\omega_1,\omega_2]$, periods forming a basis of
the complex lattice defining $E$ ($\omega_1$ is the\cr

\+                   &   & real period, and $\omega_2/\omega_1$ belongs to
Poincar\'e's half-plane).\cr

\+ {\tt \idx{eta}}   & : & quasi-periods $[\eta_1, \eta_2]$, such that
$\eta_1\omega_2-\eta_2\omega_1=i\pi$.\cr

\+ {\tt \idx{roots}} & : & roots of the associated Weierstrass equation.\cr

\+ {\tt \idx{tate}} & : & $[u^2,u,v]$ in the notation of Tate.\cr

\+ {\tt \idx{w}} & : & Mestre's $w$ (this is technical).\cr

Their use is best described by an example: assume that $E$ was output by {\tt
ellinit}, then typing {\tt E.disc} will retrieve the curve's discriminant.
The member functions {\tt area}, {\tt eta} and {\tt omega} are only
available for curves over $\Q$. Conversely, {\tt tate} and {\tt w} are only
available for curves defined over $\Q_p$.\smallskip

Some functions, in particular those relative to height computations (see 
{\tt ellheight} below) require also that the curve be in minimal Weierstrass
form. This is achieved by the function {\tt ellglobalred} below.

Points on elliptic curves are represented as two-component vectors
{\tt [x,y]}, except for the point at infinity, i.e.~the identity element of
the group law, represented by the one-component vector {\tt [0]}.

All functions related to elliptic curves share the prefix {\tt ell}, and the
precise curve we are interested in is always the first argument, in either
one of the three format discussed above, unless otherwise specified. For
instance, in functions which do not use the extra information given by long
vectors, the curve can be given either as a five component vector, or by one
of the longer vectors computed by {\tt ellinit}.

\subsecidx{elladd}$(E,z1,z2)$: sum of the points $z1$ and $z2$ on the
elliptic curve corresponding to the vector $E$.

The library syntax is $\teb{addell}(E,z1,z2)$.

\subsecidx{ellak}$(E,n)$: compute the coefficient $a_n$ of the $L$-function
of the elliptic curve $E$, i.e.~in principle coefficients of a newform of
weight 2 assuming Taniyama-Weil. $E$ must be a medium or long vector of the
type given by {\tt ellinit}. For this function to work for every $n$ and not
just those prime to the conductor, $E$ must be a minimal Weierstrass
equation. If this is not the case, use the function {\tt ellglobalred} first
before using {\tt ellak}.

The library syntax is $\teb{akell}(E,n)$.

\subsecidx{ellan}$(E,n)$: compute the vector of the first $n$ $a_k$
corresponding to the elliptic curve $E$. All comments in {\tt ellak}
description remain valid.

The library syntax is $\teb{anell}(E,n)$, where $n$ is a C integer.

\subsecidx{ellap}$(E,p,\{flag=0\})$: compute the $a_p$ corresponding to the
elliptic curve $E$ and the prime number $p$. These are defined by the
equation $\#E(\F_p)=p+1-a_p$, where $\#E(\F_p)$ stands for the number
of points of the curve $E$ over the finite field $\F_p$. When $flag$ is
$0$, this uses the baby-step giant-step method and a trick due to Mestre

  If $flag$ is $1$, compute the $a_p$ as a sum of Legendre symbols. This is
slower than the previous method as soon as $p$ is greater than 100, say.

No checking is done that $p$ is indeed prime. $E$ must be a medium or long
vector of the type given by {\tt ellinit}.

The library syntax is $\teb{ellap0}(E,p,flag)$. Also available are
$\teb{apell}(E,p)$, corresponding to $flag=0$, and $\teb{apell2}(E,p)$
($flag=1$).

\subsecidx{ellbil}$(E,z1,z2)$: If $z1$ and $z2$ are points on the elliptic
curve $E$, this function computes the value of the canonical bilinear form on
$z1$, $z2$, i.e.~{\tt ellheight(E,z1$+$z2)-ellheight(E,z1)-ellheight(E,z2)},
where $+$ denotes of course addition on $E$. In addition, $z1$ or $z2$ (but
not both) can be vectors or matrices. Note that this is equal to twice some
normalizations.

The library syntax is $\teb{bilhell}(E,z1,z2,prec)$.

\subsecidx{ellchangecurve}$(E,v)$: change the data for the elliptic curve $E$
by changing the coordinates using the vector {\tt v=[u,r,s,t]}, i.e.~if $x'$
and $y'$ are the new coordinates, then $x=u^2x'+r$, $y=u^3y'+su^2x'+t$.
The vector $E$ must be a medium or long vector of the type given by
{\tt ellinit}.

The library syntax is $\teb{coordch}(E,v)$.

\subsecidx{ellchangepoint}$(x,v)$: change the coordinates of the point or
vector of points $x$ using the vector {\tt v=[u,r,s,t]}, i.e.~if $x'$ and
$y'$ are the new coordinates, then $x=u^2x'+r$, $y=u^3y'+su^2x'+t$ (see also
{\tt ellchangecurve} above).

The library syntax is $\teb{pointch}(x,v)$.

\subsecidx{ellglobalred}$(E)$: calculate the arithmetic conductor, the global
minimal model of $E$ and the global Tamagawa number $c$. Here $E$ is an
elliptic curve given by a medium or long vector of the type given by  
{\tt ellinit}, {\it and is supposed to have all its coefficients $a_i$ in}
$\Q$. The result is a 3 component vector $[N,v,c]$. $N$ is the arithmetic
conductor of the curve, $v$ is itself a vector $[u,r,s,t]$ with rational
components. It gives a coordinate change for $E$ over $\Q$ such that the
resulting model has integral coefficients, is everywhere minimal, $a_1$ is 0
or 1, $a_2$ is 0, 1 or $-1$ and $a_3$ is 0 or 1. Such a model is unique, and
the vector $v$ is unique if we specify that $u$ is positive. To get the new
model, simply type {\tt ellchangecurve(E,v)}. Finally $c$ is the product of
the local Tamagawa numbers $c_p$, a quantity which enters in the Birch and
Swinnerton-Dyer conjecture.

The library syntax is $\teb{globalreduction}(E)$.

\subsecidx{ellheight}$(E,z,\{flag=0\})$: global \idx{N\'eron-Tate height} of
the point $z$ on the elliptic curve $E$. The vector $E$ must be a long vector
of the type given by {\tt ellinit}, with $flag$ $1$. If $flag=0$, this
computation is done using sigma and theta-functions and a trick due to J.
Silverman. If $flag=1$, use Tate's $4^n$ algorithm, which is much slower. 

The library syntax is $\teb{ellheight0}(E,z,flag,prec)$. The archimedean
contribution alone is given by the library function $\teb{hell}(E,z,prec)$. 
Also available are $\teb{ghell}(E,z,prec)$ ($flag=0$) and
$\teb{ghell2}(E,z,prec)$ ($flag=1$).

\subsecidx{ellheightmatrix}$(E,x)$: $x$ being a vector of points, this
function outputs the Gram matrix of $x$ with respect to the N\'eron-Tate
height, in other words, the {\tt (i,j)} component of the matrix is
equal to {\tt ellheight(E,x[i]+x[j])-ellheight(E,x[i])-ellheight(E,x[j])},
where {\tt x[i]+x[j]} denotes of course the sum of the points on the curve
$E$. The rank of this matrix, at least in some approximate sense, gives the
rank of the set of points, and if $x$ is a basis of the Mordell-Weil group of
$E$, its determinant is equal to the regulator of $E$. Note that this matrix
should be divided by 2 to be in accordance with certain normalizations.

The library syntax is $\teb{mathell}(E,x,prec)$.

\subsecidx{ellinit}$(E,\{flag=0\})$: compute some fixed data concerning the
elliptic curve given by the five component vector $E$, which will be
essential for most further computations on the curve. The result is a
19-component vector E (called a long vector in this section), shortened
to 13 components (medium vector) if $flag=1$. Both contain the
following information in the first 13 components:
%
$$ a_1,a_2,a_3,a_4,a_6,b_2,b_4,b_6,b_8,c_4,c_6,\Delta,j.$$
%
In particular, the discriminant is $E[12]$ (or {\tt E.disc}), and the
$j$-invariant is $E[13]$ (or {\tt E.j}). 

The other six components are only present if $flag$ is $0$ (or omitted!).
Their content depends on whether the curve is defined over $\R$ or not:
\smallskip
$\bullet$ When $E$ is defined over $\R$, $E[14]$ ({\tt E.roots}) is a
vector whose three components contain the roots of the associated Weierstrass
equation. If the roots are all real, then they are ordered by decreasing
value. If only one is real, it is the first component of $E[14]$.

$E[15]$ ({\tt E.omega[1]}) is the real period of $E$ (integral of
$dx/(2y+a_1x+a_3)$ over the connected component of the identity element of
the real points of the curve), and $E[16]$ ({\tt E.omega[2]}) is a complex
period. In other words, $\omega_1=E[15]$ and $\omega_2=E[16]$ form a basis of
the complex lattice defining $E$ ({\tt E.omega}), with
$\tau=\dfrac{\omega_2}{\omega_1}$ having positive imaginary part.

$E[17]$ and $E[18]$ are the corresponding values $\eta_1$ and $\eta_2$ such
that $\eta_1\omega_2-\eta_2\omega_1=i\pi$, and both can be retrieved by
typing {\tt E.eta} (horizontal vector whose components are the $\eta_i$).

Finally, $E[19]$ ({\tt E.area}) is the volume of the complex lattice defining
$E$.\smallskip

$\bullet$ When $E$ is defined over $\Q_p$, the $p$-adic valuation of $j$
must be negative. Then $E[14]$ ({\tt E.roots}) is the vector with a single
component equal to the $p$-adic root of the associated Weierstrass equation
corresponding to $-1$ under the Tate parametrization.

$E[15]$ is equal to the square of the $u$-value, in the notation of Tate.

$E[16]$ is the $u$-value itself, if it belongs to $\Q_p$, otherwise zero.

$E[17]$ is the value of Tate's $q$ for the curve $E$.

{\tt E.tate} will yield the three component vector $[u^2,u,q]$.

$E[18]$ ({\tt E.w}) is the value of Mestre's $w$ (this is technical), and
$E[19]$ is arbitrarily set equal to zero.
\smallskip
For all other base fields or rings, the last six components are
arbitrarily set equal to zero.

(see also the description of member functions related to elliptic curves at
the beginning of this section).

The library syntax is $\teb{ellinit0}(E,flag,prec)$. Also available are
$\teb{initell}(E,prec)$ ($flag=0$) and $\teb{smallinitell}(E,prec)$ ($flag=1$).

\subsecidx{ellisoncurve}$(E,z)$: gives 1 (i.e.~true) if the point $z$ is on
the elliptic curve $E$, 0 otherwise. If $E$ or $z$ have imprecise coefficients,
an attempt is made to take this into account, i.e.~an imprecise equality is
checked, not a precise one.

The library syntax is $\teb{oncurve}(E,z)$, and the result is a
C-long integer.

\subsecidx{ellj}$(x)$: elliptic $j$-invariant. $x$ must be a complex number
with positive imaginary part, or convertible into a power series or a
$p$-adic number with positive valuation.

The library syntax is $\teb{jell}(x,prec)$.

\subsecidx{elllocalred}$(E,p)$: calculate the Kodaira type of the local fiber
of the elliptic curve $E$ at the prime $p$. $E$ must be given by a medium or
long vector of the type given by {\tt ellinit}, and is assumed to have all
its coefficients $a_i$ in $\Z$. The result is a 4-component vector
$[f,kod,v,c]$. Here $f$ is the exponent of $p$ in the arithmetic conductor of
$E$, and $kod$ is the Kodaira type which is coded as follows:

1 means good reduction (type I$_0$), 2, 3 and 4 mean types II, III and IV 
respectively, $4+\nu$ with $\nu>0$ means type I$_\nu$;
finally the opposite values $-1$, $-2$, etc. refer to the starred types 
I$_0^*$, II$^*$, etc. The third component $v$ is itself a vector $[u,r,s,t]$
giving the coordinate changes done during the local reduction. Normally, this
has no use if $u$ is 1, that is, if the given equation was already minimal.
Finally, the last component $c$ is the local Tamagawa number $c_p$.

The library syntax is $\teb{localreduction}(E,p)$.

\subsecidx{ellorder}$(E,z)$: gives the order of the point $z$ on the elliptic
curve $E$ if it is a torsion point, zero otherwise. In the present version
\vers{}, this is implemented only for elliptic curves defined over $\Q$.

The library syntax is $\teb{orderell}(E,z)$, and the result is a \kbd{GEN}.

\subsecidx{ellordinate}$(E,x)$: gives a 0, 1 or 2-component vector containing
the $y$-coordinates of the points of the curve $E$ having $x$ as 
$x$-coordinate.

The library syntax is $\teb{ordell}(E,x)$.

\subsecidx{ellpointtoz}$(E,z)$: If $E$ is an elliptic curve with coefficients
in $\R$, this computes a complex number $t$ (modulo the lattice defining
$E$) corresponding to the point $z$, i.e.~such that, in the standard
Weierstrass model, $\wp(t)=z[1],\wp'(t)=z[2]$. In other words, this is the
inverse function of {\tt ellztopoint}.

If $E$ has coefficients in $\Q_p$, then either Tate's $u$ is in $\Q_p$, in
which case the output is a $p$-adic number $t$ corresponding to the point $z$
under the Tate parametrization, or only its square is, in which case the
output is $t+1/t$. $E$ must be a long vector output by {\tt ellinit}.

The library syntax is $\teb{zell}(E,z,prec)$.

\subsecidx{ellpow}$(E,z,n)$: computes $n$ times the point $z$ for the
group law on the elliptic curve $E$. Here, $n$ can be in $\Z$, or $n$
can be a complex quadratic integer if the curve $E$ has complex multiplication
by $n$ (if not, an error message is issued).

The library syntax is $\teb{powell}(E,z,n)$.

\subsecidx{elllseries}$(E,s,N,A)$: $E$ being a medium or long vector given by
{\tt ellinit}, this computes the value of the L-series of $E$ at $s$. It is
assumed that: $E$ is a minimal model over $\Z$, $N$ is equal to plus or
minus the conductor depending on the sign of the functional equation, that
the curve is a Weil curve. $A$ is a cutoff point for the integral, which must
be chosen close to 1 for best speed. The result being independent of $A$,
this function can be used to compute the sign of the functional equation, and
even $N$ if one wants, although it is always much faster to apply the
function {\tt ellglobalred}. 

Note that if the conductor of the curve is large, say greater than $10^{12}$,
this function will take an unreasonable amount of time since it uses a
$O(N^{1/2})$ algorithm.

The library syntax is $\teb{lseriesell}(E,s,N,A,prec)$ where $prec$ is a
C-long integer.

\subsecidx{ellsub}$(E,z1,z2)$: difference of the points $z1$ and $z2$ on the
elliptic curve corresponding to the vector $E$.

The library syntax is $\teb{subell}(E,z1,z2)$.

\subsecidx{elltaniyama}$(E)$: computes the modular parametrization of the
elliptic curve $E$, where $E$ is given in the (long or medium) format output
by {\tt ellinit}), in the form of a two-component vector $[u,v]$ of power
series, given to the current default series precision. This vector is
characterized by the following two properties. First the point $(x,y)=(u,v)$
satisfies the equation of the elliptic curve. Second, the differential
$du/(2v+a_1u+a_3)$ is equal to $f(z)dz$, a differential form on
$H/\Gamma_0(N)$ where $N$ is the conductor of the curve. The variable used in
the power series for $u$ and $v$ is $x$, which is implicitly understood to be
equal to $\exp(2i\pi z)$. It is assumed that the curve is a {\it strong} Weil
curve, and the Manin constant is equal to 1. The equation of the curve $E$
must be minimal (use {\tt ellglobalred} to get a minimal equation).

The library syntax is $\teb{taniyama}(E)$, and the precision of the result is
determined by the global variable {\tt precdl}.

\subsecidx{elltors}$(E)$: If $E$ is an elliptic curve defined over $\Q$,
this outputs the torsion subgroup of $E$ as a 3-component vector
{\tt [t,v1,v2]} with the following meaning. {\tt t} is the order of the
torsion group. {\tt v1} is a 0, 1 or 2-component vector giving the structure
of the torsion group as a product of cyclic groups, with {\tt v1[2]=2} if it
exists. Finally {\tt v2}, which is a vector of the same length as {\tt v1},
gives generators for these cyclic groups. $E$ must be a (long or medium)
vector as output by {\tt ellinit}.

The library syntax is $\teb{torsell}(E)$.

\subsecidx{ellwp}$(E)$: Computes the {\it power series\/} expansion in $x$
(starting $x^{-2}+O(x^2)$) of the Weierstrass $\wp$ function attached to the
elliptic curve $E$ as given by {\tt ellinit}. The number of terms to an
{\it even\/} power in the expansion is the default serieslength in GP, and
the second argument (C long integer) in library mode.

The library syntax is $\teb{weipell}(E,prec)$.

\subsecidx{ellztopoint}$(E,z)$: $E$ being a long vector, computes the
coordinates $[x,y]$ on the curve $E$ corresponding to the complex number $z$.
Hence this is the inverse function of {\tt ellpointtoz}. In other words, if
the curve is put in Weierstrass form, $[x,y]$ represent the Weierstrass
$\wp$-function and its derivative. If $z$ is in the lattice defining $E$ over
$\C$, the result is the point at infinity $[0]$.

The library syntax is $\teb{pointell}(E,z,prec)$.

\section{Functions related to general number fields.}

In this section can be found functions which are used almost exclusively for
working in general number fields. Other less specific functions can be found
in the next section on polynomials. Functions related to quadratic number
fields can be found in Section~3.4 above.

\noindent We shall use the following conventions:

$\bullet$ $\idx{nf}$ denotes a number field, i.e.~a 9-component vector in the
format output by {\tt nfinit}. This contains the basic arithmetic data
associated to the number field: signature, maximal order, discriminant, etc.

$\bullet$ $\idx{bnf}$ denotes a big number field, i.e.~a 10-component vector
in the format output by {\tt bnfinit}. This contains $nf$ and the deeper
invariants of the field: units, class groups, as well as a lot of technical
data necessary for some complex fonctions like {\tt bnfisprincipal}.

$\bullet$ $\idx{bnr}$ denotes a big ``ray number field'', i.e.~some data
structure output by {\tt bnrinit}, even more complicated than $bnf$,
corresponding to the ray class group structure of the field, for some
modulus.

$\bullet$ $\idx{rnf}$ denotes a relative number field (see below).
\smallskip

$\bullet$ ${\it \idx{ideal}}$ can mean any of the following:

\quad -- a $\Z$-basis, in Hermite Normal Form (HNF) or not. In
this case $x$ is a square matrix.

\quad -- an {\it \idx{idele}}, i.e.~a 2-component vector, the first
being an ideal given as a $\Z$--basis, the second being a $r_1+r_2$-component
row vector giving the complex logarithmic archimedean information.

\quad -- a $\Z_K$-generating system for an ideal.

\quad -- a {\it column} vector $x$ expressing an element of the number field
on the integral basis, in which case the ideal is treated as being the
principal idele (or ideal) generated by $x$.

\quad -- a prime ideal, i.e.~a 5-component vector in the format output by {\tt
idealprimedec}.

\quad -- a polmod $x$, i.e.~an algebraic integer, in which case the ideal
is treated as being the principal idele generated by $x$.

\quad -- an integer or a rational number, also treated as a principal idele.

{\bf Warnings.}

1) An element in $nf$ can be expressed either as a polmod or as a vector of
components on the integral basis $nf[7]$. It is absolutely essential that all
such vectors be {\it column\/} vectors.

2) When giving an ideal by a $\Z_K$ generating system to a function expecting
an ideal, it must be ensured that the function understands that it is a
$\Z_K$-generating system and not a $\Z$-generating system. When the number
of generators is strictly less than the degree of the field, there is no
ambiguity and the program assumes that one is giving a $\Z_K$-generating set.
When the number of generators is greater than or equal to the degree of the
field, however, the program assumes on the contrary that you are giving a
$\Z$-generating set. If this is not the case, you {\it must\/} absolutely
change it into a $\Z$-generating set, the simplest manner being to use {\tt
idealmul(nf,x,matid(N))} where $N$ is the degree of the field.

Concerning relative extensions, some additional definitions are necessary.

$\bullet$ A {\it \idx{relative matrix}\/} will be a matrix whose entries are
elements of a (given) number field $nf$, always expressed as column vectors
on the integral basis $nf[7]$ (or {\tt nf.zk}). Hence it is a matrix of
vectors.

$\bullet$ An {\it \idx{ideal list}\/} will be a row vector of (fractional)
ideals of the number field $nf$.

$\bullet$ A {\it \idx{pseudo-matrix}\/} will be a pair $(A,I)$ where $A$ is a
relative matrix and $I$ an ideal list whose length is the same as the number
of columns of $A$. This pair will be represented by a 2-component row vector.

$\bullet$ The {\it \idx{module}\/} generated by a pseudo-matrix $(A,I)$ is
the sum $\sum_i\a_jA_j$ where the $\a_j$ are the ideals of $I$ and $A_j$ is
the $j$-th column of $A$.

$\bullet$ A pseudo-matrix $(A,I)$ is a {\it \idx{pseudo-basis}} of the module it
generates if $A$ is a square matrix with non-zero determinant and all the
ideals of $I$ are non-zero. We say that it is in Hermite Normal Form (HNF) if
it is upper triangular and all the elements of the diagonal are equal to 1.

$\bullet$ The {\it determinant\/} of a pseudo-basis $(A,I)$ is the ideal
equal to the product of the determinant of $A$ by all the ideals of $I$. The
determinant of a pseudo-matrix is the determinant of any pseudo-basis of the
module it generates.

Finally, when defining a relative extension, the base field should be
defined by a variable having a lower priority (i.e.~a higher number)
than the variable defining the extension. For example, under GP you can
use the variable name $y$ (or $t$) to define the base field, and the
variable name $x$ to define the relative extension.

Now a last set of definitions concerning the way big ray number fields (or
$bnr$) are input, using class field theory. These are defined by a triple
$a1$, $a2$, $a3$, where the defining set $[a1,a2,a3]$ can have any of the
following forms: $[bnr]$, $[bnr,subgroup]$, $[bnf,module]$,
$[bnf,module,subgroup]$, where:

$\bullet$ $bnf$ is as output by {\tt bnfclassunit} or {\tt bnfinit}, where
units are mandatory unless the ideal is trivial; $bnr$ by {\tt bnrclass}
(with $flag>0$) or {\tt bnrinit}. This is the ground field.

$\bullet$ $module$ is either an ideal in any form (see above) or a
two-component row vector containing an ideal and an $r_1$-component row
vector of flags indicating which real Archimedean embeddings to take in the
module.

$\bullet$ $subgroup$ is the HNF matrix of a subgroup of the ray class group
of the ground field for the modulus $module$. This is input as a square
matrix expressing generators of a subgroup of the ray class group {\tt
bnr.clgp} on the given generators.

The corresponding $bnr$ is then the subfield of the ray class field of the
ground field for the given modulus, associated to the given subgroup.

All the functions which are specific to relative extensions, number
fields, big number fields, big number rays, share the prefix {\tt
rnf}, {\tt nf}, {\tt bnf}, {\tt bnr} respectively. They are meant to
take as first argument a number field of that precise type, respectively
output by {\tt rnfinit}, {\tt nfinit}, {\tt bnfinit}, and {\tt bnrinit}.

However, and even though it may not be specified in the descriptions of the
functions below, it is permissible, if the function expects a $nf$, to use a
$bnf$ instead (which contains much more information). The program will make
the effort of converting to what it needs. On the other hand, if the program
requires a big number field, the program will {\it not\/} launch {\tt
bnfinit} for you, which can be a costly operation. Instead, it will give you
a specific error message.

The data types corresponding to the structures described above are rather
complicated. Thus, as we already have seen it with elliptic curves, GP
provides you with some ``member functions'' to retrieve the data you need
from these structures (once they have been initialized of course). The
relevant types of number fields are indicated between parentheses:
\smallskip

\settabs\+xxxxxxx&(bnr,x&bnf,x&nf\hskip2pt&)x& : &\cr

\+{\tt \idx{bnf}}    &(bnr,& bnf&&)& : & big number field.\cr

\+{\tt \idx{clgp}}  &(bnr,& bnf&&)& : & classgroup. This one admits the
following three subclasses:\cr

\+      \quad {\tt\idx{cyc}} &&&&& : & \quad cyclic decomposition (SNF).\cr

\+      \quad {\tt\idx{gen}} &&&&& : & \quad generators.\cr

\+      \quad {\tt\idx{no}}  &&&&& : & \quad number of elements.\cr

\+{\tt \idx{diff}}  &(bnr,& bnf,& nf&)& : & the different ideal.\cr

\+{\tt \idx{codiff}}&(bnr,& bnf,& nf&)& : & the codifferent (inverse of the
different in the ideal group).\cr

\+{\tt \idx{disc}}  &(bnr,& bnf,& nf&)& : & discriminant.\cr

\+{\tt \idx{fu}}    &(bnr,& bnf,& nf&)& : & fundamental units.\cr

\+{\tt \idx{futu}}  &(bnr,& bnf&&)& : & $[u,w]$, $u$ is a vector of fundamental
units, $w$ generates the torsion.\cr

\+{\tt \idx{nf}}    &(bnr,& bnf,& nf&)& : & number field.\cr

\+{\tt \idx{reg}}   &(bnr,& bnf,&&)&: & regulator.\cr

\+{\tt \idx{roots}} &(bnr,& bnf,& nf&)& : & roots of the polnomial generating
the field.\cr

\+{\tt \idx{sign}}  &(bnr,& bnf,& nf&)& : & $[r_1,r_2]$ the signature of the
field. This means that the field has $r_1$ real \cr
\+ &&&&&&  embeddings, $2r_2$ complex ones.\cr

\+{\tt \idx{t2}}    &(bnr,& bnf,& nf&)& : & the T2 matrix (see {\tt nfinit}
below).\cr

\+{\tt \idx{tu}}    &(bnr,& bnf,&&)& : & a generator for the torsion units.\cr

\+{\tt \idx{tufu}}  &(bnr,& bnf,&&)& : & as {\tt futu}, but outputs $[w,u]$.\cr

\+{\tt \idx{zk}}    &(bnr,& bnf,& nf&)& : & integral basis, i.e.~a $\Z$-basis
of the maximal order.\cr

\+{\tt \idx{zkst}}  &(bnr&    &    &)& : & structure of $(\Z_K/m)^*$
(can be extracted from an $idealstar$ also).\cr

For instance, assume that ${\tt bnf = bnfinit}(pol)$, for some polynomial.
Then {\tt bnf.clgp} retrieves the class group, and {\tt bnf.clgp.no} the
class number. If we had set ${\tt bnf = nfinit}(pol)$, both would have output
an error message. All these functions are completely recursive, thus for
instance {\tt bnr.bnf.nf.zk} will yield the maximal order of {\tt bnr} (which
you could get directly with a simple {\tt bnr.zk} of course).

\medskip
The following functions, starting with ``{\tt buch}'' in library mode, and
with ``{\tt bnf}'' under GP, are implementations of the sub-exponential
algorithms for finding class and unit groups under the GRH, due to
Hafner-McCurley, Buchmann and Cohen-Diaz-Olivier.

The general call to the functions concerning class groups of general number
fields (i.e.~excluding {\tt quadclassunit}) involves a polynomial $P$ and a
technical vector $$tech=[c,c2,nrel,borne,nrpid,minsfb],$$
where the parameters are to be understood as follows:

$P$ is the defining polynomial for the number field, which must be in
$\Z[X]$, irreducible and, preferably, monic. In fact, if you supply a
non-monic polynomial at this point, GP will issue a warning, then {\sl
transform your polynomial} so that it becomes monic. Instead of the normal
result, say {\tt res}, you then get a vector {\tt [res,Mod(a,Q)]}, where {\tt
Mod(a,Q)=Mod(X,P)} gives the change of variables.

The numbers $c$ and $c2$ are positive real numbers which control the
execution time and the stack size. To get maximum speed, set $c2=c$. To get a
rigorous result (under the GRH) you must take $c2=12$ (or $c2=6$ in the
quadratic case, but then you should use the much faster function {\tt
quadclassunit} below). Reasonable values for $c$ are between $0.1$ and $2$.
(Default values $c=c2=0.3$).

$nrel$ is the number of initial extra relations requested in computing the
relation matrix. Reasonable values are between 5 and 20. (Default value is 5).

$borne$ is a multiplicative coefficient of the Minkowski bound which controls
the search for small norm relations. If this parameter is set equal to 0, the
program does not search for small norm relations. Otherwise reasonable values
are between $0.5$ and $2.0$. (Default value is $1.0$).

$nrpid$ is the maximal number of small norm relations associated to each
ideal in the factor base. Irrelevant when $borne=0$. Otherwise, reasonable
values are between 4 and 20. (Default value is 4).

$minsfb$ is the minimal number of elements in the ``sub-factorbase''. If the
program does not seem to succeed in finding a full rank matrix (which you can
see in GP by typing {\tt \bs g 2}), increase this number. Reasonable values
are between 2 and 5. (Default value is 3).

{\bf Remarks.}

Apart from the polynomial $P$, you don't need to supply any of the
technical parameters (under the library you still need to send at least
an empty vector, {\tt cgetg(1,t\_VEC)}). However, should you choose to set
some of them, they {\it must\/} be given in the requested order. For example,
if you want to specify a given value of $nrel$, you must give some values as
well for $c$ and $c2$, and provide a vector $[c,c2,nrel]$. 

Note also that you can use an $nf$ instead of $P$, which avoids recomputing
the integral basis and analogous quantities.

\smallskip
\subsecidx{bnfcertify}$(bnf)$: $bnf$ being a big number field as output by
{\tt bnfinit} or {\tt bnfclassunit}, checks whether the result is correct,
i.e.~whether it is possible to remove the assumption of the Generalized
Riemann Hypothesis. If it is correct, the answer is 1. If not, the program
may output some error message, but more probably will loop indefinitely. In
{\it no\/} occasion can the program give a wrong answer (barring bugs of
course): if the program answers 1, the answer is certified.

The library syntax is $\teb{certifybuchall}(bnf)$, and the result is
a C long.

\subsecidx{bnfclassunit}$(P,\{flag=0\},\{tech=[\,]\})$: Buchmann's
sub-exponential algorithm for computing the class group, the regulator and a
system of fundamental units of the general algebraic number field $K$ defined
by the irreducible polynomial $P$ with integer coefficients.

The result of this function is a vector $v$ with 10 components (it is {\sl
not} a $bnf$, you need {\tt bnfinit} for that), which for ease of
presentation is in fact output as a one column matrix. First we describe the
default behaviour ($flag=0$):

 $v[1]$ is equal to the polynomial $P$. Note that for optimum performance,
$P$ should have gone through {\tt polred} or {\tt nfinit(x,2)}.

 $v[2]$ is the 2-component vector $[r1,r2]$, where $r1$ and $r2$ are as usual
the number of real and half the number of complex embeddings of the number
field $K$.

 $v[3]$ is the 2-component vector containing the field discriminant and the
index.

 $v[4]$ is an integral basis in Hermite normal form.

 $v[5]$ ({\tt v.clgp}) is a 3-component vector containing the class number
({\tt v.clgp.no}), the structure of the class group as a product of cyclic
groups of order $n_i$ ({\tt v.clgp.cyc}), and the corresponding generators of
the class group of respective orders $n_i$ ({\tt v.clgp.gen}).

 $v[6]$ ({\tt v.reg}) is the regulator computed to an accuracy which is the
maximum of an internally determined accuracy and of the default.

 $v[7]$ is a measure of the correctness of the result. If it is close to 1,
the results are correct (under GRH). If it is close to a larger integer, this
shows that the product of the class number by the regulator is off by a
factor equal to this integer, and you must start again with a larger value
for $c$ or a different random seed, i.e.~use the function {\tt setrand}.
(Since the computation involves a random process, starting again with exactly
the same parameters may give the correct result.) In this case a warning
message is printed.
 
 $v[8]$ ({\tt v.tu}) a vector with 2 components, the first being the number
$w$ of roots of unity in $K$ and the second a primitive $w$-th root of unity
expressed as a polynomial.

 $v[9]$ ({\tt v.fu}) is a system of fundamental units also expressed as
polynomials.

 $v[10]$ gives a measure of the correctness of the computations of the
fundamental units (not of the regulator), expressed as a number of bits. If
this number is greater than $20$, say, everything is OK. If $v[10]\le0$,
then we have lost all accuracy in computing the units (usually an error
message will be printed and the units not given). In the intermediate cases,
one must proceed with caution (for example by increasing the current
precision).

If $flag=1$, and the precision happens to be insufficient for obtaining the
fundamental units exactly, the internal precision is doubled and the
computation redone, until the exact results are obtained. The user should be
warned that this can take a very long time when the coefficients of the
fundamental units on the integral basis are very large, for example in the
case of large real quadratic fields. In that case, there are alternate
methods for representing algebraic numbers which are not implemented in PARI.

If $flag=2$, the fundamental units and roots of unity are not computed.
Hence the result has only 7 components, the first seven ones.

$tech$ is a technical vector (empty by default) containing $c$, $c2$, $nrel$,
$borne$, $nbpid$, $minsfb$, in this order (see the beginning of the section).
You can supply any number of these {\it provided you give an actual value to
each of them} (the ``empty arg'' trick won't work here). Careful use of these
parameters may speed up your computations considerably.

The library syntax is \teb{bnfclassunit0}$(P,flag,tech,prec)$.

\subsecidx{bnfclgp}$(P,\{tech=[\,]\})$: as above but only output
$v[5]$, i.e.~the class group.

The library syntax is \teb{bnfclassgrouponly}$(P,tech,prec)$, where tech is
as above.

\subsecidx{bnfdecodemodule}$(nf,m)$: if $m$ is a module as output in the
first component of an extension given by {\tt bnrdisclist}, output the
true module.

The library syntax is $\teb{decodemodule}(nf,m)$.

\subsecidx{bnfinit}$(P,\{flag=0\},\{tech=[\,]\})$: essentially identical to
{\tt bnfclassunit} except that the output contains much technical data, and
should not be printed out explicitly in general. The result of {\tt bnfinit}
is used in programs such as {\tt bnfisprincipal}, {\tt bnfisunit} or {\tt
bnfnarrow}. The result is a 10-component vector $bnf$. 

\noindent $\bullet$ The first 6 and last 2 components are technical and in
principle are not used by the casual user. However, for the sake of
completeness, their description is as follows. We use the notations explained
in the book by H. Cohen, {\it A Course in Computational Algebraic Number
Theory\/}, Graduate Texts in Maths {\bf 138}, Springer-Verlag, 1993, Section
6.5, and pages 354 and 355 in particular.

$bnf[1]$ contains the matrix $W$ ({\tt mit} in the source code), i.e.~the
matrix in Hermite Normal Form giving on prime ideal generators
$({\bf p}_i)_{1\le i\le r}$ relations for the class group.

$bnf[2]$ contains the matrix $B$ ({\tt matalpha}), i.e.~the matrix containing
the expressions of the prime ideal factorbase in terms of the ${\bf p}_i$. It
is an $r\times c$ matrix.

 $bnf[3]$ contains the complex logarithmic embeddings of the system of
fundamental units which has been found. It is an $(r_1+r_2)\times(r_1+r_2-1)$
matrix.

 $bnf[4]$ contains the matrix $M''_C$ of Archimedean components of the
relations of the matrix $M''$, except that the first $r_1+r_2-1$ columns are
suppressed since they are already in $bnf[3]$.

 $bnf[5]$ contains the prime factor base, i.e.~the list of $k$ prime ideals
used in finding the relations.

 $bnf[6]$ contains the permutation of the prime factor base which was necessary
to reduce the relation matrix to the form explained on page 354 (i.e.~with a
big $c\times c$ identity matrix on the lower right). Note that in the above
mentioned book, the need to permute the rows of the relation matrices which
occur was not stressed.

 $bnf[9]$ is a 3-element row vector obtained as follows.  Let
$b=u_1^{-1}bnf[1]u_2$ obtained by applying the Smith normal form algorithm to
the matrix $bnf[1]$ (i.e.~{\tt mit}). Then $bnf[9]=[u_1,u_2,b]$. Note that the
final class group generators given by {\tt bnfinit} or {\tt bnfclassunit} are
obtained by LLL-reducing the generators whose list is $b$.

 Finally, $bnf[10]$ is unused and set equal to 0, but it is essential that this
component be present, because PARI distinguishes a number field {\tt nf} from
a big number field {\tt bnf} by the number of its components.
\smallskip

\noindent$\bullet$ The less technical components are as follows:

 $bnf[7]$ ({\tt bnf.nf}) is equal to the number field data $nf$ as would be given
by {\tt nfinit}.

 $bnf[8]$ is a vector containing the last 6 components of {\tt
bnfclassunit[,1]}, i.e.~the classgroup ({\tt bnf.clgp}), the regulator
({\tt bnf.reg}), the general ``check'' number which should be close to 1, the
number of roots of unity and a generator ({\tt bnf.tu}), the fundamental units
({\tt bnf.fu}), and finally the check on their computation. If the precision
becomes insufficient, GP outputs a warning (``{\tt fundamental units too
large, not given}'') and does not strive to compute the units by default
($flag=0$).

   When $flag=1$, GP insists on finding the fundamental units exactly, the
internal precision being doubled and the computation redone, until the exact
results are obtained. The user should be warned that this can take a very
long time when the coefficients of the fundamental units on the integral
basis are very large.

   When $flag=2$, on the contrary, it is initially agreed that GP
will not compute units.

   When $flag=3$, compute a very small version of {\tt bnfinit}, a ``small
big number field'' (or $sbnf$ for short) which contains enough information so
as to recover the full $bnf$ vector very rapidly, but which is much smaller
and hence easy to store and print. It is supposed to be used in conjunction
with {\tt bnfmake}. The output is a 12 component vector $v$, as follows. Let
$bnf$ be the result of a full {\tt bnfinit}, complete with units. Then $v[1]$
is the polynomial $P$, $v[2]$ is the number of real embeddings $r_1$, $v[3]$
is the field discriminant, $v[4]$ is the integral basis, $v[5]$ is the list
of roots as in the sixth component of {\tt nfinit}, $v[6]$ is the matrix $MD$
of {\tt nfinit} giving a $\Z$-basis of the different, $v[7]$ is the matrix
{\tt mit}$=bnf[1]$, $v[8]$ is the matrix {\tt matalpha}$=bnf[2]$, $v[9]$ is
the prime ideal factor base $bnf[5]$ coded in a compact way, and ordered
according to the permutation $bnf[6]$, $v[10]$ is the 2-component vector
giving the number of roots of unity and a generator, expressed on the
integral basis, $v[11]$ is the list of fundamental units, expressed on the
integral basis, $v[12]$ is a vector containing the algebraic numbers alpha
corresponding to the columns of the matrix {\tt matalpha}, expressed on the
integral basis.

   Note that all the components are exact (integral or rational), except for
the roots in $v[5]$. In practice, this is the only component which a user
is allowed to modify, by recomputing the roots to a higher accuracy if
desired. Note also that the member functions will {\it not} work on $sbnf$, you
have to explicitly use {\tt bnfmake}.

The library syntax is $\teb{bnfinit0}(P,flag,tech,prec)$.

\subsecidx{bnfisintnorm}$(bnf,x)$: compute a complete system of solutions
(modulo units of positive norm) of the absolute norm equation $Norm(a)=x$, where
$a$ is an integer in $bnf$. If $bnf$ has not been certified, the correctness
of the result depends on the validity of the GRH.

The library syntax is $\teb{bnfisintnorm(bnf,x)}$.

\subsecidx{bnfisnorm}$(bnf,x,\{flag=1\})$: Tries to tell whether the rational
number $x$ is the norm of some element y in $bnf$). Returns a vector $[a,b]$
where $x=Norm(a)*b$. Looks for a solution which is a S-unit, with S a certain
set of primes ideals containing (among others) all primes dividing x. If
$bnf$ is known to be Galois, set $flag$=0 (in this case, $x$ is a norm iff
$b=1$). If flag is non zero the program adds to S the following prime ideals,
depending on the sign of $flag$. If $flag>0$, the ideals of norm less than
$flag$. And if $flag<0$ the ideals dividing $flag$. 

 If you are willing to assume GRH, the answer is guaranteed (i.e.~$x$ is a
norm iff $b=1$), if $S$ contains all primes less than $12\log(disc(Bnf))^2$,
where $Bnf$ is the Galois closure of $bnf$.

The library syntax is $\teb{bnfisnorm}(bnf,x,flag,prec)$, where $flag$ and
$prec$ are {\tt long} integers.

\subsecidx{bnfissunit}$(bnf,sfu,x)$: $bnf$ being output by {\tt bnfinit},
$sfu$ by {\tt bnfsunit}, gives the column vector of exponents of $x$ on the
fundamental S-units and the roots of unity. If $x$ is not a unit, output an
empty vector.

The library syntax is $\teb{bnfissunit}(bnf,sfu,x)$.

\subsecidx{bnfisprincipal}$(bnf,x,\{flag=1\})$: $bnf$ being the number field
data output by {\tt bnfinit}, and $x$ being either a $\Z$-basis of an ideal
in the number field (not necessarily in HNF) or a prime ideal in the format
output by the function {\tt idealprimedec}, this function tests whether the
ideal is principal or not. The result is more complete than a simple
true/false answer: it gives a row vector $[v_1,v_2,check]$, where

 $v_1$ is the vector of components $c_i$ of the class of the ideal $x$ in the
class group, expressed on the generators $g_i$ given by {\tt bnfinit}
(specifically {\tt bnf.clgp.gen} which is the same as {\tt bnf[8][1][3]}).
The $c_i$ are chosen so that $0\le c_i<n_i$ where $n_i$ is the order of $g_i$
(the vector of $n_i$ being {\tt bnf.clgp.cyc}, that is {\tt bnf[8][1][2]}).

 $v_2$ gives on the integral basis the components of $\alpha$ such that
$x=\alpha\prod_ig_i^{c_i}$. In particular, $x$ is principal if and only if
$v_1$ is equal to the zero vector, and if this the case $x=\alpha\Z_K$ where
$\alpha$ is given by $v_2$. Note that if $\alpha$ is too large to be given, a
warning message will be printed and $v_2$ will be set equal to the empty
vector.

  Finally the third component $check$ is analogous to the last component of
{\tt bnfclassunit}: it gives a check on the accuracy of the result, in bits.
$check$ should be at least $10$, and preferably much more. In any case, the
result is checked for correctness.

If $flag=0$, output only $v_1$, which is much easier to compute.

If $flag=2$, do as if $flag$ were $0$, but double precision until a result is
obtained.

If $flag=3$, as in the default behaviour ($flag=1$), but double precision
until a result is obtained.

The user is warned that these two last setting may induce {\it very} lengthy
computations.

The library syntax is $\teb{isprincipalall}(bnf,x,flag)$.

\subsecidx{bnfisunit}$(bnf,x)$: $bnf$ being the number field data output by
{\tt bnfinit} and $x$ being an algebraic number (type integer, rational or
polmod), this outputs the decomposition of $x$ on the fundamental units and
the roots of unity if $x$ is a unit, the empty vector otherwise. More
precisely, if $u_1$,\dots,$u_r$ are the fundamental units, and $\zeta$ is
the generator of the group of roots of unity (found by {\tt bnfclassunit} or
{\tt bnfinit}), the output is a vector $[x_1,\dots,x_r,x_{r+1}]$ such that
$x=u_1^{x_1}\cdots u_r^{x_r}\cdot\zeta^{x_{r+1}}$. The $x_i$ are integers for
$i\le r$ and is an integer modulo the order of $\zeta$ for $i=r+1$.

The library syntax is $\teb{isunit}(bnf,x)$.

\subsecidx{bnfmake}$(sbnf)$: $sbnf$ being a ``small $bnf$'' as output by {\tt
bnfinit}$(x,3)$, computes the complete {\tt bnfinit} information. The result
is {\it not\/} identical to what {\tt bnfinit} would yield, but is
functionally identical. The execution time is very small compared to a
complete {\tt bnfinit}. Note that if the default precision in GP (or {\tt
prec} in library mode) is greater than the precision of the roots $sbnf[5]$,
these are recomputed so as to get a result with greater accuracy.

Note that the member functions are {\it not} available for $sbnf$, you 
have to explicitly use {\tt bnfmake}.

The library syntax is $\teb{makebigbnf}(sbnf,prec)$, where $prec$ is a
C long integer.

\subsecidx{bnfnarrow}$(bnf)$: $bnf$ being a big number field as output by
{\tt bnfinit}, computes the narrow class group of $bnf$. The output is a
3-component row vector {\tt v} analogous to the corresponding class group
component {\tt bnf.clgp} ({\tt bnf[8][1]}): the first component is the narrow
class number ({\tt v.no}), the second component is a vector containing
the SNF cyclic components of the narrow class group ({\tt v.cyc}), and the
third is a vector giving the generators of the corresponding cyclic groups
({\tt v.gen}). Note that this function is a special case of {\tt bnrclass}.

The library syntax is $\teb{buchnarrow}(bnf)$.

\subsecidx{bnfsignunit}$(bnf)$: $bnf$ being a big number field data output by
{\tt bnfinit}, this computes an $r_1\times(r_1+r_2-1)$ matrix having $\pm1$
components, giving the signs of the real embeddings of the fundamental units.

The library syntax is $\teb{signunits}(bnf)$.

\subsecidx{bnfreg}$(bnf)$: $bnf$ being a big number field output by {\tt
bnfinit}, compute its regulator.

The library syntax is $\teb{regulator}(bnf,tech,prec)$, where $tech$ is as in
{\tt bnfclassunit}.

\subsecidx{bnfsunit}$(bnf,S)$: compute the fundamental S-units of the number
field $bnf$ (output by {\tt bnfinit}), where $S$ is a list of prime ideals
(output by {\tt idealprimedec}). The output is a vector $v$ with 6
components.

$v[1]$ gives a minimal system of (integral) generators of the $S$-unit group
modulo the unit group.

$v[2]$ contains the coordinates of $v[1]$ on the ideals $S$, ordered as they
were input. This is a matrix in HNF form.

$v[3]$ gives the (complex) logarithmic embeddings of the generators in
$v[1]$.

$v[4]$ is the $S$-regulator (this is the product of the regulator, the
determinant of $v[2]$ and the natural logarithms of the norms of the ideals
in $S$).

$v[5]$ gives the $S$-class group structure, in the usual format (a row vector
whose three component give in order the S-class number, the cyclic components
and the generators).

$v[6]$ is a copy of $S$.

The library syntax is $\teb{bnfsunit}(bnf,S,prec)$.

\subsecidx{bnfunit}$(bnf)$: $bnf$ being a big number field as output by
{\tt bnfinit}, outputs a two component row vector giving in the first
component the vector of fundamental units of the number field, and in the
second component the number of bit of accuracy which remained in the
computation (which is always correct, otherwise an error message is printed).
This function is mainly for people who used the wrong flag in {\tt bnfinit} 
and would like to skip part of a lengthy {\tt bnfinit} computation.

The library syntax is $\teb{buchfu}(bnf)$.

\subsecidx{bnrclass}$(bnf,ideal,\{flag=0\})$: $bnf$ being a big number field
as output by {\tt bnfinit} (the units are mandatory unless the ideal is
trivial), and $ideal$ being either an ideal in any form or a two-component
row vector containing an ideal and an $r_1$-component row vector of flags
indicating which real Archimedean embeddings to take in the module, computes
the ray class group of the number field for the module $ideal$, as a
3-component vector as all other finite abelian groups (cardinality, vector of
cyclic components, corresponding generators).

If $flag=2$, the output is different. It is a 6-component vector $w$. $w[1]$
is $bnf$. $w[2]$ is the result of applying {\tt idealstar}$(bnf,I,2)$. $w[3]$,
$w[4]$ and $w[6]$ are technical components used only by the function {\tt
bnrisprincipal}. $w[5]$ is the structure of the ray class group as would have
been output with $flag=0$.

If $flag=1$, as above, except that the generators of the ray class group are
not computed, which saves time.

The library syntax is $\teb{bnrclass0}(bnf,ideal,flag,prec)$.

\subsecidx{bnrclassno}$(bnf,I)$: $bnf$ being a big number field as output
by {\tt bnfinit} (units are mandatory unless the ideal is trivial), and $I$
being either an ideal in any form or a two-component row vector containing an
ideal and an $r_1$-component row vector of flags indicating which real
Archimedean embeddings to take in the modulus, computes the ray class number
of the number field for the modulus $I$. This is faster than {\tt bnrclass}
and should be used if only the ray class number is desired.

The library syntax is $\teb{rayclassno}(bnf,I)$.

\subsecidx{bnrclassnolist}$(bnf,list)$: $bnf$ being a big number field as output
by {\tt bnfinit} (units are mandatory unless the ideal is trivial), and $list$
is a list of modules as ouput by {\tt ideallist} of {\tt ideallistarch}, 
output the list of the class numbers of the corresponding ray class fields.

The library syntax is $\teb{rayclassnolist}(bnf,list)$.

\subsecidx{bnrconductor}$(a_1,\{a_2\},\{a_3\}, \{flag=0\})$: conductor of the
subfield of a ray class field as defined by $[a_1,a_2,a_3]$ (see the
beginning of this section).

The library syntax is $\teb{bnrconductor0}(a_1,a_2,a_3,prec)$, where an
omitted argument among the $a_i$ is input as {\tt gzero}, and $prec$ is a $C$
long.

\subsecidx{bnrconductorofchar}$(bnr,chi)$: $bnr$ being a big ray number field
as output by {\tt bnrclass}, and $chi$ being a row vector representing a
character as expressed on the generators of the ray class group, gives the
conductor of this character as a modulus.

The library syntax is $\teb{bnrconductorofchar}(bnr,chi,prec)$ where $prec$
is a C-long.

\subsecidx{bnrdisc}$(a1,\{a2\},\{a3\},\{flag=0\})$: $a1$, $a2$, $a3$
defining a big ray number field $L$ over a groud field $K$ (see above for the
meaning of $a1$, $a2$, $a3$), outputs a 3-component row vector $[N,R_1,D]$,
where $N$ is the (absolute) degree of $L$, $R_1$ the number of real places of
$L$, and $D$ the discriminant of $L/\Q$, including sign (if $flag=0$).

   If $flag=1$, as above but output relative data. $N$ is now the degree of
$L/K$, $R_1$ is the number of real places of $K$ unramified in $L$ (so that
the number of real places of $L$ is equal to $R_1$ times the relative degree
$N$), and $D$ is the relative discriminant ideal of $L/K$.

   If $flag=2$, do as in case 0, except that if the modulus is not the exact
conductor corresponding to the $L$, no data is conputed and the result is $0$
({\tt gzero}).

   If $flag=3$, as case 2, outputting relative data.

The library syntax is $\teb{bnrdisc0}(a1,a2,a3,flag,prec)$.

\subsecidx{bnrdisclist}$(bnf,bound,\{arch\},\{flag=0\})$: $bnf$ being a big
number field as output by {\tt bnfinit} (the units are mandatory), computes a
list of discriminants of Abelian extensions of the number field by increasing
modulus norm up to bound $bound$, where the ramified archimedean places are given
by $arch$ (unramified at infinity if $arch$ is void or omitted). If $flag$
is non-zero, give arch all the possible values.

  The alternative syntax {\tt bnrdisclist}$(bnf,list)$ is supported, where
$list$ is as output by {\tt ideallist} or {\tt ideallistarch} (with units).

  The output format is as follows. The output $v$ is a row vector of row
vectors, allowing the bound to be greater than $2^{16}$ for 32-bit machines,
and $v[i][j]$ is understood to be in fact $V[2^{15}(i-1)+j]$ of a unique big
vector $V$ (note that $2^{15}$ is hardwired and can be increased in the
source code only on 64-bit machines and higher).

  Such a component $V[k]$ is itself a vector $W$ (maybe of length 0) whose
components correspond to each possible ideal of norm $k$. Each component
$W[i]$ corresponds to an Abelian extension $L$ of $bnf$ whose modulus is an
ideal of norm $k$ and no Archimedean components (hence the extension is
unramified at infinity). The extension $W[i]$ is represented by a 4-component
row vector $[m,d,r,D]$ with the following meaning. $m$ is the prime ideal
factorization of the modulus, $d=[L:\Q]$ is the absolute degree of $L$,
$r$ is the number of real places of $L$, and $D$ is the factorization of the
absolute discriminant. Each prime ideal $pr=[p,\alpha,e,f,\beta]$ in the
prime factorization $m$ is coded as $p\cdot n^2+(f-1)\cdot n+(j-1)$, where
$n$ is the degree of the base field and $j$ is such that

{\tt setrand(1); pr=idealprimedec(nf,p)[j]}.

$m$ can be decoded using {\tt bnfdecodemodule}.

The library syntax is $\teb{bnrdisclist0}(a1,a2,a3,bound,arch,flag)$.

\subsecidx{bnrinit}$(bnf,ideal,\{flag=0\})$: $bnf$ is as output by {\tt
bnfinit}, $ideal$ is a valid ideal (or a module), initialize data linked to
the ray class group structure corresponding to this module. This is the same
as {\tt bnrclass}$(bnf,ideal,flag+1)$.

The library syntax is $\teb{bnrinit0}(bnf,ideal,flag,prec)$.

\subsecidx{bnrisconductor}$(a1,\{a2\},\{a3\})$: $a1$, $a2$, $a3$ represent
an extension of the base field, given by class field theory for some modulus
encoded in the parameters. Output 1 if this modulus is the conductor, and 0
otherwise. This is slightly faster than {\tt bnrconductor}.

The library syntax is $\teb{bnrisconductor}(a1,a2,a3)$ and the result is a
{\tt long}.

\subsecidx{bnrisprincipal}$(bnr,x,\{flag=1\})$: $bnr$ being the number field
data which is output by {\tt bnrinit} and $x$ being an ideal in any form,
outputs the components of $x$ on the ray class group generators in a way
similar to {\tt bnfisprincipal}. That is a 3-component vector $v$ where
$v[1]$ is the vector of components of $x$ on the ray class group generators,
$v[2]$ gives on the integral basis an element $\alpha$ such that
$x=\alpha\prod_ig_i^{x_i}$. Finally $v[3]$ indicates the number of bits of
accuracy left in the result. In any case the result is checked for
correctness, but $v[3]$ is included to see if it is necessary to increase the
accuracy in other computations.

If $flag=0$, output only $v_1$.

{\it The settings $flag=2$ or $3$ are not available in this case}.

The library syntax is $\teb{isprincipalrayall}(bnr,x,flag)$.

\subsecidx{dirzetak}$(nf,b)$: gives as a vector the first $b$ coefficients
of the Dedekind zeta function of the number field $nf$ considered as a 
Dirichlet series.

The library syntax is $\teb{dirzetak}(nf,b)$.

\subsecidx{factornf}$(x,t)$: factorization of the univariate polynomial $x$
over the number field defined by the (univariate) polynomial $t$. $x$ may
have coefficients in $\Q$ or in the number field. The main variable of
$t$ must be of {\it lower} priority than that of $x$ (in other words the
variable number of $t$ must be {\it greater} than that of $x$). However if
the coefficients of the number field occur explicitly (as polmods) as
coefficients of $x$, the variable of these polmods {\it must} be the same as
the main variable of $t$. For example
{\tt factornf(x\pow 2+mod(y,y\pow 2+1),y\pow 2+1)} and
{\tt factornf(x\pow 2+1,y\pow 2+1)} are legal but
{\tt factornf(x\pow 2+mod(z,z\pow 2+1),y\pow 2+1)} is not.

The library syntax is $\teb{polfnf}(x,t)$.

\subsecidx{ffinit}$(p,n,\{v=x\})$: compute a monic polynomial of degree
$n$ which is irreducible over $\F_p$. For instance if {\tt P =
ffinit(3,2,y)}, you can represent elements in $\F_{3^2}$ as polymods modulo
{\tt P}.

The library syntax is $\teb{ffinit}(p,n,v)$, where $v$ is a variable number.

\subsecidx{idealadd}$(nf,x,y)$: sum of the two ideals $x$ and $y$ in the
number field $nf$. When $x$ and $y$ are given by $\Z$-bases, this does not
depend on $nf$ and can be used to compute the sum of any two $\Z$-modules.
The result is given in HNF.

The library syntax is $\teb{idealadd}(nf,x,y)$.

\subsecidx{idealaddtoone}$(nf,x,\{y\})$: $x$ and $y$ being two co-prime integral
ideals (given in any form), this gives a two-component row vector $[a,b]$
such that $a\in x$, $b\in y$ and $a+b=1$.

The alternative syntax {\tt idealaddtoone}$(nf,v)$, is supported, where $v$
is a $k$-component vector of ideals (given in any form) which sum to $\Z_K$.
This outputs a $k$-component vector $e$ such that $e[i]\in x[i]$ for $1\le
i\le k$ and $\sum_{1\le i\le k}e[i]=1$.

The library syntax is $\teb{idealaddtoone0}(nf,x,y)$, where an omitted $y$
is coded as {\tt NULL}.

\subsecidx{idealappr}$(nf,x,\{flag=0\})$: If $x$ is a fractional ideal (given
in any form), gives an element $\alpha$ in $nf$ such that for all prime
ideals $\bf p$ such that the valuation of $x$ at $\bf p$ is non-zero, we have
$v_{\bf p}(\alpha)=v_{\bf p}(x)$, and. $v_{\bf p}(\alpha)\ge0$ for all other
${\bf p}$.

If $flag$ is non-zero, $x$ must be given as a prime ideal factorisation,
as output by {\tt idealfactor}, but possibly with zero or negative exponents.
This yields an element $\alpha$ such that for all prime ideals $\bf p$
occurring in $x$, $v_{\bf p}(\alpha)$ is equal to the exponent of $\bf p$ in
$x$, and for all other prime ideals, $v_{\bf p}(\alpha)\ge0$. This
generalizes {\tt idealappr}$(nf,x,0)$ since zero exponents are allowed.
Note that the algorithm used is slightly different, so that
{\tt idealapp(nf,idealfactor(nf,x))} may not be the same as {\tt
idealappr(nf,x,1)}.

The library syntax is $\teb{idealappr0}(nf,x,flag)$.

\subsecidx{idealchinese}$(nf,x,y)$: $x$ being a prime ideal factorisation
(i.e.~a 2 by 2 matrix whose first column contain prime ideals, and the second
column integral exponents), $y$ a vector of elements in $nf$ indexed by the
ideals in $x$, compute an element $b$ such that

$v_\p(b - y_\p) \geq v_\p(x)$ for all prime ideals in $x$ and $v_\p(b)\geq 0$
for all other $\p$.

The library syntax is $\teb{idealchinese}(nf,x,y)$.

\subsecidx{idealcoprime}$(nf,x,y)$: given two integral ideals $x$ and $y$
in the number field $nf$, finds a $\beta$ in the field, expressed on the
integral basis $nf[7]$, such that $\beta\cdot y$ is an integral ideal
coprime to $x$. 

The library syntax is $\teb{idealcoprime}(nf,x)$.

\subsecidx{idealdiv}$(nf,x,y,\{flag=0\})$: quotient $x\cdot y^{-1}$ of the
two ideals $x$ and $y$ in the number field $nf$. The result is given in HNF.

If $flag$ is non-zero, the quotient $x \cdot y^{-1}$ is assumed to be an
integral ideal. This can be much faster when the norm of the quotient is
small even though the norms of $x$ and $y$ are large.

The library syntax is $\teb{idealdiv0}(nf,x,y,flag)$. Also available
are $\teb{idealdiv}(nf,x,y)$ ($flag=0$) and $\teb{idealdivexact}(nf,x,y)$
($flag=1$).

\subsecidx{idealfactor}$(nf,x)$: factors into prime ideal powers the ideal
$x$ in the number field $nf$. The output format is similar to the
{\tt factor} function, and the prime ideals are represented in the form
output by the {\tt idealprimedec} function, i.e.~as 5-element vectors.

The library syntax is $\teb{idealfactor}(nf,x)$.

\subsecidx{idealhnf}$(nf,a,\{b\})$: gives the Hermite normal form matrix
of the ideal $a$. The ideal can be given in any form whatsoever
(typically by an algebraic number of it is principal, by a $\Z_K$-system
of generators, as a prime ideal as given by {\tt idealprimedec}, or by a
$\Z$-basis).

If $b$ is not omitted, assume the ideal given was $a\Z_K+b\Z_K$, where $a$
and $b$ are elements of $K$ given either as vectors on the integral basis
$nf[7]$ or as algebraic numbers.

The library syntax is $\teb{idealhnf0}(nf,a,b)$ where an omitted $b$ is coded
as {\tt NULL}. Also available is $\teb{idealhermite}(nf,a)$ ($b$ omitted).

\subsecidx{idealintersect}$(nf,x,y)$: intersection of the two ideals $x$ and
$y$ in the number field $nf$. When $x$ and $y$ are given by $\Z$-bases, this
does not depend on $nf$ and can be used to compute the intersection of any
two $\Z$-modules. The result is given in HNF.

The library syntax is $\teb{idealintersect}(nf,x,y)$.

\subsecidx{idealinv}$(nf,x,\{flag=0\})$: inverse of the ideal $x$ in the
number field $nf$. The result is the Hermite normal form of the inverse of
the ideal, together with the opposite of the Archimedean information if it is
given.

If $flag$ is $1$, use the different. This is usually slower.

The library syntax is $\teb{idealinv0}(nf,x,flag)$. Also available is
$\teb{idealinv}(nf,x)$ ($flag=0$).

\subsecidx{ideallist}$(nf,bound,\{flag=4\})$: computes the list of all ideals
of norm less or equal to $bound$ in the number field $nf$. The result is a
row vector with exactly $bound$ components. Each component is itself a row
vector containing the information about ideals of a given norm, in no specific 
order. This information can be either the HNF of the ideal or the {\tt idealstar}
with possibly some additional information.

If $flag$ is present, its binary digits are toggles meaning

\quad 1: give also the generators in the {\tt idealstar}.

\quad 2: output $[L,U]$, where $L$ is as before and $U$ is a vector of
{\tt zinternallogs} of the units.

\quad 4: give only the ideals and not the {\tt idealstar} or the {\tt ideallog}
of the units.

The library syntax is $\teb{ideallist0}(nf,bound,flag)$, where $bound$ must
be a C long integer. Also available is $\teb{ideallist}(nf,bound)$,
corresponding to the case $flag=0$.

\subsecidx{ideallistarch}$(nf,list,\{arch=[\,]\},\{flag=0\})$: vector of
vectors of all {\tt idealstarinit} (see {\tt idealstar}) of all modules in
$list$, with archimedean part $arch$ added (void if omitted). $flag$ is
optional whose binary digits are toggles meaning: 1: give generators as well,
2: list format is $[L,U]$ (see {\tt ideallist}).

The library syntax is $\teb{ideallistarch0}(nf,list,arch,flag)$, where an
omitted $arch$ is coded as {\tt NULL}.

\subsecidx{ideallog}$(nf,x,bid)$: $nf$ being a number field, $bid$ being a
``big ideal'' as output by {\tt idealstar} and $x$ being a non-necessarily
integral element of $nf$ which must have valuation equal to 0 at all prime
ideals dividing $I=bid[1]$, computes the ``discrete logarithm'' of $x$ on the
generators given in $bid[2]$. In other words, if $g_i$ are these generators,
of orders $d_i$ respectively, the result is a column vector of integers
$(x_i)$ such that $0\le x_i<d_i$ and 
$$x\equiv\prod_ig_i^{x_i}\pmod{\ ^*I}\enspace.$$
Note that when $I$ is a module, this implies also sign conditions on the
embeddings.

The library syntax is $\teb{zideallog}(nf,x,bid)$.

\subsecidx{idealmin}$(nf,x,vdir)$: compute a minimum of the ideal $x$ in the
direction $vdir$ in the number field $nf$.

The library syntax is $\teb{minideal}(nf,x,vdir,prec)$.

\subsecidx{idealmul}$(nf,x,y,\{flag=0\})$: ideal multiplication of the ideals
$x$ and $y$ in the number field $nf$. The result is a generating set for the
ideal product with at most $n$ elements, and is in Hermite normal form if either
$x$ or $y$ is in HNF or is a prime ideal as output by {\tt idealprimedec}, 
and this is given together with the sum of the Archimedean
information in $x$ and $y$ if both are given.

If $flag$ is non-zero, reduce the result using {\tt idealred}.

The library syntax is $\teb{idealmul}(nf,x,y)$ ($flag=0$) or
$\teb{idealmulred}(nf,x,y,prec)$ ($flag\neq 0$), where as usual, $prec$ is
a $C$ long integer representing the precision.

\subsecidx{idealnorm}$(nf, x)$: computes the norm of the ideal~$x$
in the number field~$nf$.

The library syntax is $\teb{idealnorm}(nf, x)$.

\subsecidx{idealpow}$(nf,x,k,\{flag=0\})$: computes the $k$-th power of the
ideal $x$ in the number field $nf$. $k$ can be positive, negative or zero.
The result is NOT reduced, it is really the $k$-th ideal power, and is given
in HNF.

If $flag\neq 0$, reduce the result, using {\tt idealred}. Note however that
this is NOT the same as as {\tt idealpow}$(nf,x,k)$ followed by reduction,
since the reduction is performed throughout the powering process.

The library syntax corresponding to $flag=0$ is $\teb{idealpow}(nf,x,k)$. A
similar routine $\teb{idealpows}(nf,x,k)$ is available, where $k$ is now a
C-long integer. Corresponding to $flag=1$ is
$\teb{idealpowred}(nf,vp,k,prec)$, where $prec$ is a C-long integer.

\subsecidx{idealprimedec}$(nf,p)$: computes the prime ideal decomposition of
the prime number $p$ in the number field $nf$. $p$ must be a (positive) prime
number. Note that the fact that $p$ is prime is not checked, so if a
non-prime number $p$ is given it may lead to unpredictable results.

The result is a vector of 5-component vectors, each representing one of the
prime ideals above $p$ in the number field $nf$. The representation
$vp=[p,a,e,f,b]$ of a prime ideal means the following. The prime ideal is
equal to $p\Z_K+\alpha\Z_K$ where $\Z_K$ is the ring of integers of the field
and $\alpha=\sum_i a_i\omega_i$ where the $\omega_i$ form the integral basis
$nf[7]$ ({\tt nf.zk}), $e$ is the ramification index, $f$ is the residual
index, and $b$ is an $n$-component column vector representing a
$\beta\in\Z_K$ such that $vp^{-1}=\Z_K+\beta/p\Z_K$ which will be useful for
computing valuations, but which the user can ignore. The number $\alpha$ is
guaranteed to have a valuation equal to 1 at the prime ideal (this is
automatic if $e>1$).

The library syntax is $\teb{idealprimedec}(nf,p)$.

\subsecidx{idealprincipal}$(nf,x)$: creates the principal ideal generated by
the algebraic number $x$ (which must be of type integer, rational or polmod)
in the number field $nf$. The result is a one-column matrix.

The library syntax is $\teb{principalideal}(nf,x)$.

\subsecidx{idealred}$(nf,x,\{vdir=0\})$: LLL reduction of the ideal $x$ in the
number field $nf$, along the direction $vdir$. Here $vdir$ must be either an
$r1+r2$-component vector ($r1$ and $r2$ number of real and complex places of
$nf$ as usual), or the PARI zero, in which case $vdir$ is assumed to be equal
to the vector having only components equal to 1. The notion of reduction
along a direction is technical and cannot be explained here. Note that this
is {\it not\/} the same as the LLL reduction of the lattice $x$ since ideal
operations are involved. The result is the Hermite normal form of the
LLL-reduced ideal, which is usually, but not always, a reduced ideal. $x$ may
also be a 2-component vector, the first being as above, and the second
containing a matrix of Archimedean information. In that case, this matrix is
suitably updated.

The library syntax is $\teb{ideallllred}(nf,x,vdir,prec)$.

\subsecidx{idealstar}$(nf,I,\{flag=1\})$: $nf$ being a number field, and $I$
either and ideal in any form, or a row vector whose first component is an
ideal and whose second component is a row vector of $r_1$ 0 or 1, outputs
necessary data for computing in the group $(\Z_K/I)^*$.

 If $flag=2$, the result is a as a 5-component vector w. w[1] is the ideal or
module $I$ itself. w[2] is the structure of the group. The other components
are difficult to describe and are used only in conjunction with the function
{\tt ideallog}.

 If $flag=1$ (default), as $flag=2$, but do not compute explicit generators
for the cyclic components, which saves time.

 If $flag=0$, computes the structure of $(\Z_K/I)^*$ as a 3-component vector
v. v[1] is the order, v[2] is the vector of SNF cyclic components and v[3]
the corresponding generators. When the row vector is explicitly included, the
non-zero elements of this vector are considered as real embeddings of $nf$ in
the order given by {\tt polroots}, i.e.~in nf[6] ({\tt nf.roots}), and then
$I$ is a module with components at infinity.

To solve discrete logarithms (using {\tt ideallog}), you have to chose
$flag>0$.

The library syntax is $\teb{idealstar0}(nf,I,flag)$.

\subsecidx{idealtwoelt}$(nf,x,\{a\})$: computes a two-element representation
of the ideal $x$ in the number field $nf$, using a straightforward
(exponential time) search. $x$ can be an ideal in any form, (including
perhaps an Archimedean part, which is ignored) and the result is a row vector
$[a,\alpha]$ with two components such that $x=a\Z_K+\alpha\Z_K$ and $a\in\Z$,
where $a$ is the one passed as argument if any. If $x$ is given by at least
two generators, $a$ is chosen to be the positive generator of $x\cap\Z$. 

Note that when an explicit $a$ is given, we use an asymptotically faster
method, however in practice it is usually slower.

The library syntax is \sidx{ideal\string\_two\string\_elt0}
${\bf ideal\_two\_elt0}(nf,x,a)$, where an omitted $a$ is entered as
{\tt NULL}.

\subsecidx{idealval}$(nf,x,vp)$: gives the valuation of the ideal $x$
at the prime ideal $vp$ in the number field $nf$, where $vp$ must be a
5-component vector as given by {\tt idealprimedec}.

The library syntax is $\teb{idealval}(nf,x,vp)$ and the result is a C-long
integer.

\subsecidx{ideleprincipal}$(nf,x)$: creates the principal idele generated by
the algebraic number $x$ (which must be of type integer, rational or polmod)
in the number field $nf$. The result is a two-component vector, the first
being a one-column matrix representing the corresponding principal ideal, and
the second being the vector with $r_1+r_2$ components giving the complex
logarithmic embedding of $x$.

The library syntax is $\teb{principalidele}(nf,x)$.

\subsecidx{matalgtobasis}$(nf,x)$: $nf$ being a number field in {\tt nfinit}
format, and $x$ a matrix whose coefficients are expressed as polymods in $nf$,
transforms this matrix into a matrix whose coefficients are expressed on the
integral basis of $nf$. This is the same as applying {\tt nfalgtobasis} to
each entry, but it would be dangerous to use the same name.

The library syntax is $\teb{matalgtobasis}(nf,x)$.

\subsecidx{matbasistoalg}$(nf,x)$: $nf$ being a number field in {\tt nfinit}
format, and $x$ a matrix whose coefficients are expressed as column vectors
on the integral basis of $nf$, transforms this matrix into a matrix whose
coefficients are algebraic numbers expressed as polymods. This is the same
as applying {\tt nfbasistoalg} to each entry, but it would be dangerous 
to use the same name.

The library syntax is $\teb{matbasistoalg}(nf,x)$.

\subsecidx{modreverse}$(a)$: $a$ being a polmod $A(X)$ modulo $T(X)$, finds
the ``reverse polmod'' $B(X)$ modulo $Q(X)$, where $Q$ is the minimal
polynomial of $a$, which must be equal to the degree of $T$, and such that if
$\theta$ is a root of $T$ then $\theta=B(\alpha)$ for a certain root $\alpha$
of $Q$.

This is very useful when one changes the generating element in algebraic 
extensions.

The library syntax is $\teb{polmodrecip}(x)$.

\subsecidx{newtonpoly}$(x,p)$: gives the vector of the slopes of the Newton
polygon of the polynomial $x$ with respect to the prime number $p$. The $n$
components of the vector are in decreasing order, and $n$ is equal to the
degree of $x$. 

The library syntax is $\teb{newtonpoly}(x,p)$.

\subsecidx{nfalgtobasis}$(nf,x)$: this is the inverse function of {\tt
nfbasistoalg}. Given an object $x$ whose entries are expressed as algebraic
numbers in the number field $nf$, transforms it so that the entries are
expressed as a column vector on the integral basis $nf[7]$ (= {\tt nf.zk}).

The library syntax is $\teb{algtobasis}(nf,x)$.

\subsecidx{nfbasis}$(x,\{flag=0\},\{p\})$: \idx{integral basis} of the number
field defined by the irreducible, preferably monic, polynomial $x$, using the
\idx{round 4} algorithm by default. (This program is the translation in C by
Pascal Letard of a program written by David Ford in Maple.) The binary digits
of $flag$ have the following meaning:

1: Assume that no square of a prime greater than the default {\tt primelimit}
divides the discriminant of $x$, i.e.~that the index of $x$ has only small
prime divisors.

2: Use \idx{round 2} algorithm. For small degrees and coefficient size, this is
sometimes a little faster. (This program is the translation in C of a program
written by David Ford in Algeb.)

Thus for instance, if $flag=3$, this uses the round 2 algorithm and outputs
an order which will be maximal at all the small primes.

If $p$ is present, we assume (without checking!) that it is the two-column
matrix of the factorization of the discriminant of the polynomial $x$. Note
that it does {\it not} need to be a complete factorization. This is
especially useful if only a local integral basis for some small set of places
is desired: only factors with exponents greater or equal to 2 will be
considered.

The library syntax is $\teb{nfbasis0}(x,flag,p)$. An extended version
is $\teb{nfbasis}(x,\&d,flag,p)$, where $d$ will receive the discriminant of
the number field ({\it not} of the polynomial $x$), and an omitted $p$ should
be input as {\tt gzero}. Also available are $\teb{base}(x,\&d)$ ($flag=0$),
$\teb{base2}(x,\&d)$ ($flag=2$) and $\teb{factoredbase}(x,p,\&d)$.

\subsecidx{nfbasistoalg}$(nf,x)$: this is the inverse function of {\tt
nfalgtobasis}. Given an object $x$ whose entries are expressed on the
integral basis $nf[7]$ (={\tt nf.zk}), transforms it into an object whose
entries are algebraic numbers (i.e.~polmods).

The library syntax is $\teb{basistoalg}(nf,x)$.

\subsecidx{nfdetint}$(nf,x)$: given a pseudo-matrix $x$, computes a non-zero
ideal contained in (i.e.~multiple of) the determinant of $x$. This is
particularly useful in conjunction with {\tt nfhnfmod}

The library syntax is $\teb{nfdetint}(nf,x)$.

\subsecidx{nfdisc}$(x,\{flag=0\},\{p\})$: \idx{field discriminant} of the
number field defined by the integral, preferably monic, irreducible
polynomial $x$. $flag$ and $p$ are exactly as in {\tt nfbasis}. That is, $p$
provides the matrix of a partial factorization of the discriminant of $x$,
and binary digits of $flag$ are as follows:

 1: assume that no square of a prime greater than {\tt primelimit}
divides the discriminant.

 2: use the round 2 algorithm, instead of the default round 4. This should be
slower except maybe for polynomials of small degree and coefficients.

The library syntax is $\teb{nfdiscf0}(x,flag,p)$ where, to omit $p$, you
should input {\tt gzero}. You can also use $\teb{discf}(x)$ ($flag=0$).

\subsecidx{nfeltdiv}$(nf,x,y)$: given two elements $x$ and $y$ as column
vectors on the integral basis $nf[7]$ ({\tt nf.zk}), computes their quotient
$x/y$ in the number field $nf$.

The library syntax is \sidx{element\string\_div} 
${\bf element\_div}(nf,x,y)$.

\subsecidx{nfeltdiveuc}$(nf,x,y)$: given two elements $x$ and $y$ as column
vectors on the integral basis $nf[7]$ ({\tt nf.zk}), computes an algebraic
integer $q$ in the number field $nf$ such that the components of $x-qy$ are
reasonably small. In fact, this is functionally identical to 
{\tt round(nfeltdiv(nf,x,y))}.

The library syntax is $\teb{nfdiveuc}(nf,x,y)$.

\subsecidx{nfeltdivrem}$(nf,x,y)$: given two elements $x$ and $y$ as column
vectors on the integral basis $nf[7]$ ({\tt nf.zk}), gives a two-element row
vector $[q,r]$ such that $x=qy+r$, $q$ is an algebraic integer in $nf$, and
the components of $r$ are reasonably small.

The library syntax is $\teb{nfdivres}(nf,x,y)$.

\subsecidx{nfeltmod}$(nf,x,y)$: given two elements $x$ and $y$ as column
vectors on the integral basis $nf[7]$ ({\tt nf.zk}), computes an element $r$
of $nf$ of the form $r=x-qy$ with $q$ and algebraic integer, and such that
$r$ is small. This is functionally identical to
$${\tt x - nfeltmul(nf,round(nfeltdiv(nf,x,y)),y)}.$$

The library syntax is $\teb{nfmod}(nf,x,y)$.

\subsecidx{nfeltmul}$(nf,x,y)$: given two elements $x$ and $y$ as column
vectors on the integral basis $nf[7]$ ({\tt nf.zk}), computes their product
$x*y$ in the number field $nf$.

The library syntax is \sidx{element\string\_mul}
${\bf element\_mul}(nf,x,y)$.

\subsecidx{nfeltpow}$(nf,x,k)$: given an element $x$ as a column vector on
the integral basis $nf[7]$ ({\tt nf.zk}) and a positive or negative integer
$k$, computes $x^k$ in the number field $nf$.

The library syntax is \sidx{element\string\_pow}
${\bf element\_pow}(nf,x,k)$.

\subsecidx{nfeltreduce}$(nf,x,ideal)$: Given an ideal in Hermite Normal Form
and an element x of the number field $nf$, finds an element $r$ in $nf$ such
that $x-r$ belongs to the ideal and $r$ is small.

The library syntax is \sidx{element\string\_reduce}
${\bf element\_reduce}(nf,x,ideal)$.

\subsecidx{nfeltval}$(nf,x,pr)$: given an element $x$ as a column
vector on the integral basis $nf[7]$ ({\tt nf.zk}), and a prime ideal $pr$
in the format output by {\tt idealprimedec}, computes their the valuation at
$pr$ of the element $x$. The same result could be obtained using {\tt
idealval(nf,x,pr)} (since $x$ would then be converted to a principal ideal),
but it would be less efficient.

The library syntax is \sidx{element\string\_val}
${\bf element\_val}(nf,x,pr)$, and the result
is a C long.

\subsecidx{nffactor}$(nf,x)$: factorization of the univariate
polynomial $x$ over the number field $nf$ given by {\tt nfinit}. $x$ has
coefficients in $nf$ (i.e.~either scalar, polymod, polynomial or column
vector). The main variable of $nf$ must be of {\it lower} priority than that
of $x$ (in other words, the variable number of $nf$ must be {\it greater}
than that of $x$). However if the polynomial defining the number field
occurs explicitly  in the coefficients of $x$ (as modulus of a {\tt
t\_POLMOD}), its main variable must be {\it the same} as the main variable of
$x$. For example, if {\tt nf=nfinit(y\pow 2+1)} then {\tt nffactor(nf,x\pow
2+Mod(y,y\pow 2+1))} and {\tt nffactor(nf,x\pow 2+1)} are both legal but
{\tt nffactor(nf,x\pow 2+Mod(z,z\pow 2+1))} is not.

The library syntax is $\teb{nffactor}(nf,x)$.

\subsecidx{nffactormod}$(nf,x,pr)$: factorization of the univariate
polynomial $x$ modulo the prime ideal $pr$ in the number field $nf$.
$x$ can have coefficients in the number field (scalar, polmod,
polynomial, column vector) or modulo the prime ideal (integermod
modulo the rational prime under $pr$, polymod or polynomial with integermod
coefficients, column vector of integermod). The prime ideal $pr$ {\it
must} be in the format output by {\tt idealprimedec}. The main variable of
$nf$ must be of lower priority than that of $x$ (in other words the variable
number of $nf$ must be greater than that of $x$). However if the coefficients
of the number field occur explicitly (as polymods) as coefficients of $x$,
the variable of these polymods {\it must} be the same as the main variable of
$t$ (see {\tt nffactor}).

The library syntax is $\teb{nffactormod}(nf,x,pr)$.

\subsecidx{nfgaloisapply}$(nf,aut,x)$: $nf$ being a number field as output by
{\tt nfinit}, and $aut$ being a Galois automorphism of $nf$ expressed either
as a polynomial or a polmod (such automorphisms being found using for example
one of the variants of {\tt nfgaloisconj}), computes the action of the
automorphism $aut$ on the object $x$ in the number field. $x$ can be an
element (scalar, polmod, polynomial or column vector) of the number field, an
ideal (either given by $\Z_K$-generators or by a $\Z$-basis), a prime ideal
(given as a 5-element row vector) or an idele (given as a 2-element row
vector). Because of possible confusion with elements and ideals, other vector
or matrix arguments are forbidden.

The library syntax is $\teb{galoisapply}(nf,aut,x)$.

\subsecidx{nfgaloisconj}$(nf,\{flag=0\})$: $nf$ being a number field as output
by {\tt nfinit}, computes the conjugates of a root $r$ of the non-constant
polynomial $x=nf[1]$ expressed as polynomials in $r$. This can be used even
if the number field $nf$ is not Galois since some conjugates may lie in the
field. The method uses $p$-adic approximations to the roots and {\tt qflll}.
However, in rare cases some conjugates may be missed (see below, $flag=1$).
As a note to old-timers of PARI, starting with version 1.39 this function
works much better than the preceding version.

If $flag=2$, as above, but using complex approximations to the roots and
an integral LLL ({\tt qflll(x,1)}, through {\tt lindep(x,1)}).

Set $flag=1$, ONLY when the number field $nf$ is Galois, since otherwise it
runs into an infinite loop. On the other hand, if the field is Galois, it is
guaranteed to give all the conjugates after a finite time. The method uses
$p$-adic approximations to the roots and an integral LLL ({\tt qflll(x,1)}).

The library syntax is $\teb{galoisconj0}(nf,flag,prec)$.

\subsecidx{nfhilbert}$(nf,a,b,\{pr\})$: if $pr$ is omitted, compute the global
Hilbert symbol $(a,b)$ in $nf$, that is $1$ is $x^2 - a y^2 - b z^2$ has a non
trivial solution $(x,y,z)$ in $nf$, and $-1$ otherwise. Otherwise compute the
local symbol modulo the prime ideal $pr$ (as output by {\tt idealprimedec}).

The library syntax is $\teb{nfhilbert}(nf,a,b,pr)$, where an omitted $pr$ is
coded as {\tt NULL}.

\subsecidx{nfhnf}$(nf,x)$: given a pseudo-matrix $(A,I)$, finds a
pseudo-basis in Hermite Normal Form of the module it generates.

The library syntax is $\teb{nfhermite}(nf,x)$.

\subsecidx{nfhnfmod}$(nf,x,detx)$: given a pseudo-matrix $(A,I)$ and an ideal
$detx$ which is contained in (read integral multiple of) the determinant of
$(A,I)$ finds a pseudo-basis in Hermite Normal Form of the module generated
by $(A,I)$. This avoids coefficient explosion. $detx$ can be computed using
the function {\tt nfdetint}.

The library syntax is $\teb{nfhermitemod}(nf,x,detx)$.

\subsecidx{nfinit}$(pol,\{flag=0\})$: $pol$ being a non-constant, preferably
monic, irreducible polynomial in $\Z[X]$, computes a 9-component vector
$nf$ useful in working in the number field $K$ defined by $pol$.

 $nf[1]$ contains the polynomial $pol$ ({\tt nf.pol}).

 $nf[2]$ contains $[r1,r2]$ ({\tt nf.sign}), the number of real and complex
places of $K$.

 $nf[3]$ contains the discriminant $d(K)$ ({\tt nf.disc}) of the number field
$K$.

 $nf[4]$ contains the index of $nf[1]$, i.e.~$[\Z_K:\Z[\theta]]$,
where $\theta$ is any root of $nf[1]$.

 $nf[5]$ is a vector containing 7 matrices $M$, $MC$, $T2$, $T$, $MD$, $TI$,
$MDI$ useful for certain computations in the number field $K$. The matrix $M$
is the $(r1+r2)\times n$ matrix whose columns represent the numerical values
of the conjugates of the elements of the integral basis. The matrix $MC$ is
essentially the conjugate of the transpose of $M$, except that the last $r2$
columns are also multiplied by 2. The matrix $T2$ is an $n\times n$ matrix
equal to the real part of the product $MC\cdot M$ (which is a real positive
definite symmetric matrix), the so-called $T_2$-matrix ({\tt nf.t2}). 
The matrix $T$ is the $n\times n$ matrix whose coefficients are 
$\text{Tr}(\omega_i\omega_j)$ where
the $\omega_i$ are the elements of the integral basis. Note that
$T=\overline{MC}\cdot M$ and in particular that $T=T_2$ if the field is
totally real (in practice $T_2$ will have real approximate entries and $T$
will have integer entries). Note also that $\det(T)$ is equal to the
discriminant of the field $K$. The columns of $MD$ ({\tt nf.diff}) express a
$\Z$-basis of the different of $K$ on the integral basis $nf[7]$ ({\tt nf.zk}). 
$TI$ is equal to $d(K)T^{-1}$, which has integral coefficients. Finally, the columns
of $MDI$ express a $\Z$-basis of $d(K)$ times the codifferent ideal
(which will be an integral ideal) on the integral basis $nf[7]$ 
({\tt nf.disc$*$nf.codiff}).

 $nf[6]$ is the vector containing the $r1+r2$ roots ({\tt nf.roots}) of $nf[1]$
corresponding to the $r1+r2$ embeddings of the number field into $\C$
(the first $r1$ components are real, the next $r2$ have positive imaginary
part).

 $nf[7]$ is an integral basis in Hermite normal form for $\Z_K$ ({\tt
nf.zk}) expressed on the powers of~$\theta$.

 $nf[8]$ is the $n\times n$ integral matrix expressing the power basis in
terms of the integral basis, and finally

 $nf[9]$ is the $n\times n^2$ matrix giving the multiplication table of the
integral basis.

If a non monic polynomial is input, {\tt nfinit} will transform it into a
monic one, then reduce it (see $flag=3$).

If $flag=1$: do not compute the different, replace it by a dummy $0$.

If $flag=2$: $pol$ is changed into another polynomial $P$ defining the same
number fields, which is as simple as can easily be found using the {\tt
polred} algorithm, and all the subsequent computations are done using this
new polynomial. In particular, the first component of the result is the
modified polynomial.

If $flag=3$, do a {\tt polred} as in case 2, but output $[nf,Mod(a,P)]$,
where $nf$ is as before and $Mod(a,P)=Mod(x,pol)$ gives the change of
variables. This is implicit when $pol$ is not monic: first a linear change
of variables is performed, to get a monic polynomial, then a {\tt polred}
reduction.

If $flag=4$, as $2$ but use a partial {\tt polred}.

If $flag=5$, as $3$ using a partial {\tt polred}.

The library syntax is $\teb{nfinit0}(x,flag,prec)$.

\subsecidx{nfisideal}$(nf,x)$: returns 1 if $x$ is an ideal in the number
field $nf$, 0 otherwise.

The library syntax is $\teb{isideal}(x)$.

\subsecidx{nfisincl}$(x,y,\{flag=0\})$: tests whether the number field $K$
defined by the polynomial $x$ is conjugate to a subfield of the field $L$
defined by $y$ (where $x$ and $y$ must be in $\Q[X]$). If they are not,
the output is the number 0. If they are, the output is a vector of
polynomials, each polynomial $a$ representing an embedding of $K$ into $L$,
i.e.~being such that $y\mid x\circ a$.

If $flag=1$, $x$ and $y$ {\it must} be number fields ($nf$) as output by
{\tt nfinit}, and not mere polynomials. This use a much faster algorithm,
but it may miss some embeddings, so that you need them all, you may have to
use the much slower default algorithm to be sure.

The library syntax is $\teb{nfisincl0}(x,y,flag)$.

\subsecidx{nfisisom}$(x,y,\{flag=0\})$: tests whether the two number fields
defined by the polynomials $x$ and $y$ (which must be in $\Q[X]$) are
isomorphic. If they are not, the output is the number 0. If they are, the
output is a vector of polynomials, each polynomial $a$ representing an
isomorphism, i.e.~being such that $y\mid x\circ a$.

Setting $flag=1$ has the same consequences as for the {\tt nfisincl}:
$x$ and $y$ have to be of type $nf$, and the computation will be much faster,
but some isomorphisms may be missing. To summarize, if you do not care about
the complete list of isomorphisms: set the $flag$ first. If the answer gives
at least one isomorphism, stop. Otherwise (i.e.~if the function returns 0)
use the default.

The library syntax is $\teb{nfisisom0}(x,y,flag)$.

\subsecidx{nfnewprec}$(nf)$: transform the number field $nf$ into the
corresponding data using current (usually larger) precision.

The library syntax is $\teb{nfnewprec}(nf,prec)$.

\subsecidx{nfsubfields}$(nf,\{d=0\})$: find all subfields of degree $d$ of
the number field $nf$ (all subfields if $d$ is null or omitted). Result is a
vector of subfields, each being given by $[g,h]$, where $g$ is an absolute
equation and $h$ expresses one of the roots of $g$ in terms of the root $x$
of the polynomial defining $nf$. This is a crude implementation by M.~Olivier
of an algorithm due to J.~Kl\"uners.

The library syntax is $\teb{subfields}(nf,d)$.

\subsecidx{nfroots}$(nf,x)$: roots of the polynomial $x$ in the number field
$nf$ given by {\tt nfinit} without multiplicity. $x$ has coefficients in the
number field (scalar, polymod, polynomial, column vector). The main variable
of $nf$ must be of lower priority than that of $x$ (in other words the
variable number of $nf$ must be greater than that of $x$). However if the
coefficients of the number field occur explicitly (as polymods) as
coefficients of $x$, the variable of these polymods {\it must} be the same as
the main variable of $t$ (see {\tt nffactor}).

The library syntax is $\teb{nfroots}(nf,x)$.

\subsecidx{nfrootsof1}$(nf)$: computes the number of roots of unity $w$ and a
primitive $w$-th root of unity (expressed on the integral basis) belonging to
the number field $nf$. The result is a two-component vector $[w,z]$ where
$z$ is a column vector expressing a primitive $w$-th root of unity on the
integral basis $nf[7]$ ({\tt nf.zk}).

The library syntax is $\teb{rootsof1}(nf)$.

\subsecidx{nfsnf}$(nf,x)$: given a torsion module $x$ as a 3-component row
vector $[A,I,J]$ where $A$ is a square invertible $n\times n$ matrix, $I$ and
$J$ are two ideal lists, outputs an ideal list $d_1,\dots,d_n$ which is the
Smith normal form of $x$. In other words, $x$ is isomorphic to
$\Z_K/d_1\oplus\cdots\oplus\Z_K/d_n$ and $d_i$ divides $d_{i-1}$ for $i\ge2$.
The link between $x$ and $[A,I,J]$ is as follows: if $e_i$ is the canonical
basis of $K^n$, $I=[b_1,\dots,b_n]$ and $J=[a_1,\dots,a_n]$, then $x$ is
isomorphic to
$$ (b_1e_1\oplus\cdots\oplus b_ne_n) / (a_1A_1\oplus\cdots\oplus a_nA_n)
\enspace, $$
where the $A_j$ are the columns of the matrix $A$. Note that every finitely
generated torsion module can be given in this way, and even with $b_i=Z_K$
for all $i$.

The library syntax is $\teb{nfsmith}(nf,x)$.

\subsecidx{polcompositum}$(x,y,\{flag=0\})$: $x$ and $y$ being polynomials in
$\Z[x]$ in the same variable, outputs a vector giving the list of all
possible compositums of the number fields defined by $x$ and $y$, if $x$ and
$y$ are irreducible, or of the corresponding \'etale algebras, if they are
only squarefree. Error if one of the polynomials is not squarefree.

If $flag=1$, output a vector of 3-component vectors $[z,a,b]$, where $z$
ranges through the list of all possible compositums as above, and $a$ (resp.
$b$) expresses the root of $x$ (resp. $y$) as a polmod in a root of $z$.

The library syntax is $\teb{compositum0}(x,y,flag)$.

\subsecidx{polgalois}$(x)$: Galois group of the non-constant polynomial
$x\in\Q[X]$. In the present version \vers, $x$ must be irreducible and
the degree of $x$ must be less than or equal to 7. On certain versions for
which the data file of Galois resolvents has been installed (available
in the Unix distribution as a separate package), degrees 8, 9, 10 and 11
are also implemented.

The output is a 3-component vector $[n,s,k]$ with the following meaning: $n$
is the cardinality of the group, $s$ is its signature ($s=1$ if the group is
a subgroup of the alternating group $A_n$, $s=-1$ otherwise), and $k$ is the
number of the group corresponding to a given pair $(n,s)$ ($k=1$ except in 2
cases). Specifically, the groups are coded as follows, using standard
notations (see GTM 138 quoted above):
\smallskip
In degree 1: $S_1=[1,-1,1]$.
\smallskip
In degree 2: $S_2=[2,-1,1]$.
\smallskip
In degree 3: $A_3=C_3=[3,1,1]$, $S_3=[6,-1,1]$.
\smallskip
In degree 4: $C_4=[4,-1,1]$, $V_4=[4,1,1]$, $D_4=[8,-1,1]$, $A_4=[12,1,1]$,
$S_4=[24,-1,1]$.
\smallskip
In degree 5: $C_5=[5,1,1]$, $D_5=[10,1,1]$, $M_{20}=[20,-1,1]$, $A_5=[60,1,1]$, $S_5=[120,-1,1]$.
\smallskip
In degree 6: $C_6=[6,-1,1]$, $S_3=[6,-1,2]$, $D_6=[12,-1,1]$, $A_4=[12,1,1]$,
$G_{18}=[18,-1,1]$, $S_4^-=[24,-1,1]$, $A_4\times C_2=[24,-1,2]$,
$S_4^+=[24,1,1]$, $G_{36}^-=[36,-1,1]$, $G_{36}^+=[36,1,1]$,
$S_4\times C_2=[48,-1,1]$, $A_5=PSL_2(5)=[60,1,1]$, $G_{72}=[72,-1,1]$,
$S_5=PGL_2(5)=[120,-1,1]$, $A_6=[360,1,1]$, $S_6=[720,-1,1]$.
\smallskip
In degree 7: $C_7=[7,1,1]$, $D_7=[14,-1,1]$, $M_{21}=[21,1,1]$,
$M_{42}=[42,-1,1]$, $PSL_2(7)=PSL_3(2)=[168,1,1]$, $A_7=[2520,1,1]$,
$S_7=[5040,-1,1]$.
\smallskip
The method used is that of resolvent polynomials. Beware that in the case of
degree 7 one has to factor polynomials of degree 35 over $\Z$, and this
can take a long time. Furthermore there is a risk that the PARI stack
overflows, so it is prudent in this case to start with a large stack.

The library syntax is $\teb{galois}(x,prec)$.


\subsecidx{polred}$(x,\{flag=0\},\{p\})$: finds polynomials with reasonably
small coefficients defining subfields of the number field defined by $x$.
One of the polynomials always defines $\Q$ (hence is equal to $(x-1)$,
where $n$ is the degree), and another always defines the same number field as
$x$ if $x$ is irreducible.

The following binary digits of $flag$ are significant:

1: do a partial reduction only. This means that only a suborder of the
maximal order may be used.

2: give also elements. The result is a two-column matrix, the first column
giving the elements defining these subfields, the second giving the
corresponding minimal polynomials.

If $p$ is given, it is assumed that it is the two-column matrix of the
factorization of the discriminant of the polynomial $x$.

The library syntax is $\teb{polred0}(x,flag,p,prec)$, where an omitted $p$ is
coded by $gzero$. Also available are $\teb{polred}(x,prec)$ and
$\teb{factoredpolred}(x,p,prec)$, both corresponding to $flag=0$.

\subsecidx{polredabs}$(x,\{flag=0\})$: finds one of the polynomial defining
the same number field as the one defined by $x$, and such that the sum of the
squares of the modulus of the roots (i.e.~the $T_2$-norm) is minimal.

The binary digits of $flag$ mean

1: outputs a two-component row vector $[P,a]$, where $P$ is the default
output and $a$ is an element expressed on a root of the polynomial $x$,
whose minimal polynomial is equal to $P$.

2: skip the initial {\tt polred}.

4: Give {\it all} polynomials of minimal $T_2$ norm.

The library syntax is $\teb{polredabs0}(x,flag,prec)$.

\subsecidx{polredord}$(x)$: finds polynomials with reasonably small
coefficients and of the same degree as that of $x$ defining suborders of the
order defined by $x$. One of the polynomials always defines $\Q$ (hence
is equal to $(x-1)^n$, where $n$ is the degree), and another always defines
the same order as $x$ if $x$ is irreducible.

The library syntax is $\teb{ordred}(x)$.

\subsecidx{poltschirnhaus}$(x)$: x being a non-constant separable polynomial,
apply a random Tschirnhausen transformation, so as to obtain a new equation
for the number field (or more generally the \'etale algebra) defined by $x$.
This is for instance useful when computing resolvents, hence is used in the
{\tt polgalois} function above.

The library syntax is $\teb{tschirnhaus(x)}$.

\subsecidx{rnfalgtobasis}$(rnf,x)$: $rnf$ being a relative number field 
extension $L/K$ as output by {\tt rnfinit} and $x$ being an element of $L$
expressed as a polynomial or polymod with polymod coefficients, expresses
$x$ on the relative integral basis.

The library syntax is $\teb{rnfalgtobasis}(rnf,x)$.

\subsecidx{rnfbasis}$(bnf,x)$: given a big number field $bnf$ as 
output by {\tt bnfinit}, and either a polynomial $x$ with coefficients in
$bnf$ defining a relative extension $L$ of $bnf$, or a pseudo-basis $x$ of
such an extension, gives either a true $bnf$-basis of $L$ if it exists, or an
$n+1$-element generating set of $L$ if not, where $n$ is the rank of $L$ over
$bnf$.

The library syntax is $\teb{rnfbasis}(bnf,x)$.

\subsecidx{rnfbasistoalg}$(rnf,x)$: $rnf$ being a relative number field 
extension $L/K$ as output by {\tt rnfinit} and $x$ being an element of $L$
expressed on the relative integral basis, computes the representation of
$x$ as a polymod with polymods coefficients.

The library syntax is $\teb{rnfbasistoalg}(rnf,x)$.

\subsecidx{rnfcharpoly}$(nf,T,a,\{v=x\})$: characteristic polynomial of $a$
over $nf$, where $a$ belongs to the algebra defined by $T$ over $nf$,
i.e.~$nf[X]/(T)$. Returns a polynomial in variable $v$ ($x$ by default).

The library syntax is $\teb{rnfcharpoly}{nf,T,a,v}$, where $v$ is a variable
number.

\subsecidx{rnfconductor}$(bnf,pol)$: $bnf$ being a big number field
as output by {\tt bnfinit}, and $pol$ a relative polynomial
defining an Abelian extension, computes the class field theory
conductor of this Abelian extension. The result is a 3-component
vector [conductor,rayclassgroup,subgroup], where conductor is the
conductor of the extension given as a 2-component row vector 
$[f_0,f_\infty]$, rayclassgroup is the full ray class group corresponding
to the conductor given as a 3-component vector [h,cyc,gen] as usual
for a group, and subgroup is a matrix in HNF defining the subgroup of
the ray class group on the given generators gen.

The library syntax is $\teb{rnfconductor}(rnf,pol,prec)$.

\subsecidx{rnfdedekind}$(nf,pol,pr)$: given a number field $nf$ as
output by {\tt nfinit} and a polynomial $pol$ with coefficients in $nf$
defining a relative extension $L$ of $nf$, perfoms the relative Dedekind
criterion over the order defined by a root of $pol$ for the prime ideal $pr$
and output a 3-component vector as result. The first component is a flag
equal to 1 if the enlarged order is $pr$-maximal and to 0 otherwise, the
second component is a pseudo-basis of the enlarged order and the third
component is the valuation at $pr$ of the order discriminant.

The library syntax is $\teb{rnfdedekind}(nf,pol,pr)$.

\subsecidx{rnfdet}$(nf,M)$: given a pseudomatrix $M$ over the maximal
order of $nf$, compute its pseudodeterminant.

The library syntax is $\teb{rnfdet}(nf,M)$.

\subsecidx{rnfdisc}$(nf,pol)$: given a number field $nf$ as output by {\tt
nfinit} and a polynomial $pol$ with coefficients in $nf$ defining a relative
extension $L$ of $nf$, computes the relative discriminant of $L$. This is a
two-element row vector $[D,d]$, where $D$ is the relative ideal discriminant
and $d$ is the relative discriminant considered as an element of
$nf^*/{nf^*}^2$. The main variable of $nf$ {\it must\/} be of lower priority
than that of $pol$.

Note: As usual, $nf$ can be a $bnf$ as output by {\tt nfinit}.

The library syntax is $\teb{rnfdiscf}(bnf,pol)$.

\subsecidx{rnfeltabstorel}$(rnf,x)$: $rnf$ being a relative number field 
extension $L/K$ as output by {\tt rnfinit} and $x$ being an element of $L$
expressed as a polynomial modulo the absolute equation $rnf[11][1]$, computes
$x$ as an element of the relative extension $L/K$ as a polymod with
polymod coefficients. 

The library syntax is $\teb{rnfelementabstorel}(rnf,x)$.

\subsecidx{rnfeltdown}$(rnf,x)$: $rnf$ being a relative number field 
extension $L/K$ as output by {\tt rnfinit} and $x$ being an element of $L$
expressed as a polynomial or polymod with polymod coefficients, computes
$x$ as an element of $K$ as a polymod, assuming $x$ is in $K$ (otherwise
an error will occur). If $x$ is given on the relative integral
basis, apply {\tt rnfbasistoalg} first, otherwise Pari will believe you are
dealing with a vector.

The library syntax is $\teb{rnfelementdown}(rnf,x)$.

\subsecidx{rnfeltreltoabs}$(rnf,x)$: $rnf$ being a relative number field 
extension $L/K$ as output by {\tt rnfinit} and $x$ being an element of $L$
expressed as a polynomial or polymod with polymod coefficients, computes
$x$ as an element of the absolute extension $L/\Q$ as a polynomial modulo
the absolute equation $rnf[11][1]$. If $x$ is given on the relative integral
basis, apply {\tt rnfbasistoalg} first, otherwise Pari will believe you are
dealing with a vector.

The library syntax is $\teb{rnfelementreltoabs}(rnf,x)$.

\subsecidx{rnfeltup}$(rnf,x)$: $rnf$ being a relative number field 
extension $L/K$ as output by {\tt rnfinit} and $x$ being an element of $K$
expressed as a polynomial or polymod, computes $x$ as an element of the 
absolute extension $L/\Q$ as a polynomial modulo the absolute equation
$rnf[11][1]$. Note that it is unnecessary to compute $x$ as an element of the
relative extension $L/K$ (its expression would be identical to itself).
If $x$ is given on the integral basis of $K$, apply {\tt nfbasistoalg} first,
otherwise Pari will believe you are dealing with a vector.

The library syntax is $\teb{rnfelementup}(rnf,x)$.

\subsecidx{rnfequation}$(nf,pol,\{flag=0\})$: given a number field $nf$ as
output by {\tt nfinit} (or simply a polynomial) and a polynomial $pol$ with
coefficients in $nf$ defining a relative extension $L$ of $nf$, computes the
absolute equation of $L$ over $\Q$.

  If $flag$ is non-zero, output a 3-component row vector $[z,a,k]$, where $z$
is the absolute equation of $L$ over $\Q$, as in the default behaviour,
$a$ expresses as a polmod a root $\beta$ of $pol$ in terms of a root $\theta$
of $z$, and $k$ is a small integer such that $\theta=\beta+k\alpha$ where
$\alpha$ is a root of the polynomial defining the base field $nf$.

  The main variable of $nf$ {\it must\/} be of lower priority than that of
$pol$. Note that for efficiency, this does not check whether the relative
equation is irreducible over $nf$, but only if it is squarefree. If it is
reducible but squarefree, the result will be the absolute equation of the
\'etale algebra defined by $pol$. If $pol$ is not squarefree, an error message
will be issued.

The library syntax is $\teb{rnfequation0}(nf,pol,flag)$.

\subsecidx{rnfhnfbasis}$(bnf,x)$: given a big number field $bnf$ as 
output by {\tt bnfinit}, and either a polynomial $x$ with coefficients in
$bnf$ defining a relative extension $L$ of $bnf$, or a pseudo-basis $x$ of
such an extension, gives either a true $bnf$-basis of $L$ in upper triangular
Hermite Normal Form, if it exists, zero otherwise.

The library syntax is $\teb{rnfhermitebasis}(nf,x)$.

\subsecidx{rnfidealabstorel}$(rnf,x)$: $rnf$ being a relative number field 
extension $L/K$ as output by {\tt rnfinit} and $x$ being an ideal of
the absolute extension $L/\Q$ given in HNF (if it is not, apply {\tt idealhnf}
first), computes the relative pseudomatrix in HNF giving the ideal $x$ 
considered as an ideal of the relative extension $L/K$.

The library syntax is $\teb{rnfidealabstorel}(rnf,x)$.

\subsecidx{rnfidealdown}$(rnf,x)$: $rnf$ being a relative number field 
extension $L/K$ as output by {\tt rnfinit} and $x$ being an ideal of
the absolute extension $L/\Q$ given in HNF (if it is not, apply {\tt idealhnf}
first), gives the ideal of $K$ below $x$, i.e.~the intersection of $x$ with $K$.
Note that, if $x$ is given as a relative ideal (i.e.~a pseudomatrix in HNF),
then it is not necessary to use this function since the result is simply
the first ideal of the ideal list of the pseudomatrix.

The library syntax is $\teb{rnfidealdown}(rnf,x)$.

\subsecidx{rnfidealhnf}$(rnf,x)$: $rnf$ being a relative number field 
extension $L/K$ as output by {\tt rnfinit} and $x$ being a relative ideal
(which can be, as in the absolute case, of many different types, including
of course elements), computes as a 2-component row vector the relative
hermite normal form of $x$, the first component being the HNF matrix
(with entries on the integral basis), and the second component the ideals.

The library syntax is $\teb{rnfidealhermite}(rnf,x)$.

\subsecidx{rnfidealmul}$(rnf,x,y)$: $rnf$ being a relative number field 
extension $L/K$ as output by {\tt rnfinit} and $x$ and $y$ being ideals of the
relative extension $L/K$ given by pseudo-matrices, outputs the ideal product,
again as a relative ideal.

The library syntax is $\teb{rnfidealmul}(rnf,x,y)$.

\subsecidx{rnfidealnormabs}$(rnf,x)$: $rnf$ being a relative number field 
extension $L/K$ as output by {\tt rnfinit} and $x$ being a relative ideal
(which can be, as in the absolute case, of many different types, including
of course elements), computes the norm of the ideal $x$ considered as an ideal
of the absolute extension $L/\Q$. This is identical to
 {\tt idealnorm(rnfidealnormrel(rnf,x))}, only faster.

The library syntax is $\teb{rnfidealnormabs}(rnf,x)$.

\subsecidx{rnfidealnormrel}$(rnf,x)$: $rnf$ being a relative number field 
extension $L/K$ as output by {\tt rnfinit} and $x$ being a relative ideal
(which can be, as in the absolute case, of many different types, including
of course elements), computes the relative norm of $x$ as a ideal of $K$ 
in HNF.

The library syntax is $\teb{rnfidealnormrel}(rnf,x)$.

\subsecidx{rnfidealreltoabs}$(rnf,x)$: $rnf$ being a relative number field 
extension $L/K$ as output by {\tt rnfinit} and $x$ being a relative ideal
(which can be, as in the absolute case, of many different types, including
of course elements), computes the HNF matrix of the ideal $x$ considered
as an ideal of the absolute extension $L/\Q$.

The library syntax is $\teb{rnfidealreltoabs}(rnf,x)$.

\subsecidx{rnfidealtwoelt}$(rnf,x)$: $rnf$ being a relative number field 
extension $L/K$ as output by {\tt rnfinit} and $x$ being an ideal of the
relative extension $L/K$ given by a pseudo-matrix, gives a vector of
two generators of $x$ over $\Z_L$ expressed as polymods with polymod
coefficients.

The library syntax is $\teb{rnfidealtwoelement}(rnf,x)$.

\subsecidx{rnfidealup}$(rnf,x)$: $rnf$ being a relative number field 
extension $L/K$ as output by {\tt rnfinit} and $x$ being an ideal of
$K$, gives the ideal $x\Z_L$ as an absolute ideal of $L/\Q$ (the relative
ideal representation is trivial: the matrix is the identity matrix, and
the ideal list starts with $x$, all the other ideals being $\Z_K$).

The library syntax is $\teb{rnfidealup}(rnf,x)$.

\subsecidx{rnfinit}$(nf,pol)$: $nf$ being a number field in {\tt nfinit}
format considered as base field, and $pol$ a polynomial defining a relative
extension over $nf$, this computes all the necessary data to work in the
relative extension. The main variable of $pol$ must be of higher priority
(i.e.~lower number) than that of $nf$, and the coefficients of $pol$ must
be in $nf$.

The result is a 11-component row vector as follows (most of the components
are technical), the numbering being very close to that of {\tt nfinit}.
In the following description, we let $K$ be the base field defined by $nf$,
$m$ be the degree of the base field, $n$ the relative degree, $L$ the top
field (of relative degree $n$ or absolute degree $nm$), $r_1$ and $r_2$ the
number of real and complex places of $K$.

$rnf[1]$ contains the relative polynomial $pol$.

$rnf[2]$ is a row vector with $r_1+r_2$ entries, entry $j$ being
a 2-component row vector $[r_{j,1},r_{j,2}]$ where $r_{j,1}$ and $r_{j,2}$
are the number of real and complex places of $L$ above the $j$-th place of
$K$ so that $r_{j,1}=0$ and $r_{j,2}=n$ if $j$ is a complex place, while if
$j$ is a real place we have $r_{j,1}+2r_{j,2}=n$.

$rnf[3]$ is a two component row vector $[\d(L/K),s]$ where $\d(L/K)$ is the
relative ideal discriminant of $L/K$ and $s$ is the discriminant of $L/K$
viewed as an element of $K^*/(K^*)^2$, in other words it is the output of
{\tt rnfdisc}.

$rnf[4]$ is the ideal index $\f$, i.e.~such that $d(pol)\Z_K=\f^2\d(L/K)$.

$rnf[5]$ is a vector $vm$ with 7 entries useful for certain computations is the
relative extension $L/K$. $vm[1]$ is a vector of $r_1+r_2$ matrices, the
$j$-th matrix being an $(r_{1,j}+r_{2,j})\times n$ matrix $M_j$ representing
the numerical values of the conjugates of the $j$-th embedding of the elements
of the integral basis, where $r_{i,j}$ is as in $rnf[2]$. $vm[2]$
is a vector of $r_1+r_2$ matrices, the $j$-th matrix $MC_j$ being essentially
the conjugate of the matrix $M_j$ except that the last $r_{2,j}$ columns are
also multiplied by 2. $vm[3]$ is a vector of $r_1+r_2$ matrices $T2_j$, where
$T2_j$ is an $n\times n$ matrix equal to the real part of the product
$MC_j\cdot M_j$ (which is a real positive definite matrix). $vm[4]$ is the
$n\times n$ matrix $T$ whose entries are the relative traces of 
$\omega_i\omega_j$ expressed as polymods in $nf$, where the $\omega_i$ are
the elements of the relative integral basis. Note that the $j$-th embedding
of $T$ is equal to $\overline{MC_j}\cdot M_j$, and in particular will be equal
to $T2_j$ if $r_{2,j}=0$. Note also that the relative ideal discriminant of
$L/K$ is equal to $\det(T)$ times the square of the product of the ideals
in the relative pseudo-basis (in $rnf[7][2]$). The last 3 entries
$vm[5]$, $vm[6]$ and $vm[7]$ are linked to the different as in {\tt nfinit},
but have not yet been implemented.

$rnf[6]$ is a row vector with $r_1+r_2$ entries, the $j$-th entry being the
row vector with $r_{1,j}+r_{2,j}$ entries of the roots of the $j$-th embedding
of the relative polynomial $pol$.

$rnf[7]$ is a two-component row vector, where the first component is the
relative integral pseudo basis expressed as polynomials (in the variable of
$pol$) with polymod coefficients in $nf$, and the second component is the
ideal list of the pseudobasis in HNF.

$rnf[8]$ is the inverse matrix of the integral basis matrix, with coefficients
polymods in $nf$. 

$rnf[9]$ may be the multiplication table of the integral basis, but is not
implemented at present.

$rnf[10]$ is $nf$.

$rnf[11]$ is a vector $vabs$ with 5 entries describing the {\it absolute\/}
extension $L/\Q$. $vabs[1]$ is an absolute equation. $vabs[2]$ expresses
the generator $\alpha$ of the number field $nf$ as a polynomial modulo the 
absolute equation $vabs[1]$. $vabs[3]$ is a small integer $k$ such that,
if $\beta$ is an abstract root of $pol$ and $\alpha$ the generator of $nf$,
the generator whose root is $vabs$ will be $\beta + k \alpha$. Note that one
must be very careful if $k\neq0$ when dealing simultaneously with absolute
and relative quantities since the generator chosen for the absolute extension
is not the same as for the relative. If this happens, one can of course
go on working, but we strongly advise to change the relative polynomial
so that its root will be $\beta + k \alpha$. Typically, the GP instruction
would be

  {\tt pol = subst(pol, x, x - k*Mod(y,nf.pol))}

Finally, $vabs[4]$ is the absolute integral basis of $L$ expressed in HNF
(hence as would be output by {\tt nfinit(vabs[1])}) and $vabs[5]$
the inverse matrix of the integral basis, allowing to go from polymod to
integral basis representation.

The library syntax is $\teb{rnfinitalg}(nf,pol,prec)$.

\subsecidx{rnfisfree}$(bnf,x)$: given a big number field $bnf$ as 
output by {\tt bnfinit}, and either a polynomial $x$ with coefficients in
$bnf$ defining a relative extension $L$ of $bnf$, or a pseudo-basis $x$ of
such an extension, returns true (1) if $L/bnf$ is free, false (0) if not.

The library syntax is $\teb{rnfisfree}(bnf,x)$, and the result is a
C-long integer.

\subsecidx{rnfisnorm}$(bnf,ext,el,\{flag=1\})$: similar to {\tt bnfisnorm}
but in the relative case. This tries to decide whether the element $el$ in
$bnf$ is the norm of some $y$ in $ext$. $bnf$ is as output by {\tt bnfinit}. 

$ext$ is a relative extension which has to be a row vector whose components
are:

$ext[1]$: a relative equation of the number field $ext$ over $bnf$. As usual,
the priority of the variable of the polynomial defining the ground field $bnf$
(say $y$) must be lower than the main variable of $ext[1]$, say $x$.

$ext[2]$: the generator $y$ of the base field as a polynomial in $x$ (as
given by {\tt rnfequation} with $flag = 1$).

$ext[3]$: is the {\tt bnfinit} of the absolute extension $ext/\Q$.

This returns a vector $[a,b]$, where $el=Norm(a)*b$. Looks for a solution
which is a S-integer, with S a list of places (in $bnf$) containing the
ramified primes, the generators of the class group of $ext$, as well as those
primes dividing $el$. If $ext$/$bnf$ is known to be Galois, set $flag=0$ (here
$el$ is a norm iff $b=1$). If $flag$ is non zero add to S all the places above
the primes: dividing $flag$ if $flag<0$, less than $flag$ if $flag>0$. The
answer is guaranteed (i.e.~$el$ norm iff $b=1$) under GRH, if S contains all
primes less than $12\log(Ext)^2$, where $Ext$ is the normal closure of
$ext / bnf$.

The library syntax is $\teb{rnfisnorm}(bnf,ext,x,flag,prec)$.

\subsecidx{rnfkummer}$(bnr,subgroup,\{deg=0\})$: $bnr$ being as output
by {\tt bnrinit}, finds a relative equation for the class field corresponding
to the module in $bnr$ and the given congruence subgroup. If $deg$ is
positive, output the list of all relative equations of degree $deg$ contained
in the ray class field defined by $bnr$.

(THIS PROGRAM IS STILL IN DEVELOPMENT STAGE)

The library syntax is $\teb{rnfkummer}(bnr,subgroup,deg,prec)$, where $deg$
is a {\tt long} integer.

\subsecidx{rnflllgram}$(nf,pol,order)$: given a polynomial $pol$ with
coefficients in $nf$ and an order $order$ as output by {\tt rnfpseudobasis}
or similar, gives $[[neworder],U]$, where $neworder$ is a reduced order and
$U$ is the unimodular transformation matrix.

The library syntax is $\teb{rnflllgram}(nf,pol,order,prec)$.

\subsecidx{rnfnormgroup}$(bnr,pol)$: $bnr$ being a big ray class field
as output by {\tt bnrinit} and $pol$ a relative polynomial defining
an Abelian extension, computes the norm group (alias Artin or Takagi
group) corresponding to the Abelian extension of $bnf=bnr[1]$ defined by
$pol$, where the module corresponding to $bnr$ is assumed to be a multiple
of the conductor. The result is the HNF defining the norm group on the
given generators of $bnr[5][3]$. Note that neither the fact that $pol$
defines an Abelian extension nor the fact that the module is a multiple of
the conductor is checked.

The library syntax is $\teb{rnfnormgroup}(bnr,pol)$.

\subsecidx{rnfpolred}$(nf,pol)$: relative version of {\tt polred}. Given a
polynomial $pol$ with coefficients in $nf$, finds a list of relative
polynomials defining some subfields, hopefully simpler and containing the
original field.

The library syntax is $\teb{rnfpolred}(nf,pol,prec)$.

\subsecidx{rnfpolredabs}$(nf,pol)$: relative version of {\tt polredabs}.
Given a polynomial $pol$ with coefficients in $nf$, finds a list of simpler
relative polynomials defining the same field. 

{\bf Remark.} In the present implementation, although this is slower than 
{\tt rnfpolred}, it is much more efficient, the difference being more dramatic
than in the absolute case. This is because the implementation of {\tt rnfpolred}
is based on an incomplete reduction theory of lattices over number fields
(i.e.~the function {\tt rnflllgram}) which deserves to be improved.

The library syntax is $\teb{rnfpolredabs}(nf,pol,prec)$.

\subsecidx{rnfpseudobasis}$(nf,pol)$: given a number field $nf$ as output by
{\tt nfinit} and a polynomial $pol$ with coefficients in $nf$ defining a
relative extension $L$ of $nf$, computes a pseudo-basis $(A,I)$ and the
relative discriminant of $L$. This is output as a four-element row vector
$[A,I,D,d]$, where $D$ is the relative ideal discriminant and $d$ is the
relative discriminant considered as an element of $nf^*/{nf^*}^2$.

Note: As usual, $nf$ can be a $bnf$ as output by {\tt bnfinit}.

The library syntax is $\teb{rnfpseudobasis}(nf,pol)$.

\subsecidx{rnfsteinitz}$(nf,x)$: given a number field $nf$ as output
by {\tt nfinit} and either a polynomial $x$ with coefficients in $nf$ defining
a relative extension $L$ of $nf$, or a pseudo-basis $x$ of such an extension
as output for example by {\tt rnfpseudobasis}, computes another pseudo-basis
$(A,I)$ (not in HNF in general) such that all the ideals of $I$ except
perhaps the last one are equal to the ring of integers of $nf$, and outputs
the four-component row vector $[A,I,D,d]$ as in {\tt rnfpseudobasis}. The name of
this function comes from the fact that the ideal class of the last ideal of
$I$ (which is well defined) is called the {\it steinitz class\/} of the
module $\Z_L$.

Note: $nf$ can be a $bnf$ as output by {\tt bnfinit}.

The library syntax is $\teb{rnfsteinitz}(nf,x)$.

\subsecidx{subgrouplist}$(bnr,\{bound\},\{flag=0\})$: $bnr$ being as output by
{\tt bnrinit} or a list of cyclic components of a finite Abelian group $G$,
outputs the list of subgroups of $G$ (of index bounded by $bound$, if not
omitted). Subgroups are given as HNF left divisors of the SNF matrix
corresponding to $G$. If $flag=0$ (default) and $bnr$ is as output by {\tt
bnrinit}, gives only the subgroups whose modulus is the conductor.

The library syntax is $\teb{subgrouplist0}(bnr,bound,flag,prec)$, where
$bound$, $flag$ and $prec$ are long integers.

\subsecidx{zetak}$(znf,x,\{flag=0\})$: $znf$ being a number field initialized
by {\tt zetakinit} ({\it not} by {\tt nfinit}), computes the value of the
Dedekind zeta function of the number field at the complex number $x$. If
$flag=1$ compute Dedekind $\Lambda$ function instead (i.e.~the product of the
Dedekind zeta function by its gamma and exponential factors).

The accuracy of the result depends in an essential way on the accuracy of
both the {\tt zetakinit} program and the current accuracy, but even so the
result may be off by up to 5 or 10 decimal digits.

The library syntax is $\teb{glambdak}(znf,x,prec)$ or
$\teb{gzetak}(nfz,x,prec)$.

\subsecidx{zetakinit}$(x)$: compute a number of initialization data
concerning the number field defined by the polynomial $x$ so as to be
able to compute the Dedekind zeta and lambda functions (respectively
{\tt zetak}$(x)$ and {\tt zetak}$(x,1)$). This function calls in particular
the {\tt bnfinit} program, and is extremely dependent on the current
precision. The result is a 9-component vector $v$ whose components are very
technical and cannot really be used by the user except through the programs
{\tt zetak}. The only component which can be used if it has not been done
already is $v[1][4]$ which is the result of the {\tt bnfinit} call.

The library syntax is $\teb{initzeta}(x)$.

\section{Polynomials and power series.}

We group here all functions which are specific to polynomials or power
series. Many other functions which can be applied on these objects are
described in the other sections. Also, some of the functions described here
can be applied to other types.

\subsecidx{O}$(a$\kbd{\pow}$b)$: $p$-adic (if $a$ is an integer greater or equal to 2)
or power series zero (in all other cases), with precision given by $b$.

The library syntax is $\teb{ggrandocp}(a,b)$, where $b$ is a {\tt long}.

\subsecidx{deriv}$(x,y)$: derivative of $x$ with respect to the simple
variable $y$. $x$ can be any type except polmod. The derivative of a scalar
type is zero, and the derivative of a vector or matrix is done componentwise.
One can use $x'$ as a shortcut if derivation is with respect to the main variable
of $x$.

The library syntax is $\teb{deriv}(x,v)$, where $v$ is the number of the
variable $y$.

\subsecidx{eval}$(x)$: replace in $x$ the formal variables by the values that
have been assigned to them after the creation of $x$. This is mainly useful
in GP, and not in library mode. Do not confuse this with substitution (see
{\tt subst} below). Applying this function to a character string yields the
output from the corresponding GP command, as if directly input from the
keyboard (see \secref{se:strings}).

The library syntax is $\teb{geval}(x)$. The more basic function
$\teb{poleval}(q,x)$, $\teb{qfeval}(q,x)$ and $\teb{hqfeval}(q,x)$, evaluate
$q$ at $x$, where $q$ is respectively assumed to be a polynomial, a quadratic
form (a symetric matrix), an hermitian form (an hermitian complex matrix).

\subsecidx{factorpadic}$(pol,p,r,\{flag=0\})$: $p$-adic factorization of the
polynomial $pol$ to precision $r$, the result being a two-column matrix as in
{\tt factor}. $r$ must be in general be strictly larger than the $p$-adic
valuation of the discriminant of $pol$ for the result to make any sense. The
method used is Ford-Letard's implementation of the round 4 algorithm of
Zassenhaus. 

If $flag=1$, use an algorithm due to Buchmann and Lenstra, which is usually 
less efficient.

The library syntax is $\teb{factorpadic4}(pol,p,r)$, where $r$ is a C-long
integer.

\subsecidx{intformal}$(x,y)$: \idx{formal integration} of $x$ with respect to
the simple variable $y$. No logarithmic terms must occur in the result. $x$
can be of any type. When $x$ is a rational function, it is assumed that the
base ring is an integral domain of characteristic zero.

The library syntax is $\teb{integ}(x)$.

\subsecidx{padicappr}$(pol,a)$: vector of $p$-adic roots of the polynomial
$pol$ congruent to the $p$-adic number $a$ modulo $p$ (or modulo 4 if $p=2$),
and with the same $p$-adic precision as $a$. The number $a$ can be an
ordinary $p$-adic number (type \typ{PADIC}, i.e.~an element of $\Q_p$) or
can be an element of a finite extension of $\Q_p$, in which case it is of
type {\tt POLMOD}, where at least one of the coefficients of the polmod is a
$p$-adic number. In this case, the result is the vector of roots belonging to
the same extension of $\Q_p$ as $a$.

The library syntax is $\teb{apprgen9}(pol,a)$, but if $a$ is known to be
simply a $p$-adic number (type \typ{PADIC}), the syntax
$\teb{apprgen}(pol,a)$ can be used.

\subsecidx{polcoeff}$(x,s)$: coefficient of degree $s$ of the polynomial $x$.

The library syntax is $\teb{truecoeff}(x,s)$.

\subsecidx{poldegree}$(x)$: degree of the polynomial $x$. This is to be
understood as follows. When $x$ is a polynomial or rational function, it
gives the degree of $x$, the degree of $0$ being $-1$ by convention. When
$x$ is a non-zero scalar, it gives 0, and when $x$ is a zero scalar, it gives
$-1$. Error otherwise.

The library syntax is $\teb{degree}(x)$, where the result is a {\tt long}.

\subsecidx{polcyclo}$(n,\{v=x\})$: $n$-th cyclotomic polynomial, in variable
$v$ ($x$ by default). The integer $n$ must be positive.

The library syntax is $\teb{cyclo}(n,v)$, where $n$ and $v$ are C-long
integer ($v$ is a variable number, usually obtained through {\tt varn}).

\subsecidx{poldisc}$(pol)$: discriminant of the polynomial $pol$. The
algorithm used is the \idx{subresultant algorithm}.

The library syntax is $\teb{discsr}(x)$.

\subsecidx{poldiscreduced}$(f)$: reduced discriminant vector of the
polynomial $f$. This is the vector of elementary divisors of
$\Z[\alpha]/f'(\alpha)\Z[\alpha]$, where $\alpha$ is a root of the polynomial
$f$. The components of the result are all positive, and their product is
equal to the absolute value of the discriminant of $f$.

The library syntax is $\teb{reduceddiscsmith}(x)$.

\subsecidx{polinterpolate}$(xa,ya,\{v=x\})$: given the data vectors $xa$ and
$ya$ of the same length $n$ ($xa$ containing the $x$-coordinates, and $ya$
the corresponding $y$-coordinates), this function finds the
\idx{interpolating polynomial} passing through these points and evaluates it
at $v$.

The library syntax is $\teb{polint}(xa,ya,v,\&er)$, where $er$ will contain an
error estimate on the returned value.

\subsecidx{polisirreducible}$(pol)$: $pol$ being a polynomial
(univariate in the present version \vers), returns 1 if $pol$ is
non-constant and irreducible, 0 otherwise. Irreducibility is checked over
the smallest base field over which $pol$ seems to be defined.

The library syntax is $\teb{gisirreducible}(pol)$.

\subsecidx{polkaramul}$(x,y,k)$: Karatsuba multiplication of polynomials $x$
and $y$ recursively called $k$ times. This is a very primitive and
preliminary attempt at a sturdy Karatsuba program, and will hopefully
be improved (in particular the recursion variable $k$ will disappear).

The library syntax is $\teb{karamul}(x,y,k)$, where $k$ is a {\tt long}.

\subsecidx{pollead}$(x)$: leading coefficient of the polynomial or power
series $x$.

The library syntax is $\teb{leadingcoeff}(x)$.

\subsecidx{pollegendre}$(n,\{v=x\})$: creates the $n^{\text{th}}$
\idx{Legendre polynomial}, in variable $v$.

The library syntax is $\teb{legendre}(n)$, where $x$ is a C-long integer.

\subsecidx{polrecip}$(pol)$: reciprocal polynomial of $pol$, i.e.~the
coefficients are in reverse order. $pol$ must be a polynomial.

The library syntax is $\teb{polrecip}(x)$.

\subsecidx{polresultant}$(x,y,\{flag=0\})$: resultant of the two polynomials
$x$ and $y$ with exact entries. The algorithm used is the subresultant
algorithm by default.

If $flag=1$, use the determinant of Sylvester's matrix instead.

The library syntax is $\teb{polresultant0}(x,y,flag)$. Also available are
$\teb{subres}(x,y)$ ($flag=0$) and $\teb{resultant2}(x,y)$ ($flag=1$).

\subsecidx{polroots}$(pol,\{flag=0\})$: complex roots of the polynomial $pol$,
given as a column vector where each root is repeated according to its
multiplicity. The precision is given as for transcendental functions: under
GP it is kept in the variable {\tt realprecision} and is transparent to the
user, but it must be explicitly given as a second argument in library mode.

The algorithm used is a modification of A.~Sch\"onhage's remarkable
root-finding algorithm, due to and implemented by X.~Gourdon. Barring bugs,
it is guaranteed to converge and to give the roots to the required accuracy.

If $flag=1$, use a variant of the Newton-Raphson method, which is {\it not}
guaranteed to converge, but is rather fast. If you get the messages ``too
many iterations in roots'' or ``INTERNAL ERROR: incorrect result in roots'',
use the default function (i.e.~no flag or $flag=0$). This used to be the
default root-finding function used in PARI until version 1.39.06.

The library syntax is $\teb{roots}(pol,prec)$ or $\teb{rootsold}(pol,prec)$.

\subsecidx{polrootsmod}$(pol,p,\{flag=0\})$: row vector of roots modulo $p$
of the polynomial $pol$. The particular non-prime value $p=4$ is accepted,
mainly for $2$-adic computations. Multiple roots are {\it not} repeated.

If $p<100$, you may try setting $flag=1$, which uses a naive search. In this
case, multiple roots {\it are} repeated with their order of multiplicity.

The library syntax is $\teb{rootmod}(x,p)$ ($flag=0$) or
$\teb{rootmod2}(x,p)$ ($flag=1$).

\subsecidx{polrootspadic}$(pol,p,r)$: row vector of $p$-adic roots of the
polynomial $pol$ with $p$-adic precision equal to $r$. Multiple roots are
{\it not} repeated.

The library syntax is $\teb{rootpadic}(pol,p,r)$, where $r$ is a C-long integer.

\subsecidx{polsturm}$(pol,\{a\},\{b\})$: number of real roots of the real
polynomial $pol$ in the interval $]a,b]$, using Sturm's algorithm. $a$
(resp. $b$) is taken to be $-\infty$ (resp. $+\infty$) if omitted.

The library syntax is $\teb{sturmpart}(pol,a,b)$. Use NULL to omit an argument.
$\teb{sturm}(pol)$ is equivalent to $\teb{sturmpart}(pol,NULL,NULL)$.
The result is a C-long integer.

\subsecidx{polsubcyclo}$(p,d,\{v=x\})$: gives the polynomial (in variable
$v$) defining the sub-Abelian extension of degree $d$ of $\Q(\zeta_p)$,
where $d\mid\phi(p)$. $p$ must be a prime or an odd prime power.

The library syntax is $\teb{subcyclo}(p,d,v)$, where $v$ is a variable
number.

\subsecidx{polsylvestermatrix}$(x,y)$: forms the Sylvester matrix
corresponding to the two polynomials $x$ and $y$, where the coefficients of
the polynomials are put in the columns of the matrix (which is the natural
direction for solving equations afterwards). The use of this matrix can be
essential when dealing with polynomials with inexact entries, since
polynomial Euclidean division doesn't make much sense in that case.

The library syntax is $\teb{sylvestermatrix}(x,y)$.

\subsecidx{polsym}$(x,n)$: creates the vector of the \idx{symmetric powers}
of the roots of the polynomial $x$ up to power $n$.

The library syntax is $\teb{polsym}(x)$.

\subsecidx{poltchebi}$(n,\{v=x\})$: creates the $n^{\text{th}}$ Tchebicheff
polynomial, in variable $v$.

The library syntax is $\teb{tchebi}(n,v)$, where $n$ and $v$ are C-long
integers ($v$ is a variable number).

\subsecidx{polzagier}$(n,m)$: creates Zagier's polynomial $P_{n,m}$ used in
the functions {\tt sumalt} and {\tt sumpos} (with $flag=1$). The exact
definition can be found in a forthcoming paper. One must have $m\le n$.

The library syntax is either $\teb{polzagreel}(n,m,prec)$ if the result is
only wanted as a polynomial with real coefficients to the precision $prec$,
or as $\teb{polzag}(n,m)$ if the result is wanted exactly, where $n$ and $m$
must be C long integers.

\subsecidx{serconvol}$(x,y)$: convolution (or \idx{Hadamard product}) of the
two power series $x$ and $y$; in other words if $x=\sum a_k*X^k$ and $y=\sum
b_k*X^k$ then {\tt serconvol}$(x,y)=\sum a_k*b_k*X^k$.

The library syntax is $\teb{convol}(x,y)$.

\subsecidx{serlaplace}$(x)$: $x$ must be a power series with only
non-negative exponents. If $x=\sum (a_k/k!)*X^k$ then the result is $\sum
a_k*X^k$.

The library syntax is $\teb{laplace}(x)$.

\subsecidx{serreverse}$(x)$: reverse power series (i.e.~$x^{-1}$, not $1/x$)
of $x$. $x$ must be a power series whose valuation is exactly equal to one.

The library syntax is $\teb{recip}(x)$.

\subsecidx{subst}$(x,y,z)$:
replace the simple variable $y$ by the argument $z$ in the ``polynomial''
expression $x$. Every type is allowed for $x$, but if it is not a genuine
polynomial (or power series, or rational function), the substitution will be
done as if the scalar components were polynomials of degree one. In
particular, beware that:

\bprog
? subst(1, x, [0,1; 1,0])
\%1 = [1,0;0,1]

? subst(1, x, Mat([0,1]))
\q  ***   forbidden substitution by a non square matrix
\eprog

If $x$ is a power series, $z$ must be either a polynomial, a power series, or
a rational function. $y$ must be a simple variable name.

The library syntax is $\teb{gsubst}(x,v,z)$, where $v$ is the number of
the variable $y$.

\subsecidx{taylor}$(x,y)$: Taylor expansion around $0$ of $x$ with respect to
\label{se:taylor}
the simple variable $y$. $x$ can be of any reasonable type, for example a
rational function. The number of terms of the expansion is transparent to the
user under GP, but must be given as a second argument in library mode.

The library syntax is $\teb{tayl}(x,y,n)$, where the C-long integer $n$
is the desired number of terms in the expansion.

\subsecidx{thue}$(tnf,a,\{sol\})$: solve the equation $P(x,y)=a$ in integers
$x$ and $y$, where $tnf$ was created with {\tt thueinit}$(P)$. $sol$, if
present contains the solutions of $Norm(x)=a$ modulo units of positive norm
in the number field defined by $P$ (as computed by {\tt bnfisintnorm}). If
$tnf$ was computed without assuming GRH ($flag=1$ in {\tt thueinit}), the
result is unconditional.

The library syntax is $\teb{thue}(tnf,a,sol)$, where an omitted $sol$ is
coded as {\tt NULL}.

\subsecidx{thueinit}$(P,\{flag=0\})$: initialize the $tnf$ corresponding to 
$P$. It is to be used to solve Thue equations $P(x,y) = a$, where $a$ is some
integer. If flag is non-zero, certify the result unconditionnaly, Otherwise,
assume GRH, the latter being much faster of course.

The library syntax is $\teb{thueinit}(P,flag,prec)$.

\section{Vectors, matrices, linear algebra and sets.}
\label{se:linear_algebra}

\subsecidx{algdep}$(x,k,\{flag=0\})$: \sidx{algebraic dependence} $x$ being
real or complex, finds a polynomial of degree at most $k$ having $x$ as
approximate root. The algorithm used is a variant of the LLL algorithm due
to Hastad, Lagarias and Schnorr (STACS 1986). Note that the polynomial which
is obtained is not necessarily the ``correct'' one (it's not even guaranteed
to be irreducible!). One can check the closeness either by a polynomial
evaluation or substitution, or by computing the roots of the polynomial given
by algdep.

If $flag$ is non-zero, use a standard LLL. $flag$ then indicates a precision,
which should be between $0.5$ and $1.0$ times the number of decimal digits
to which $x$ was computed.

The library syntax is $\teb{algdep0}(x,k,dec,prec)$, where $k$ and $flag$ are
C-long integers. Also available is $\teb{algdep}(x,k,prec)$ ($flag=0$).

\subsecidx{charpoly}$(A,\{v=x\},\{flag=0\})$: \idx{characteristic polynomial}
of $A$ with respect to the variable $v$, i.e.~determinant of $v*I-A$ if $A$
is a square matrix, determinant of the map multiplication by $A$ if $A$ is a
scalar, in particular a polymod (e.g {\tt charpoly(I,x)=x\pow2+1}), error if
$A$ is of any other type. The value of $flag$ is only significant for matrices.

If $flag=0$, the method used is essentially the same as for computing the
adjoint matrix, i.e.~computing the traces of the powers of $A$.

If $flag=1$, use Lagrange interpolation which is almost always slower.

If $flag=2$, use the Hessenberg form. This is faster than the default when
the coefficients are integermod a prime or real numbers, but is usually
slower in other base rings.

The library syntax is $\teb{charpoly0}(A,v,flag)$, where $v$ is the variable 
number. Also available are the functions $\teb{caract}(A,v)$ ($flag=1$),
$\teb{carhess}(A,v)$ ($flag=2$), and $\teb{caradj}(A,v,pt)$. Where, in this
last case, $pt$ is a {\tt GEN*} which, if not equal to NULL, will contain the
address of the adjoint matrix of $A$ (see {\tt matadjoint}), so both can be
obtained at once.

\subsecidx{concat}$(x,y)$: concatenation of $x$ and $y$. If $x$ or $y$ is
not a vector or matrix, it is considered as a one-dimensional vector. All
types are allowed for $x$ and $y$, but the sizes must be compatible. Note
that matrices are concatenated horizontally, i.e.~the number of rows stays
the same. Using transpositions, it is easy to concatenate them vertically.

To concatenate vectors sideways (i.e.~to obtain a two-row or two-column
matrix), first transform the vector into a one-row or one-column matrix using
the function {\tt Mat}.

The empty matrix $[;]$ ({\it not $[]$\/}) is considered to have a number of
rows compatible with any operation, in particular concatenation.

The library syntax is $\teb{concat}(x,y)$.

\subsecidx{lindep}$(x,\{flag=0\})$: \sidx{linear dependence}$x$ being a
vector with real or complex coefficients, finds a small integral linear
combination among these coefficients.

If $flag=0$, use a variant of the LLL algorithm due to Hastad, Lagarias and
Schnorr (STACS 1986).

If $flag>0$, use the LLL algorithm. $flag$ is a parameter which should be
between one half the number of decimal digits of precision and that number
(see {\tt algdep} above).

If $flag<0$, return as soon as one relation has been found.

The library syntax is $\teb{lindep0}(x,flag,prec)$. Also available is
$\teb{lindep}(x,prec)$ ($flag=0$).

\subsecidx{listcreate}$(n)$: creates an empty list of maximal length $n$.

This function is useless in library mode.

\subsecidx{listinsert}$(list,x,n)$: insert the object $x$ at position $n$ in 
$list$ (which must be of type \typ{LIST}). All the remaining elements of 
$list$ (after position $n$ included), are shifted to the right. This and {\tt
listput} are the only commands which enables you to increase a list's
effective length (as long as it remains under the maximal length specified by
{\tt listcreate}).

This function is useless in library mode.

\subsecidx{listkill}$(list)$: kill $list$. This deletes all elements from
$list$ and sets its effective length to $0$. The maximal length is not
affected.

This function is useless in library mode.

\subsecidx{listput}$(list,x,\{n\})$: sets the $n$-th element of the list
$list$ (which must be of type \typ{LIST}) equal to $x$. If $n$ is omitted,
or greater than the list current effective length, just append $x$. This and
{\tt listinsert} are the only commands which enables you to increase a list's
effective length (as long as it remains under the maximal length specified by
{\tt listcreate}).

If you want to put an element in an occupied cell, i.e.~if you don't want to
change the effective length, you can consider the list as a vector and use
the usual {\tt list[n] = x} construct.

This function is useless in library mode.

\subsecidx{listsort}$(list,\{flag=0\})$: sort $list$ (which must be of type
\typ{LIST}) in place. If $flag$ is non-zero, suppress all repeated
coefficients. This is much faster than the {\tt vecsort} command since no
copy has to be made.

This function is useless in library mode.

\subsecidx{matadjoint}$(x)$: \idx{adjoint matrix} of $x$, i.e.~the matrix $y$
of cofactors of $x$, satisfying $x*y=\text{det}(x)*\text{Id}$. $x$ must be a
(non-necessarily invertible) square matrix.

The library syntax is $\teb{adj}(x)$.

\subsecidx{matcompanion}$(x)$: the companion matrix to the polynomial $x$.

The library syntax is $\teb{assmat}(x)$.

\subsecidx{matdet}$(x,\{flag=0\})$: determinant of $x$. $x$ must be a
square matrix.

If $flag=0$, use Gauss-Bareiss.

If $flag=1$, use classical gaussian elimination, which is better when the
entries of the matrix are reals or integers for example, but usually much
worse for more complicated entries like multivariate polynomials.

The library syntax is $\teb{det}(x)$ ($flag=0$) and $\teb{det2}(x)$
($flag=1$).

\subsecidx{matdetint}$(x)$: $x$ being an $m\times n$ matrix with integer
coefficients, this function computes a multiple of the determinant of the
lattice generated by the columns of $x$ if it is of rank $m$, and returns
zero otherwise. This function can be useful in conjunction with the function
{\tt mathnfmod} which needs to know such a multiple. Other ways to obtain
this determinant (assuming the rank is maximal) is {\tt
matdet(qflll(x,4)[2]$*$x)} or more simply {\tt matdet(mathnf(x))}. Try to see
which is faster in your case.

The library syntax is $\teb{detint}(x)$.

\subsecidx{matdiagonal}$(x)$: $x$ being a vector, creates the diagonal matrix
whose diagonal entries are those of $x$.

The library syntax is $\teb{diagonal}(x)$.

\subsecidx{mateigen}$(x)$: gives the eigenvectors of $x$ as columns of a
matrix.

The library syntax is $\teb{eigen}(x)$.

\subsecidx{mathess}$(x)$: Hessenberg form of the square matrix $x$.

The library syntax is $\teb{hess}(x)$.

\subsecidx{mathilbert}$(x)$: $x$ being a C-long integer, creates the
\idx{Hilbert matrix} of order $x$, i.e.~the matrix whose coefficient
($i$,$j$) is $1\over {i+j-1}$.

The library syntax is $\teb{mathilbert}(x)$.

\subsecidx{mathnf}$(x,\{flag=0\})$: if $x$ is a (not necessarily square)
matrix of maximal rank, finds the {\it upper triangular} Hermite Normal Form
of $x$. If the rank of $x$ is equal to its number of rows, the result is a
square matrix. In general, the columns of the result form a basis of the
lattice spanned by the columns of $x$. 

If $flag=0$, use the na\"\i ve algorithm.

If $flag=1$, use Batut's algorithm. Output a two-component row vector
$[H,U]$, where $H$ is the {\it upper triangular} Hermite Normal Form of $x$
(i.e.~the default result) and $U$ is the unimodular transformation matrix such
that $xU=[0|H]$. If the rank of $x$ is equal to its number of rows, $H$ is a
square matrix. In general, the columns of $H$ form a basis of the lattice
spanned by the columns of $x$.

If $flag=2$, use Havas's algorithm. Output $[H,U,P]$, such that
$H$ and $U$ are as before and $P$ is a permutation of the rows such that $P$
applied to $xU$ gives $H$. This does not work very well in present version
\vers.

If $flag=3$, use Batut's algorithm, and output $[H,U,P]$ as in the previous
case.

If $flag=4$, as in case 1 above, but use some LLL reduction along the way.

The library syntax is $\teb{mathnf0}(x,flag)$. Also available are
$\teb{hnf}(x)$ ($flag=0$) and $\teb{hnfall}(x)$ ($flag=1$).

\subsecidx{mathnfmod}$(x,d)$: if $x$ is a (not necessarily square) matrix of
maximal rank with integer entries, and $d$ is a multiple of the (non-zero)
determinant of the lattice spanned by the columns of $x$, finds the {\sl
upper triangular} Hermite Normal Form of $x$.

If the rank of $x$ is equal to its number of rows, the result is a square
matrix. In general, the columns of the result form a basis of the lattice
spanned by the columns of $x$. This is much faster than {\tt mathnf} when $d$
is known.

The library syntax is $\teb{hnfmod}(x,d)$.

\subsecidx{mathnfmodid}$(x,d)$: output the (upper triangular) Hermite normal
form of $x$ concatenated with $d$ times the identity matrix.

The library syntax is $\teb{hnfmodid}(x,d)$.

\subsecidx{matid}$(n)$: creates the $n\times n$ identity matrix.

The library syntax is $\teb{idmat}(n)$ where $n$ is a C-long integer.

Related functions are $\teb{gscalmat}(x,n)$, which creates $x$ times the
identity matrix ($x$ being a \kbd{GEN} and $n$ a C-long integer), and
$\teb{gscalsmat}(x,n)$ which is the same when $x$ is a C-long integer.

\subsecidx{matimage}$(x,\{flag=0\})$: gives a basis for the image of the
matrix $x$ as columns of a matrix. A priori the matrix can have entries of
any type. If $flag=0$, use standard Gauss pivot. If $flag=1$, use {\tt
matsupplement}.

The library syntax is $\teb{matimage0}(x,flag)$. Also available is
$\teb{image}(x)$ ($flag=0$).

\subsecidx{matimagecompl}$(x)$: gives the vector of the column indices which
are not extracted by the function {\tt matimage}. Hence the number of
components of {\tt matimagecompl(x)} plus the number of columns of {\tt
matimage(x)} is equal to the number of columns of the matrix $x$.

The library syntax is $\teb{imagecompl}(x)$.

\subsecidx{matindexrank}$(x)$: $x$ being a matrix of rank $r$, gives two
vectors $y$ and $z$ of length $r$ giving a list of rows and columns
respectively (starting from 1) such that the extracted matrix obtained from
these 2 vectors using {\tt vecextract}$(x,y,z)$ is invertible.

The library syntax is $\teb{indexrank}(x)$.

\subsecidx{matintersect}$(x,y)$: $x$ and $y$ being two matrices with the same
number of rows each of whose columns are independent, finds a basis of the
$\Q$-vector space equal to the intersection of the spaces spanned by the
columns of $x$ and $y$ respectively. See also the function {\tt
\sidx{idealintersect}} above, which does the same for free $\Z$-modules.

The library syntax is $\teb{intersect}(x,y)$.

\subsecidx{matinverseimage}$(x,y)$: gives a column vector belonging to the
inverse image of the column vector $y$ by the matrix $x$ if one exists, the
empty vector otherwise. To get the complete inverse image, it suffices to add
to the result any element of the kernel of $x$ obtained for example by
{\tt matker}.

The library syntax is $\teb{inverseimage}(x,y)$.

\subsecidx{matisdiagonal}$(x)$: returns true (1) if $x$ is a diagonal matrix,
false (0) if not.

The library syntax is $\teb{isdiagonal}(x)$, and this returns a C-long
integer.

\subsecidx{matker}$(x,\{flag=0\})$: gives a basis for the kernel of the
matrix $x$ as columns of a matrix. A priori the matrix can have entries of
any type. 

If $x$ is known to have integral entries, set $flag=1$.

The library syntax is $\teb{matker0}(x,flag)$. Also available are
$\teb{ker}(x)$ ($flag=0$) and $\teb{keri}(x)$ ($flag=1$).

\subsecidx{matkerint}$(x,\{flag=0\})$: gives an LLL-reduced $\Z$-basis
for the lattice equal to the kernel of the matrix $x$ as columns of the
matrix $x$ with integer entries (rational entries are not permitted).

If $flag=0$, use a modified integer LLL algorithm.

If $flag=1$, use {\tt matrixqz}$(x,-2)$. If LLL reduction of the final result
is not desired, you can save time using {\tt matrixqz(matker(x),-2)} instead.

If $flag=2$, use another modified LLL. In the present version \vers, only
independent rows are allowed in this case. 

The library syntax is $\teb{matkerint0}(x,flag)$. Also available is
$\teb{kerint}(x)$ ($flag=0$).

\subsecidx{matmuldiagonal}$(x,d)$: product of the matrix $x$ by the diagonal
matrix whose diagonal entries are those of the vector $d$. Equivalent to,
but much faster than $x*${\tt matdiagonal($d$)}.

The library syntax is $\teb{matmuldiagonal}(x,d)$.

\subsecidx{matmultodiagonal}$(x,y)$: product of the matrices $x$ and $y$
knowing that the result is a diagonal matrix. Much faster than $x*y$ in
that case.

The library syntax is $\teb{matmultodiagonal}(x,y)$.

\subsecidx{matpascal}$(x)$: creates as a matrix the lower triangular \idx{pascal
triangle} of order $x+1$ (i.e.~with binomial coefficients up to $x$).

The library syntax is $\teb{matpascal}(x)$, where $x$ is a C-long integer.

\subsecidx{matrank}$(x)$: rank of the matrix $x$.

The library syntax is $\teb{rank}(x)$, and the result is a C-long integer.

\subsecidx{matrixqz}$(x,p)$: $x$ being an $m\times n$ matrix with $m\ge n$
with rational or integer entries, this function has varying behaviour
depending on the sign of $p$:

If $p\geq 0$, $x$ is assumed to have of maximal rank. This function returns a
matrix having only integral entries, having the same image as $x$, such that
the GCD of all its $n\times n$ subdeterminants is equal to 1 when $p$ is
equal to 0, or not divisible by $p$ otherwise. Here $p$ must be a prime
number (when it is non-zero). However, if the function is used when $p$ has
no small prime factors, it will either work or give the message ``impossible
inverse modulo'' and a non-trivial divisor of $p$.

If $p=-1$, this function returns a matrix whose columns form a basis of the
lattice equal to $\Z^n$ intersected with the lattice generated by the
columns of $x$.

If $p=-2$, returns a matrix whose columns form a basis of the lattice equal
to $\Z^n$ intersected with the $\Q$-vector space generated by the
columns of $x$.

The library syntax is $\teb{matrixqz0}(x,p)$.

\subsecidx{matsize}$(x)$: $x$ being a vector or matrix, returns a row vector
with two components, the first being the number of rows (1 for a row vector),
the second the number of columns (1 for a column vector).

The library syntax is $\teb{matsize}(x)$.

\subsecidx{matsnf}$(x,\{flag=0\})$: if $x$ is a (singular or non-singular)
square matrix outputs the vector of elementary divisors of $x$ (i.e.~the
diagonal of the Smith normal form of $x$).

If $flag=0$ (default), assume $x$ has integer coefficients.

If $flag=1$, as case $0$, but output $[U,V,D]$, where $u$ and $v$ are two
unimodular matrices such that $UxV$ is the diagonal matrix D (whose diagonal
is {\tt matsnf(x)}).

If $flag=2$, as $0$ but $x$ may have polynomial entries.

If $flag=3$, as $1$, where $x$ may have polynomial entries.

The library syntax is $\teb{matsnf0}(x,flag)$. Also available is $smith(x)$
($flag=0$).

\subsecidx{matsolve}$(x,y)$: $x$ being a square matrix and $y$ a column
vector, finds the solution $u$ of $x*u=y$, using Gaussian elimination. This
has the same effect as, but is much faster, than $x^{-1}*y$.

The library syntax is $\teb{gauss}(x,y)$.

\subsecidx{matsolvemod}$(m,d,y,\{flag=0\})$: $m$ being an arbitrary matrix
with integral entries, $d$ a vector of positive integer moduli, and $y$ an
integral column vector, gives a small integer solution to the system of
congruences $\sum_i m_{i,j}x_j\equiv y_i\pmod{d_i}$ if one exists, otherwise
returns zero.

If $flag=1$, all solutions are returned in the form of a two-component row
vector $[x,u]$, where $x$ is a small integer solution to the system of
congruences and $u$ is a matrix whose columns give a basis of the homogeneous
system (so that all solutions can be obtained by adding $x$ to any linear
combinations of columns of $u$). If no solution exists, returns zero.

The library syntax is $\teb{matsolvemod0}(m,d,y,flag)$. Also available
are $\teb{gaussmodulo}(m,d,y)$ ($flag=0$)
and $\teb{gaussmodulo2}(m,d,y)$ ($flag=1$).

\subsecidx{matsupplement}$(x)$: assuming that the columns of the matrix $x$
are linearly independent (if they are not, an error message is issued), find
a square invertible matrix whose first columns are the columns of $x$, i.e.
supplement the columns of $x$ to a basis of the whole space.

The library syntax is $\teb{suppl}(x)$.

\subsecidx{mattranspose}$(x)$ or $x\tilde{\ }$: transpose of $x$.
This has an effect only on vectors and matrices.

The library syntax is $\teb{gtrans}(x)$.
\subsecidx{qfgaussred}$(x)$: \idx{decomposition into squares} of the
quadratic form represented by the symmetric matrix $x$. The result is a
matrix whose diagonal entries are the coefficients of the squares, and the
non-diagonal entries represent the bilinear forms.

The library syntax is $\teb{sqred}(x)$.

\subsecidx{qfjacobi}$(x)$: $x$ being a real symmetric matrix, this gives a
vector having two components: the first one is the vector of eigenvalues of
$x$, the second is the corresponding orthogonal matrix of eigenvectors of
$x$. The method used is Jacobi's method for symmetric matrices.

The library syntax is $\teb{jacobi}(x)$.

\subsecidx{qflll}$(x,\{flag=0\})$: LLL algorithm applied to the {\it columns}
of the (not necessarily square) matrix $x$. The columns of $x$ must however
be of maximal rank (unless specified otherwise below). The result is a square
transformation matrix $T$ such that $x\cdot T$ is an LLL-reduced basis of the
lattice generated by the column vectors of $x$.

If $flag=0$ (default), the computations are done with real numbers (i.e.~not
with rational numbers) hence are fast but as presently programmed (version
\vers) are numerically unstable.

If $flag=1$, it is assumed that the corresponding Gram matrix is integral.
The computation is done entirely with integers and the algorithm is both
accurate and quite fast. In this case, $x$ needs not be of maximal rank.

If $flag=2$, similar to case 1, except $x$ should be an integer matrix whose
columns are linearly independent. The output is a square transformation
matrix~$T$ such that $x \cdot T$ is a {\it partially} reduced basis of the
lattice generated by the column vectors of $x$. A basis is said to be {\sl
partially reduced} if $\| v_i \pm v_j \| \geq \|v_i\|$ for any two distinct
basis vectors $v_i, \, v_j$.

This can be faster than case 1 when one row of $x$ is huge and the rest of
$x$ is small. If $T1 = {\tt qflll}(x,2)$ and $T2 = {\tt qflll}(x*T1,1)$, then
output $x \cdot T1 \cdot T2$ is an LLL reduced basis for $x$.

If $flag=3$, all computations are done in rational numbers. This does not
incur numerical instability, but is extremely slow. This function is
essentially superseded by case 1, so will soon disappear.

If $flag=4$, $x$ is assumed to have integral entries, but needs not be of
maximal rank. The result is a two-component vector of matrices, the columns
of the first matrix representing a basis of the integer kernel of $x$ (not
necessarily LLL-reduced) and the columns of the second matrix being an
LLL-reduced $\Z$-basis of the image of the matrix $x$.

If $flag=5$, case as case $4$, but $x$ may have polynomial coefficients.

If $flag=7$, use an older version of case $0$ above.

If $flag=8$, same as case $0$, where $x$ may have polynomial coefficients.

If $flag=9$, variation on case $1$, using content.

The library syntax is $\teb{qflll0}(x,flag,prec)$. Also available are
$\teb{lll}(x,prec)$ ($flag=0$), $\teb{lllint}(x)$ ($flag=1$), and
$\teb{lllkerim}(x)$ ($flag=4$).

\subsecidx{qflllgram}$(x,\{flag=0\})$: same as {\tt qflll} except that the
matrix $x$ which must now be a square symmetric real matrix is the Gram matrix of 
the lattice vectors, and not the coordinates of the vectors themselves. The result 
is again the transformation matrix $T$ which gives (as columns) the coefficients 
with respect to the initial basis vectors. The flags have more or less the same
meaning, but some are missing. In brief:

$flag=0$: numerically instable in the present version \vers.

$flag=1$: $x$ has integer entries, the computations are all done in integers.

$flag=4$: $x$ has integer entries, give the kernel and reduced image.

$flag=5$: same as $4$ for generic $x$.

$flag=7$: An older version of case $0$.

The library syntax is $\teb{qflllgram0}(x,flag,prec)$. Also available are
$\teb{lllgram}(x,prec)$ ($flag=0$), $\teb{lllgramint}(x)$ ($flag=1$), and
$\teb{lllgramkerim}(x)$ ($flag=4$).

\subsecidx{qfminim}$(x,b,m,\{flag=0\})$: $x$ being a square and symmetric
matrix representing a positive definite quadratic form, this function
deals with the minimal vectors of $x$, depending on $flag$.

If $flag=0$ (default), seek vectors of square norm less than or equal to $b$
(for the norm defined by $x$), and at most $2m$ of these vectors. The result
is a three-component vector, the first component being the number of vectors,
the second being the maximum norm found, and the last vector is a matrix
whose columns are the vectors found, only one being given for each
pair $\pm v$ (at most $m$ such pairs).

If $flag=1$, ignore $m$ and return the first vector whose norm is less than
$b$.

In both these cases, $x$ {\it is assumed to have integral entries}, and the
function searches for the minimal non-zero vectors whenever $b=0$.

If $flag=2$, $x$ can have non integral real entries, but $b=0$ is now
meaningless (use Fincke-Pohst algorithm).

The library syntax is $\teb{minim}(x,b,m)$ ($flag=0$), $\teb{minim2}(x,b,m)$
($flag=1$), or finally ${\bf fincke\_pohst}(x,b,m,prec)$ ($flag=2$).
\sidx{fincke\string\_pohst}

\subsecidx{qfperfection}$(x)$: $x$ being a square and symmetric matrix with
integer entries representing a positive definite quadratic form, output the
perfection rank of the form. That is, gives the rank of the family of the $s$
symmetric matrices $v_iv_i^t$, where $s$ is half the number of minimal
vectors and the $v_i$ ($1\le i\le s$) are the minimal vectors.

As a side note to old-timers, this used to fail bluntly when $x$ had more
than $5000$ minimal vectors. Beware that the computations can now be very
lengthy when $x$ has many minimal vectors.

The library syntax is $\teb{perf}(x)$

\subsecidx{qfsign}$(x)$: signature of the quadratic form represented by the
symmetric matrix $x$. The result is a two-component vector.

The library syntax is $\teb{signat}(x)$

\subsecidx{setintersect}$(x,y)$: intersection of the two sets $x$ and $y$.

The library syntax is $\teb{setintersect}(x,y)$.

\subsecidx{setisset}$(x)$: returns true (1) if $x$ is a set, false (0) if
not. In PARI, a set is simply a row vector whose entries are strictly
increasing. To convert any vector (and other objects) into a set, use the
function {\tt Set}.

The library syntax is $\teb{setisset}(x)$, and this returns a C-long integer.

\subsecidx{setminus}$(x,y)$: difference of the two sets $x$ and $y$, i.e.
set of elements of $x$ which do not belong to $y$.

The library syntax is $\teb{setminus}(x,y)$.

\subsecidx{setsearch}$(x,y,\{flag=0\})$: searches if $y$ belongs to the set
$x$. If it does and $flag$ is zero or omitted, returns the index $j$ such that
$x[j]==y$, otherwise returns 0. If $flag$ is non-zero return the index $j$
where $y$ should be inserted, and $0$ if it already belongs to $x$ (this is
meant to be used in conjunction with {\tt listinsert}).

This function works also if $x$ is a {\it sorted} list (see {\tt listsort}).

The library syntax is $\teb{setsearch}(x,y,flag)$ which returns a C-long
integer.

\subsecidx{setunion}$(x,y)$: union of the two sets $x$ and $y$.

The library syntax is $\teb{setunion}(x,y)$.

\subsecidx{trace}$(x)$: This applies to quite general $x$. If $x$ is not a
matrix, it is equal to the sum of $x$ and its conjugate, except for polmods
where it is the trace as an algebraic number.

For $x$ a square matrix, it is the ordinary trace. If $x$ is a
non-square matrix (but not a vector), an error occurs.

The library syntax is $\teb{gtrace}(x)$.

\subsecidx{vecextract}$(x,y,\{z\})$: extraction of components of the
vector or matrix $x$ according to $y$. $x$ must be a vector or
a matrix. In the case of a matrix, the components are as usual the
{\it columns} of $x$. The parameter $y$ must be either a number of type
integer or a vector. If $y$ is an integer, it is considered as a mask:
The binary bits of $y$ are read from right to left, but correspond to 
taking the components from left to right. For example, if $y=13=(1101)_2$
then the components 1,3 and 4 are extracted. 

If $y$ is a vector, which must have integer entries, these
entries correspond to the component numbers to be extracted, in the order
specified.

If $z$ is not omitted, $x$ must be a matrix. $y$ is then the {\it line} mask,
and $z$ the {\it column} mask, where the mask concept as been explained
above.

The library syntax is $\teb{extract}(x,y)$ or $\teb{matextract}(x,y,z)$.

\subsecidx{vecindexsort}$(x)$: indirect sorting of the vector $x$, i.e.~if
$x$ is an $n$-component vector, creates a permutation of $[1,2,\dots,n]$
which applied to the components of $x$ sorts $x$ in increasing order.

The library syntax is $\teb{indexsort}(x)$. Also available is
$\teb{sindexsort}$ which returns a vector (type \typ{VEC}) of $C$-long
integers $v$, which is thus not a PARI object, where $v[1]\dots v[n]$
contains the indices.

\subsecidx{veclexsort}$(x)$ sort the elements of the vector $x$ by 
ascending lexicographic order (see {\tt lex} above).

The library syntax is $\teb{lexsort}(x)$.

\subsecidx{vecsort}$(x,{k})$: sort the vector $x$ in ascending order, using
the heapsort method. $x$ must be a vector, and its components integers,
reals, or fractions. A related function is {\tt vecindexsort} (see above)
which gives the indices of the sorted vector in terms of the initial one. For
example, {\tt vecextract(x,vecindexsort(x))} is equivalent to {\tt
vecsort(x)}.

If $k$ is omitted, sort according to the value of the $k$-th component of
$x$. $k$ can also be a vector, in which case the sorting is done
lexicographically according to the components listed in the vector $k$. For
example, if $k=[2,1,3]$, sorting will be done with respect to the second
component, and when these are equal, with respect to the first, and when
these are equal, with respect to the third.

The library syntax is $\teb{vecsort0}(x,k)$. To omit $k$, use {\tt NULL}
instead, or use the simpler function $\teb{sort}(x)$.

\section{Sums, products, integrals and similar functions.}

Although the GP calculator is programmable, it is useful to have
preprogrammed a number of loops, including sums, products, and a certain
number of recursions. Also, a number of functions from numerical analysis
like numerical integration and summation of series will be described here.

One of the parameters in these loops must be the control variable, hence a
simple variable name. The last parameter must be any legal PARI expression,
including of course expressions using loops. 
Since it is much easier to program directly the loops in library mode, these
functions are mainly useful for GP programming. The use of these functions
in library mode is a little tricky and its explanation will be 
omitted, although the reader can try and figure it out by himself by reading
the source code (check the comments in {\tt anal.c}, the block functions in
{\tt init.c}, and then the functions themselves, mostly in {\tt bibli2.c} and
{\tt sumiter.c}). A brief explanatory sketch is given in Section~11. Hence
in this section we only give the library syntax, with no semantic
explanation.

The letter $X$ will always denote any simple variable name, and represents
the formal parameter used in the function.

\noindent {\bf (numerical) integration}:\sidx{numerical integration} A number
of Romberg-like integration methods are implemented (see {\tt intnum} as
opposed to {\tt intformal} which we already described). The user should not
require too much accuracy: 18 or 28 decimal digits is OK, but not much more.
In addition, analytical cleanup of the integral must have been done: there
must be no singularities in the interval or at the boundaries. In practice
this can be accomplished with a simple change of variable. Furthermore, for
improper integrals, where one or both of the limits of integration are plus
or minus infinity, the function must decrease sufficiently rapidly at
infinity. This can often be accomplished through integration by parts.

Note that \idx{infinity} can be represented with essentially no loss of
accuracy by 1e4000. However beware of real underflow when dealing with
rapidly decreasing functions. For example, if one wants to compute the
$\int_0^\infty e^{-x^2}\,dx$ to 28 decimal digits, then one should set
infinity equal to 10 for example, and certainly not to 1e4000.

The integrand may have values belonging to a vector space over the real
numbers; in particular, it can be complex-valued or vector-valued.

See also the discrete summation methods below (sharing the prefix {\tt sum}).

\subsecidx{intnum}$(X=a,b,expr,\{flag=0\})$: numerical integration of $expr$
(smooth in $]a,b[$), with respect to $X$.

Set $flag=0$ (or omit it altogether) when $a$ and $b$ are not too large, the
function is smooth, and can be evaluated exactly everywhere on the interval
$[a,b]$.

If $flag=1$, use a general driver routine for doing numerical integration,
making no particular assumption (slow).

$flag=2$ is tailored for being used when $a$ or $b$ are infinite. One
{\it must} have $ab>0$, and in fact if for example $b=\infty$, then it is
preferable to have $a$ as large as possible, at least $a\ge1$.

If $flag=3$, the function is allowed to be undefined (but continuous) at $a$
or $b$, for example the function $\sin(x)/x$ at $x=0$.

Library syntax is \tec{intnum0}{(entree *ep,GEN a,GEN b,char *expr,long
flag,long prec)}.

\subsecidx{matrix}$(m,n,X,Y,expr)$: creation of the $m\times n$ matrix whose
coefficients are given by the expression $expr$. There are two formal
parameters in $expr$, the first one ($X$) corresponding to the rows, the
second ($Y$) to the columns, and $X$ goes from 1 to $m$, $Y$ goes from 1 to
$n$.

Library syntax is \tec{matrice}{(GEN nlig,GEN ncol,entree *ep1,entree *ep2,char *ch)}.

\subsecidx{prod}$(X=a,b,expr,\{x=1\})$: product of expression $expr$,
initialized at $x$, the formal parameter $X$ going from $a$ to $b$. As for
{\tt sum}, the main purpose of the initialization parameter $x$ is to force
the type of the operations being performed. For example if it is put equal to
the integer 1, operations will start being done exactly. If it is put equal
to the real $1.$, they will be done using real numbers having the default
precision. If it is put equal to the power series $1+O(X^k)$ for a certain
$k$, they will be done using power series of precision at most $k$. These
are the three most common initializations.

\noindent As an extreme example, compare

\bprog
? prod(i=1, 100, 1-X\pow i);  \bs\bs this has degree $5050$ !!

time = 20,627 ms.

? prod(i=1, 100, 1-X\pow i, 1+O(X\pow 101))

time = 43 ms.

\%2 = 1 - X - X\pow 2 + X\pow 5 + X\pow 7 - X\pow 12 - X\pow 15 + X\pow 22 +%
X\pow 26 - X\pow 35 - X\pow 40 +
X\pow 51 + X\pow 57 - X\pow 70 - X\pow 77 + X\pow 92 + X\pow 100 + O(X\pow 101)
\eprog

The library syntax is \tec{produit}{(entree *ep, GEN a, GEN b, char *ch,
GEN x)}.

\subsecidx{prodeuler}$(X=a,b,expr)$: product of expression $expr$,
initialized at 1. (i.e.~a {\it real} number equal to 1 to the current
{\tt realprecision}), the formal parameter $X$ ranging over the prime numbers
between $a$ and $b$.\sidx{Euler product}

The library syntax is \tec{prodeuler}{(entree *ep, GEN a, GEN b, char *ch,
long prec)}.

\subsecidx{prodinf}$(X=a,expr,\{flag=0\})$: \idx{infinite product} of
expression $expr$, the formal parameter $X$ starting at $a$. The evaluation
stops when the relative error of the expression minus 1 is less than the
default precision. The expressions must always evaluate to an element of
$\C$.

If $flag=1$, do the product of the ($1+expr$) instead.

The library syntax is \tec{prodinf}{(entree *ep, GEN a, char *ch, long
prec)} ($flag=0$), or \tec{prodinf1}{}\ with the same arguments ($flag=1$).

\subsecidx{solve}$(X=a,b,expr)$: real root of expression $expr$ between $a$
and $b$, under the condition $expr(X=a)*expr(X=b)\le0$. The method used is
Brent's method.

The library syntax is \tec{zbrent}{(entree *ep, GEN a, GEN b, char *ch, long
prec)}.

\subsecidx{sum}$(X=a,b,expr,\{x=0\})$: sum of expression $expr$, initialized
at $x$, the formal parameter going from $a$ to $b$. As for {\tt prod}, the
initialization parameter $x$ may be given to force the type of the operations
being performed.

\noindent As an extreme example, compare 

\bprog
? sum(i=1, 5000, 1/j); \bs\bs rational number whose denominator has $2166$
digits.

time = 3mn, 59,593 ms.

? sum(i=1, 5000, 1/j, 0.)

time = 198 ms.

\%2 = 9.094508852984436967261245533
\eprog

The library syntax is \tec{somme}{(entree *ep, GEN x, GEN a, GEN b, char *ch)}.

\subsecidx{sumalt}$(X=a, expr, \{flag=0\})$: numerical summation of the
series $expr$, which should be an \idx{alternating series}, the formal
variable $X$ starting at $a$. 

If $flag=0$, use an algorithm of F.~Villegas as modified by D.~Zagier. This
is much better than Euler-Van Wijngaarden's method which was used formerly.
Beware that the stopping criterion is that the term gets small enough, hence
terms which are equal to 0 will create problems and should be removed.

If $flag=1$, use a variant with slightly different polynomials. Sometimes
faster.

Divergent alternating series can sometimes be summed by this method, as well
as series which are not exactly alternating (see for example Section~11).

Important hint: a consequent speed gain can be obtained by writing the
$(-1)^X$ which may occur in the expression as {\tt (1.-X\%2$*$2)}.

The library syntax is \tec{sumalt}{(entree *ep, GEN a, char *ch, long flag, 
long prec)}.

\subsecidx{sumdiv}$(n,X,expr)$: sum of expression $expr$ over
the positive divisors of $n$.

In the present version \vers, $n$ is restricted to being less than $2^{31}$.

The library syntax is \tec{divsum}{(entree *ep, GEN num, char *ch)}.

\subsecidx{suminf}$(X=a,expr)$: \idx{infinite sum} of expression $expr$, the
formal parameter $X$ starting at $a$. The evaluation stops when the relative
error of the expression is less than the default precision. The expressions
must always evaluate to a complex number.

The library syntax is \tec{suminf}{(entree *ep, GEN a, char *ch, long prec)}.

\subsecidx{sumpos}$(X=a,expr,\{flag=0\})$: numerical summation of the series
$expr$, which must be a series of terms having the same sign, the formal
variable $X$ starting at $a$. The algorithm used is van Wijngaarden's trick
for converting such a series into an alternating one, and is quite slow.
Beware that the stopping criterion is that the term gets small enough, hence
terms which are equal to 0 will create problems and should be removed.

If $flag=1$, use slightly different polynomials. Sometimes faster.

The library syntax is \tec{sumpos}{(entree *ep, GEN a, char *ch, long flag,
long prec)}.

\subsecidx{vector}$(n,X,expr)$: creates a row vector (type \typ{VEC}) with
$n$ components whose components are the expression $expr$ evaluated at the
integral points between 1 and $n$.

The library syntax is \tec{vecteur}{(GEN nmax, entree *ep, char *ch)}.

\subsecidx{vectorv}$(n,X,expr)$: creates a column vector (type \typ{COL}) 
with $n$ components whose components are the expression $expr$ evaluated at
the integral points between 1 and $n$.

The library syntax is \tec{vvecteur}{(GEN nmax, entree *ep, char *ch)}.

\section{Plotting functions.}

  Although plotting is not even a side purpose of PARI, a number of plotting
functions are provided. Moreover, a lot of people felt like suggesting
ideas or submitting huge patches for this section of the code. Among these,
special thanks go to Klaus-Peter Nischke who suggested the recursive plotting
and the forking/resizing stuff under X11, and Ilya Zakharevich who
undertook a complete rewrite of the graphic code, so that most of it is now
platform-independent and should be relatively easy to port or expand.

These graphic functions are either

$\bullet$ high-level plotting functions (all the functions starting with {\tt
ploth}) in which the user has little to do but explain what type of plot he
wants, and whose syntax is similar to the one used in the preceding section
(with somewhat more complicated flags).

$\bullet$ low-level plotting functions, where every drawing primitive (point,
line, box, etc...) must be specified by the user. These low-level functions
(called {\it rectplot} functions, sharing the prefix {\tt plot}) work as
follows. You have at your disposal 16 virtual windows which are filled
independently, and can then be physically ORed on a single window at
user-defined positions. These windows are numbered from 0 to 15, and must be
initialized before being used by the function {\tt plotinit}, which specifies
the height and width of the virtual window (called a {\it rectwindow} in the
sequel). At all times, a virtual cursor (initialized at $[0,0]$) is
associated to the window, and its current value can be obtained using the
function {\tt plotcursor}.

  A number of primitive graphic objects (called {\it rect} objects) can then
be drawn in these windows, using a default color associated to that window
(which can be changed under X11, using the {\tt plotcolor} function, black
otherwise) and only the part of the object which is inside the window will be
drawn, with the exception of polygons and strings which are drawn entirely
(but the virtual cursor can move outside of the window). The ones sharing the
prefix {\tt plotr} draw relatively to the current position of the virtual
cursor, the others use absolute coordinates. Those having the prefix
{\tt plotrecth} put in the rectwindow a large batch of rect objects
corresponding to the output of the related {\tt ploth} function.

   Finally, the actual physical drawing is done using the function {\tt
plotdraw}. Note that the windows are preserved so that further drawings using
the same windows at different positions or different windows can be done
without extra work. If you want to erase a window (and free the corresponding
memory), use the function {\tt plotkill}. It is not possible to partially
erase a window. Erase it completely, initialize it again and then fill it
with the graphic objects that you want to keep.

   In addition to initializing the window, you may want to have a scaled
window to avoid unnecessary conversions. For this, use the function {\tt
plotscale} below. As long as this function is not called, the scaling is
simply the number of pixels, the origin being at the upper left and the
$y$-coordinates going downwards. 

   Note that in the present version \vers{} all these plotting functions
(both low and high level) have been written for the X11-window system (hence
also for GUI's based on X11 such as Openwindows and Motif), and for
Sunview/Suntools only, though very little code remains which is actually
platform-dependent. A Macintosh, and an Atari/Gem port were provided for
previous versions. These {\it may} be adapted in future releases.

   Under X11/Suntools, the physical window (opened by {\tt plotdraw} or any
of the {\tt ploth*} functions) is completely separated from GP (technically,
a {\tt fork} is done, and the non-graphical memory is immediately freed in
the child process), which means you can go on working in the current GP
session, without having to kill the window first. Under X11, this window can
be closed, enlarged or reduced using the standard window manager functions.
No zooming procedure is implemented though (yet).

$\bullet$ Finally, note that in the same way that {\tt printtex} allows you
to have a \TeX{} output corresponding to printed results, the functions
starting with {\tt ps} allow you to have {\tt \idx{postscript}} output of the
plots. This will not be absolutely identical with the screen output, but will
be sufficiently close. Note that you can use postscript output even if you do
not have the plotting routines enabled. The postscript output is written in a
file whose name is derived from the {\tt \idx{psfile}} default ({\tt
./pari.ps} if you did not tamper with it). Each time a new postscript output
is asked for, the postscript output is appended to that file. Hence the user
must remove this file, or change the value of {\tt psfile}, first if he does
not want unnecessary drawings from preceding sessions to appear. On the other
hand, in this manner as many plots as desired can be kept in a single
file.
\smallskip

{\bf None of the graphic functions are available within the PARI library, you
must be under GP to use them}. The reason for that is that you really should
not use PARI for heavy-duty graphical work, there are much better specialized
alternatives around. This whole set of routines was only meant as a
convenient, but simple-minded, visual aid. If you really insist on using
these in your program (we warned you), the source ({\tt plot*.c}) should be
readable enough for you to manage something.

\subsecidx{plot}$(X=a,b,expr)$: crude (ASCII) plot of the function
represented by expression $expr$ from $a$ to $b$.

\subsecidx{plotbox}$(w,x2,y2)$: let $(x1,y1)$ be the current position of the
virtual cursor. Draw in the rectwindow $w$ the outline of the rectangle which
is such that the points $(x1,y1)$ and $(x2,y2)$ are opposite corners. Only
the part of the rectangle which is in $w$ is drawn. The virtual cursor does
{\it not} move.

\subsecidx{plotcolor}$(w,c)$: set default color to $c$ in rectwindow $w$.
In present version \vers, this is only implemented for X11 window system,
and you only have the following palette to choose from:

1=black, 2=blue, 3=sienna, 4=red, 5=cornsilk, 6=grey, 7=gainsborough.

Note that it should be fairly easy for you to hardwire some more colors by
tackling with the files {\tt rect.h} and {\tt plotX.c}. User-defined
colormaps would be nice, and {\it may} be available in future versions.

\subsecidx{plotcopy}$(w1,w2,dx,dy)$: copy the contents of rectwindow
$w1$ to rectwindow $w2$, with offset $(dx,dy)$.

\subsecidx{plotcursor}$(w)$: give as a 2-component vector the current
(scaled) position of the virtual cursor corresponding to the rectwindow $w$.

\subsecidx{plotdraw}$(list)$: physically draw the rectwindows given in $list$
which must be a vector whose number of components is divisible by 3. If
$list=[w1,x1,y1,w2,x2,y2,\dots]$, the windows $w1$, $w2$, etc... are
physically placed with their upper left corner at physical position
$(x1,y1)$, $(x2,y2)$, \dots respectively, and are then drawn together.
Overlapping regions will thus be drawn twice, and the windows are considered
transparent. Then display the whole drawing in a special window on your
screen.

\subsecidx{ploth}$(X=a,b,expr,\{flag=0\},\{n=0\})$: high precision plot of
the function $y=f(x)$ represented by the expression $expr$, $x$ going from
$a$ to $b$. This opens a specific window (which is killed whenever you click
on it), and returns a four-component vector giving the coordinates of the
bounding box in the form $[xmin,xmax,ymin,ymax]$.

{\bf Important note}: Since this may involve a lot of function calls, it is
advised to keep the current precision to a minimum (e.g. 9) before calling
this function.

$n$ specifies the number of reference point on the graph (0 means use the
hardwired default values, that is: 1000 for general plot, 1500 for
parametric plot, and 15 for recursive plot).

If no $flag$ is given, $expr$ is either a scalar expression $f(X)$, in which
case the plane curve $y=f(X)$ will be drawn, or a vector
$[f_1(X),\dots,f_k(X)]$, and then all the curves $y=f_i(X)$ will be drawn in
the same window.

\noindent Binary digits of $flag$ mean:

$\bullet$ 1: {\it \idx{parametric plot}}. Here $expr$ must be a vector with
an even number of components. Successive pairs are then understood as the
parametric coordinates of a plane curve. Each of these are then drawn.

For instance:

{\tt ploth(X=0,2*Pi,[sin(X),cos(X)],1)} will draw a circle.

{\tt ploth(X=0,2*Pi,[sin(X),cos(X)])} will draw two entwined sinusoidal
curves.

{\tt ploth(X=0,2*Pi,[X,X,sin(X),cos(X)],1)} will draw a circle and the line
$y=x$.


$\bullet$ 2: {\it \idx{recursive plot}}. If this flag is set, only {\it one}
curve can be drawn at time, i.e.~$expr$ must be either a two-component vector
(for a single parametric curve, and the parametric flag {\it has} to be set),
or a scalar function. The idea is to choose pairs of successive reference
points, and if their middle point is not too far away from the segment
joining them, draw this as a local approximation to the curve. Otherwise, add
the middle point to the reference points. This is very fast, and usually more
precise than usual plot. Compare the results of 

$${\tt ploth(X=-1,1,sin(1/X),2)}\quad\text{and}\quad{\tt ploth(X=-1,1,sin(1/X))}$$
for instance. But beware that if you are extremely unlucky, or choose too few
reference points, you may draw some nice polygon bearing little resemblance
to the original curve.

$\bullet$ 8: do not print the $x$-axis.

$\bullet$ 16: do not print the $y$-axis.

$\bullet$ 32: do not print frame.

$\bullet$ 64: only plot reference points, do not join them.

\subsecidx{plothraw}$(listx,listy,\{flag=0\})$: high precision plot of the
points whose (x,y)-coordinates are in the vectors of equal length $listx$ and
$listy$. Automatic positioning and scaling is done, but with the same scaling
factor on $x$ and $y$. If $flag$ is non-zero, join points.

\subsecidx{plothsizes}$()$: return data corresponding to the output window
in the form of a 6-component vector: window width and height, sizes for ticks
in horizontal and vertical directions (this is intended for the {\tt gnuplot}
interface and is currently not significant), width and height of characters.

\subsecidx{plotinit}$(w,x,y)$: initialize the rectwindow $w$ to width $x$
and height $y$, and position the virtual cursor at $(0,0)$. This destroys
any rect objects you may have already drawn in $w$.

\subsecidx{plotkill}$(w)$: erase rectwindow $w$ and free the corresponding
memory. Note that if you want to use the rectwindow $w$ again, you have to
use {\tt initrect} first to specify the new size. So it's better in this case
to use {\tt initrect} directly as this throws away any previous work in the
given rectwindow.

\subsecidx{plotlines}$(w,X,Y,\{flag=0\})$: draw on the rectwindow $w$
the polygon such that the (x,y)-coordinates of the vertices are in the
vectors of equal length $X$ and $Y$. For simplicity, the whole
polygon is drawn, not only the part of the polygon which is inside the
rectwindow. If $flag$ is non-zero, close the polygon. In any case, the
virtual cursor does not move.

$X$ and $Y$ are allowed to be scalars (in this case, both have to).
There, a single segment will be drawn, between the virtual cursor current
position and the point $(X,Y)$. And only the part thereof which
actually lies within the boundary of $w$. Then {\it move} the virtual cursor
to $(X,Y)$, even if it is outside the window. If you want to draw a
line from $(x1,y1)$ to $(x2,y2)$ where $(x1,y1)$ is not necessarily the
position of the virtual cursor, use {\tt plotmove(w,x1,y1)} before using this
function.

\subsecidx{plotlinetype}$(w,type)$: this is intended for the {\tt gnuplot}
interface and is currently not significant.

\subsecidx{plotmove}$(w,x,y)$: move the virtual cursor of the rectwindow $w$
to position $(x,y)$.

\subsecidx{plotpoints}$(w,X,Y)$: draw on the rectwindow $w$ the
points whose (x,y)-coordinates are in the vectors of equal length $X$ and
$Y$ and which are inside $w$. The virtual cursor does {\it not} move. This is
basically the same function as {\tt plothraw}, but either with no scaling
factor or with a scale chosen using the function {\tt plotscale}.

As was the case with the {\tt plotlines} function, $X$ and $Y$ are allowed to
be (simultaneously) scalar. In this case, draw the single point $(X,Y)$ on
the rectwindow $w$ (if it is actually inside $w$), and in any case {\it move}
the virtual cursor to position $(x,y)$.

\subsecidx{plotpointtype}$(w,type)$: this is intended for the {\tt gnuplot}
interface and is currently not significant.

\subsecidx{plotrbox}$(w,dx,dy)$: draw in the rectwindow $w$ the outline of
the rectangle which is such that the points $(x1,y1)$ and $(x1+dx,y1+dy)$ are
opposite corners, where $(x1,y1)$ is the current position of the cursor.
Only the part of the rectangle which is in $w$ is drawn. The virtual cursor
does {\it not} move.

\subsecidx{plotrecth}$(w,X=a,b,expr,\{flag=0\},\{n=0\})$: writes to
rectwindow $w$ the output of {\tt ploth}$(w,X=a,b,expr,flag,n)$.

\subsecidx{plotrecthraw}$(w,data,\{flag=0\})$: plot graph(s) for 
$data$ in rectwindow $w$. $flag$ has the same signification here as in
{\tt ploth}, though recursive plot is no more significant.

$data$ is a vector of vectors, each corresponding to a list a coordinates.
If parametric plot is set, there must be an even number of vectors, each
successive pair corresponding to a curve. Otherwise, the first one containe
the $x$ coordinates, and the other ones contain the $y$-coordinates
of curves to plot.

\subsecidx{plotrline}$(w,dx,dy)$: draw in the rectwindow $w$ the part of the
segment $(x1,y1)-(x1+dx,y1+dy)$ which is inside $w$, where $(x1,y1)$ is the
current position of the virtual cursor, and move the virtual cursor to
$(x1+dx,y1+dy)$ (even if it is outside the window).

\subsecidx{plotrmove}$(w,dx,dy)$: move the virtual cursor of the rectwindow
$w$ to position $(x1+dx,y1+dy)$, where $(x1,y1)$ is the initial position of
the cursor (i.e.~to position $(dx,dy)$ relative to the initial cursor).

\subsecidx{plotrpoint}$(w,dx,dy)$: draw the point $(x1+dx,y1+dy)$ on the
rectwindow $w$ (if it is inside $w$), where $(x1,y1)$ is the current position
of the cursor, and in any case move the virtual cursor to position
$(x1+dx,y1+dy)$.

\subsecidx{plotscale}$(w,x1,x2,y1,y2)$: scale the local coordinates of the
rectwindow $w$ so that $x$ goes from $x1$ to $x2$ and $y$ goes from $y1$ to
$y2$ ($x2<x1$ and $y2<y1$ being allowed). Initially, after the initialization
of the rectwindow $w$ using the function {\tt plotinit}, the default scaling
is the graphic pixel count, and in particular the $y$ axis is oriented
downwards since the origin is at the upper left. The function {\tt plotscale}
allows to change all these defaults and should be used whenever functions are
graphed.

\subsecidx{plotstring}$(w,x)$: draw on the rectwindow $w$ the String $x$ (see
Section 2.4), at the current position of the cursor.

\subsecidx{plotterm}$(type)$: this is intended for the {\tt gnuplot}
interface and is currently not significant.

\subsecidx{psdraw}$(list)$: same as {\tt plotdraw}, except that the output is
a postscript program appended to the {\tt psfile}.

\subsecidx{psploth}$(X=a,b,expr)$: same as {\tt ploth}, except that the 
output is a postscript program appended to the {\tt psfile}.

\subsecidx{psplothraw}$(listx,listy)$: same as {\tt plothraw}, except that
the output is a postscript program appended to the {\tt psfile}.

\section{Programming under GP and user-defined functions.}
\sidx{programming}\label{se:programming}

\subsec{\idx{Variables} and symbolic expressions}.

  In GP you can use up to 16383 variable names (up to 65535 on 64-bit
machines). These names can be any standard identifier names, i.e.~they must
start with a letter and contain only valid keyword characters: \kbd{\_} or
alphanumeric characters ([{\tt \_A-Za-z0-9}]). To avoid confusion with other
symbols, you must not use other non-alphanumeric symbols like \kbd{\$}, or
'\kbd{.}'. In addition to the function names which you must not use (see the
list with \b{c}), there are exactly three special variable names which you
are not allowed to use: {\tt Pi} and {\tt Euler}, which represent well known
constants, and {\tt I}$=\sqrt{-1}$.

Note that GP names are now case sensitive. This means for instance that the
symbol {\tt i} is perfectly safe to use, and will not be mistaken for
$\sqrt{-1}$, and that {\tt o} is not synonymous anymore to {\tt O}. If you
grew addicted to the previous behaviour, you can have it back by setting the
default {\tt compatible} to $3$.

  Now the main thing to understand is that PARI/GP is {\it not} a symbolic
manipulation package, although it shares some of the functionalities. One of
the main consequences of this fact is that all expressions are evaluated as
soon as they are written, they never stay in a purely abstract
form%
\footnote{*}{An obvious but important exception is character strings which
are evaluated\dots essentially to themselves (type \typ{STR}). Not exactly
so though, since we do some work to treat correctly the quoted characters
(preceded by a \b{}).}.
%
As an important example, consider what happens when
you use a variable name {\sl before} assigning a value into it. This is
perfectly acceptable to GP, which considers this variable in fact as a
polynomial of degree 1, with coefficients 1 in degree 1, 0 in degree 0, whose
variable is the variable name you used.

  If later you assign a value to that variable, the objects which you have
created before will still be considered as polynomials. If you want to obtain
their value, use the function {\tt eval} (see Section~7 above).

  Another consequence is that the variables are numbered in the order that
they appear, and the main variable of an expression is always the lowest
numbered variable. Hence if you are working with expressions involving
several variables and want to have them ordered in a specific manner {\it in
the internal representation}, the simplest is just to write down the
variables one after the other under GP before starting any real computations.
If you already have started working and want to change the names of the
variables in an object, use the function {\tt changevar} (see Section~2). If
you only want to have them ordered when the result is printed, you can also
use the function {\tt reorder} (see below), but this won't change anything to 
the internal representation.

  Finally, note that if $x$ is a vector or list, you can assign a result to
$x[m]$ (i.e.~write something like $x[k]=expr$). If $x$ is a matrix, you can
assign a result to $x[m,n]$, but {\it not} to $x[m]$, which is a vector. If
you want to assign an expression to the $m$-th column of a matrix $x$, use
$x[,m]=expr$ instead. Similarly, use $x[m,]=expr$ to assign an expression to
the $m$-th row of $x$. This process is recursive, so if $x$ is a matrix of
matrices of \dots, an expression such as $x[1,1][,3][4]=1$ would be perfectly
valid (assuming of course that all matrices along the way have the correct
dimensions).

\subsec{\idx{Expression}s and \idx{expression sequence}s}.

  An expression is formed by combining the GP operators, functions (including
user-defined functions) and control statements. It may be preceded by an
assignment statement '$=$' into a variable. It always has a value, which can
be any PARI object.

  Several expressions can be combined on a single line by separating them
with semicolons (';') and also with colons (':') for those who are used to
BASIC. Such an expression sequence will be called simply a $seq$. A $seq$
also has a value, which is the value of the last non-empty expression in the
sequence. Under GP, the value of the $seq$ is always put on the stack (i.e.
it will become the next object $\%n$), and only that value. The values of
the other expressions in the $seq$ are discarded after the execution of the
$seq$ is complete, except of course if they were assigned into variables. In
addition, the value of the $seq$ (or of course of an expression if there is
only one) is printed if the line does not end with a semicolon (';').

\subsecidx{Control statements}.

  A number of control statements are available under GP. They are simpler and
have a slightly different syntax than their C counterparts, but are quite
powerful enough to write any kind of program. Some of them are specific to
GP, since they are made for number theorists. They are as follows. As usual,
$X$ will denote any simple variable name, and $seq$ will always denote a
sequence of expressions, including the empty sequence.

\subsubsecidx{break}$(\{n=1\})$: interrupt execution of current $seq$, and
immediately exit from the $n$ innermost enclosing loops.

\subsubsecidx{for}$(X=a,b,seq)$: the formal variable $X$ going from $a$ to
$b$, the $seq$ is evaluated. Nothing is done if $a>b$. $a$ and $b$ must be in
$\R$.

\subsubsecidx{fordiv}$(n,X,seq)$: the formal variable $X$ ranging through the
positive divisors of $n$, the sequence $seq$ is evaluated. $n$ must be of
type integer.

\subsubsecidx{forprime}$(X=a,b,seq)$: the formal variable $X$ ranging over
the prime numbers between $a$ to $b$ (including $a$ and $b$ if they are
prime), the $seq$ is evaluated. Nothing is done if $a>b$. Note that $a$ and
$b$ must be in $\R$.

\subsubsecidx{forstep}$(X=a,b,s,seq)$: the formal variable $X$ going from $a$
to $b$, in increments of $s$, the $seq$ is evaluated. Nothing is done if
$s>0$ and $a>b$ or if $s<0$ and $a<b$. $a$, $b$ and $s$ must be in $\R$,
and $s$ must be non-zero.

\subsubsecidx{forvec}$(X=v,seq)$: $v$ being an $n$-component vector (where
$n$ is arbitrary) of two-component vectors $[a_i,b_i]$ for $1\le i\le n$, the
$seq$ is evaluated with the formal variable $x[1]$ going from $a_1$ to
$b_1$,\dots,$x[n]$ going from $a_n$ to $b_n$. The formal variable with the
highest index moves the fastest. 

\subsubsecidx{if}$(a,\{seq1\},\{seq2\})$: if $a$ is non-zero, the expression
sequence $seq1$ is evaluated, otherwise the expression $seq2$ is evaluated.
Of course, $seq1$ or $seq2$ may be empty, so {\tt if ($a$,$seq$)} evaluates
$seq$ if $a$ is not equal to zero (you don't have to write the second comma),
does nothing otherwise; {\tt if ($a$,,$seq$)} evaluates $seq$ if $a$ is equal to
zero, does nothing otherwise. You could get the same result using the {\tt !}
({\tt not}) operator: {\tt if (!$a$,$seq$)}.

  Note that the boolean operators {\tt \&\&} and {\tt ||} are evaluated
according to operator precedence as explained in \secref{se:operators}, but
that, contrary to other operators, the evaluation of the arguments is
stopped as soon as the final truth value could be determined. For instance
\bprog
if (reallydoit \&\& longcomplicatedfunction(), $\dots$)
\eprog

\noindent is a perfectly safe statement.

  Recall that functions such as {\tt break} and {\tt next} operate on {\it
loops\/} (such as {\tt for$xxx$}, {\tt while}, {\tt until}). The {\tt if}
statement is {\it not\/} a loop (obviously!).

\subsubsecidx{next}$()$: interrupt execution of current $seq$, and
immediately start another iteration of the innermost enclosing loop.

\subsubsecidx{return}$(\{x=0\})$: return from current subroutine, with result
$x$.

\subsubsecidx{until}$(a,seq)$: evaluate expression sequence $seq$ until $a$
is not equal to 0 (i.e.~until $a$ is true). If $a$ is initially not equal to
0, $seq$ is evaluated once (more generally, the condition on $a$ is tested
{\it after} execution of the $seq$, not before as in {\tt while}).

\subsubsecidx{while}$(a,seq)$: while $a$ is non-zero evaluate the expression
sequence $seq$. The test is made {\it before} evaluating the $seq$, hence in
particular if $a$ is initially equal to zero the $seq$ will not be evaluated
at all.\smallskip

\subsec{Specific functions used in GP programming}.

  In addition to the general PARI functions, it is necessary to have some
functions which will be of use specifically for GP, though a few of these can
be accessed under library mode. Before we start describing these, we recall
the difference between {\it strings} and {\it keywords} (see
\secref{se:strings}): the latter don't get expanded at all, and you can type
them without any enclosing quotes. The former are dynamic objects, where
everything outside quotes gets immediately expanded.

We need an additional notation for this chapter. An argument between braces,
followed by a star, like $\{str\}*$, means that any number of such arguments
(possibly $0$) can be given.

\subsubsecidx{addhelp}$(S,str)$:\label{se:addhelp} change the help message
for the symbol $S$. The string $str$ is expanded on the spot and stored as
the online help for $S$. If $S$ is a function that {\it you} defined, its
definition will still be printed before the message $str$. It is recommanded
that you document global variables and user functions in this way. Of course
GP won't protest if you don't do that.

There's nothing to prevent you from modifying the help of original PARI
functions (but if you do, we'd like to hear why you needed to do it!).

\subsubsecidx{alias}$(newkey,key)$: Define the keyword $newkey$ as an alias
for keyword $key$. $key$ must correspond to an existing {\it function} name.
This is different from the general user macros in that alias expansion takes
place immediately upon execution, without having to look up any function
code, and is thus much faster. A sample alias file {\tt lib/gpalias} is
provided with the standard distribution. Alias commands are meant to be read
upon startup from the {\tt .gprc} file, to cope with function names you are
dissatisfied with, and should be useless in interactive usage.

\subsubsecidx{allocatemem}$(\{x=0\})$: this is a very special operation which
allows the user to change the stack size {\it after} initialization. $x$
must be a non-negative integer. If $x!=0$, a new stack of size $16*\lceil
x/16\rceil$ bytes will be allocated, all the PARI data on the old stack will
be moved to the new one, and the old stack will be discarded. If $x=0$, the
size of the new stack will be double that of the old one.

Although it is a function, this must be the {\it only} instruction in any GP
sequence. The technical reason is that this routine terminates by a
{\tt longjmp} and not by a return.

The library syntax is $\teb{allocatemoremem}(x)$, where $x$ is an unsigned 
long, and the return type is void. GP uses a variant which ends by a
{\tt longjmp}.

\subsubsecidx{default}$({key},{val})$: set the default corresponding to
keyword $key$ to value $val$. $val$ is a string (which of course accepts
numeric arguments without adverse effects, due to the expansion mechanism).
See section 2.1 for a list of available defaults, and section 2.2 for some
shortcut alternatives. \label{se:default}

If $val$ is omitted, print the current value of default $key$. If $key$
is omitted, print the current values of all the defaults.

\subsubsecidx{error}$(\{str\}*)$: output its argument list (each of them
interpreted as a string), then interrupt the running GP program, returning to
prompting mode.

Example: {\tt error("n = ", n, " is not squarefree !")}.

Note that, due to the automatic concatenation of strings, you could in fact
use only one argument, just by suppressing the commas.

\subsubsecidxunix{extern}$(str)$: the string $str$ is the name of an external
command (i.e.~one you would type from your UNIX shell prompt). This command is
immediately run and its input fed into GP, just as if read from a file.

\subsubsecidx{getheap}$()$: returns a two-component row vector giving the number
of objects on the heap and the amount of memory they occupy in long words.
Useful mainly for debugging purposes.

The library syntax is $\teb{getheap}()$.

\subsubsecidx{getrand}$()$: returns the current value of the random number 
seed. Useful mainly for debugging purposes.

The library syntax is $\teb{getrand}()$.

\subsubsecidx{getstack}$()$: returns the current value of {\tt top$-$avma},
i.e.~the number of bytes used up to now on the stack. Should be equal to 0
in between commands. Useful mainly for debugging purposes.

The library syntax is $\teb{getstack}()$.

\subsubsecidx{gettime}$()$: returns the time (in milliseconds) elapsed since 
either the last call to {\tt gettime}, or to the beginning of the containing 
GP instruction (if inside GP), whichever came last.

The library syntax is $\teb{gettime}()$.

\subsubsecidx{input}$()$: reads a string, interpreted as a GP expression, from
the input file, usually standard input (i.e.~the keyboard). If a sequence of
expressions is given, the result is the result of the last expression of the
sequence. When using this instruction, it is useful to prompt for the string
by using the {\tt print1} function. Note that in the present version 2.16 of
{\tt pari.el}, when using GP under GNU Emacs (see Section~11) one {\it must\/}
prompt for the string, with a string which ends with the same prompt as the
current one (usually a '?').

\subsubsecidxunix{install}$("name","code",\{"gpname"\},\{"lib"\})$: load from
dynamic library 'lib' the function 'name'. Assign to it the name 'gpname' in
this GP session, with argument code 'code' (see
\secref{se:gp.interface} for an explanation of those). If 'lib' is
omitted, use 'libpari.so'. If 'gpname' is omitted, use 'name'.
\label{se:install}

This function is mostly useful to add custom functions to the GP interpreter.
But, in particular, it gives you access to all functions defined in the PARI
library. For instance, the function {\tt GEN addii(GEN x, GEN y)} adds two
PARI integers, and is not directly accessible under GP (it's eventualy called
by the {\tt +} operator of course):

\bprog
? install("addii","GG")
? addii(1,2)
\%1 = 3
\eprog

\noindent{\bf Caution:} this function may not work on all systems, especially
when gp has been compiled statically. In that case, the first use of an
installed function will provoke a Segmentation Fault, i.e.~a major internal
blunder (this should never happen with a dynamicaly linked executable). This
{\it will} be the fate of statically linked gp on Linux and DEC OSF1 at least
(no other examples have been communicated to us).

 Hence, if you intend to use this function, please check first on some
harmless example such as the one above that it works properly on your
machine.

\subsubsecidx{kill}$(x)$:\label{se:kill} kills the present value of the
variable, alias or user-defined function $x$ (you can only kill your own
functions). The corresponding identifier can now be used to name any GP
object (variable or function). This is the only way to replace a variable by
a function having the same name (or the other way round), as in the following
example:

\bprog
? f = 1
\%1 = 1
? f(x) = 0
  ***   unused characters: f(x)=0
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \pow----
? kill(f)
? f(x) = 0
? f()
\%2 = 0
\eprog

  In case you kill a variable, all objects that used it become invalid. You
can still display them, even though the killed variable will be printed in a
funny way (using the same convention as the library function {\tt fetch\_var}
see \secref{se:vars}). For example:

\bprog
? x\pow 2 + 1
\%1 = x\pow2 + 1
? kill(x)
? \%1
\%2 = \#<0>\pow2 + 1
\eprog

\subsubsecidx{print}$(\{str\}*)$: output its (string) arguments in raw
format, ending with a newline.

\subsubsecidx{print1}$(\{str\}*)$: output its (string) arguments in raw
format, without ending with a newline (note that you can still embed newlines
within your strings, using the \b{n} notation !).

\subsubsecidx{printp}$(\{str\}*)$: output its (string) arguments in prettyprint
(beautified) format, ending with a newline.

\subsubsecidx{printp1}$(\{str\}*)$: output its (string) arguments in
prettyprint (beautified) format, without ending with a newline.

\subsubsecidx{printtex}$(\{str\}*)$: outputs its (string) arguments in \TeX{}
format. This output can then be used in a \TeX{} manuscript. The printing is
done on the standard output. If you want to print it to a file you should use
{\tt writetex} (see below).

An other possibility is to enable the {\tt log} default (see the shortcut
\b{l} and the default {\tt logfile} as well). You could for instance do:
%
\bprog
  default(logfile, "new.tex");
  default(log, 1);
  printtex(result);
\eprog\noindent
(you can use the automatic string expansion/concatenation process to have
dynamic file names if you wish).

\subsubsecidx{quit}$()$: exits GP.\label{se:quit}

\subsubsecidx{read}$(\{str\})$: read in the file whose name results from the
expansion of the string $str$. If $str$ is omitted, re-read the last file that
was fed into GP.\label{se:read}

\subsubsecidx{reorder}$(\{x=[\,]\})$: $x$ must be a vector. If $x$ is the
empty vector, this gives the vector whose components are the existing
variables in increasing order (i.e.~in decreasing importance). Killed
variables (see {\tt kill} above) will be shown as {\tt 0}. If $x$ is
non-empty, it must be a permutation of variable names, and this permutation
gives a new order of importance of the variables, {\it for output only}. For
example, if the existing order is {\tt [x,y,z]}, then after {\tt
reorder([z,x])} the order of importance of the variables, with respect to
output, will be {\tt [z,y,x]}. The internal representation is unaffected.
\label{se:reorder}

\subsubsecidx{setrand}$(n)$: reseeds the random number generator to the value
$n$. The initial seed (in UNIX systems at least) is $n=1$.

The library syntax is $\teb{setrand}(n)$, where $n$ is a C-long integer. 
The value returned is $n$ once again, but as a \kbd{GEN}.

\subsubsecidxunix{system}$(str)$: $str$ is a string representing a system
command. This command is executed, its output written to the standard output
(this won't get into your logfile), and control goes back to the PARI system.
This simply calls the C {\tt system} command.

\subsubsecidx{type}$(x,\{t\})$:  This is useful only under GP: if $t$ is
not present, return the internal type number of the PARI object $x$.
Else, makes a copy of $x$ and sets its type equal to type $t$, which
can be either a number or, preferably since internal codes may eventually
change, a symbolic name such as \typ{FRACN} (you can skip the \typ{}
part here, so that {\tt FRACN} by itself would also be all right). Check out
existing type names with the metacommand \b{t}.\label{se:gptype}

   Type changes must be used with extreme caution, otherwise disasters may
occur (\kbd{SEGV} or \kbd{SIGBUS} being one's best bet), but one instance
where it can be useful is \kbd{type(x,RFRACN)} when \kbd{x} is a rational
function (type \typ{RFRAC}). In this case, the created object, as well as
the objects created from it, will not be reduced automatically, making the
operations much faster. In fact this function is the {\it only} way to create
reducible rationals (type \typ{FRACN}) or rational functions (type 
\typ{RFRACN}) in GP.

There is no equivalent library syntax, since the internal functions \key{typ}
and \key{settyp} are available. Note that \key{settyp} does {\it not} create
a copy of {\tt x}, contrary to most PARI functions. It just changes the type in
place (and returns nothing). \key{typ} returns a C long integer. Note also
the different spellings of the internal functions (\key{set})\key{typ} and of
the GP function \key{type}\footnote{*}{This is due to the fact that 
\key{type} is a reserved identifier for some C compilers.}.

\subsubsecidx{whatnow}$(key)$: if keyword $key$ is the name of a function
that was present in GP version 1.39.15 or lower, outputs the new function
name and syntax, if it changed at all ($381$ out of $558$
did).\label{se:whatnow}

\subsubsecidx{write}$(filename,\{str*\})$: write (append) to $filename$
the remaining arguments (same format as printf).\label{se:write}

\subsubsecidx{writetex}$(filename,\{str*\})$: as above in \TeX\ format.
\label{se:writetex}

\smallskip
\subsecidx{User defined functions}.

It is very easy to define a new function under GP, which can then be used
like any other function. The syntax is as follows:

{\tt name(list of true formal variables, list of local variables) = $seq$}

\noindent where \kbd{name} is the name that you want to give to your
function. This is subject to the same syntactic restrictions as variable
names. In addition, variable names are not valid names, you have to
\kbd{kill} the variable first (see \secref{se:kill}). There's nothing wrong
about previously used function names: you are just redefining the function
(the previous definition is lost of course). On the other hand, if you want
to use as a variable identifier the name of a user-defined function, it is
enough (and necessary) to \kbd{kill} this function first.

 {\tt list of true formal variables} is the list of variables corresponding
to those which you will actually use when calling your function, the
variables being separated by commas, and the list being allowed to be empty.

{\tt list of local variables} is the list of the additional local variables
which you will use in the definition of the function. If you omit some or all
of these local variable declarations, the function will probably still work,
but the non-declared variables will become global, hence known outside of the
function, and this may have undesirable side-effects. On the other hand, in
some cases it may also be what you want. Finally, as usual $seq$ is any
expression sequence.

  An equal ({\tt =}) sign after the name of any variable, followed by any
expression, gives the variable a default value, in case the user would not
supply it. The expression gets evaluated the moment the function is defined,
and is fixed afterward. A variable for which you supply no default value will
be initialized to zero.

  For instance {\tt foo(x=1,y=2,z=3) = print(x":"y":"z)}, defines a
function which prints its arguments (at most three of them), separated by
colons. This then follows the rules of default arguments generation as
explained at the beginning of \secref{se:functions}section 3.

  Once the function is defined using the above syntax, you can use it like
any other function. In addition, you can also recall its definition exactly
as you do for predefined functions, that is by writing {\tt ?$name$}. This
will print the list of arguments, as well as their default values, the text
of $seq$, and a short help text if one was provided using the {\tt addhelp}
function (see \secref{se:addhelp}). One small difference with predefined
functions is that you can never redefine such a function, while you can
redefine a user-defined function as many times as you want, without using the
{\tt kill} instruction.

An amusing example of a user-defined function is the following. It is
intended to illustrate both the use of user-defined functions and the power
of the {\tt sumalt} function. Although since version 1.34 the \idx{Riemann
zeta-function} is included in the standard functions, let us assume that this
is not the case (or that we want another implementation). One way to define
it, which is probably the simplest (but certainly not the most efficient), is
as follows:

\sidx{zeta function}
{\tt zet(s, j) = sumalt(j=1, (-1)\pow(j-1)*j\pow(-s)) / (1 - 2\pow(1-s))}

  Then this gives reasonably good accuracy and speed as long as you are not
too far from the domain of convergence. Try it for $s$ integral between $-5$
and $5$, say, or for $s=0.5+i*t$ where $t=14.134\dots$ Of course, the call to
the function is done by {\tt zet(s)}, the variable {\tt j} must not be given
(though nothing bad will happen if you give it). 

  In fact, since loop indexes are not visible outside their loops, we should
not have declared {\tt j} at all in the function prototype.

\subsec{Special \idx{editing character}s}. A GP program can of course have
more than one line. Since GP executes your commands as soon as you have
finished typing them, there must be a way to tell it to wait for the next
line or lines of input before doing anything. There are two ways of doing
this.

The first one is simply to use the \idx{backslash character} \kbd{\bs} at the
end of the line that you are typing, just before hitting {\tt <Return>}. This
tells GP that what you will write on the next line is the physical
continuation of what you have just written. In other words, it makes GP
forget your newline character. For example if you use this while defining a
function, and if you ask for the definition of the function using {\tt
?name}, you will see that your backslash has disappeared and that everything
is on the same line. You can type a \kbd{\bs} anywhere. It will be
interpreted as above only if it is immediately followed by a newline. For
example, you can type

\bprog
3 + \bs
4
\eprog

\noindent instead of typing {\tt 3 + 4}.

The second one cannot be used everywhere, but is in general more useful. It
is the use of braces {\tt \obr} and  {\tt \cbr}.\sidx{brace characters} When
GP sees an opening brace ({\tt \obr}) {\it at the beginning of a line} (modulo
spaces as usual), it understands that you are typing a multi-line command,
and newlines will be ignored (but registered, contrary to when you use a
backslash) until you type a closing brace {\tt \cbr}. However, there is an
important (but easily obeyed) restriction: inside an open brace-close brace
pair, all your input lines will be concatenated, suppressing any newlines.
Thus, all newlines should occur after a semicolon (\kbd{;}), a comma 
(\kbd{,}) or an operator (for clarity's sake, we don't recommand splitting an
identifier over two lines in this way). For instance, the following program

\bprog\obr
\q a = b
\q b = c
\cbr\eprog

\noindent would silently produce garbage, since what GP will really see is
{\tt a=bb=c} which will affect the value of {\tt c} to both {\tt bb} and 
{\tt a} (if this really is what you intended, you're a hopeless case).

\subsec{The GP/PARI \idx{programming} language}.

As we have seen, the GP calculator uses a purely interpreted language. The
structure of this language is in fact more reminiscent of LISP with a
functional notation, {\tt f(x,y)} rather than {\tt (f x y)}: all programming
constructs, such as {\tt if, while,} etc... are functions\footnote{*}{Not
exactly, since not all their arguments need be evaluated. For instance it
would be stupid to evaluate both branches of an {\tt if} statement: since
only one will apply, GP only expands this one.}, and the main loop does not
really execute, but rather evaluates (sequences of) expressions.

Of course, it is by no means a true LISP. Function names are distinct from
variable names: once a name has been used as a variable name, this cannot be
changed in the same session. Predefined function names cannot be used for
anything else, and the number of actual parameters must match the declaration
given in the online help. Identifiers that are used for user-defined
functions can be freely redefined for other functions, or totally forgotten
(using {\tt kill}) and later reused for a variable, for example.

Each variable has a stack of values, implemented as a linked list. When a new
scope is entered, during a function call, the value of the actual parameter
is pushed on the stack. If the parameter is not supplied, a special $0$ value
called {\bf \idx{gnil}} is pushed on the stack (this value is not printed if
it is returned as the result of a GP expression sequence). Upon exit, the
stack decreases. You can {\tt kill} a variable, decreasing the stack
yourself. This should be used only at the top level of GP, to undo the effect
of an assignment, not from a function. However, the stack has a bottom: the
value of a variable is the monomial of degree 1 in this variable, as is
natural for a mathematician.

Note that the iterative constructs which use a variable name ({\tt for,
fordiv, forprime, prod, sum, vector, matrix, plot,} etc.) also consider the
given variable to be local to the construct. A value is pushed on entry and
pulled on exit. So, it is not necessary for a function using such a construct
to declare the variable as a dummy formal parameter. In particular, in our
{\tt zet} example above, the variable {\tt j} need not be declared.

Otherwise, it is strongly recommended to declare in this way all other
variables that are used inside a function: If a function accesses a variable
which is not one of its formal parameters, the value used will be the one
which happens to be on top of the stack at the time of the call. This could
be a ``global'' value, or a local value belonging to any function higher in
the call chain. So, be warned.

{\bf Implementation note.} For the curious reader, here is how these stacks
are handled: a \idx{hashing function} is computed from the identifier, and
used as an index in {\tt \idx{hashtable}}, a table of pointers. Each of these
pointers begins a linked list of structures (type {\tt \idx{entree}}). The
linked list is searched linearly for the identifier (each list will have less
than 7 components or so). When the correct {\tt entree} is found, it points
to the top of the stack of values for that identifier if it is a variable, to
the function itself if it is a predefined function, and to a copy of the text
of the function if it is a user-defined function. When an error occurs, all
of this maze (rather a tree, in fact) is searched and (hopefully) replaced in
the situation preceding the last call of the main evaluator.

\section{Using GP under GNU \idx{Emacs}.}
\label{se:emacs}

Thanks to the initial help of Annette Hoffman from the University of
Saarbr\"ucken, but now since version 1.34.05 thanks to David Carlisle from
the University of Manchester, it is possible and in fact desirable to use GP
as a subprocess of GNU Emacs. This is of course possible only if GNU Emacs has
been installed on your machine.

To use this, you must include in your {\tt .emacs} file the following line:

{\tt (load "\idx{pari}" nil t)}

where {\tt pari.el} is the name of the file that will have to be loaded by
GNU Emacs (if you have changed the name, or if you have the file in a
different directory, you must of course supply the correct name). This file
is included in the PARI distribution.

Once this is done, under GNU Emacs if you type {\tt M-x gp} (where as usual
{\tt M} is the {\tt Meta} key, i.e.~Escape, or on SUN keyboards, the Left
key), a special shell will be started, which in particular launches GP with
the default stack size, prime limit and input buffer size. If you type
instead {\tt C-u M-x gp}, you will be asked for the name of the GP
executable, the stack size, the prime limit and the input buffer size before
the execution of GP begins. If for any of these you simply type return, the
default value will be used. On UNIX machines it will be the place you told
{\tt Configure} (usually {\tt /usr/local/bin/gp}) for the executable, 4000000
for the stack, 500000 for the prime limit and 30000 for the buffer size.

\smallskip
  You can then work as usual under GP, but with two notable advantages (which
don't really matter if readline is available to you, see below). First and
foremost, you have at your disposal all the facilities of a text editor like
Emacs, in particular for correcting or copying blocks. Second, you can have
an on-line help which is much more complete than what you obtain by typing
{\tt ?name}. This is done by typing {\tt M-?}. In the minibuffer, Emacs asks
what function you want to describe, and after your reply you obtain the
description which is in the users manual, including the description of
functions (such as \kbd{\bs}, \kbd{\%}) which use special symbols.

  This help system can also be menu-driven, by using the command {\tt
M-\char`\\ c} which opens a help menu window which enables you to choose the
category of commands for which you want an explanation.

  Nevertheless, if extended help is available on your system (see
\secref{se:exthelp}), you should use it instead of the above, since it's
nicer (it ran through \TeX) and understand some more keywords.

  Finally you can use command completion in the following way. After the
prompt, type the first few letters of the command, then {\tt M-<TAB>} where
{\tt <TAB>} is the TAB key. If there exists a unique command starting with
the letters you have typed, the command name will be completed. If not,
either the list of commands starting with the letters you typed will be
displayed in a separate window (which you can then kill by typing as usual
C-x 1 or by typing in more letters), or ``no match found'' will be displayed
in the Emacs command line. If your GP was linked with the readline library,
read the section on completion in the section below (the paragraph on online
help is not relevant).

\smallskip
You also have at your disposal a few other commands. Read the file
{\tt emacs/pari.txt} in standard distribution for details.

Note that if for some reason the session crashes (due to a bug in your
program or in the PARI system), you will usually stay under Emacs, but the GP
buffer will be killed. To recover it, simply type again {\tt M-x gp} (or 
{\tt C-u M-x gp}), and a new session of GP will be started after the old one,
so you can recover what you have typed. Note that this will of course
{\it not} work if for some reason you exited Emacs before coming back (except
for the {\tt C-z} temporary stopping command).

\section{Using GP under \idx{readline}.}
\sidx{line editor}\sidx{completion}

  Thanks to the initial help of Ilya Zakharevich, there is a possibility of
line editing and command name completion outside of an Emacs buffer {\it if}
you could compile GP with GNU readline library. If you don't have Emacs
available, or can't stand using it, we really advise you to make sure you get
this very useful library before configuring or compiling GP.

  In fact, the help and completion mechanism of GP itself are both currently
{\it more} powerful outside an Emacs buffer!

\subsec{A (too) short introduction to readline}:
\label{se:readline}
  The basics are as follows (read the readline user manual !), assume that
{\tt C-} stands for ``the {\tt Control} key combined with another'' and the
same for {\tt M-} with the {\tt Meta} key (generally {\tt C-} combinations
act on characters, while the {\tt M-} ones operate on words). Typing any
ordinary key inserts text where the cursor stands, the arrow keys enabling
you to move in the line. There are many more movement commands, which will be
familiar to the Emacs user, for instance {\tt C-a}/{\tt C-e} will take you to
the start/end of the line, {\tt M-b}/{\tt M-f} move the cursor
backward/forward by a word, etc. Just press the {\tt Return} key at any point
to send your command to GP.

  All the commands you type in are stored in a history (the multiline
commands being saved as a unique line). The Up and Down arrows (or {\tt
C-p}/{\tt C-n}) will move you through it, {\tt M-<}/{\tt M->} sending you
to the start/end of the history. {\tt C-r}/{\tt C-s} will start an
incremental backward/forward search. You can kill text ({\tt C-k} kills till
the end of line, {\tt M-d} to the end of current word) which you can then
yank back using the {\tt C-y} key ({\tt M-y} will rotate the kill-ring). {\tt
C-\_} will undo your last changes incrementally ({\tt M-r} undoes all changes
made to the current line). {\tt M-t} will transpose the two words preceding
the cursor.

  Keeping the {\tt M-} key down while you enter an integer (a minus sign
meaning reverse behaviour) gives an argument to your next readline command
(for instance {\tt M-- C-k} will kill text back to the start of line). If you
prefer \idx{Vi}--style editing, {\tt M-C-j} will toggle you to Vi mode. Of
course you can change all these default bindings. For that you need to write a
{\tt .inputrc} file in your home directory. For instance (notice the
embedding conditional in case you would want specific bindings for GP):
%
\bprog
\$if Pari-GP
\q set show-all-if-ambiguous
\q "\b{C}-h": backward-delete-char
\q "\b{e}\b{C}-h": backward-kill-word
\q "\b{C}-xd": dump-functions
\q "(" : "\b{C}-v()\b{C}-b" \qquad \# can be annoying when copy-pasting !
\$endif
\eprog
%
{\tt C-x C-r} will re-read this init file, incorporating any changes made to
it during the current session.

\subsec{Command completion and online help}

  As in the Emacs shell, {\tt <TAB>} will complete words for you. But, under
readline, this mechanism will be context-dependent: GP will strive to only
give you meaningful completions in a given context (it will fail sometimes,
but usually under stringent conditions).

  For instance, shortly after a \kbd{\til}, we expect a user name, then a
path to some file. Directly after {\tt default(} has been typed, we would
expect one of the {\tt default} keywords. After {\tt whatnow(} , we expect
the name of an old function, which may well have disappeared form this
version. After a '.', we expect a member keyword. And generally of course, we
expect any GP symbol which may be found in the hashing lists: functions (both
yours and GP's), and variables.

  If, at any time, only one completion is meaningful, GP will provide it
(together with an opening parenthesis if it's a function). Otherwise, hitting
{\tt <TAB>} once more will give you the list of possible completions. Just
experiment with this mechanism as often as possible, you'll probably find it
very convenient. For instance, you could obtain {\tt
default(seriesprecision,10)}, just by hitting {\tt def<TAB>se<TAB>,10)},
which saves 16 keystrokes (out of 27).

  Hitting {\tt M-h} will give you the usual short online help concerning the
word directly beneath the cursor, {\tt M-H} will yield the extended help
corresponding to the {\tt help} default program (usually opens a \idx{dvi}
previewer, or runs a primitive tex-to-ASCII program). None of these disturb
the line you were editing.
\vfill\eject
