pari-doc 2.9.1-1 / usr / share / pari / doc / usersch5.tex

% Copyright (c) 2000  The PARI Group
%
% This file is part of the PARI/GP documentation
%
% Permission is granted to copy, distribute and/or modify this document
% under the terms of the GNU General Public License
\chapter{Technical Reference Guide: the basics}

In the following chapters, we describe all public low-level functions of the
PARI library. These include specialized functions for handling all the PARI
types. Simple higher level functions, such as arithmetic or transcendental
functions, are described in Chapter~3 of the GP user's manual; we will
eventually see more general or flexible versions in the chapters to come. A
general introduction to the major concepts of PARI programming can be found
in Chapter~4, which you should really read first.

We shall now study specialized functions, more efficient than the library
wrappers, but sloppier on argument checking and damage control; besides
speed, their main advantage is to give finer control about the inner
workings of generic routines, offering more options to the programmer.

\misctitle{Important advice} Generic routines eventually call lower level
functions. Optimize your algorithms first, not overhead and conversion costs
between PARI routines. For generic operations, use generic routines first;
do not waste time looking for the most specialized one available unless you
identify a genuine bottleneck, or you need some special behavior the generic
routine does not offer. The PARI source code is part of the documentation;
look for inspiration there.\smallskip

The type \kbd{long} denotes a \tet{BITS_IN_LONG}-bit signed long integer (32
or 64 bits). The type \tet{ulong} is defined as \kbd{unsigned long}. The word
\emph{stack} always refer to the PARI stack, allocated through an initial
\kbd{pari\_init} call. Refer to Chapters 1--2 and~4 for general background.
\kbdsidx{BIL}

We shall often refer to the notion of \tev{shallow} function, which means that
some components of the result may point to components of the input, which is
more efficient than a \emph{deep} copy (full recursive copy of the object
tree). Such outputs are not suitable for \kbd{gerepileupto} and particular
care must be taken when garbage collecting objects which have been input to
shallow functions: corresponding outputs also become invalid and should no
longer be accessed.

A function is \emph{not stack clean} if it leaves intermediate data on the
stack besides its output, for efficiency reasons.

\section{Initializing the library}

The following functions enable you to start using the PARI functions
in a program, and cleanup without exiting the whole program.

\subsec{General purpose}

\fun{void}{pari_init}{size_t size, ulong maxprime} initialize the
library, with a stack of \kbd{size} bytes and a prime table
up to the maximum of \kbd{maxprime} and $2^{16}$. Unless otherwise
mentioned, no PARI function will function properly before such an
initialization.

\fun{void}{pari_close}{void} stop using the library (assuming it was
initialized with \kbd{pari\_init}) and frees all allocated objects.

\subsec{Technical functions}\label{se:pari_init_tech}

\fun{void}{pari_init_opts}{size_t size, ulong maxprime, ulong opts} as
\kbd{pari\_init}, more flexible. \kbd{opts} is a mask of flags
among the following:

  \kbd{INIT\_JMPm}: install PARI error handler. When an exception is
raised, the program is terminated with \kbd{exit(1)}.

  \kbd{INIT\_SIGm}: install PARI signal handler.

  \kbd{INIT\_DFTm}: initialize the \kbd{GP\_DATA} environment structure.
This one \emph{must} be enabled once. If you close pari, then restart it,
you need not reinitialize \kbd{GP\_DATA}; if you do not, then old values are
restored.

  \kbd{INIT\_noPRIMEm}: do not compute the prime table (ignore the
  \kbd{maxprime} argument). The user \emph{must} call
  \tet{pari_init_primes} later.

  \kbd{INIT\_noIMTm}: (technical, see \kbd{pari\_mt\_init} in the Developer's
Guide for detail). Do not call \tet{pari_mt_init} to initialize the
multi-thread engine. If this flag is set, \kbd{pari\_mt\_init()} will need to
be called manually. See \kbd{examples/pari-mt.c} for an example.

  \kbd{INIT\_noINTGMPm}: do not install PARI-specific GMP memory functions.
This option is ignored when the GMP library is not in use. You may
install PARI-specific GMP memory functions later by calling

\fun{void}{pari_kernel_init}{void}

\noindent and restore the previous values using

\fun{void}{pari_kernel_close}{void}

This option should not be used without a thorough understanding of the
problem you are trying to solve. The GMP memory functions are global
variables used by the GMP library. If your program is linked with two
libraries that require these variables to be set to different values,
conflict ensues. To avoid a conflict, the proper solution is to record
their values with \kbd{mp\_get\_memory\_functions} and to call
\kbd{mp\_set\_memory\_functions} to restore the expected values each time the
code switches from using one library to the other. Here is an example:
\bprog
void *(*pari_alloc_ptr) (size_t);
void *(*pari_realloc_ptr) (void *, size_t, size_t);
void (*pari_free_ptr) (void *, size_t);
void *(*otherlib_alloc_ptr) (size_t);
void *(*otherlib_realloc_ptr) (void *, size_t, size_t);
void (*otherlib_free_ptr) (void *, size_t);

void init(void)
{
  pari_init(8000000, 500000);
  mp_get_memory_functions(&pari_alloc_ptr,&pari_realloc_ptr,
                          &pari_free_ptr);
  otherlib_init();
  mp_get_memory_functions(&otherlib_alloc_ptr,&otherlib_realloc_ptr,
                          &otherlib_free_ptr);
}
void function_that_use_pari(void)
{
  mp_set_memory_functions(pari_alloc_ptr,pari_realloc_ptr,
                          pari_free_ptr);
  /*use PARI functions*/
}
void function_that_use_otherlib(void)
{
  mp_set_memory_functions(otherlib_alloc_ptr,otherlib_realloc_ptr,
                          otherlib_free_ptr);
  /*use OTHERLIB functions*/
}
@eprog

\fun{void}{pari_close_opts}{ulong init_opts} as \kbd{pari\_close},
for a library initialized with a mask of options using
\kbd{pari\_init\_opts}. \kbd{opts} is a mask of flags among

  \kbd{INIT\_SIGm}: restore \kbd{SIG\_DFL} default action for signals
tampered with by PARI signal handler.

  \kbd{INIT\_DFTm}: frees the \kbd{GP\_DATA} environment structure.

  \kbd{INIT\_noIMTm}: (technical, see \kbd{pari\_mt\_init} in the Developer's
Guide for detail). Do not call \tet{pari_mt_close} to close the multi-thread
engine.

\fun{void}{pari_sig_init}{void (*f)(int)} install the signal handler \kbd{f}
(see \kbd{signal(2)}): the signals \kbd{SIGBUS}, \kbd{SIGFPE}, \kbd{SIGINT},
\kbd{SIGBREAK}, \kbd{SIGPIPE} and \kbd{SIGSEGV} are concerned.

\fun{void}{pari_init_primes}{ulong maxprime} Initialize the PARI
primes. This function is called by \kbd{pari\_init(\dots,maxprime)}.
It is provided for users calling \kbd{pari\_init\_opts} with the
flag \kbd{INIT\_noPRIMEm}.

\fun{void}{pari_sighandler}{int signum} the actual signal handler that
PARI uses. This can be used as argument to \kbd{pari\_sig\_init} or
\kbd{signal(2)}.

\fun{void}{pari_stackcheck_init}{void *stackbase} controls the system stack
exhaustion checking code in the GP interpreter. This should be used when the
system stack base address change or when the address seen by \kbd{pari\_init}
is too far from the base address. If \kbd{stackbase} is \kbd{NULL}, disable the
check, else set the base address to \kbd{stackbase}. It is normally used this
way
\bprog
int thread_start (...)
{
  long first_item_on_the_stack;
  ...
  pari_stackcheck_init(&first_item_on_the_stack);
}
@eprog

\fun{int}{pari_daemon}{void} forks a PARI daemon, detaching from the main
process group. The function returns 1 in the parent, and 0 in the
forked son.

\fun{void}{paristack_setsize}{size_t rsize, size_t vsize}
sets the default \kbd{parisize} to \kbd{rsize} and the
default \kbd{parisizemax} to \kbd{vsize}, and reallocate the
stack to match these value, destroying its content.
Generally used just after \kbd{pari\_init}.

\fun{void}{paristack_resize}{ulong newsize}
changes the current stack size to \kbd{newsize}
(double it if \kbd{newsize} is 0).
The new size is clipped to be at least the current stack size and
at most \kbd{parisizemax}. The stack content is not affected
by this operation.

\fun{void}{parivstack_reset}{void}
resets the current stack to its default size \kbd{parisize},
destroying its content. Used to recover memory after a
computation that enlarged the stack.

\fun{void}{paristack_newrsize}{ulong newsize}
\emph{(does not return)}. Library version of
\bprog
  default(parisize, "newsize")
@eprog\noindent Set the default \kbd{parisize} to \kbd{newsize}, or double
\kbd{parisize} if \kbd{newsize} is equal to 0, then call
\kbd{cb\_pari\_err\_recover(-1)}.

\fun{void}{parivstack_resize}{ulong newsize}
\emph{(does not return)}. Library version of
\bprog
  default(parisizemax, "newsize")
@eprog\noindent Set the default \kbd{parisizemax} to \kbd{newsize} and call
\kbd{cb\_pari\_err\_recover(-1)}.

\subsec{Notions specific to the GP interpreter}

An \kbd{entree} is the generic object attached to an identifier (a name)
in GP's interpreter, be it a built-in or user function, or a variable. For
a function, it has at least the following fields:

  \kbd{char *name}: the name under which the interpreter knows us.

  \kbd{void *value}:  a pointer to the C function to call.

  \kbd{long menu}: a small integer $\geq 1$ (to which group of function
                    help do we belong, for the \kbd{?$n$} help menu).

  \kbd{char *code}: the prototype code.

  \kbd{char *help}: the help text for the function.

A routine in GP is described to the analyzer by an \kbd{entree}
structure. Built-in PARI routines are grouped in \emph{modules}, which
are arrays of \kbd{entree} structs, the last of which satisfy
\kbd{name = NULL} (sentinel). There are currently five modules in PARI/GP:

\item general functions (\tet{functions_basic}, known to \kbd{libpari}),

\item gp-specific functions (\tet{functions_gp}),

\item gp-specific highlevel functions (\tet{functions_highlevel}),

\noindent and two modules of obsolete functions. The function
\kbd{pari\_init} initializes the interpreter and declares all symbols in
\kbd{functions\_basic}. You may declare further functions on a case by case
basis or as a whole module using

\fun{void}{pari_add_function}{entree *ep} adds a single routine to the
table of symbols in the interpreter. It assumes \kbd{pari\_init} has been
called.

\fun{void}{pari_add_module}{entree *mod} adds all the routines in module
\kbd{mod} to the table of symbols in the interpreter. It assumes
\kbd{pari\_init} has been called.

\noindent For instance, gp implements a number of private routines, which
it adds to the default set via the calls
\bprog
  pari_add_module(functions_gp);
  pari_add_module(functions_highlevel);
@eprog

A GP \kbd{default} is likewise attached to a helper routine, that is run
when the value is consulted, or changed by \tet{default0} or \tet{setdefault}.
Such routines are grouped in the module \tet{functions_default}.

\fun{void}{pari_add_defaults_module}{entree *mod} adds all the defaults in
module \kbd{mod} to the interpreter. It assumes that \kbd{pari\_init} has
been called. From this point on, all defaults in module \kbd{mod} are known
to \tet{setdefault} and friends.

\subsec{Public callbacks}

The \kbd{gp} calculator associates elaborate functions (for instance the
break loop handler) to the following callbacks, and so can you:

\doc{cb_pari_ask_confirm}{void (*cb_pari_ask_confirm)(const char *s)}
initialized to \kbd{NULL}. Called with argument $s$ whenever PARI wants
confirmation for action $s$, for instance in \tet{secure} mode.

\doc{cb_pari_init_histfile}{void (*cb_pari_init_histfile)(void)}
initialized to \kbd{NULL}. Called when the \kbd{histfile} default
is changed. The intent is for that callback to read the file content, append
it to history in memory, then dump the expanded history to the new
\kbd{histfile}.

\doc{cb_pari_is_interactive}{int (*cb_pari_is_interactive)(void)};
initialized to \kbd{NULL}.

\doc{cb_pari_quit}{void (*cb_pari_quit)(long)}
initialized to a no-op. Called when \kbd{gp} must evaluate the \kbd{quit}
command.

\doc{cb_pari_start_output}{void (*cb_pari_start_output)(void)}
initialized to \kbd{NULL}.

\doc{cb_pari_handle_exception}{int (*cb_pari_handle_exception)(long)}
initialized to \kbd{NULL}. If not \kbd{NULL}, this routine is called with
argument $-1$ on \kbd{SIGINT}, and argument \kbd{err} on error \kbd{err}. If
it returns a non-zero value, the error or signal handler returns, in effect
further ignoring the error or signal, otherwise it raises a fatal error.
A possible simple-minded handler, used by the \kbd{gp} interpreter, is

\fun{int}{gp_handle_exception}{long err} if the \kbd{breakloop}
default is enabled (set to $1$) and \tet{cb_pari_break_loop} is not
\kbd{NULL}, we call this routine with \kbd{err} argument and return the
result.

\doc{cb_pari_err_handle}{int (*cb_pari_err_handle)(GEN)}
If not \kbd{NULL}, this routine is called with a \typ{ERROR} argument
from \kbd{pari\_err}. If it returns a non-zero value, the error returns, in
effect further ignoring the error, otherwise it raises a fatal error.

The default behaviour is to print a descriptive error
message (display the error), then return 0, thereby raising a fatal error.
This differs from \tet{cb_pari_handle_exception} in that the
function is not called on \kbd{SIGINT} (which do not generate a \typ{ERROR}),
only from \kbd{pari\_err}. Use \tet{cb_pari_sigint} if you need to handle
\kbd{SIGINT} as well.

\doc{cb_pari_break_loop}{int (*cb_pari_break_loop)(int)}
initialized to \kbd{NULL}.

\doc{cb_pari_sigint}{void (*cb_pari_sigint)(void)}.
Function called when we receive \kbd{SIGINT}. By default, raises
\bprog
  pari_err(e_MISC, "user interrupt");
@eprog\noindent A possible simple-minded variant, used by the
\kbd{gp} interpreter, is

\fun{void}{gp_sigint_fun}{void}

\doc{cb_pari_pre_recover}{void (*cb_pari_err_recover)(long)}
initialized to \kbd{NULL}. If not \kbd{NULL}, this routine is called just
before PARI cleans up from an error. It is not required to return.  The error
number is passed as argument, unless the PARI stack has been destroyed
(\kbd{allocatemem}), in which case $-1$ is passed.

\doc{cb_pari_err_recover}{void (*cb_pari_err_recover)(long)}
initialized to \kbd{pari\_exit()}. This callback must not return.
It is called after PARI has cleaned-up from an error. The error number is
passed as argument, unless the PARI stack has been destroyed, in which case
it is called with argument $-1$.

\doc{cb_pari_whatnow}{int (*cb_pari_whatnow)(PariOUT *out, const char *s, int
flag)} initialized to \kbd{NULL}. If not \kbd{NULL}, must check whether $s$
existed in older versions of \kbd{pari} (the \kbd{gp} callback checks against
\kbd{pari-1.39.15}). All output must be done via \kbd{out} methods.

\item $\fl = 0$: should print verbosely the answer, including help text if
available.

\item $\fl = 1$: must return $0$ if the function did not change, and a
non-$0$ result otherwise. May print a help message.

\subsec{Configuration variables}

\tet{pari_library_path}: If set, It should be a path to the libpari library.
It is used by the function \tet{gpinstall} to locate the PARI library when
searching for symbols.  This should only be useful on Windows.

\subsec{Utility functions}

\fun{void}{pari_ask_confirm}{const char *s} raise an error if the
callback \tet{cb_pari_ask_confirm} is \kbd{NULL}. Otherwise
calls
\bprog
  cb_pari_ask_confirm(s);
@eprog

\fun{char*}{gp_filter}{const char *s} pre-processor for the GP
parser: filter out whitespace and GP comments from $s$.

\fun{GEN}{pari_compile_str}{const char *s} low-level form of
\tet{compile_str}: assumes that $s$ does not contain spaces or GP comments and
returns the closure attached to the GP expression $s$. Note
that GP metacommands are not recognized.

\fun{int}{gp_meta}{const char *s, int ismain} low-level component of
\tet{gp_read_str}: assumes that $s$ does not contain spaces or GP comments and
try to interpret $s$ as a GP metacommand (e.g. starting by \kbd{\bs} or
\kbd{?}). If successful, execute the metacommand and return $1$; otherwise
return $0$. The \kbd{ismain} parameter modifies the way \kbd{\bs r} commands
are handled: if non-zero, act as if the file contents were entered via
standard input (i.e. call \tet{switchin} and divert \tet{pari_infile});
otherwise, simply call \tet{gp_read_file}.

\fun{void}{pari_hit_return}{void} wait for the use to enter \kbd{\bs n}
via standard input.

\fun{void}{gp_load_gprc}{void} read and execute the user's \kbd{GPRC} file.

\fun{void}{pari_center}{const char *s} print $s$, centered.

\fun{void}{pari_print_version}{void} print verbose version information.

\fun{const char*}{gp_format_time}{long t} format a delay of $t$ ms
suitable for \kbd{gp} output, with \kbd{timer} set.

\fun{const char*}{gp_format_prompt}{const char *p} format a prompt $p$
suitable for \kbd{gp} prompting (includes colors and protecting ANSI escape
sequences for readline).

\fun{void}{pari_alarm}{long s} set an alarm after $s$ seconds (raise an
\tet{e_ALARM} exception).

\fun{void}{gp_help}{const char *s, long flag} print help for $s$, depending
on the value of \fl:

\item \tet{h_REGULAR}, basic help (\kbd{?});

\item \tet{h_LONG}, extended help (\kbd{??});

\item \tet{h_APROPOS}, a propos help (\kbd{??}).

\fun{const char **}{gphelp_keyword_list}{void} return a
\kbd{NULL}-terminated array a strings, containing keywords known to
\kbd{gphelp} besides GP functions (e.g. \kbd{modulus} or \kbd{operator}).
Used by the online help system and the contextual completion engine.

\fun{void}{gp_echo_and_log}{const char *p, const char *s} given a prompt
$p$ and attached input command $s$, update logfile and possibly
print on standard output if \tet{echo} is set and we are not in interactive
mode. The callback \tet{cb_pari_is_interactive} must be set to a sensible
value.

\fun{void}{gp_alarm_handler}{int sig} the \kbd{SIGALRM} handler
set by the \kbd{gp} interpreter.

\fun{void}{print_fun_list}{char **list, long n}
print all elements of \kbd{list} in columns, pausing (hit return)
every $n$ lines. \kbd{list} is \kbd{NULL} terminated.

\subsec{Saving and restoring the GP context}

\fun{void}{gp_context_save}{struct gp_context* rec} save the current GP
context.

\fun{void}{gp_context_restore}{struct gp_context* rec} restore a GP context.
The new context must be an ancestor of the current context.

\subsec{GP history}

These functions allow to control the GP history (the \kbd{\%} operator).

\fun{void}{pari_add_hist}{GEN x, long t} adds \kbd{x} as the last history
entry; $t$ is the time we used to compute it.

\fun{GEN}{pari_get_hist}{long p}, if $p>0$ returns entry of index $p$
(i.e. \kbd{\%p}), else returns entry of index $n+p$ where $n$ is the
index of the last entry (used for \kbd{\%}, \kbd{\%`}, \kbd{\%``}, etc.).

\fun{long}{pari_get_histtime}{long p} as \tet{pari_get_hist},
returning the time used to compute the history entry, instead of the entry
itself.

\fun{ulong}{pari_nb_hist}{void} return the index of the last entry.

\section{Handling \kbd{GEN}s}
\noindent Almost all these functions are either macros or inlined. Unless
mentioned otherwise, they do not evaluate their arguments twice. Most of them
are specific to a set of types, although no consistency checks are made:
e.g.~one may access the \kbd{sign} of a \typ{PADIC}, but the result is
meaningless.

\subsec{Allocation}

\fun{GEN}{cgetg}{long l, long t} allocates (the root of) a \kbd{GEN}
of type $t$ and length $l$. Sets $z[0]$.

\fun{GEN}{cgeti}{long l} allocates a \typ{INT} of length $l$ (including the
2 codewords). Sets $z[0]$ only.

\fun{GEN}{cgetr}{long l} allocates a \typ{REAL} of length $l$ (including the
2 codewords). Sets $z[0]$ only.

\fun{GEN}{cgetc}{long prec} allocates a \typ{COMPLEX} whose real and
imaginary parts are \typ{REAL}s of length \kbd{prec}.

\fun{GEN}{cgetg_copy}{GEN x, long *lx} fast version of \kbd{cgetg}:
allocate a \kbd{GEN} with the same type and length as $x$, setting \kbd{*lx}
to \kbd{lg(x)} as a side-effect. (Only sets the first codeword.) This is
a little faster than \kbd{cgetg} since we may reuse the bitmask in
$x[0]$ instead of recomputing it, and we do not need to check that the
length does not overflow the possibilities of the
implementation (since an object with that length already exists). Note that
\kbd{cgetg} with arguments known at compile time, as in
\bprog
  cgetg(3, t_INTMOD)
@eprog\noindent will be even faster since the compiler will directly perform
all computations and checks.

\fun{GEN}{vectrunc_init}{long l} perform \kbd{cgetg(l,t\_VEC)}, then
set the length to $1$ and return the result. This is used to  implement
vectors whose final length is easily bounded at creation time, that we intend
to fill gradually using:

\fun{void}{vectrunc_append}{GEN x, GEN y} assuming $x$ was allocated using
\tet{vectrunc_init}, appends $y$ as the last element of $x$, which
grows in the process. The function is shallow: we append $y$, not a copy;
it is equivalent to
\bprog
  long lx = lg(x); gel(x,lx) = y; setlg(x, lx+1);
@eprog\noindent
Beware that the maximal size of $x$ (the $l$ argument to \tet{vectrunc_init})
is unknown, hence unchecked, and stack corruption will occur if we append
more than $l-1$ elements to $x$. Use the safer (but slower)
\kbd{shallowconcat} when $l$ is not easy to bound in advance.

An other possibility is simply to allocate using \kbd{cgetg(l, t)} then fill
the components as they become available: this time the downside is that we do
not obtain a correct \kbd{GEN} until the vector is complete. Almost no PARI
function will be able to operate on it.

\fun{void}{vectrunc_append_batch}{GEN x, GEN y} successively apply
\bprog
  vectrunc_append(x, gel(y, i))
@eprog
for all elements of the vector $y$.

\fun{GEN}{vecsmalltrunc_init}{long l}

\fun{void}{vecsmalltrunc_append}{GEN x, long t} analog to the above for a
\typ{VECSMALL} container.

\subsec{Length conversions}

These routines convert a non-negative length to different units. Their
behavior is undefined at negative integers.

\fun{long}{ndec2nlong}{long x} converts a number of decimal digits to a number
of words. Returns $ 1 + \kbd{floor}(x \times \B \log_2 10)$.

\fun{long}{ndec2prec}{long x} converts a number of decimal digits to a number
of codewords. This is equal to 2 + \kbd{ndec2nlong(x)}.

\fun{long}{ndec2nbits}{long x} convers a number of decimal digits to a
number of bits.

\fun{long}{prec2ndec}{long x} converts a number of codewords to a
number of decimal digits.

\fun{long}{nbits2nlong}{long x} converts a number of bits to a number of
words. Returns the smallest word count containing $x$ bits, i.e $
\kbd{ceil}(x / \B)$.

\fun{long}{nbits2ndec}{long x} converts a number of bits to a number of
decimal digits.

\fun{long}{nbits2lg}{long x} converts a number of bits to a length
in code words. Currently  an alias for \kbd{nbits2nlong}.

\fun{long}{nbits2prec}{long x} converts a number of bits to a number of
codewords. This is equal to 2 + \kbd{nbits2nlong(x)}.

\fun{long}{nbits2extraprec}{long x} converts a number of bits to the mantissa
length of a \typ{REAL} in codewords. This is currently an alias to
\kbd{nbits2nlong(x)}.

\fun{long}{nchar2nlong}{long x} converts a number of bytes to number of
words. Returns the smallest word count containing $x$ bytes, i.e
$\kbd{ceil}(x / \kbd{sizeof(long)})$.

\fun{long}{prec2nbits}{long x} converts a \typ{REAL} length into a number
of significant bits; returns $(x - 2)\B$.

\fun{double}{prec2nbits_mul}{long x, double y} returns
\kbd{prec2nbits}$(x)\times y$.

\fun{long}{bit_accuracy}{long x} converts a length into a number
of significant bits; currently an alias for \kbd{prec2nbits}.

\fun{double}{bit_accuracy_mul}{long x, double y} returns
\kbd{bit\_accuracy}$(x)\times y$.

\fun{long}{realprec}{GEN x} length of a \typ{REAL} in words; currently an alias
for \kbd{lg}.

\fun{long}{bit_prec}{GEN x} length of a \typ{REAL} in bits.

\fun{long}{precdbl}{long prec} given a length in words corresponding to a
\typ{REAL} precision, return the length corresponding to doubling the
precision. Due to the presence of 2 code words, this is
 $2(\kbd{prec} - 2) + 2$.

\subsec{Read type-dependent information}

\fun{long}{typ}{GEN x} returns the type number of~\kbd{x}. The header files
included through \kbd{pari.h} define symbolic constants for the \kbd{GEN}
types: \typ{INT} etc. Never use their actual numerical values. E.g to determine
whether \kbd{x} is a \typ{INT}, simply check
\bprog
  if (typ(x) == t_INT) { }
@eprog\noindent
The types are internally ordered and this simplifies the implementation of
commutative binary operations (e.g addition, gcd). Avoid using the ordering
directly, as it may change in the future; use type grouping functions
instead (\secref{se:typegroup}).

\fun{const char*}{type_name}{long t} given a type number \kbd{t} this routine
returns a string containing its symbolic name. E.g \kbd{type\_name(\typ{INT})}
returns \kbd{"\typ{INT}"}. The return value is read-only.

\fun{long}{lg}{GEN x} returns the length of~\kbd{x} in \B-bit words.

\fun{long}{lgefint}{GEN x} returns the effective length of the \typ{INT}
\kbd{x} in \B-bit words.

\fun{long}{signe}{GEN x} returns the sign ($-1$, 0 or 1) of~\kbd{x}. Can be
used for \typ{INT}, \typ{REAL}, \typ{POL} and \typ{SER} (for the last two
types, only 0 or 1 are possible).

\fun{long}{gsigne}{GEN x} returns the sign of a real number $x$,
valid for \typ{INT}, \typ{REAL} as \kbd{signe}, but also for \typ{FRAC}
and \typ{QUAD} of positive discriminants. Raise a type error if \kbd{typ(x)}
is not among those.

\fun{long}{expi}{GEN x} returns the binary exponent of the real number equal
to the \typ{INT}~\kbd{x}. This is a special case of \kbd{gexpo}.

\fun{long}{expo}{GEN x} returns the binary exponent of the
\typ{REAL}~\kbd{x}.

\fun{long}{mpexpo}{GEN x} returns the binary exponent of the \typ{INT}
or \typ{REAL}~\kbd{x}.

\fun{long}{gexpo}{GEN x} same as \kbd{expo}, but also valid when \kbd{x}
is not a \typ{REAL} (returns the largest exponent found among the components
of \kbd{x}). When \kbd{x} is an exact~0, this returns
\hbox{\kbd{-HIGHEXPOBIT}}, which is lower than any valid exponent.

\fun{long}{valp}{GEN x} returns the $p$-adic valuation (for
a \typ{PADIC}) or $X$-adic valuation (for a \typ{SER}, taken with respect to
the main variable) of~\kbd{x}.

\fun{long}{precp}{GEN x} returns the precision of the \typ{PADIC}~\kbd{x}.

\fun{long}{varn}{GEN x} returns the variable number of the
\typ{POL} or \typ{SER}~\kbd{x} (between 0 and \kbd{MAXVARN}).

\fun{long}{gvar}{GEN x} returns the main variable number when any variable
at all occurs in the composite object~\kbd{x} (the smallest variable number
which occurs), and \tet{NO_VARIABLE} otherwise.

\fun{long}{gvar2}{GEN x} returns the variable number for the ring over which
$x$ is defined, e.g. if $x\in \Z[a][b]$ return (the variable number for)
$a$. Return \tet{NO_VARIABLE} if $x$ has no variable or is not defined over a
polynomial ring.

\fun{long}{degpol}{GEN x} is a simple macro returning \kbd{lg(x) - 3}.
This is the degree of the \typ{POL}~\kbd{x} with respect to its main
variable, \emph{if} its leading coefficient is non-zero (a rational $0$ is
impossible, but an inexact $0$ is allowed, as well as an exact modular $0$,
e.g. \kbd{Mod(0,2)}). If $x$ has no coefficients (rational $0$ polynomial),
its length is $2$ and we return the expected $-1$.

\fun{long}{lgpol}{GEN x} is equal to \kbd{degpol(x) + 1}. Used to loop over
the coefficients of a \typ{POL} in the following situation:
\bprog
    GEN xd = x + 2;
    long i, l = lgpol(x);
    for (i = 0; i < l; i++) foo( xd[i] ).
@eprog

\fun{long}{precision}{GEN x} If \kbd{x} is of type \typ{REAL}, returns the
precision of~\kbd{x}, namely the length of \kbd{x} in \B-bit words if \kbd{x}
is not zero, and a reasonable quantity obtained from the exponent of \kbd{x}
if \kbd{x} is numerically equal to zero. If \kbd{x} is of type
\typ{COMPLEX}, returns the minimum of the precisions of the real and
imaginary part. Otherwise, returns~0 (which stands for infinite precision).

\fun{long}{lgcols}{GEN x} is equal to \kbd{lg(gel(x,1))}. This is the length
of the columns of a \typ{MAT} with at least one column.

\fun{long}{nbrows}{GEN x} is equal to \kbd{lg(gel(x,1))-1}. This is the number
of rows of a \typ{MAT} with at least one column.

\fun{long}{gprecision}{GEN x} as \kbd{precision} for scalars. Returns the
lowest precision encountered among the components otherwise.

\fun{long}{sizedigit}{GEN x} returns 0 if \kbd{x} is exactly~0. Otherwise,
returns \kbd{\key{gexpo}(x)} multiplied by $\log_{10}(2)$. This gives a crude
estimate for the maximal number of decimal digits of the components
of~\kbd{x}.

\subsec{Eval type-dependent information}
These routines convert type-dependent information to bitmask to fill the
codewords of \kbd{GEN} objects (see \secref{se:impl}). E.g for a
\typ{REAL}~\kbd{z}:
\bprog
  z[1] = evalsigne(-1) | evalexpo(2)
@eprog
Compatible components of a codeword for a given type can be OR-ed as above.

\fun{ulong}{evaltyp}{long x} convert type~\kbd{x} to bitmask (first
codeword of all \kbd{GEN}s)

\fun{long}{evallg}{long x} convert length~\kbd{x} to bitmask (first
codeword of all \kbd{GEN}s). Raise overflow error if \kbd{x} is so large that
the corresponding length cannot be represented

\fun{long}{_evallg}{long x} as \kbd{evallg} \emph{without} the overflow
check.

\fun{ulong}{evalvarn}{long x} convert variable number~\kbd{x} to bitmask
(second codeword of \typ{POL} and \typ{SER})

\fun{long}{evalsigne}{long x} convert sign~\kbd{x} (in $-1,0,1$) to bitmask
(second codeword of \typ{INT}, \typ{REAL}, \typ{POL}, \typ{SER})

\fun{long}{evalprecp}{long x} convert $p$-adic ($X$-adic) precision~\kbd{x}
to bitmask (second codeword of \typ{PADIC}, \typ{SER}). Raise overflow error
if \kbd{x} is so large that the corresponding precision cannot be
represented.

\fun{long}{_evalprecp}{long x} same as \kbd{evalprecp} \emph{without} the
overflow check.

\fun{long}{evalvalp}{long x} convert $p$-adic ($X$-adic) valuation~\kbd{x} to
bitmask (second codeword of \typ{PADIC}, \typ{SER}). Raise overflow error if
\kbd{x} is so large that the corresponding valuation cannot be represented.

\fun{long}{_evalvalp}{long x} same as \kbd{evalvalp} \emph{without} the
overflow check.

\fun{long}{evalexpo}{long x} convert exponent~\kbd{x} to bitmask (second
codeword of \typ{REAL}). Raise overflow error if \kbd{x} is so
large that the corresponding exponent cannot be represented

\fun{long}{_evalexpo}{long x} same as \kbd{evalexpo} \emph{without} the
overflow check.

\fun{long}{evallgefint}{long x} convert effective length~\kbd{x} to bitmask
(second codeword \typ{INT}). This should be less or equal than the length
of the \typ{INT}, hence there is no overflow check for the effective length.

\subsec{Set type-dependent information}
Use these functions and macros with extreme care since usually the
corresponding information is set otherwise, and the components and further
codeword fields (which are left unchanged) may not be compatible with the new
information.

\fun{void}{settyp}{GEN x, long s} sets the type number of~\kbd{x} to~\kbd{s}.

\fun{void}{setlg}{GEN x, long s} sets the length of~\kbd{x} to~\kbd{s}. This
is an efficient way of truncating vectors, matrices or polynomials.

\fun{void}{setlgefint}{GEN x, long s} sets the effective length
of the \typ{INT} \kbd{x} to~\kbd{s}. The number \kbd{s} must be less than or
equal to the length of~\kbd{x}.

\fun{void}{setsigne}{GEN x, long s} sets the sign of~\kbd{x} to~\kbd{s}.
If \kbd{x} is a \typ{INT} or \typ{REAL}, \kbd{s} must be equal to $-1$, 0
or~1, and if \kbd{x} is a \typ{POL} or \typ{SER}, \kbd{s} must be equal to 0
or~1. No sanity check is made; in particular, setting the sign of a
$0$ \typ{INT} to $\pm1$ creates an invalid object.

\fun{void}{togglesign}{GEN x} sets the sign $s$ of~\kbd{x} to $-s$, in place.

\fun{void}{togglesign_safe}{GEN *x} sets the $s$ sign of~\kbd{*x} to $-s$, in
place, unless \kbd{*x} is one of the integer universal constants in which case
replace \kbd{*x} by its negation (e.g.~replace \kbd{gen\_1} by \kbd{gen\_m1}).

\fun{void}{setabssign}{GEN x} sets the sign $s$ of~\kbd{x} to $|s|$, in place.

\fun{void}{affectsign}{GEN x, GEN y} shortcut for \kbd{setsigne(y, signe(x))}.
No sanity check is made; in particular, setting the sign of a
$0$ \typ{INT} to $\pm1$ creates an invalid object.

\fun{void}{affectsign_safe}{GEN x, GEN *y} sets the sign of~\kbd{*y} to that
of~\kbd{x}, in place, unless \kbd{*y} is one of the integer universal
constants in which case replace \kbd{*y} by its negation if needed
(e.g.~replace \kbd{gen\_1} by \kbd{gen\_m1} if \kbd{x} is negative). No other
sanity check is made; in particular, setting the sign of a $0$
\typ{INT} to $\pm1$ creates an invalid object.

\fun{void}{normalize_frac}{GEN z} assuming $z$ is of the form \kbd{mkfrac(a,b)}
with $b\neq 0$, make sure that $b > 0$ by changing the sign of $a$ in place if
needed (use \kbd{togglesign}).

\fun{void}{setexpo}{GEN x, long s} sets the binary exponent of the
\typ{REAL}~\kbd{x} to \kbd{s}. The value \kbd{s} must be a 24-bit signed
number.

\fun{void}{setvalp}{GEN x, long s} sets the $p$-adic or $X$-adic valuation
of~\kbd{x} to~\kbd{s}, if \kbd{x} is a \typ{PADIC} or a \typ{SER},
respectively.

\fun{void}{setprecp}{GEN x, long s} sets the $p$-adic precision of the
\typ{PADIC}~\kbd{x} to~\kbd{s}.

\fun{void}{setvarn}{GEN x, long s} sets the variable number of the \typ{POL}
or \typ{SER}~\kbd{x} to~\kbd{s} (where $0\le \kbd{s}\le\kbd{MAXVARN}$).

\subsec{Type groups}\label{se:typegroup}
In the following functions, \kbd{t} denotes the type of a \kbd{GEN}.
They used to be implemented as macros, which could evaluate their argument
twice; \emph{no longer}: it is not inefficient to write
\bprog
  is_intreal_t(typ(x))
@eprog

\fun{int}{is_recursive_t}{long t} \kbd{true} iff \kbd{t} is a recursive
type (the non-recursive types are \typ{INT}, \typ{REAL},
\typ{STR}, \typ{VECSMALL}). Somewhat contrary to intuition, \typ{LIST} is
also non-recursive, ; see the Developer's guide for details.

\fun{int}{is_intreal_t}{long t} \kbd{true} iff \kbd{t} is \typ{INT}
or \typ{REAL}.

\fun{int}{is_rational_t}{long t} \kbd{true} iff \kbd{t} is \typ{INT}
or \typ{FRAC}.

\fun{int}{is_real_t}{long t} \kbd{true} iff \kbd{t} is \typ{INT}
or \typ{REAL} or \typ{FRAC}.

\fun{int}{is_vec_t}{long t} \kbd{true} iff \kbd{t} is \typ{VEC}
or \typ{COL}.

\fun{int}{is_matvec_t}{long t} \kbd{true} iff \kbd{t} is \typ{MAT}, \typ{VEC}
or \typ{COL}.

\fun{int}{is_scalar_t}{long t} \kbd{true} iff \kbd{t} is a scalar, i.e
a \typ{INT},
a \typ{REAL},
a \typ{INTMOD},
a \typ{FRAC},
a \typ{COMPLEX},
a \typ{PADIC},
a \typ{QUAD},
or
a \typ{POLMOD}.

\fun{int}{is_extscalar_t}{long t} \kbd{true} iff \kbd{t} is a scalar (see
\kbd{is\_scalar\_t}) or \kbd{t} is \typ{POL}.

\fun{int}{is_const_t}{long t} \kbd{true} iff \kbd{t} is a scalar which is not
\typ{POLMOD}.

\fun{int}{is_noncalc_t}{long t} true if generic operations (\kbd{gadd},
\kbd{gmul}) do not make sense for $t$: corresponds to types
\typ{LIST}, \typ{STR}, \typ{VECSMALL}, \typ{CLOSURE}

\subsec{Accessors and components}\label{se:accessors}
The first two functions return \kbd{GEN} components as copies on the stack:

\fun{GEN}{compo}{GEN x, long n} creates a copy of the \kbd{n}-th true
component (i.e.\ not counting the codewords) of the object~\kbd{x}.

\fun{GEN}{truecoeff}{GEN x, long n} creates a copy of the coefficient of
degree~\kbd{n} of~\kbd{x} if \kbd{x} is a scalar, \typ{POL} or \typ{SER},
and otherwise of the \kbd{n}-th component of~\kbd{x}.
\smallskip

\noindent On the contrary, the following routines return the address of a
\kbd{GEN} component. No copy is made on the stack:

\fun{GEN}{constant_coeff}{GEN x} returns the address of the constant
coefficient of \typ{POL}~\kbd{x}. By convention, a $0$ polynomial (whose
\kbd{sign} is $0$) has \kbd{gen\_0} constant term.

\fun{GEN}{leading_coeff}{GEN x} returns the address of the leading coefficient
of \typ{POL}~\kbd{x}, i.e. the coefficient of largest index stored in the
array representing $x$. This may be an inexact $0$. By convention, return
\kbd{gen\_0} if the coefficient array is empty.

\fun{GEN}{gel}{GEN x, long i} returns the address of the
\kbd{x[i]} entry of~\kbd{x}. (\kbd{el} stands for element.)

\fun{GEN}{gcoeff}{GEN x, long i, long j} returns the address of the
\kbd{x[i,j]} entry of \typ{MAT}~\kbd{x}, i.e.~the coefficient at row~\kbd{i}
and column~\kbd{j}.

\fun{GEN}{gmael}{GEN x, long i, long j} returns the address of the
\kbd{x[i][j]} entry of~\kbd{x}. (\kbd{mael} stands for multidimensional array
element.)

\fun{GEN}{gmael2}{GEN A, long x1, long x2} is an alias for \kbd{gmael}.
Similar macros \tet{gmael3}, \tet{gmael4}, \tet{gmael5} are available.

\section{Global numerical constants}
These are defined in the various public PARI headers.

\subsec{Constants related to word size}

\noindent \kbd{long} $\tet{BITS_IN_LONG} = 2^{\tet{TWOPOTBITS_IN_LONG}}$:
number of bits in a \kbd{long} (32 or 64).

\noindent \kbd{long} \tet{BITS_IN_HALFULONG}: \kbd{BITS\_IN\_LONG} divided by
$2$.

\noindent \kbd{long} \tet{LONG_MAX}: the largest positive \kbd{long}.

\noindent \kbd{ulong} \tet{ULONG_MAX}: the largest \kbd{ulong}.

\noindent \kbd{long} \tet{DEFAULTPREC}:    the length (\kbd{lg}) of a
\typ{REAL} with 64 bits of accuracy

\noindent \kbd{long} \tet{MEDDEFAULTPREC}: the length (\kbd{lg}) of a
\typ{REAL} with 128 bits of accuracy

\noindent \kbd{long} \tet{BIGDEFAULTPREC}: the length (\kbd{lg}) of a
\typ{REAL} with 192 bits of accuracy

\noindent \kbd{ulong} \tet{HIGHBIT}: the largest power of $2$ fitting in an
\kbd{ulong}.

\noindent \kbd{ulong} \tet{LOWMASK}: bitmask yielding the least significant
bits.

\noindent \kbd{ulong} \tet{HIGHMASK}: bitmask yielding the most significant
bits.

\noindent The last two are used to implement the following convenience macros,
returning half the bits of their operand:

\fun{ulong}{LOWWORD}{ulong a} returns least significant bits.

\fun{ulong}{HIGHWORD}{ulong a} returns most significant bits.

\noindent Finally

\fun{long}{divsBIL}{long n} returns the Euclidean quotient of $n$ by
\kbd{BITS\_IN\_LONG} (with non-negative remainder).

\fun{long}{remsBIL}{n} returns the (non-negative) Euclidean remainder of $n$
by \kbd{BITS\_IN\_LONG}

\fun{long}{dvmdsBIL}{long n, long *r}

\fun{ulong}{dvmduBIL}{ulong n, ulong *r} sets $r$ to \kbd{remsBIL(n)}
and returns \kbd{divsBIL(n)}.

\subsec{Masks used to implement the \kbd{GEN} type}

These constants are used by higher level macros, like \kbd{typ} or \kbd{lg}:

\noindent \tet{EXPOnumBITS},
\tet{LGnumBITS},
\tet{SIGNnumBITS},
\tet{TYPnumBITS},
\tet{VALPnumBITS},
\tet{VARNnumBITS}:
number of bits used to encode \kbd{expo}, \kbd{lg}, \kbd{signe},
\kbd{typ}, \kbd{valp}, \kbd{varn}.

\noindent \tet{PRECPSHIFT},
\tet{SIGNSHIFT},
\tet{TYPSHIFT},
\tet{VARNSHIFT}: shifts used to recover or encode \kbd{precp}, \kbd{varn},
\kbd{typ}, \kbd{signe}

\noindent \tet{CLONEBIT},
\tet{EXPOBITS},
\tet{LGBITS},
\tet{PRECPBITS},
\tet{SIGNBITS},
\tet{TYPBITS},
\tet{VALPBITS},
\tet{VARNBITS}: bitmasks used to extract \kbd{isclone}, \kbd{expo}, \kbd{lg},
\kbd{precp}, \kbd{signe}, \kbd{typ}, \kbd{valp}, \kbd{varn} from \kbd{GEN}
codewords.

\noindent \tet{MAXVARN}: the largest possible variable number.

\noindent \tet{NO_VARIABLE}:  sentinel returned by \kbd{gvar(x)} when \kbd{x}
does not contain any polynomial; has a lower priority than any valid variable
number.

\noindent \tet{HIGHEXPOBIT}: a power of $2$, one more that the largest possible
exponent for a \typ{REAL}.

\noindent \tet{HIGHVALPBIT}: a power of $2$, one more that the largest possible
valuation for a \typ{PADIC} or a \typ{SER}.

\subsec{$\log 2$, $\pi$}

These are \kbd{double} approximations to useful constants:

\noindent \tet{LOG2}: $\log 2$.

\noindent \tet{LOG10_2}: $\log 2 / \log 10$.

\noindent \tet{LOG2_10}: $\log 10 / \log 2$.

\noindent \tet{M_PI}: $\pi$.

\section{Iterating over small primes, low-level interface}
\label{se:primetable}

One of the methods used by the high-level prime iterator (see
\secref{se:primeiter}), is a precomputed table. Its direct use is deprecated,
but documented here.

After \kbd{pari\_init(size, maxprime)}, a ``prime table'' is
initialized with the successive \emph{differences} of primes up to (possibly
just a little beyond) \kbd{maxprime}. The prime table occupies roughly
$\kbd{maxprime}/\log(\kbd{maxprime})$ bytes in memory, so be sensible when
choosing \kbd{maxprime}; it is $500000$ by default under \kbd{gp} and there
is no real benefit in choosing a much larger value: the high-level
iterator provide \emph{fast} access to primes up to the \emph{square}
of \kbd{maxprime}. In any case, the implementation requires that
$\tet{maxprime} < 2^{\B} - 2048$, whatever memory is available.

PARI currently guarantees that the first 6547 primes, up to and including
65557, are present in the table, even if you set \kbd{maxprime} to zero.
in the \kbd{pari\_init} call.

\noindent Some convenience functions:

\fun{ulong}{maxprime}{} the largest prime computable using our prime table.

\fun{void}{maxprime_check}{ulong B} raise an error if \kbd{maxprime()} is $< B$.

After the following initializations (the names $p$ and \var{ptr} are
arbitrary of course)
\bprog
byteptr ptr = diffptr;
ulong p = 0;
@eprog
\noindent calling the macro \tet{NEXT_PRIME_VIADIFF_CHECK}$(p, \var{ptr})$
repeatedly will assign the successive prime numbers to $p$. Overrunning the
prime table boundary will raise the error \tet{e_MAXPRIME}, which just
prints the error message:

\kbd{*** not enough precomputed primes, need primelimit \til $c$}

\noindent (for some numerical value $c$), then the macro aborts the
computation. The alternative macro \tet{NEXT_PRIME_VIADIFF} operates in the
same way, but will omit that check, and is slightly faster. It should be used
in the following way:
%
\bprog
byteptr ptr = diffptr;
ulong p = 0;

if (maxprime() < goal) pari_err_MAXPRIME(goal); /*@Ccom not enough primes */
while (p <= goal) /*@Ccom run through all primes up to \kbd{goal} */
{
  NEXT_PRIME_VIADIFF(p, ptr);
  ...
}
@eprog\noindent
Here, we use the general error handling function \kbd{pari\_err} (see
\secref{se:err}), with the codeword \kbd{e\_MAXPRIME}, raising the ``not enough
primes'' error. This could be rewritten as
\bprog
maxprime_check(goal);
while (p <= goal) /*@Ccom run through all primes up to \kbd{goal} */
{
  NEXT_PRIME_VIADIFF(p, ptr);
  ...
}
@eprog

\fun{bytepr}{initprimes}{ulong maxprime, long *L, ulong *lastp}
computes a (malloc'ed) ``prime table'', in fact a table of all prime
differences for $p < \kbd{maxprime}$ (and possibly a little beyond). Set $L$
to the table length (argument to \kbd{malloc}), and \var{lastp} to the last
prime in the table.

\fun{void}{initprimetable}{ulong maxprime} computes a prime table (of all prime
differences for $p < \kbd{maxprime}$) and assign it to the global variable
\kbd{diffptr}. Don't change \kbd{diffptr} directly, call this function
instead. This calls \kbd{initprimes} and updates internal data recording the
table size.

\fun{ulong}{init_primepointer_geq}{ulong a, byteptr *pd}
returns the smallest prime $p \geq a$, and sets \kbd{*pd} to the proper offset
of \kbd{diffptr} so that \kbd{NEXT\_PRIME\_VIADIFF(p, *pd)} correctly
returns \kbd{unextprime(p + 1)}.

\fun{ulong}{init_primepointer_gt}{ulong a, byteptr *pd} returns the smallest
prime $p > a$.

\fun{ulong}{init_primepointer_leq}{ulong a, byteptr *pd} returns the largest
prime $p \leq a$.

\fun{ulong}{init_primepointer_lt}{ulong a, byteptr *pd} returns the largest
prime $p < a$.

\section{Handling the PARI stack}

\subsec{Allocating memory on the stack}

\fun{GEN}{cgetg}{long n, long t} allocates memory on the stack for
an object of length \kbd{n} and type~\kbd{t}, and initializes its first
codeword.

\fun{GEN}{cgeti}{long n} allocates memory on the stack for a \typ{INT}
of length~\kbd{n}, and initializes its first codeword. Identical to
\kbd{cgetg(n,\typ{INT})}.

\fun{GEN}{cgetr}{long n} allocates memory on the stack for a \typ{REAL}
of length~\kbd{n}, and initializes its first codeword. Identical to
\kbd{cgetg(n,\typ{REAL})}.

\fun{GEN}{cgetc}{long n} allocates memory on the stack for a
\typ{COMPLEX}, whose real and imaginary parts are \typ{REAL}s
of length~\kbd{n}.

\fun{GEN}{cgetp}{GEN x} creates space sufficient to hold the
\typ{PADIC}~\kbd{x}, and sets the prime $p$ and the $p$-adic precision to
those of~\kbd{x}, but does not copy (the $p$-adic unit or zero representative
and the modulus of)~\kbd{x}.

\fun{GEN}{new_chunk}{size_t n} allocates a \kbd{GEN} with $n$ components,
\emph{without} filling the required code words. This is the low-level
constructor underlying \kbd{cgetg}, which calls \kbd{new\_chunk} then sets
the first code word. It works by simply returning the address
\kbd{((GEN)avma) - n}, after checking that it is larger than \kbd{(GEN)bot}.

\fun{void}{new_chunk_resize}{size_t x} this function is called by
\kbd{new\_chunk} when the PARI stack overflows. There is no need to call it
manually. It will either extend the stack or report an \kbd{e\_STACK} error.

\fun{char*}{stack_malloc}{size_t n} allocates memory on the stack for $n$
chars (\emph{not} $n$ \kbd{GEN}s). This is faster than using \kbd{malloc},
and easier to use in most situations when temporary storage is needed. In
particular there is no need to \kbd{free} individually all variables thus
allocated: a simple \kbd{avma = oldavma} might be enough. On the other hand,
beware that this is not permanent independent storage, but part of the stack.

\fun{char*}{stack_calloc}{size_t n} as \kbd{stack\_malloc}, setting the memory
to zero.

\noindent Objects allocated through these last three functions cannot be
\kbd{gerepile}'d, since they are not yet valid \kbd{GEN}s: their codewords
must be filled first.

\fun{GEN}{cgetalloc}{long t, size_t l}, same as \kbd{cgetg(t, l)}, except
that the result is allocated using \tet{pari_malloc} instead of the PARI
stack. The resulting \kbd{GEN} is now impervious to garbage collecting
routines, but should be freed using \tet{pari_free}.

\subsec{Stack-independent binary objects}

\fun{GENbin*}{copy_bin}{GEN x} copies $x$ into a malloc'ed structure suitable
for stack-independent binary transmission or storage. The object obtained
is architecture independent provided, \kbd{sizeof(long)} remains the same
on all PARI instances involved, as well as the multiprecision kernel (either
native or GMP).

\fun{GENbin*}{copy_bin_canon}{GEN x} as \kbd{copy\_bin}, ensuring furthermore
that the binary object is independent of the multiprecision kernel. Slower
than \kbd{copy\_bin}.

\fun{GEN}{bin_copy}{GENbin *p} assuming $p$ was created by \kbd{copy\_bin(x)}
(not necessarily by the same PARI instance: transmission or external storage
may be involved), restores $x$ on the PARI stack.

\noindent The routine \kbd{bin\_copy} transparently encapsulate the following
functions:

\fun{GEN}{GENbinbase}{GENbin *p} the \kbd{GEN} data actually stored in $p$.
All addresses are stored as offsets with respect to a common reference point,
so the resulting \kbd{GEN} is unusable unless it is a non-recursive type;
private low-level routines must be called first to restore absolute addresses.

\fun{void}{shiftaddress}{GEN x, long dec} converts relative addresses to
absolute ones.

\fun{void}{shiftaddress_canon}{GEN x, long dec} converts relative addresses to
absolute ones, and converts leaves from a canonical form to the one
specific to the multiprecision kernel in use. The \kbd{GENbin} type stores
whether leaves are stored in canonical form, so \kbd{bin\_copy} can call
the right variant.

\noindent Objects containing closures are harder to e.g. copy and save to disk,
since closures contain pointers to libpari functions that will not be valid in
another gp instance: there is little chance for them to be loaded at the exact
same address in memory. Such objects must be saved along with a linking table.

\fun{GEN}{copybin_unlink}{GEN C} returns a linking table allowing to safely
store and transmit \typ{CLOSURE} objects in $C$.  If $C = \kbd{NULL}$ return a
linking table corresponding to the content of all gp variables. $C$ may then be
dumped to disk in binary form, for instance.

\fun{void}{bincopy_relink}{GEN C, GEN V} given a binary object $C$, as dumped
by writebin and read back into a session, and a linking table $V$, restore all
closures contained in $C$ (function pointers are translated to their current
value).

\subsec{Garbage collection}
See \secref{se:garbage} for a detailed explanation and many examples.

\fun{void}{cgiv}{GEN x} frees object \kbd{x}, assuming it is the last created
on the stack.

\fun{GEN}{gerepile}{pari_sp p, pari_sp q, GEN x} general garbage collector
for the stack.

\fun{void}{gerepileall}{pari_sp av, int n, ...} cleans up the stack from
\kbd{av} on (i.e from \kbd{avma} to \kbd{av}), preserving the \kbd{n} objects
which follow in the argument list (of type \kbd{GEN*}). For instance,
\kbd{gerepileall(av, 2, \&x, \&y)} preserves \kbd{x} and \kbd{y}.

\fun{void}{gerepileallsp}{pari_sp av, pari_sp ltop, int n, ...}
cleans up the stack between \kbd{av} and \kbd{ltop}, updating
the \kbd{n} elements which follow \kbd{n} in the argument list (of type
\kbd{GEN*}). Check that the elements of \kbd{g} have no component between
\kbd{av} and \kbd{ltop}, and assumes that no garbage is present between
\kbd{avma} and \kbd{ltop}. Analogous to (but faster than) \kbd{gerepileall}
otherwise.

\fun{GEN}{gerepilecopy}{pari_sp av, GEN x} cleans up the stack  from
\kbd{av} on, preserving the object \kbd{x}. Special case of \kbd{gerepileall}
(case $\kbd{n} = 1$), except that the routine returns the preserved \kbd{GEN}
instead of updating its address through a pointer.

\fun{void}{gerepilemany}{pari_sp av, GEN* g[], int n} alternative interface
to \kbd{gerepileall}. The preserved \kbd{GEN}s are the elements of the array
\kbd{g} of length $n$: \kbd{g[0]}, \kbd{g[1]}, \dots,
\kbd{g[$n$-1]}. Obsolete: no more efficient than \kbd{gerepileall},
error-prone, and clumsy (need to declare an extra \kbd{GEN *g}).

\fun{void}{gerepilemanysp}{pari_sp av, pari_sp ltop, GEN* g[], int n}
alternative interface to \kbd{gerepileallsp}. Obsolete.

\fun{void}{gerepilecoeffs}{pari_sp av, GEN x, int n} cleans up the stack
from \kbd{av} on, preserving \kbd{x[0]}, \dots, \kbd{x[n-1]} (which are
\kbd{GEN}s).

\fun{void}{gerepilecoeffssp}{pari_sp av, pari_sp ltop, GEN x, int n}
cleans up the stack from \kbd{av} to \kbd{ltop}, preserving \kbd{x[0]},
\dots, \kbd{x[n-1]} (which are \kbd{GEN}s). Same assumptions as in
\kbd{gerepilemanysp}, of which this is a variant. For instance
\bprog
  z = cgetg(3, t_COMPLEX);
  av = avma; garbage(); ltop = avma;
  z[1] = fun1();
  z[2] = fun2();
  gerepilecoeffssp(av, ltop, z + 1, 2);
  return z;
@eprog\noindent
cleans up the garbage between \kbd{av} and \kbd{ltop}, and connects \kbd{z}
and its two components. This is marginally more efficient than the standard
\bprog
  av = avma; garbage(); ltop = avma;
  z = cgetg(3, t_COMPLEX);
  z[1] = fun1();
  z[2] = fun2(); return gerepile(av, ltop, z);
@eprog\noindent

\fun{GEN}{gerepileupto}{pari_sp av, GEN q} analogous to (but faster than)
\kbd{gerepilecopy}. Assumes that \kbd{q} is connected and that its root was
created before any component. If \kbd{q} is not on the stack, this is
equivalent to \kbd{avma = av}; in particular, sentinels which are not even
proper \kbd{GEN}s such as \kbd{q = NULL} are allowed.

\fun{GEN}{gerepileuptoint}{pari_sp av, GEN q} analogous to (but faster than)
\kbd{gerepileupto}. Assumes further that \kbd{q} is a \typ{INT}. The
length and effective length of the resulting \typ{INT} are equal.

\fun{GEN}{gerepileuptoleaf}{pari_sp av, GEN q} analogous to (but faster than)
\kbd{gerepileupto}. Assumes further that \kbd{q} is a leaf, i.e a
non-recursive type (\kbd{is\_recursive\_t(typ(q))} is non-zero). Contrary to
\kbd{gerepileuptoint} and \kbd{gerepileupto}, \kbd{gerepileuptoleaf} leaves
length and effective length of a \typ{INT} unchanged.

\subsec{Garbage collection: advanced use}

\fun{void}{stackdummy}{pari_sp av, pari_sp ltop} inhibits the memory area
between \kbd{av} \emph{included} and \kbd{ltop} \emph{excluded} with respect to
\kbd{gerepile}, in order to avoid a call to \kbd{gerepile(av, ltop,...)}.
The stack space is not reclaimed though.

More precisely, this routine assumes that \kbd{av} is recorded earlier
than \kbd{ltop}, then marks the specified stack segment as a
non-recursive type of the correct length. Thus gerepile will not inspect
the zone, at most copy it. To be used in the following situation:
\bprog
  av0 = avma; z = cgetg(t_VEC, 3);
  gel(z,1) = HUGE(); av = avma; garbage(); ltop = avma;
  gel(z,2) = HUGE(); stackdummy(av, ltop);
@eprog\noindent
Compared to the orthodox
\bprog
  gel(z,2) = gerepile(av, ltop, gel(z,2));
@eprog\noindent
or even more wasteful
\bprog
  z = gerepilecopy(av0, z);
@eprog\noindent
we temporarily lose $(\kbd{av} - \kbd{ltop})$ words but save a costly
\kbd{gerepile}. In principle, a garbage collection higher up the call
chain should reclaim this later anyway.

Without the \kbd{stackdummy}, if the $[\kbd{av}, \kbd{ltop}]$ zone is
arbitrary (not even valid \kbd{GEN}s as could happen after direct
truncation via \kbd{setlg}), we would leave dangerous data in the middle
of~\kbd{z}, which would be a problem for a later
\bprog
  gerepile(..., ... , z);
@eprog\noindent
And even if it were made of valid \kbd{GEN}s, inhibiting the area makes sure
\kbd{gerepile} will not inspect their components, saving time.

Another natural use in low-level routines is to ``shorten'' an existing
\kbd{GEN} \kbd{z} to its first $\kbd{n}-1$ components:
\bprog
  setlg(z, n);
  stackdummy((pari_sp)(z + lg(z)), (pari_sp)(z + n));
@eprog\noindent
or to its last \kbd{n} components:
\bprog
  long L = lg(z) - n, tz = typ(z);
  stackdummy((pari_sp)(z + L), (pari_sp)z);
  z += L; z[0] = evaltyp(tz) | evallg(L);
@eprog

The first scenario (safe shortening an existing \kbd{GEN}) is in fact so
common, that we provide a function for this:

\fun{void}{fixlg}{GEN z, long ly} a safe variant of \kbd{setlg(z, ly)}. If
\kbd{ly} is larger than \kbd{lg(z)} do nothing. Otherwise, shorten $z$ in
place, using \kbd{stackdummy} to avoid later \kbd{gerepile} problems.

\fun{GEN}{gcopy_avma}{GEN x, pari_sp *AVMA} return a copy of $x$ as from
\kbd{gcopy}, except that we pretend that initially \kbd{avma} is \kbd{*AVMA},
and that \kbd{*AVMA} is updated accordingly (so that the total size of $x$ is
the difference between the two successive values of \kbd{*AVMA}). It is not
necessary for \kbd{*AVMA} to initially point on the stack: \tet{gclone} is
implemented using this mechanism.

\fun{GEN}{icopy_avma}{GEN x, pari_sp av} analogous to \kbd{gcopy\_avma} but
simpler: assume $x$ is a \typ{INT} and return a copy allocated as if
initially we had \kbd{avma} equal to \kbd{av}. There is no need to pass a
pointer and update the value of the second argument: the new (fictitious)
\kbd{avma} is just the return value (typecast to \kbd{pari\_sp}).

\subsec{Debugging the PARI stack}

\fun{int}{chk_gerepileupto}{GEN x} returns 1 if \kbd{x} is suitable for
\kbd{gerepileupto}, and 0 otherwise. In the latter case, print a warning
explaining the problem.

\fun{void}{dbg_gerepile}{pari_sp ltop} outputs the list of all objects on the
stack between \kbd{avma} and \kbd{ltop}, i.e. the ones that would be inspected
in a call to \kbd{gerepile(...,ltop,...)}.

\fun{void}{dbg_gerepileupto}{GEN q} outputs the list of all objects on the
stack that would be inspected in a call to \kbd{gerepileupto(...,q)}.

\subsec{Copies}

\fun{GEN}{gcopy}{GEN x} creates a new copy of $x$ on the stack.

\fun{GEN}{gcopy_lg}{GEN x, long l} creates a new copy of $x$
on the stack, pretending that \kbd{lg(x)} is $l$, which must be less than or
equal to \kbd{lg(x)}. If equal, the function is equivalent to \kbd{gcopy(x)}.

\fun{int}{isonstack}{GEN x} \kbd{true} iff $x$ belongs to the stack.

\fun{void}{copyifstack}{GEN x, GEN y} sets \kbd{y = gcopy(x)} if
$x$ belongs to the stack, and \kbd{y = x} otherwise. This macro evaluates
its arguments once, contrary to
\bprog
  y = isonstack(x)? gcopy(x): x;
@eprog

\fun{void}{icopyifstack}{GEN x, GEN y} as \kbd{copyifstack} assuming \kbd{x}
is a \typ{INT}.

\subsec{Simplify}

\fun{GEN}{simplify}{GEN x} you should not need that function in library mode.
One rather uses:

\fun{GEN}{simplify_shallow}{GEN x} shallow, faster, version of \tet{simplify}.

\section{The PARI heap}
\subsec{Introduction}

It is implemented as a doubly-linked list of \kbd{malloc}'ed blocks of
memory, equipped with reference counts. Each block has type \kbd{GEN} but need
not be a valid \kbd{GEN}: it is a chunk of data preceded by a hidden header
(meaning that we allocate $x$ and return $x + \kbd{header size}$). A
\tev{clone}, created by \tet{gclone}, is a block which is a valid \kbd{GEN}
and whose \emph{clone bit} is set.

\subsec{Public interface}

\fun{GEN}{newblock}{size_t n} allocates a block of $n$ \emph{words} (not bytes).

\fun{void}{killblock}{GEN x} deletes the block~$x$ created by \kbd{newblock}.
Fatal error if $x$ not a block.

\fun{GEN}{gclone}{GEN x} creates a new permanent copy of $x$ on the heap
(allocated using \kbd{newblock}). The \emph{clone bit} of the result is set.

\fun{GEN}{gcloneref}{GEN x} if $x$ is not a clone, clone it and return the
result; otherwise, increase the clone reference count and return $x$.

\fun{void}{gunclone}{GEN x} deletes a clone. Deletion at first only decreases
the reference count by $1$. If the count remains positive, no further action is
taken; if the count becomes zero, then the clone is actually deleted. In the
current implementation, this is an alias for \kbd{killblock}, but it is cleaner
to kill clones (valid \kbd{GEN}s) using this function, and other blocks using
\kbd{killblock}.

\fun{void}{gunclone_deep}{GEN x} is only useful in the context of the GP
interpreter which may replace arbitrary components of container types
(\typ{VEC}, \typ{COL}, \typ{MAT}, \typ{LIST}) by clones. If $x$ is such
a container, the function recursively deletes all clones among the components
of $x$, then unclones $x$. Useless in library mode: simply use
\kbd{gunclone}.

\fun{void}{traverseheap}{void(*f)(GEN, void *), void *data} this applies
\kbd{f($x$, data)} to each object $x$ on the PARI heap, most recent
first. Mostly for debugging purposes.

\fun{GEN}{getheap}{} a simple wrapper around \kbd{traverseheap}. Returns  a
two-component row vector giving the number of objects on the heap and the
amount of memory they occupy in long words.

\fun{GEN}{cgetg_block}{long x, long y} as \kbd{cgetg(x,y)}, creating the return
value as a \kbd{block}, not on the PARI stack.

\fun{GEN}{cgetr_block}{long prec} as \kbd{cgetr(prec)}, creating the return
value as a \kbd{block}, not on the PARI stack.

\subsec{Implementation note} The hidden block header is manipulated using the
following private functions:

\fun{void*}{bl_base}{GEN x} returns the pointer that was actually allocated
by \kbd{malloc} (can be freed).

\fun{long}{bl_refc}{GEN x} the reference count of $x$: the number of pointers
to this block. Decremented in \kbd{killblock}, incremented by the private
function \fun{void}{gclone_refc}{GEN x}; block is freed when the reference
count reaches $0$.

\fun{long}{bl_num}{GEN x} the index of this block in the list of all blocks
allocated so far (including freed blocks). Uniquely identifies a block until
$2^\B$ blocks have been allocated and this wraps around.

\fun{GEN}{bl_next}{GEN x} the block \emph{after} $x$ in the linked list of
blocks (\kbd{NULL} if $x$ is the last block allocated not yet killed).

\fun{GEN}{bl_prev}{GEN x} the block allocated \emph{before} $x$ (never
\kbd{NULL}).

We documented the last four routines as functions for clarity (and type
checking) but they are actually macros yielding valid lvalues. It is allowed
to write \kbd{bl\_refc(x)++} for instance.

\section{Handling user and temp variables}
Low-level implementation of user / temporary variables is liable to change. We
describe it nevertheless for completeness. Currently variables are
implemented by a single array of values divided in 3 zones: 0--\kbd{nvar}
(user variables), \kbd{max\_avail}--\kbd{MAXVARN} (temporary variables),
and \kbd{nvar+1}--\kbd{max\_avail-1} (pool of free variable numbers).

\subsec{Low-level}

\fun{void}{pari_var_init}{}: a small part of \kbd{pari\_init}. Resets
variable counters \kbd{nvar} and \kbd{max\_avail}, notwithstanding existing
variables! In effect, this even deletes \kbd{x}. Don't use it.

\fun{void}{pari_var_close}{void} attached destructor, called by
\kbd{pari\_close}.

\fun{long}{pari_var_next}{}: returns \kbd{nvar}, the number of the next user
variable we can create.

\fun{long}{pari_var_next_temp}{} returns \kbd{max\_avail}, the number of the
next temp variable we can create.

\fun{long}{pari_var_create}{entree *ep} low-level initialization of an
\kbd{EpVAR}. Return the attached (new) variable number.

\fun{GEN}{vars_sort_inplace}{GEN z} given a \typ{VECSMALL} $z$ of variable
numbers, sort $z$ in place according to variable priorities (highest priority
comes first).

\fun{GEN}{vars_to_RgXV}{GEN h} given a \typ{VECSMALL} $z$ of variable numbers,
return the \typ{VEC} of \kbd{pol\_x}$(z[i])$.

\subsec{User variables}

\fun{long}{fetch_user_var}{char *s} returns a user variable whose name
is \kbd{s}, creating it is needed (and using an existing variable otherwise).
Returns its variable number.

\fun{GEN}{fetch_var_value}{long v} returns a shallow copy of the
current value of the variable numbered $v$. Return \kbd{NULL} for a temporary
variable.

\fun{entree*}{is_entry}{const char *s} returns the \kbd{entree*} attached
to an identifier \kbd{s} (variable or function), from the interpreter
hashtables. Return \kbd{NULL} is the identifier is unknown.

\subsec{Temporary variables}

\fun{long}{fetch_var}{void} returns the number of a new temporary variable
(decreasing \kbd{max\_avail}).

\fun{long}{delete_var}{void} delete latest temp variable created and return
the number of previous one.

\fun{void}{name_var}{long n, char *s} rename temporary variable number
\kbd{n} to \kbd{s}; mostly useful for nicer printout. Error when trying to
rename a user variable.

\section{Adding functions to PARI}
\subsec{Nota Bene}
%
As mentioned in the \kbd{COPYING} file, modified versions of the PARI package
can be distributed under the conditions of the GNU General Public License. If
you do modify PARI, however, it is certainly for a good reason, and we
would like to know about it, so that everyone can benefit from your changes.
There is then a good chance that your improvements are incorporated into the
next release.

We classify changes to PARI into four rough classes, where changes of the
first three types are almost certain to be accepted. The first type includes
all improvements to the documentation, in a broad sense. This includes
correcting typos or inaccuracies of course, but also items which are not
really covered in this document, e.g.~if you happen to write a tutorial,
or pieces of code exemplifying fine points unduly omitted in the present
manual.

The second type is to expand or modify the configuration routines and skeleton
files (the \kbd{Configure} script and anything in the \kbd{config/}
subdirectory) so that compilation is possible (or easier, or more efficient)
on an operating system previously not catered for. This includes discovering
and removing idiosyncrasies in the code that would hinder its portability.

The third type is to modify existing (mathematical) code, either to correct
bugs, to add new functionality to existing functions, or to improve their
efficiency.

Finally the last type is to add new functions to PARI. We explain here how
to do this, so that in particular the new function can be called from \kbd{gp}.

\subsec{Coding guidelines}\label{se:coding_guidelines}
\noindent
Code your function in a file of its own, using as a guide other functions
in the PARI sources. One important thing to remember is to clean the stack
before exiting your main function, since otherwise successive calls to
the function clutters the stack with unnecessary garbage, and stack
overflow occurs sooner. Also, if it returns a \kbd{GEN} and you want it
to be accessible to \kbd{gp}, you have to make sure this \kbd{GEN} is
suitable for \kbd{gerepileupto} (see \secref{se:garbage}).

If error messages or warnings are to be generated in your function, use
\kbd{pari\_err} and \kbd{pari\_warn} respectively.
Recall that \kbd{pari\_err} does not return but ends with a \kbd{longjmp}
statement. As well, instead of explicit \kbd{printf}~/ \kbd{fprintf}
statements, use the following encapsulated variants:

\fun{void}{pari_putc}{char c}: write character \kbd{c} to the output stream.

\fun{void}{pari_puts}{char *s}: write \kbd{s} to the output stream.

\fun{void}{pari_printf}{const char *fmt, ...}: write following arguments to the
output stream, according to the conversion specifications in format \kbd{fmt}
(see \tet{printf}).

\fun{void}{err_printf}{const char *fmt, ...}: as \tet{pari_printf}, writing to
PARI's current error stream.

\fun{void}{err_flush}{void} flush error stream.

Declare all public functions in an appropriate header file, if you
want to access them from C. The other functions should be declared
\kbd{static} in your file.

Your function is now ready to be used in library mode after compilation and
creation of the library. If possible, compile it as a shared library (see
the \kbd{Makefile} coming with the \kbd{extgcd} example in the
distribution). It is however still inaccessible from \kbd{gp}.\smallskip

\subsec{GP prototypes, parser codes}
\label{se:gp.interface}
A \tev{GP prototype} is a character string describing all the GP parser needs
to know about the function prototype. It contains a sequence of the following
atoms:

\settabs\+\indent&\kbd{Dxxx}\quad&\cr

\noindent\item Return type: \kbd{GEN} by default (must be valid for
\kbd{gerepileupto}), otherwise the following can appear as the \emph{first}
char of the code string:
%
\+& \kbd{i} & return \kbd{int}\cr
\+& \kbd{l} & return \kbd{long}\cr
\+& \kbd{u} & return \kbd{ulong}\cr
\+& \kbd{v} & return \kbd{void}\cr
\+& \kbd{m} & return a \kbd{GEN} which is not \kbd{gerepile}-safe.\cr

The \kbd{m} code is used for member functions, to avoid unnecessary copies. A
copy opcode is generated by the compiler if the result needs to be kept safe
for later use.

\noindent\item Mandatory arguments, appearing in the same order as the
input arguments they describe:
%
\+& \kbd{G} & \kbd{GEN}\cr
\+& \kbd{\&}& \kbd{*GEN}\cr
\+& \kbd{L} & \kbd{long} (we implicitly typecast \kbd{int} to \kbd{long})\cr
\+& \kbd{U} & \kbd{ulong} \cr
\+& \kbd{V} & loop variable\cr
\+& \kbd{n} & variable, expects a \idx{variable number} (a \kbd{long}, not an
\kbd{*entree})\cr
\+& \kbd{W} & a \kbd{GEN} which is a lvalue to be modified in place
(for \typ{LIST})\cr
\+& \kbd{r} & raw input (treated as a string without quotes). Quoted
 args are copied as strings\cr
\+&&\quad Stops at first unquoted \kbd{')'} or \kbd{','}. Special chars can
be quoted using \kbd{'\bs'}\cr
\+&&\quad Example: \kbd{aa"b\bs n)"c} yields the string \kbd{"aab\bs{n})c"}\cr
\+& \kbd{s} & expanded string. Example: \kbd{Pi"x"2} yields \kbd{"3.142x2"}\cr
\+&&\quad Unquoted components can be of any PARI type, converted to string
          following\cr
\+&&\quad current output format\cr
\+& \kbd{I} & closure whose value is ignored, as in \kbd{for} loops,\cr
\+&&\quad to be processed by \fun{void}{closure_evalvoid}{GEN C}\cr
\+& \kbd{E} & closure whose value is used, as in \kbd{sum} loops,\cr
\+&&\quad to be processed by \fun{void}{closure_evalgen}{GEN C}\cr
\+& \kbd{J} & implicit function of arity $1$, as in \kbd{parsum} loops,\cr
\+&&\quad to be processed by \fun{void}{closure_callgen1}{GEN C}\cr

\noindent A \tev{closure} is a GP function in compiled (bytecode) form. It
can be efficiently evaluated using the \kbd{closure\_eval}$xxx$ functions.

\noindent\item Automatic arguments:
%
\+& \kbd{f} &  Fake \kbd{*long}. C function requires a pointer but we
do not use the resulting \kbd{long}\cr
\+& \kbd{b} &  current real precision in bits \cr
\+& \kbd{p} &  current real precision in words \cr
\+& \kbd{P} &  series precision (default \kbd{seriesprecision},
 global variable \kbd{precdl} for the library)\cr
\+& \kbd{C} &  lexical context (internal, for \kbd{eval},
               see \kbd{localvars\_read\_str})\cr

\noindent\item Syntax requirements, used by functions like
 \kbd{for}, \kbd{sum}, etc.:
%
\+& \kbd{=} & separator \kbd{=} required at this point (between two
arguments)\cr

\noindent\item Optional arguments and default values:
%
\+& \kbd{E*} & any number of expressions, possibly 0 (see \kbd{E})\cr
\+& \kbd{s*} & any number of strings, possibly 0 (see \kbd{s})\cr
\+& \kbd{D\var{xxx}} &  argument can be omitted and has a default value\cr

The \kbd{E*} code reads all remaining arguments in closure context and passes
them as a single \typ{VEC}.
The \kbd{s*} code reads all remaining arguments in \tev{string context} and
passes the list of strings as a single \typ{VEC}. The automatic concatenation
rules in string context are implemented so that adjacent strings
are read as different arguments, as if they had been comma-separated. For
instance, if the remaining argument sequence is: \kbd{"xx" 1, "yy"}, the
\kbd{s*} atom sends \kbd{[a, b, c]}, where
$a$, $b$, $c$ are \kbd{GEN}s of type \typ{STR} (content \kbd{"xx"}),
\typ{INT} (equal to $1$) and \typ{STR} (content \kbd{"yy"}).

The format to indicate a default value (atom starts with a \kbd{D}) is
``\kbd{D\var{value},\var{type},}'', where \var{type} is the code for any
mandatory atom (previous group), \var{value} is any valid GP expression
which is converted according to \var{type}, and the ending comma is
mandatory. For instance \kbd{D0,L,} stands for ``this optional argument is
converted to a \kbd{long}, and is \kbd{0} by default''. So if the
user-given argument reads \kbd{1 + 3} at this point, \kbd{4L} is sent to
the function; and \kbd{0L} if the argument is omitted. The following
special notations are available:

\settabs\+\indent\indent&\kbd{Dxxx}\quad& optional \kbd{*GEN},&\cr
\+&\kbd{DG}& optional \kbd{GEN}, & send \kbd{NULL} if argument omitted.\cr

\+&\kbd{D\&}& optional \kbd{*GEN}, send \kbd{NULL} if argument omitted.\cr
\+&&\quad The argument must be prefixed by \kbd{\&}.\cr

\+&\kbd{DI}, \kbd{DE}& optional closure, send \kbd{NULL} if argument omitted.\cr

\+&\kbd{DP}& optional \kbd{long}, send \kbd{precdl} if argument omitted.\cr

\+&\kbd{DV}& optional \kbd{*entree}, send \kbd{NULL} if argument omitted.\cr

\+&\kbd{Dn}& optional variable number, $-1$ if omitted.\cr

\+&\kbd{Dr}& optional raw string, send \kbd{NULL} if argument omitted.\cr

\+&\kbd{Ds}& optional \kbd{char *}, send \kbd{NULL} if argument omitted.\cr

\misctitle{Hardcoded limit} C functions using more than 20 arguments are not
supported. Use vectors if you really need that many parameters.

When the function is called under \kbd{gp}, the prototype is scanned and each
time an atom corresponding to a mandatory argument is met, a user-given
argument is read (\kbd{gp} outputs an error message it the argument was
missing). Each time an optional atom is met, a default value is inserted if the
user omits the argument. The ``automatic'' atoms fill in the argument list
transparently, supplying the current value of the corresponding variable (or a
dummy pointer).

For instance, here is how you would code the following prototypes, which
do not involve default values:
\bprog
GEN f(GEN x, GEN y, long prec)   ----> "GGp"
void f(GEN x, GEN y, long prec)  ----> "vGGp"
void f(GEN x, long y, long prec) ----> "vGLp"
long f(GEN x)                    ----> "lG"
int f(long x)                    ----> "iL"
@eprog\noindent
If you want more examples, \kbd{gp} gives you easy access to the parser codes
attached to all GP functions: just type \kbd{\b{h} \var{function}}. You
can then compare with the C prototypes as they stand in \kbd{paridecl.h}.

\misctitle{Remark} If you need to implement complicated control statements
(probably for some improved summation functions), you need to know
how the parser implements closures and lexicals and how the evaluator lets
you deal with them, in particular the \tet{push_lex} and \tet{pop_lex}
functions. Check their descriptions and adapt the source code in
\kbd{language/sumiter.c} and \kbd{language/intnum.c}.

\subsec{Integration with \kbd{gp} as a shared module}

In this section we assume that your Operating System is supported by
\tet{install}. You have written a function in C following the guidelines is
\secref{se:coding_guidelines}; in case the function returns a \kbd{GEN}, it
must satisfy \kbd{gerepileupto} assumptions (see \secref{se:garbage}).

You then succeeded in building it as part of a shared library and want to
finally tell \kbd{gp} about your function. First, find a name for it. It does
not have to match the one used in library mode, but consistency is nice. It
has to be a valid GP identifier, i.e.~use only alphabetic characters, digits
and the underscore character (\kbd{\_}), the first character being
alphabetic.

Then figure out the correct \idx{parser code} corresponding to the function
prototype (as explained in~\secref{se:gp.interface}) and write a GP script
like the following:
\bprog
install(libname, code, gpname, library)
addhelp(gpname, "some help text")
@eprog
\noindent The \idx{addhelp} part is not mandatory, but very useful if you
want others to use your module. \kbd{libname} is how the function is named in
the library, usually the same name as one visible from C.

Read that file from your \kbd{gp} session, for instance from your
\idx{preferences file} (or \kbd{gprc}), and that's it. You
can now use the new function \var{gpname} under \kbd{gp}, and we would very
much like to hear about it!
\smallskip

\misctitle{Example}
A complete description could look like this:
\bprog
{
  install(bnfinit0, "GD0,L,DGp", ClassGroupInit, "libpari.so");
  addhelp(ClassGroupInit, "ClassGroupInit(P,{flag=0},{data=[]}):
    compute the necessary data for ...");
}
@eprog\noindent which means we have a function \kbd{ClassGroupInit} under
\kbd{gp}, which calls the library function \kbd{bnfinit0} . The function has
one mandatory argument, and possibly two more (two \kbd{'D'} in the code),
plus the current real precision. More precisely, the first argument is a
\kbd{GEN}, the second one is converted to a \kbd{long} using \kbd{itos}
(\kbd{0} is passed if it is omitted), and the third one is also a \kbd{GEN},
but we pass \kbd{NULL} if no argument was supplied by the user. This matches
the C prototype (from \kbd{paridecl.h}):
%
\bprog
  GEN bnfinit0(GEN P, long flag, GEN data, long prec)
@eprog\noindent
This function is in fact coded in \kbd{basemath/buch2.c}, and is in this case
completely identical to the GP function \kbd{bnfinit} but \kbd{gp} does not
need to know about this, only that it can be found somewhere in the shared
library \kbd{libpari.so}.

\misctitle{Important note} You see in this example that it is the
function's responsibility to correctly interpret its operands: \kbd{data =
NULL} is interpreted \emph{by the function} as an empty vector. Note that
since \kbd{NULL} is never a valid \kbd{GEN} pointer, this trick always
enables you to distinguish between a default value and actual input: the
user could explicitly supply an empty vector!

\subsec{Library interface for \kbd{install}}

There is a corresponding library interface for this \kbd{install}
functionality, letting you expand the GP parser/evaluator available in the
library with new functions from your C source code. Functions such as
\tet{gp_read_str} may then evaluate a GP expression sequence involving calls
to these new function!

\fun{entree *}{install}{void *f, const char *gpname, const char *code}

\noindent where \kbd{f} is the (address of the) function (cast to
\kbd{void*}), \kbd{gpname} is the name by which you want to access your
function from within your GP expressions, and \kbd{code} is as above.


\subsec{Integration by patching \kbd{gp}}

If \tet{install} is not available, and installing Linux or a BSD operating
system is not an option (why?), you have to hardcode your function in the
\kbd{gp} binary. Here is what needs to be done:

\item Fetch the complete sources of the PARI distribution.

\item Drop the function source code module in an appropriate directory
(a priori \kbd{src/modules}), and declare all public functions
in \kbd{src/headers/paridecl.h}.

\item Choose a help section and add a file
\kbd{src/functions/\var{section}/\var{gpname}}
containing the following, keeping the notation above:
\bprog
Function:  @com\var{gpname}
Section:   @com\var{section}
C-Name:    @com\var{libname}
Prototype: @com\var{code}
Help:      @com\var{some help text}
@eprog\noindent
(If the help text does not fit on a single line, continuation lines must
start by a whitespace character.) Two GP2C-related fields (\kbd{Description}
and \kbd{Wrapper}) are also available to improve the code GP2C generates when
compiling scripts involving your function. See the GP2C documentation for
details.

\item Launch \kbd{Configure}, which should pick up your C files and build an
appropriate \kbd{Makefile}. At this point you can recompile \kbd{gp}, which
will first rebuild the functions database.

\misctitle{Example} We reuse the \kbd{ClassGroupInit} / \kbd{bnfinit0}
from the preceding section. Since the C source code is already part
of PARI, we only need to add a file

 \kbd{functions/number\_fields/ClassGroupInit}

\noindent containing the following:
\bprog
Function: ClassGroupInit
Section: number_fields
C-Name: bnfinit0
Prototype: GD0,L,DGp
Help: ClassGroupInit(P,{flag=0},{tech=[]}): this routine does @com\dots
@eprog\noindent
and recompile \kbd{gp}.

\section{Globals related to PARI configuration}
\subsec{PARI version numbers}

\noindent \tet{paricfg_version_code} encodes in a single \kbd{long}, the Major
and minor version numbers as well as the patchlevel.

\fun{long}{PARI_VERSION}{long M, long m, long p} produces the version code
attached to release $M.m.p$. Each code identifies a unique PARI release,
and corresponds to the natural total order on the set of releases (bigger
code number means more recent release).

\noindent \tet{PARI_VERSION_SHIFT} is the number of bits used to store each of
the integers $M$, $m$, $p$ in the version code.

\noindent \tet{paricfg_vcsversion} is a version string related to the
revision control system used to handle your sources, if any. For instance
\kbd{git-}\emph{commit hash} if compiled from a git repository.

The two character strings \tet{paricfg_version} and \tet{paricfg_buildinfo},
correspond to the first two lines printed by \kbd{gp} just before the
Copyright message. The character string \tet{paricfg_compiledate} is the
date of compilation which appears on the next line. The character string
\tet{paricfg_mt_engine} is the name of the threading engine on the next line.

\fun{GEN}{pari_version}{} returns the version number as a PARI object, a
\typ{VEC} with three \typ{INT} and one \typ{STR} components.

\subsec{Miscellaneous}

\tet{paricfg_datadir}: character string. The location of PARI's \tet{datadir}.

\newpage
\chapter{Arithmetic kernel: Level 0 and 1}

\section{Level 0 kernel (operations on ulongs)}

\subsec{Micro-kernel}
The Level 0 kernel simulates basic operations of the 68020 processor on which
PARI was originally implemented. They need ``global'' \kbd{ulong} variables
\kbd{overflow} (which will contain only 0 or 1) and \kbd{hiremainder} to
function properly. A routine using one of these lowest-level functions
where the description mentions either \kbd{hiremainder} or \kbd{overflow}
must declare the corresponding
\bprog
  LOCAL_HIREMAINDER;  /* provides 'hiremainder' */
  LOCAL_OVERFLOW;     /* provides 'overflow' */
@eprog\noindent
in a declaration block. Variables \kbd{hiremainder} and \kbd{overflow} then
become available in the enclosing block. For instance a loop over the powers
of an \kbd{ulong}~\kbd{p} protected from overflows could read
\bprog
 while (pk < lim)
 {
   LOCAL_HIREMAINDER;
   ...
   pk = mulll(pk, p); if (hiremainder) break;
 }
@eprog\noindent
For most architectures, the functions mentioned below are really chunks of
inlined assembler code, and the above `global' variables are actually
local register values.

\fun{ulong}{addll}{ulong x, ulong y} adds \kbd{x} and \kbd{y}, returns the
lower \B\ bits and puts the carry bit into \kbd{overflow}.

\fun{ulong}{addllx}{ulong x, ulong y} adds \kbd{overflow} to the sum of the
\kbd{x} and \kbd{y}, returns the lower \B\ bits and puts the carry bit into
\kbd{overflow}.

\fun{ulong}{subll}{ulong x, ulong y} subtracts \kbd{x} and \kbd{y}, returns
the lower \B\ bits and put the carry (borrow) bit into \kbd{overflow}.

\fun{ulong}{subllx}{ulong x, ulong y} subtracts \kbd{overflow} from the
difference of \kbd{x} and \kbd{y}, returns the lower \B\ bits and puts the
carry (borrow) bit into \kbd{overflow}.

\fun{int}{bfffo}{ulong x} returns the number of leading zero bits in \kbd{x}.
That is, the number of bit positions by which it would have to be shifted
left until its leftmost bit first becomes equal to~1, which can be between 0
and $\B-1$ for nonzero \kbd{x}. When \kbd{x} is~0, the result is undefined.

\fun{ulong}{mulll}{ulong x, ulong y} multiplies \kbd{x} by \kbd{y}, returns
the lower \B\ bits and stores the high-order \B\ bits into \kbd{hiremainder}.

\fun{ulong}{addmul}{ulong x, ulong y} adds \kbd{hiremainder} to the product
of \kbd{x} and \kbd{y}, returns the lower \B\ bits and stores the high-order
\B\ bits into \kbd{hiremainder}.

\fun{ulong}{divll}{ulong x, ulong y} returns the quotient of
$  \left(\kbd{hiremainder} * 2^{\B}\right) + \kbd{x} $
by \kbd{y} and stores the remainder into \kbd{hiremainder}. An error occurs
if the quotient cannot be represented by an \kbd{ulong}, i.e.~if initially
$\kbd{hiremainder}\ge\kbd{y}$.

\misctitle{Obsolete routines} Those functions are awkward and no longer used;
they are only provided for backward compatibility:

\fun{ulong}{shiftl}{ulong x, ulong y} returns $x$ shifted left by $y$ bits,
i.e.~\kbd{$x$ << $y$}, where we assume that $0\leq y\leq\B$. The global variable
\kbd{hiremainder} receives the bits that were shifted out,
i.e.~\kbd{$x$ >> $(\B - y)$}.

\fun{ulong}{shiftlr}{ulong x, ulong y} returns $x$ shifted right by $y$ bits,
i.e.~\kbd{$x$ >> $y$}, where we assume that $0\leq y\leq\B$. The global variable
\kbd{hiremainder} receives the bits that were shifted out,
i.e.~\kbd{$x$ << $(\B - y)$}.

\subsec{Modular kernel}
The following routines are not part of the level 0 kernel per se, but
implement modular operations on words in terms of the above. They are written
so that no overflow may occur. Let $m \geq 1$ be the modulus; all operands
representing classes modulo $m$ are assumed to belong to $[0,m-1]$. The
result may be wrong for a number of reasons otherwise: it may not be reduced,
overflow can occur, etc.

\fun{int}{odd}{ulong x} returns 1 if $x$ is odd, and 0 otherwise.

\fun{int}{both_odd}{ulong x, ulong y} returns 1 if $x$ and $y$ are both odd,
and 0 otherwise.

\fun{ulong}{invmod2BIL}{ulong x} returns the smallest
positive representative of $x^{-1}$ mod $2^\B$, assuming $x$ is odd.

\fun{ulong}{Fl_add}{ulong x, ulong y, ulong m} returns the smallest
positive representative of $x + y$ modulo $m$.

\fun{ulong}{Fl_neg}{ulong x, ulong m} returns the smallest
positive representative of $-x$ modulo $m$.

\fun{ulong}{Fl_sub}{ulong x, ulong y, ulong m} returns the smallest
positive representative of $x - y$ modulo $m$.

\fun{long}{Fl_center}{ulong x, ulong m, ulong mo2} returns the representative
in $]-m/2,m/2]$ of $x$ modulo $m$. Assume $0 \leq x < m$ and
$\kbd{mo2}  = m >> 1$.

\fun{ulong}{Fl_mul}{ulong x, ulong y, ulong m} returns the smallest positive
representative of $x y$ modulo $m$.

\fun{ulong}{Fl_double}{ulong x, ulong m} returns $2x$ modulo $m$.

\fun{ulong}{Fl_triple}{ulong x, ulong m} returns $3x$ modulo $m$.

\fun{ulong}{Fl_halve}{ulong x, ulong m} returns $z$ such that $2\*z = x$ modulo
$m$ assuming such $z$ exists.

\fun{ulong}{Fl_sqr}{ulong x, ulong m} returns the smallest positive
representative of $x^2$ modulo $m$.

\fun{ulong}{Fl_inv}{ulong x, ulong m} returns the smallest
positive representative of $x^{-1}$ modulo $m$. If $x$ is not invertible
mod~$m$, raise an exception.

\fun{ulong}{Fl_invsafe}{ulong x, ulong m} returns the smallest
positive representative of $x^{-1}$ modulo $m$. If $x$ is not invertible
mod~$m$, return $0$ (which is ambiguous if $m=1$).

\fun{ulong}{Fl_invgen}{ulong x, ulong m, ulong *pg} set \kbd{*pg} to
$g = \gcd(x,m)$ and return $u$ (invertible) such that $x u = g$ modulo $m$.
We have $g = 1$ if and only if $x$ is invertible, and in this case $u$
is its inverse.

\fun{ulong}{Fl_div}{ulong x, ulong y, ulong m} returns the smallest
positive representative of $x y^{-1}$ modulo $m$. If $y$ is not invertible
mod $m$, raise an exception.

\fun{ulong}{Fl_powu}{ulong x, ulong n, ulong m} returns the smallest
positive representative of $x^n$ modulo $m$.

\fun{GEN}{Fl_powers}{ulong x, long n, ulong p} returns
$[\kbd{x}^0, \dots, \kbd{x}^\kbd{n}]$ modulo $m$, as a \typ{VECSMALL}.

\fun{ulong}{Fl_sqrt}{ulong x, ulong p} returns the square root of \kbd{x}
modulo \kbd{p} (smallest positive representative). Assumes \kbd{p} to be
prime, and \kbd{x} to be a square modulo \kbd{p}.

\fun{ulong}{Fl_sqrtl}{ulong x, ulong l, ulong p} returns a $l$-the root of \kbd{x}
modulo \kbd{p}. Assumes \kbd{p} to be prime and $p \equiv 1 \pmod{l}$, and
\kbd{x} to be a $l$-th power modulo \kbd{p}.

\fun{ulong}{Fl_order}{ulong a, ulong o, ulong p} returns the order of the
\kbd{Fp} \kbd{a}. It is assumed that \kbd{o} is a multiple of the order of
\kbd{a}, $0$ being allowed (no non-trivial information).

\fun{ulong}{random_Fl}{ulong p} returns a pseudo-random integer uniformly
distributed in $0, 1, \dots p-1$.

\fun{ulong}{pgener_Fl}{ulong p} returns the smallest \idx{primitive root}
modulo \kbd{p}, assuming \kbd{p} is prime.

\fun{ulong}{pgener_Zl}{ulong p} returns the smallest primitive root modulo
$p^k$, $k > 1$, assuming $p$ is an odd prime.

\fun{ulong}{pgener_Fl_local}{ulong p, GEN L}, see \kbd{gener\_Fp\_local},
\kbd{L} is an \kbd{Flv}.

\subsec{Modular kernel with ``precomputed inverse''}

This is based on an algorithm by T. Grandlund and N. M\"{o}ller in
``Improved division by invariant integers''
\url{http://gmplib.org/~tege/division-paper.pdf}.

In the following, we set $B=\B$.

\fun{ulong}{get_Fl_red}{ulong p} returns a pseudo inverse \var{pi} for $p$

\fun{ulong}{divll_pre}{ulong x, ulong p, ulong yi}
as divll, where $yi$ is the pseudo inverse of $y$.

\fun{ulong}{remll_pre}{ulong u1, ulong u0, ulong p, ulong pi} returns
the Euclidean remainder of $u_1\*2^B+u_0$ modulo $p$, assuming $pi$ is the
pseudo inverse of $p$.  This function is faster if $u_1 < p$.

\fun{ulong}{remlll_pre}{ulong u2, ulong u1, ulong u0, ulong p, ulong pi}
returns the Euclidean remainder of $u_2\*2^{2\*B}+u_1\*2^{B}+u_0$ modulo $p$,
assuming $pi$ is the pseudo inverse of $p$.

\fun{ulong}{Fl_sqr_pre}{ulong x, ulong p, ulong pi} returns $x^2$ modulo $p$,
assuming $pi$ is the pseudo inverse of $p$.

\fun{ulong}{Fl_mul_pre}{ulong x, ulong y, ulong p, ulong pi} returns $x\*y$
modulo $p$, assuming $pi$ is the pseudo inverse of $p$.

\fun{ulong}{Fl_addmul_pre}{ulong a, ulong b, ulong c, ulong p,  ulong pi}
returns $a\*b+c$ modulo $p$, assuming $pi$ is the pseudo inverse of $p$.

\fun{ulong}{Fl_addmulmul_pre}{ulong a,ulong b, ulong c,ulong d, ulong p, ulong pi}
returns $a\*b+c\*d$ modulo $p$, assuming $pi$ is the pseudo inverse of $p$.

\fun{ulong}{Fl_powu_pre}{ulong x, ulong n, ulong p, ulong pi} returns
$x^n$ modulo $p$, assuming $pi$ is the pseudo inverse of $p$.

\fun{GEN}{Fl_powers_pre}{ulong x, long n, ulong p, ulong pi} returns
the vector (\typ{VECSMALL}) $(x^0, \dots, x^n)$, assuming $pi$ is
the pseudo inverse of $p$.

\fun{ulong}{Fl_sqrt_pre}{ulong x, ulong p, ulong pi} returns a square root
of $x$ modulo $p$, assuming $pi$ is the pseudo inverse of $p$.
See \kbd{Fl\_sqrt}.

\fun{ulong}{Fl_sqrtl_pre}{ulong x, ulong l, ulong p, ulong pi}
returns a $l$-the root of \kbd{x}
modulo \kbd{p}, assuming $pi$ is the pseudo inverse of $p$,
$p$ prime and $p \equiv 1 \pmod{l}$, and \kbd{x} to be a $l$-th power modulo
\kbd{p}.

\subsec{Switching between Fl\_xxx and standard operators}

Even though the \kbd{Fl\_xxx} routines are efficient, they are slower than
ordinary \kbd{long} operations, using the standard \kbd{+}, \kbd{\%}, etc.
operators.
The following macro is used to choose in a portable way the most efficient
functions for given operands:

\fun{int}{SMALL_ULONG}{ulong p} true if $2p^2 <2^\B$. In that case, it is
possible to use ordinary operators efficiently. If $p < 2^\B$, one
may still use the \kbd{Fl\_xxx} routines. Otherwise, one must use generic
routines. For instance, the scalar product of the \kbd{GEN}s $x$ and $y$ mod
$p$ could be computed as follows.
\bprog
    long i, l = lg(x);
    if (lgefint(p) > 3)
    { /* arbitrary */
      GEN s = gen_0;
      for (i = 1; i < l; i++) s = addii(s, mulii(gel(x,i), gel(y,i)));
      return modii(s, p).
    }
    else
    {
      ulong s = 0, pp = itou(p);
      x = ZV_to_Flv(x, pp);
      y = ZV_to_Flv(y, pp);
      if (SMALL_ULONG(pp))
      { /* very small */
        for (i = 1; i < l; i++)
        {
          s += x[i] * y[i];
          if (s & HIGHBIT) s %= pp;
        }
        s %= pp;
      }
      else
      { /* small */
        for (i = 1; i < l; i++)
          s = Fl_add(s, Fl_mul(x[i], y[i], pp), pp);
      }
      return utoi(s);
    }
@eprog\noindent
In effect, we have three versions of the same code: very small, small, and
arbitrary inputs. The very small and arbitrary variants use lazy reduction
and reduce only when it becomes necessary: when overflow might occur (very
small), and at the very end (very small, arbitrary).

\section{Level 1 kernel (operations on longs, integers and reals)}

\misctitle{Note} Some functions consist of an elementary operation,
immediately followed by an assignment statement. They will be introduced as
in the following example:

\fun{GEN}{gadd[z]}{GEN x, GEN y[, GEN z]} followed by the explicit
description of the function

\fun{GEN}{gadd}{GEN x, GEN y}

\noindent which creates its result on the stack, returning a \kbd{GEN} pointer
to it, and the parts in brackets indicate that there exists also a function

\fun{void}{gaddz}{GEN x, GEN y, GEN z}

\noindent which assigns its result to the pre-existing object
\kbd{z}, leaving the stack unchanged. These assignment variants are kept for
backward compatibility but are inefficient: don't use them.

\subsec{Creation}

\fun{GEN}{cgeti}{long n} allocates memory on the PARI stack for a \typ{INT}
of length~\kbd{n}, and initializes its first codeword. Identical to
\kbd{cgetg(n,\typ{INT})}.

\fun{GEN}{cgetipos}{long n} allocates memory on the PARI stack for a
\typ{INT} of length~\kbd{n}, and initializes its two codewords. The sign
of \kbd{n} is set to $1$.

\fun{GEN}{cgetineg}{long n} allocates memory on the PARI stack for a negative
\typ{INT} of length~\kbd{n}, and initializes its two codewords. The sign
of \kbd{n} is set to $-1$.

\fun{GEN}{cgetr}{long n} allocates memory on the PARI stack for a \typ{REAL}
of length~\kbd{n}, and initializes its first codeword. Identical to
\kbd{cgetg(n,\typ{REAL})}.

\fun{GEN}{cgetc}{long n} allocates memory on the PARI stack for a
\typ{COMPLEX}, whose real and imaginary parts are \typ{REAL}s
of length~\kbd{n}.

\fun{GEN}{real_1}{long prec} create a \typ{REAL} equal to $1$ to \kbd{prec}
words of accuracy.

\fun{GEN}{real_1_bit}{long bitprec} create a \typ{REAL} equal to $1$ to
\kbd{bitprec} bits of accuracy.

\fun{GEN}{real_m1}{long prec} create a \typ{REAL} equal to $-1$ to \kbd{prec}
words of accuracy.

\fun{GEN}{real_0_bit}{long bit} create a \typ{REAL} equal to $0$ with
exponent $-\kbd{bit}$.

\fun{GEN}{real_0}{long prec} is a shorthand for
\bprog
  real_0_bit( -prec2nbits(prec) )
@eprog

\fun{GEN}{int2n}{long n} creates a \typ{INT} equal to \kbd{1<<n} (i.e
$2^n$ if $n \geq 0$, and $0$ otherwise).

\fun{GEN}{int2u}{ulong n} creates a \typ{INT} equal to $2^n$.

\fun{GEN}{real2n}{long n, long prec} create a \typ{REAL} equal to $2^n$
to \kbd{prec} words of accuracy.

\fun{GEN}{real_m2n}{long n, long prec} create a \typ{REAL} equal to $-2^n$
to \kbd{prec} words of accuracy.

\fun{GEN}{strtoi}{char *s} convert the character string \kbd{s} to a
non-negative \typ{INT}.
Decimal numbers, hexadecimal numbers prefixed by \kbd{0x} and binary numbers prefixed
by \kbd{0b} are allowed.  The string \kbd{s} consists exclusively of digits:
no leading sign, no whitespace. Leading zeroes are discarded.

\fun{GEN}{strtor}{char *s, long prec} convert the character string \kbd{s} to
a non-negative \typ{REAL} of precision \kbd{prec}. The string \kbd{s}
consists exclusively of digits and optional decimal point and exponent
(\kbd{e} or \kbd{E}): no leading sign, no whitespace. Leading zeroes are
discarded.

\subsec{Assignment}
In this section, the \kbd{z} argument in the \kbd{z}-functions must be of type
\typ{INT} or~\typ{REAL}.

\fun{void}{mpaff}{GEN x, GEN z} assigns \kbd{x} into~\kbd{z} (where \kbd{x}
and \kbd{z} are \typ{INT} or \typ{REAL}).
Assumes that $\kbd{lg(z)} > 2$.

\fun{void}{affii}{GEN x, GEN z} assigns the \typ{INT} \kbd{x} into the
\typ{INT}~\kbd{z}.

\fun{void}{affir}{GEN x, GEN z} assigns the \typ{INT} \kbd{x} into the
\typ{REAL}~\kbd{z}. Assumes that $\kbd{lg(z)} > 2$.

\fun{void}{affiz}{GEN x, GEN z} assigns \typ{INT}~\kbd{x} into \typ{INT} or
\typ{REAL}~\kbd{z}. Assumes that $\kbd{lg(z)} > 2$.

\fun{void}{affsi}{long s, GEN z} assigns the \kbd{long}~\kbd{s} into the
\typ{INT}~\kbd{z}. Assumes that $\kbd{lg(z)} > 2$.

\fun{void}{affsr}{long s, GEN z} assigns the \kbd{long}~\kbd{s} into the
\typ{REAL}~\kbd{z}. Assumes that $\kbd{lg(z)} > 2$.

\fun{void}{affsz}{long s, GEN z} assigns the \kbd{long}~\kbd{s} into the
\typ{INT} or \typ{REAL}~\kbd{z}. Assumes that $\kbd{lg(z)} > 2$.

\fun{void}{affui}{ulong u, GEN z} assigns the \kbd{ulong}~\kbd{u} into the
\typ{INT}~\kbd{z}. Assumes that $\kbd{lg(z)} > 2$.

\fun{void}{affur}{ulong u, GEN z} assigns the \kbd{ulong}~\kbd{u} into the
\typ{REAL}~\kbd{z}. Assumes that $\kbd{lg(z)} > 2$.

\fun{void}{affrr}{GEN x, GEN z} assigns the \typ{REAL}~\kbd{x} into the
\typ{REAL}~\kbd{z}.

\fun{void}{affgr}{GEN x, GEN z} assigns the scalar \kbd{x} into the
\typ{REAL}~\kbd{z}, if possible.

\noindent The function \kbd{affrs} and \kbd{affri} do not exist. So don't use
them.

\fun{void}{affrr_fixlg}{GEN y, GEN z} a variant of \kbd{affrr}. First shorten
$z$ so that it is no longer than $y$, then assigns $y$ to $z$. This is used
in the following scenario: room is reserved for the result but, due to
cancellation, fewer words of accuracy are available than had been
anticipated; instead of appending meaningless $0$s to the mantissa, we store
what was actually computed.

Note that shortening $z$ is not quite straightforward, since \kbd{setlg(z, ly)}
would leave garbage on the stack, which \kbd{gerepile} might later inspect.
It is done using

\fun{void}{fixlg}{GEN z, long ly} see \tet{stackdummy} and the examples that
follow.

\subsec{Copy}

\fun{GEN}{icopy}{GEN x} copy relevant words of the \typ{INT}~\kbd{x} on the
stack: the length and effective length of the copy are equal.

\fun{GEN}{rcopy}{GEN x} copy the \typ{REAL}~\kbd{x} on the stack.

\fun{GEN}{leafcopy}{GEN x} copy the leaf~\kbd{x} on the
stack (works in particular for \typ{INT}s and \typ{REAL}s).
Contrary to \kbd{icopy}, \kbd{leafcopy} preserves the original
length of a \typ{INT}. The obsolete form \fun{GEN}{mpcopy}{GEN x}
is still provided for backward compatibility.

This function also works on recursive types, copying them as if they were
leaves, i.e.~making a shallow copy in that case: the components of the copy
point to the same data as the component of the source; see also
\kbd{shallowcopy}.

\fun{GEN}{leafcopy_avma}{GEN x, pari_sp av} analogous to \kbd{gcopy\_avma}
but simpler: assume $x$ is a leaf and return a copy allocated as if
initially we had \kbd{avma} equal to \kbd{av}. There is no need to pass a
pointer and update the value of the second argument: the new (fictitious)
\kbd{avma} is just the return value (typecast to \kbd{pari\_sp}).

\fun{GEN}{icopyspec}{GEN x, long nx} copy the \kbd{nx} words
\kbd{x[2]}, \dots, \kbd{x[nx+1]} to make up a new \typ{INT}. Set the sign
to $1$.

\subsec{Conversions}

\fun{GEN}{itor}{GEN x, long prec} converts the \typ{INT}~\kbd{x} to a
\typ{REAL} of length \kbd{prec} and return the latter.
Assumes that $\kbd{prec} > 2$.

\fun{long}{itos}{GEN x} converts the \typ{INT}~\kbd{x} to a \kbd{long} if
possible, otherwise raise an exception. We consider the conversion
to be possible if and only if $|x| \leq \kbd{LONG\_MAX}$, i.e. $|x| < 2^{63}$
on a 64-bit architecture. Since the range is symetric, the output of
\kbd{itos} can safely be negated.

\fun{long}{itos_or_0}{GEN x} converts the \typ{INT}~\kbd{x} to a \kbd{long} if
possible, otherwise return $0$.

\fun{int}{is_bigint}{GEN n} true if \kbd{itos(n)} would give an error.

\fun{ulong}{itou}{GEN x} converts the \typ{INT}~\kbd{|x|} to an \kbd{ulong} if
possible, otherwise raise an exception. The conversion is possible if
and only if $\kbd{lgefint}(x) \leq 3$.

\fun{long}{itou_or_0}{GEN x} converts the \typ{INT}~\kbd{|x|} to an
\kbd{ulong} if possible, otherwise return $0$.

\fun{GEN}{stoi}{long s} creates the \typ{INT} corresponding to the
\kbd{long}~\kbd{s}.

\fun{GEN}{stor}{long s, long prec} converts the \kbd{long}~\kbd{s} into a
\typ{REAL} of length \kbd{prec} and return the latter. Assumes that
$\kbd{prec} > 2$.

\fun{GEN}{utoi}{ulong s} converts the \kbd{ulong}~\kbd{s} into a \typ{INT}
and return the latter.

\fun{GEN}{utoipos}{ulong s} converts the \emph{non-zero} \kbd{ulong}~\kbd{s}
into a \typ{INT} and return the latter.

\fun{GEN}{utoineg}{ulong s} converts the \emph{non-zero} \kbd{ulong}~\kbd{s}
into the \typ{INT} $-s$ and return the latter.

\fun{GEN}{utor}{ulong s, long prec} converts the \kbd{ulong}~\kbd{s} into a
\typ{REAL} of length \kbd{prec} and return the latter. Assumes that
$\kbd{prec} > 2$.

\fun{GEN}{rtor}{GEN x, long prec} converts the \typ{REAL}~\kbd{x} to a
\typ{REAL} of length \kbd{prec} and return the latter. If
$\kbd{prec} < \kbd{lg(x)}$, round properly. If $\kbd{prec} > \kbd{lg(x)}$,
pad with zeroes. Assumes that $\kbd{prec} > 2$.

\noindent The following function is also available as a special case of
\tet{mkintn}:

\fun{GEN}{uu32toi}{ulong a, ulong b} returns the \kbd{GEN} equal to $2^{32} a +
b$, \emph{assuming} that $a,b < 2^{32}$. This does not depend on
\kbd{sizeof(long)}: the behavior is as above on both $32$ and $64$-bit
machines.

\fun{GEN}{uutoi}{ulong a, ulong b} returns the \kbd{GEN} equal to
$2^{\B} a + b$.

\fun{GEN}{uutoineg}{ulong a, ulong b} returns the \kbd{GEN} equal to
$-(2^{\B} a + b)$.

\subsec{Integer parts}
The following four functions implement the conversion from \typ{REAL} to
\typ{INT} using standard rounding modes. Contrary to usual semantics
(complement the mantissa with an infinite number of 0), they will raise an
error \emph{precision loss in truncation} if the \typ{REAL} represents a
range containing more than one integer.

\fun{GEN}{ceilr}{GEN x} smallest integer larger or equal
to the \typ{REAL}~\kbd{x} (i.e.~the \kbd{ceil} function).

\fun{GEN}{floorr}{GEN x} largest integer smaller or equal to the
\typ{REAL}~\kbd{x} (i.e.~the \kbd{floor} function).

\fun{GEN}{roundr}{GEN x} rounds the \typ{REAL} \kbd{x} to the nearest integer
(towards~$+\infty$ in case of tie).

\fun{GEN}{truncr}{GEN x} truncates the \typ{REAL}~\kbd{x} (not the same as
\kbd{floorr} if \kbd{x} is negative).

The following four function are analogous, but can also treat the trivial
case when the argument is a \typ{INT}:

\fun{GEN}{mpceil}{GEN x}
as \kbd{ceilr} except that \kbd{x} may be a \typ{INT}.

\fun{GEN}{mpfloor}{GEN x}
as \kbd{floorr} except that \kbd{x} may be a \typ{INT}.

\fun{GEN}{mpround}{GEN x}
as \kbd{roundr} except that \kbd{x} may be a \typ{INT}.

\fun{GEN}{mptrunc}{GEN x}
as \kbd{truncr} except that \kbd{x} may be a \typ{INT}.

\fun{GEN}{diviiround}{GEN x, GEN y} if \kbd{x} and \kbd{y} are \typ{INT}s,
returns the quotient $\kbd{x}/\kbd{y}$ of \kbd{x} and~\kbd{y}, rounded to
the nearest integer. If $\kbd{x}/\kbd{y}$ falls exactly halfway between
two consecutive integers, then it is rounded towards~$+\infty$ (as for
\tet{roundr}).

\fun{GEN}{ceil_safe}{GEN x}, \kbd{x} being a real number (not necessarily a
\typ{REAL}) returns the smallest integer which is larger than any possible
incarnation of \kbd{x}. (Recall that a \typ{REAL} represents an interval of
possible values.) Note that \kbd{gceil} raises an exception if the input
accuracy is too low compared to its magnitude.

\fun{GEN}{floor_safe}{GEN x}, \kbd{x} being a real number (not necessarily a
\typ{REAL}) returns the largest integer which is smaller than any possible
incarnation of \kbd{x}. (Recall that a \typ{REAL} represents an interval of
possible values.) Note that \kbd{gfloor} raises an exception if the input
accuracy is too low compared to its magnitude.

\fun{GEN}{trunc_safe}{GEN x}, \kbd{x} being a real number (not necessarily a
\typ{REAL}) returns the integer with the largest absolute value, which is closer
to $0$ than any possible incarnation of \kbd{x}. (Recall that a \typ{REAL}
represents an interval of possible values.)

\fun{GEN}{roundr_safe}{GEN x} rounds the \typ{REAL} \kbd{x} to the nearest
integer (towards~$+\infty$). Complement the mantissa with an infinite number
of $0$ before rounding, hence never raise an exception.

\subsec{$2$-adic valuations and shifts}

\fun{long}{vals}{long s} 2-adic valuation of the \kbd{long}~\kbd{s}. Returns
$-1$ if \kbd{s} is equal to 0.

\fun{long}{vali}{GEN x} 2-adic valuation of the \typ{INT}~\kbd{x}. Returns $-1$
if \kbd{x} is equal to 0.

\fun{GEN}{mpshift}{GEN x, long n} shifts the~\typ{INT} or
\typ{REAL} \kbd{x} by~\kbd{n}. If \kbd{n} is positive, this is a left shift,
i.e.~multiplication by $2^{\kbd{n}}$. If \kbd{n} is negative, it is a right
shift by~$-\kbd{n}$, which amounts to the truncation of the quotient of \kbd{x}
by~$2^{-\kbd{n}}$.

\fun{GEN}{shifti}{GEN x, long n} shifts the \typ{INT}~$x$ by~$n$.

\fun{GEN}{shiftr}{GEN x, long n} shifts the \typ{REAL}~$x$ by~$n$.

\fun{void}{shiftr_inplace}{GEN x, long n} shifts the \typ{REAL}~$x$ by~$n$,
in place.

\fun{GEN}{trunc2nr}{GEN x, long n} given a \typ{REAL} $x$, returns
\kbd{truncr(shiftr(x,n))}, but faster, without leaving garbage on the stack
and never raising a \emph{precision loss in truncation} error.
Called by \tet{gtrunc2n}.

\fun{GEN}{trunc2nr_lg}{GEN x, long lx, long n} given a \typ{REAL} $x$, returns
\kbd{trunc2nr(x,n)}, pretending that the length of $x$ is \kbd{lx}, which
must be $\leq \kbd{lg}(x)$.

\fun{GEN}{mantissa2nr}{GEN x, long n} given a \typ{REAL} $x$, returns
the mantissa of $x 2^n$ (disregards the exponent of $x$). Equivalent to
\bprog
  trunc2nr(x, n-expo(x)+bit_prec(x)-1)
@eprog

\fun{GEN}{mantissa_real}{GEN z, long *e} returns the mantissa $m$ of $z$, and
sets \kbd{*e} to the exponent $\kbd{bit\_accuracy(lg(z))}-1-\kbd{expo}(z)$,
so that $z = m / 2^e$.

\misctitle{Low-level} In the following two functions, $s$(ource) and $t$(arget)
need not be valid \kbd{GEN}s (in practice, they usually point to some part of a
\typ{REAL} mantissa): they are considered as arrays of words representing some
mantissa, and we shift globally $s$ by $n > 0$ bits, storing the result in
$t$. We assume that $m\leq M$ and only access $s[m], s[m+1],\ldots s[M]$
(read) and likewise for $t$ (write); we may have $s = t$ but more general
overlaps are not allowed. The word $f$ is concatenated to $s$ to supply extra
bits.

\fun{void}{shift_left}{GEN t, GEN s, long m, long M, ulong f, ulong n}
shifts the mantissa
$$s[m], s[m+1],\ldots s[M], f$$
left by $n$ bits.

\fun{void}{shift_right}{GEN t, GEN s, long m, long M, ulong f, ulong n}
shifts the mantissa
$$f, s[m], s[m+1],\ldots s[M]$$
right by $n$ bits.

\subsec{From \typ{INT} to bits or digits in base $2^k$ and back}

\fun{GEN}{binary_zv}{GEN x} given a \typ{INT} $x$, return a \typ{VECSMALL} of
bits, from most significant to least significant.

\fun{GEN}{binary_2k}{GEN x, long k} given a \typ{INT} $x$, and
$k > 0$, return a \typ{VEC} of digits of $x$ in base $2^k$, as \typ{INT}s, from
most significant to least significant.

\fun{GEN}{binary_2k_nv}{GEN x, long k} given a \typ{INT} $x$, and $0 < k <
\tet{BITS_IN_LONG}$, return a \typ{VECSMALL} of digits of $x$ in base $2^k$, as
\kbd{ulong}s, from most significant to least significant.

\fun{GEN}{bits_to_int}{GEN x, long l} given a vector $x$ of $l$ bits (as a
\typ{VECSMALL} or even a pointer to a part of a larger vector, so not a
proper \kbd{GEN}), return the integer $\sum_{i = 1}^l x[i] 2^{l-i}$, as a
\typ{INT}.

\fun{ulong}{bits_to_u}{GEN v, long l} same as \tet{bits_to_int}, where
$l < \tet{BITS_IN_LONG}$, so we can return an \kbd{ulong}.

\fun{GEN}{fromdigitsu}{GEN x, GEN B}
given a \typ{VECSMALL} $x$ of length $l$ and a \typ{INT} $B$,
return the integer $\sum_{i = 1}^l x[i] B^{i-1}$, as a \typ{INT},
where the \kbd{x[i]} are seen as unsigned integers.

\fun{GEN}{fromdigits_2k}{GEN x, long k} converse of \tet{binary_2k};
given a \typ{VEC} $x$ of length $l$ and a positive \kbd{long} $k$,
where each $x[i]$ is a \typ{INT} with $0\leq x[i] < 2^k$, return the
integer $\sum_{i = 1}^l x[i] 2^{k(l-i)}$, as a \typ{INT}.

\fun{GEN}{nv_fromdigits_2k}{GEN x, long k} as \tet{fromdigits_2k}, but
with $x$ being a \typ{VECSMALL} and each $x[i]$ being a \kbd{ulong}
with $0\leq x[i] < 2^{\min\{k,\tet{BITS_IN_LONG}\}}$.  Here $k$ may be
any positive \kbd{long}, and the $x[i]$ are regarded as $k$-bit
integers by truncating or extending with zeroes.

\subsec{Integer valuation}
For integers $x$ and $p$, such that $x\neq 0$ and $|p| > 1$, we define
$v_p(x)$ to be the largest integer exponent $e$ such that $p^e$ divides $x$.
If $p$ is prime, this is the ordinary valuation of $x$ at $p$.

\fun{long}{Z_pvalrem}{GEN x, GEN p, GEN *r} applied to \typ{INT}s
$\kbd{x}\neq 0$ and~\kbd{p}, $|\kbd{p}| > 1$, returns $e := v_p(x)$
The quotient $\kbd{x}/\kbd{p}^e$ is returned in~\kbd{*r}. If
$|\kbd{p}|$ is a prime, \kbd{*r} is the prime-to-\kbd{p} part of~\kbd{x}.

\fun{long}{Z_pval}{GEN x, GEN p} as \kbd{Z\_pvalrem} but only returns
$v_p(x)$.

\fun{long}{Z_lvalrem}{GEN x, ulong p, GEN *r} as \kbd{Z\_pvalrem},
except that \kbd{p} is an \kbd{ulong} ($\kbd{p} > 1$).

\fun{long}{Z_lvalrem_stop}{GEN *x, ulong p, int *stop} returns $e := v_p(x)$
and replaces $x$ by $x / p^e$. Set \kbd{stop} to $1$ if the new value
of $x$ is $ < p^2$ (and $0$ otherwise). To be used when trial dividing $x$
by successive primes: the \kbd{stop} condition is cheaply tested while
testing whether $p$ divides $x$ (is the quotient less than $p$?), and allows
to decide that $n$ is prime if no prime $< p$ divides $n$. Not memory-clean.

\fun{long}{Z_lval}{GEN x, ulong p} as \kbd{Z\_pval},
except that \kbd{p} is an \kbd{ulong} ($\kbd{p} > 1$).

\fun{long}{u_lvalrem}{ulong x, ulong p, ulong *r} as \kbd{Z\_pvalrem},
except the inputs/outputs are now \kbd{ulong}s.

\fun{long}{u_lvalrem_stop}{ulong *n, ulong p, int *stop} as
\kbd{Z\_pvalrem\_stop}.

\fun{long}{u_pvalrem}{ulong x, GEN p, ulong *r} as \kbd{Z\_pvalrem},
except \kbd{x} and \kbd{r} are now \kbd{ulong}s.

\fun{long}{u_lval}{ulong x, ulong p} as \kbd{Z\_pval},
except the inputs are now \kbd{ulong}s.

\fun{long}{u_pval}{ulong x, GEN p} as \kbd{Z\_pval},
except \kbd{x} is now an \kbd{ulong}.

\fun{long}{z_lval}{long x, ulong p} as \kbd{u\_lval}, for signed \kbd{x}.

\fun{long}{z_lvalrem}{long x, ulong p} as \kbd{u\_lvalrem}, for signed \kbd{x}.

\fun{long}{z_pval}{long x, GEN p} as \kbd{Z\_pval},
except \kbd{x} is now a \kbd{long}.

\fun{long}{z_pvalrem}{long x, GEN p} as \kbd{Z\_pvalrem},
except \kbd{x} is now a \kbd{long}.

\fun{long}{Q_pval}{GEN x, GEN p} valuation at the \typ{INT} \kbd{p}
of the \typ{INT} or \typ{FRAC}~\kbd{x}.

\fun{long}{factorial_lval}{ulong n, ulong p} returns $v_p(n!)$, assuming
$p$ is prime.


The following convenience functions generalize \kbd{Z\_pval} and its variants
to ``containers'' (\kbd{ZV} and \kbd{ZX}):


\fun{long}{ZV_pvalrem}{GEN x, GEN p, GEN *r} $x$ being a \kbd{ZV} (a vector
of \typ{INT}s), return the min $v$ of the valuations of its components and
set \kbd{*r} to $x/p^v$. Infinite loop if $x$ is the zero vector.
This function is not stack clean.

\fun{long}{ZV_pval}{GEN x, GEN p} as \kbd{ZV\_pvalrem} but only returns the
``valuation''.

\fun{int}{ZV_Z_dvd}{GEN x, GEN p} returns $1$ if $p$ divides all components
of $x$ and $0$ otherwise. Faster than testing \kbd{ZV\_pval(x,p) >= 1}.

\fun{long}{ZV_lvalrem}{GEN x, ulong p, GEN *px} as \kbd{ZV\_pvalrem},
except that \kbd{p} is an \kbd{ulong} ($\kbd{p} > 1$).
This function is not stack-clean.

\fun{long}{ZV_lval}{GEN x, ulong p} as \kbd{ZV\_pval},
except that \kbd{p} is an \kbd{ulong} ($\kbd{p} > 1$).


\fun{long}{ZX_pvalrem}{GEN x, GEN p, GEN *r} as \kbd{ZV\_pvalrem}, for
a \kbd{ZX} $x$ (a \typ{POL} with \typ{INT} coefficients).
This function is not stack-clean.

\fun{long}{ZX_pval}{GEN x, GEN p} as \kbd{ZV\_pval} for a \kbd{ZX} $x$.

\fun{long}{ZX_lvalrem}{GEN x, ulong p, GEN *px} as \kbd{ZV\_lvalrem},
a \kbd{ZX} $x$.
This function is not stack-clean.

\fun{long}{ZX_lval}{GEN x, ulong p} as \kbd{ZX\_pval},
except that \kbd{p} is an \kbd{ulong} ($\kbd{p} > 1$).

\subsec{Generic unary operators} Let ``\op'' be a unary operation among

\item \key{neg}: negation ($-x$).

\item \key{abs}: absolute value ($|x|$).

\item \key{sqr}: square ($x^2$).

\noindent The names and prototypes of the low-level functions corresponding
to \op\ are as follows. The result is of the same type as~\kbd{x}.

\funno{GEN}{\op i}{GEN x} creates the result of \op\ applied to the
\typ{INT}~\kbd{x}.

\funno{GEN}{\op r}{GEN x} creates the result of \op\ applied to the
\typ{REAL}~\kbd{x}.

\funno{GEN}{mp\op}{GEN x} creates the result of \op\ applied to the
\typ{INT} or \typ{REAL}~\kbd{x}.

\noindent Complete list of available functions:

\fun{GEN}{absi}{GEN x}, \fun{GEN}{absr}{GEN x}, \fun{GEN}{mpabs}{GEN x}

\fun{GEN}{negi}{GEN x}, \fun{GEN}{negr}{GEN x}, \fun{GEN}{mpneg}{GEN x}

\fun{GEN}{sqri}{GEN x}, \fun{GEN}{sqrr}{GEN x}, \fun{GEN}{mpsqr}{GEN x}

\fun{GEN}{absi_shallow}{GEN x} $x$ being a \typ{INT}, returns a shallow copy of
$|x|$, in particular returns $x$ itself when $x \geq 0$, and \kbd{negi($x$)}
otherwise.

\fun{GEN}{mpabs_shallow}{GEN x} $x$ being a \typ{INT} or a \typ{REAL}, returns
a shallow copy of $|x|$, in particular returns $x$ itself when $x \geq 0$, and
\kbd{mpneg($x$)} otherwise.


\noindent Some miscellaneous routines:

\fun{GEN}{sqrs}{long x} returns $x^2$.

\fun{GEN}{sqru}{ulong x} returns $x^2$.

\subsec{Comparison operators}

\fun{long}{minss}{long x, long y}

\fun{ulong}{minuu}{ulong x, ulong y}

\fun{double}{mindd}{double x, double y} returns the \kbd{min} of $x$ and $y$.


\fun{long}{maxss}{long x, long y}

\fun{ulong}{maxuu}{ulong x, ulong y}

\fun{double}{maxdd}{double x, double y} returns the \kbd{max} of $x$ and $y$.

\smallskip

\fun{int}{mpcmp}{GEN x, GEN y} compares the \typ{INT} or \typ{REAL}~\kbd{x}
to the \typ{INT} or \typ{REAL}~\kbd{y}. The result is the sign of
$\kbd{x}-\kbd{y}$.

\fun{int}{cmpii}{GEN x, GEN y} compares the \typ{INT} \kbd{x} to the
\typ{INT}~\kbd{y}.

\fun{int}{cmpir}{GEN x, GEN y} compares the \typ{INT} \kbd{x} to the
\typ{REAL}~\kbd{y}.

\fun{int}{cmpis}{GEN x, long s} compares the \typ{INT}~\kbd{x} to the
\kbd{long}~\kbd{s}.

\fun{int}{cmpsi}{long s, GEN x} compares the \kbd{long}~\kbd{s} to the
\typ{INT}~\kbd{x}.

\fun{int}{cmpsr}{long s, GEN x} compares the \kbd{long}~\kbd{s} to the
\typ{REAL}~\kbd{x}.

\fun{int}{cmpri}{GEN x, GEN y} compares the \typ{REAL}~\kbd{x} to the
\typ{INT}~\kbd{y}.

\fun{int}{cmprr}{GEN x, GEN y} compares the \typ{REAL}~\kbd{x} to the
\typ{REAL}~\kbd{y}.

\fun{int}{cmprs}{GEN x, long s} compares the \typ{REAL}~\kbd{x} to the
\kbd{long}~\kbd{s}.

\fun{int}{equalii}{GEN x, GEN y} compares the \typ{INT}s \kbd{x} and~\kbd{y}.
The result is $1$ if $\kbd{x} = \kbd{y}$, $0$ otherwise.

\fun{int}{equalrr}{GEN x, GEN y} compares the \typ{REAL}s \kbd{x} and~\kbd{y}.
The result is $1$ if $\kbd{x} = \kbd{y}$, $0$ otherwise. Equality is decided
according to the following rules: all real zeroes are equal, and
different from a non-zero real; two non-zero reals are equal if all their
digits coincide up to the length of the shortest of the two, and the
remaining words in the mantissa of the longest are all $0$.

\fun{int}{equalsi}{long s, GEN x}

\fun{int}{equalis}{GEN x, long s} compare the \typ{INT} \kbd{x} and
the \kbd{long}~\kbd{s}. The result is $1$ if $\kbd{x} = \kbd{y}$, $0$ otherwise.

The remaining comparison operators disregard the sign of their operands

\fun{int}{absequaliu}{GEN x, ulong u} compare the absolute value of the
\typ{INT} \kbd{x} and the \kbd{ulong}~\kbd{s}. The result is $1$ if
$|\kbd{x}| = \kbd{y}$, $0$ otherwise. This is marginally more efficient
than \kbd{equalis} even when \kbd{x} is known to be non-negative.

\fun{int}{absequalui}{ulong u, GEN x}

\fun{int}{abscmpiu}{GEN x, ulong u} compare the absolute value of the
\typ{INT} \kbd{x} and the \kbd{ulong}~\kbd{u}.

\fun{int}{abscmpui}{ulong u, GEN x}


\fun{int}{abscmpii}{GEN x, GEN y} compares the \typ{INT}s \kbd{x} and~\kbd{y}.
The result is the sign of $|\kbd{x}| - |\kbd{y}|$.

\fun{int}{absequalii}{GEN x, GEN y} compares the \typ{INT}s \kbd{x}
and~\kbd{y}. The result is $1$ if $|\kbd{x}| = |\kbd{y}|$, $0$ otherwise.

\fun{int}{abscmprr}{GEN x, GEN y} compares the \typ{REAL}s \kbd{x} and~\kbd{y}.
The result is the sign of $|\kbd{x}| - |\kbd{y}|$.

\fun{int}{absrnz_equal2n}{GEN x} tests whether a non-zero \typ{REAL} \kbd{x}
is equal to $\pm 2^e$ for some integer $e$.

\fun{int}{absrnz_equal1}{GEN x} tests whether a non-zero \typ{REAL} \kbd{x}
is equal to $\pm 1$.

\subsec{Generic binary operators}\label{se:genbinop} The operators in this
section have arguments of C-type \kbd{GEN}, \kbd{long}, and \kbd{ulong}, and
only \typ{INT} and \typ{REAL} \kbd{GEN}s are allowed. We say an argument is a
real type if it is a \typ{REAL} \kbd{GEN}, and an integer type otherwise. The
result is always a \typ{REAL} unless both \kbd{x} and \kbd{y} are integer
types.

Let ``\op'' be a binary operation among

\item \key{add}: addition (\kbd{x + y}).

\item \key{sub}: subtraction (\kbd{x - y}).

\item \key{mul}: multiplication (\kbd{x * y}).

\item \key{div}: division (\kbd{x / y}). In the case where \kbd{x} and \kbd{y}
are both integer types, the result is the Euclidean quotient, where the
remainder has the same sign as the dividend~\kbd{x}. It is the ordinary
division otherwise. A division-by-$0$ error occurs if \kbd{y} is equal to
$0$.

The last two generic operations are defined only when arguments have integer
types; and the result is a \typ{INT}:

\item \key{rem}: remainder (``\kbd{x \% y}''). The result is the Euclidean
remainder corresponding to \kbd{div},~i.e. its sign is that of the
dividend~\kbd{x}.

\item \key{mod}: true remainder (\kbd{x \% y}). The result is the true
Euclidean remainder, i.e.~non-negative and less than the absolute value
of~\kbd{y}.

\misctitle{Important technical note} The rules given above fixing the output
type (to \typ{REAL} unless both inputs are integer types) are subtly
incompatible with the general rules obeyed by PARI's generic functions, such
as \kbd{gmul} or \kbd{gdiv} for instance: the latter return a result
containing as much information as could be deduced from the inputs, so it is
not true that if $x$ is a \typ{INT} and $y$ a \typ{REAL}, then
\kbd{gmul(x,y)} is always the same as \kbd{mulir(x,y)}. The exception
is $x = 0$, in that case we can deduce that the result is an exact $0$,
so \kbd{gmul} returns \kbd{gen\_0}, while \kbd{mulir} returns a
\typ{REAL} $0$. Specifically, the one resulting from the conversion of
\kbd{gen\_0} to a \typ{REAL} of precision \kbd{precision(y)}, multiplied by
$y$; this determines the exponent of the real $0$ we obtain.

The reason for the discrepancy between the two rules is that we use the two
sets of functions in different contexts: generic functions allow to write
high-level code forgetting about types, letting PARI return results which are
sensible and as simple as possible; type specific functions are used in
kernel programming, where we do care about types and need to maintain strict
consistency: it is much easier to compute the types of results when they are
determined from the types of the inputs only (without taking into account
further arithmetic properties, like being non-0).
\smallskip

The names and prototypes of the low-level functions corresponding
to \op\ are as follows. In this section, the \kbd{z} argument in the
\kbd{z}-functions must be of type \typ{INT} when no \kbd{r} or \kbd{mp}
appears in the argument code (no \typ{REAL} operand is involved, only integer
types), and of type \typ{REAL} otherwise.

\funno{GEN}{mp\op[z]}{GEN x, GEN y[, GEN z]} applies \op\ to
the \typ{INT} or \typ{REAL} \kbd{x} and~\kbd{y}. The function
\kbd{mpdivz} does not exist (its semantic would change drastically
depending on the type of the \kbd{z} argument), and neither do
\kbd{mprem[z]} nor \kbd{mpmod[z]} (specific to integers).

\funno{GEN}{\op si[z]}{long s, GEN x[, GEN z]} applies \op\ to the
\kbd{long}~\kbd{s} and the \typ{INT}~\kbd{x}.
 These functions always return the global constant
\kbd{gen\_0} (not a copy) when the sign of the result is $0$.

\funno{GEN}{\op sr[z]}{long s, GEN x[, GEN z]} applies \op\ to the
\kbd{long}~\kbd{s} and the \typ{REAL}~\kbd{x}.

\funno{GEN}{\op ss[z]}{long s, long t[, GEN z]} applies \op\ to the longs
\kbd{s} and~\kbd{t}. These functions always return the global constant
\kbd{gen\_0} (not a copy) when the sign of the result is $0$.

\funno{GEN}{\op ii[z]}{GEN x, GEN y[, GEN z]} applies \op\ to the
\typ{INT}s \kbd{x} and~\kbd{y}. These functions always return the global
constant \kbd{gen\_0} (not a copy) when the sign of the result is $0$.

\funno{GEN}{\op ir[z]}{GEN x, GEN y[, GEN z]} applies \op\ to the
\typ{INT} \kbd{x} and the \typ{REAL}~\kbd{y}.

\funno{GEN}{\op is[z]}{GEN x, long s[, GEN z]} applies \op\ to the
\typ{INT}~\kbd{x} and the \kbd{long}~\kbd{s}. These functions always return
the global constant \kbd{gen\_0} (not a copy) when the sign of the result
is $0$.

\funno{GEN}{\op ri[z]}{GEN x, GEN y[, GEN z]} applies \op\ to the
\typ{REAL}~\kbd{x} and the \typ{INT}~\kbd{y}.

\funno{GEN}{\op rr[z]}{GEN x, GEN y[, GEN z]} applies \op\ to the
\typ{REAL}s~\kbd{x} and~\kbd{y}.

\funno{GEN}{\op rs[z]}{GEN x, long s[, GEN z]} applies \op\ to the
\typ{REAL}~\kbd{x} and the \kbd{long}~\kbd{s}.

\noindent Some miscellaneous routines:

\fun{long}{expu}{ulong x} assuming $x > 0$, returns the binary exponent of
the real number equal to $x$. This is a special case of \kbd{gexpo}.

\fun{GEN}{adduu}{ulong x, ulong y}

\fun{GEN}{addiu}{GEN x, ulong y}

\fun{GEN}{addui}{ulong x, GEN y} adds \kbd{x} and \kbd{y}.

\fun{GEN}{subuu}{ulong x, ulong y}

\fun{GEN}{subiu}{GEN x, ulong y}

\fun{GEN}{subui}{ulong x, GEN y} subtracts \kbd{x} by \kbd{y}.

\fun{GEN}{muluu}{ulong x, ulong y} multiplies \kbd{x} by \kbd{y}.

\fun{GEN}{mului}{ulong x, GEN y} multiplies \kbd{x} by \kbd{y}.

\fun{GEN}{muluui}{ulong x, ulong y, GEN z} return $xyz$.

\fun{GEN}{muliu}{GEN x, ulong y} multiplies \kbd{x} by \kbd{y}.

\fun{void}{addumului}{ulong a, ulong b, GEN x} return $a + b|X|$.

\fun{GEN}{addmuliu}{GEN x, GEN y, ulong u} returns $x +yu$.

\fun{GEN}{addmulii}{GEN x, GEN y, GEN z} returns $x + yz$.

\fun{GEN}{addmulii_inplace}{GEN x, GEN y, GEN z} returns $x + yz$, but
returns $x$ itself and not a copy if $yz = 0$. Not suitable for
\tet{gerepile} or \tet{gerepileupto}.

\fun{GEN}{addmuliu_inplace}{GEN x, GEN y, ulong u} returns $x +yu$, but
returns $x$ itself and not a copy if $yu = 0$. Not suitable for
\tet{gerepile} or \tet{gerepileupto}.

\fun{GEN}{submuliu_inplace}{GEN x, GEN y, ulong u} returns $x- yu$, but
returns $x$ itself and not a copy if $yu = 0$. Not suitable for
\tet{gerepile} or \tet{gerepileupto}.

\fun{GEN}{lincombii}{GEN u, GEN v, GEN x, GEN y} returns $ux + vy$.

\fun{GEN}{mulsubii}{GEN y, GEN z, GEN x} returns $yz - x$.

\fun{GEN}{submulii}{GEN x, GEN y, GEN z} returns $x - yz$.

\fun{GEN}{submuliu}{GEN x, GEN y, ulong u} returns $x -yu$.

\fun{GEN}{mulu_interval}{ulong a, ulong b} returns $a(a+1)\cdots b$, assuming
that $a \leq b$.

\fun{GEN}{muls_interval}{long a, long b} returns $a(a+1)\cdots b$, assuming
that $a \leq b$.

\fun{GEN}{invr}{GEN x} returns the inverse of the non-zero \typ{REAL}~$x$.

\fun{GEN}{truedivii}{GEN x, GEN y} returns the true Euclidean quotient
(with non-negative remainder less than $|y|$).

\fun{GEN}{truedivis}{GEN x, long y} returns the true Euclidean quotient
(with non-negative remainder less than $|y|$).

\fun{GEN}{truedivsi}{long x, GEN y} returns the true Euclidean quotient
(with non-negative remainder less than $|y|$).

\fun{GEN}{centermodii}{GEN x, GEN y, GEN y2}, given
\typ{INT}s \kbd{x}, \kbd{y}, returns $z$ congruent to \kbd{x} modulo \kbd{y},
such that $-\kbd{y}/2 \leq z < \kbd{y}/2$. The function requires an extra
argument \kbd{y2}, such that \kbd{y2 = shifti(y, -1)}. (In most cases, \kbd{y}
is constant for many reductions and \kbd{y2} need only be computed once.)

\fun{GEN}{remi2n}{GEN x, long n} returns \kbd{x} mod $2^n$.

\fun{GEN}{addii_sign}{GEN x, long sx, GEN y, long sy} add the \typ{INT}s
$x$ and $y$ as if their signs were \kbd{sx} and \kbd{sy}.

\fun{GEN}{addir_sign}{GEN x, long sx, GEN y, long sy}
add the \typ{INT} $x$ and the \typ{REAL} $y$ as if their signs were \kbd{sx}
and \kbd{sy}.

\fun{GEN}{addrr_sign}{GEN x, long sx, GEN y, long sy} add the \typ{REAL}s $x$
and $y$ as if their signs were \kbd{sx} and \kbd{sy}.

\fun{GEN}{addsi_sign}{long x, GEN y, long sy} add $x$ and the \typ{INT} $y$
as if its sign was \kbd{sy}.

\fun{GEN}{addui_sign}{ulong x, GEN y, long sy} add $x$ and the \typ{INT} $y$
as if its sign was \kbd{sy}.

\subsec{Exact division and divisibility}

\fun{GEN}{diviiexact}{GEN x, GEN y} returns the Euclidean quotient
$\kbd{x} / \kbd{y}$, assuming $\kbd{y}$ divides $\kbd{x}$. Uses Jebelean
algorithm (Jebelean-Krandick bidirectional exact division is not
implemented).

\fun{GEN}{diviuexact}{GEN x, ulong y} returns the Euclidean quotient
$\kbd{x} / \kbd{y}$, assuming $\kbd{y}$ divides
$\kbd{x}$ and $\kbd{y}$ is non-zero.

\fun{GEN}{diviuuexact}{GEN x, ulong y, ulong z} returns the Euclidean
quotient $x/(yz)$, assuming $yz$ divides $x$ and $yz \neq 0$.

The following routines return 1 (true) if \kbd{y} divides \kbd{x}, and
0 otherwise. (Error if $y$ is $0$, even if $x$ is $0$.) All \kbd{GEN} are
assumed to be \typ{INT}s:

\fun{int}{dvdii}{GEN x, GEN y},
\fun{int}{dvdis}{GEN x, long y},
\fun{int}{dvdiu}{GEN x, ulong y},

\fun{int}{dvdsi}{long x, GEN y},
\fun{int}{dvdui}{ulong x, GEN y}.

The following routines return 1 (true) if \kbd{y} divides \kbd{x}, and in
that case assign the quotient to \kbd{z}; otherwise they return 0. All
\kbd{GEN} are assumed to be \typ{INT}s:

\fun{int}{dvdiiz}{GEN x, GEN y, GEN z},
\fun{int}{dvdisz}{GEN x, long y, GEN z}.

\fun{int}{dvdiuz}{GEN x, ulong y, GEN z} if \kbd{y} divides \kbd{x}, assigns
the quotient $|\kbd{x}|/\kbd{y}$ to \kbd{z} and returns 1 (true), otherwise
returns 0 (false).

\subsec{Division with integral operands and \typ{REAL} result}

\fun{GEN}{rdivii}{GEN x, GEN y, long prec}, assuming $x$ and $y$
are both of type \typ{INT}, return the quotient $x/y$ as a \typ{REAL} of
precision \kbd{prec}.

\fun{GEN}{rdiviiz}{GEN x, GEN y, GEN z}, assuming $x$ and $y$
are both of type \typ{INT}, and $z$ is a \typ{REAL},
assign the quotient $x/y$ to $z$.

\fun{GEN}{rdivis}{GEN x, long y, long prec}, assuming \kbd{x}
is of type \typ{INT}, return the quotient x/y as a \typ{REAL} of
precision \kbd{prec}.

\fun{GEN}{rdivsi}{long x, GEN y, long prec}, assuming \kbd{y}
is of type \typ{INT}, return the quotient x/y as a \typ{REAL} of
precision \kbd{prec}.

\fun{GEN}{rdivss}{long x, long y, long prec}, return the quotient x/y as a
\typ{REAL} of precision \kbd{prec}.


\subsec{Division with remainder} The following functions return two objects,
unless specifically asked for only one of them~--- a quotient and a remainder.
The quotient is returned and the remainder is returned through the variable
whose address is passed as the \kbd{r} argument. The term \emph{true
Euclidean remainder} refers to the non-negative one (\kbd{mod}), and
\emph{Euclidean remainder} by itself to the one with the same sign as the
dividend (\kbd{rem}). All \kbd{GEN}s, whether returned directly or through a
pointer, are created on the stack.

\fun{GEN}{dvmdii}{GEN x, GEN y, GEN *r} returns the Euclidean quotient of the
\typ{INT}~\kbd{x} by a \typ{INT}~\kbd{y} and puts the remainder
into~\kbd{*r}. If \kbd{r} is equal to \kbd{NULL}, the remainder is not
created, and if \kbd{r} is equal to  \kbd{ONLY\_REM}, only the remainder is
created and returned. In the generic case, the remainder is created after the
quotient and can be disposed of individually with a \kbd{cgiv(r)}. The
remainder is always of the sign of the dividend~\kbd{x}. If the remainder
is $0$ set \kbd{r = gen\_0}.

\fun{void}{dvmdiiz}{GEN x, GEN y, GEN z, GEN t} assigns the Euclidean
quotient of the \typ{INT}s \kbd{x} and \kbd{y} into the \typ{INT}~\kbd{z},
and the Euclidean remainder into the \typ{INT}~\kbd{t}.

\noindent Analogous routines \tet{dvmdis}\kbd{[z]}, \tet{dvmdsi}\kbd{[z]},
\tet{dvmdss}\kbd{[z]} are available, where \kbd{s} denotes a \kbd{long}
argument. But the following routines are in general more flexible:

\fun{long}{sdivss_rem}{long s, long t, long *r} computes the Euclidean
quotient and remainder of the longs \kbd{s} and~\kbd{t}. Puts the remainder
into \kbd{*r}, and returns the quotient. The remainder is of the sign of the
dividend~\kbd{s}, and has strictly smaller absolute value than~\kbd{t}.

\fun{long}{sdivsi_rem}{long s, GEN x, long *r} computes the Euclidean
quotient and remainder of the \kbd{long}~\kbd{s} by the \typ{INT}~\kbd{x}. As
\kbd{sdivss\_rem} otherwise.

\fun{long}{sdivsi}{long s, GEN x} as \kbd{sdivsi\_rem}, without
remainder.

\fun{GEN}{divis_rem}{GEN x, long s, long *r} computes the Euclidean quotient
and remainder of the \typ{INT}~\kbd{x} by the \kbd{long}~\kbd{s}. As
\kbd{sdivss\_rem} otherwise.

\fun{GEN}{diviu_rem}{GEN x, ulong s, ulong *r} computes the Euclidean quotient
and remainder of \emph{absolute value} of the \typ{INT}~\kbd{x} by the
\kbd{ulong}~\kbd{s}. As \kbd{sdivss\_rem} otherwise.

\fun{ulong}{udiviu_rem}{GEN n, ulong d, ulong *r} as \tet{diviu_rem}, assuming
that $|n|/d$ fits into an \kbd{ulong}.

\fun{ulong}{udivui_rem}{ulong x, GEN y, ulong *rem}
computes the Euclidean quotient and remainder of $x$ by $y$. As
\kbd{sdivss\_rem} otherwise.

\fun{ulong}{udivuu_rem}{ulong x, ulong y, ulong *rem}
computes the Euclidean quotient and remainder of $x$ by $y$. As
\kbd{sdivss\_rem} otherwise.

\fun{ulong}{ceildivuu}{ulong x, ulong y} return the ceiling of $x / y$.

\fun{GEN}{divsi_rem}{long s, GEN y, long *r} computes the Euclidean quotient
and remainder of the \kbd{long}~\kbd{s} by the \kbd{GEN}~\kbd{y}. As
\kbd{sdivss\_rem} otherwise.

\fun{GEN}{divss_rem}{long x, long y, long *r} computes the Euclidean quotient
and remainder of the \kbd{long}~\kbd{x} by the \kbd{long}~\kbd{y}. As
\kbd{sdivss\_rem} otherwise.
\smallskip
\fun{GEN}{truedvmdii}{GEN x, GEN y, GEN *r}, as \kbd{dvmdii} but with a
non-negative remainder.

\fun{GEN}{truedvmdis}{GEN x, long y, GEN *z}, as \kbd{dvmdis} but with a
non-negative remainder.

\fun{GEN}{truedvmdsi}{long x, GEN y, GEN *z}, as \kbd{dvmdsi} but with a
non-negative remainder.

\subsec{Modulo to longs} The following variants of \kbd{modii} do not
clutter the stack:

\fun{long}{smodis}{GEN x, long y} computes the true Euclidean
remainder of the \typ{INT}~\kbd{x} by the \kbd{long}~\kbd{y}. This is the
non-negative remainder, not the one whose sign is the sign of \kbd{x}
as in the \kbd{div} functions.

\fun{long}{smodss}{long x, long y} computes the true Euclidean
remainder of the \kbd{long}~\kbd{x} by a \kbd{long}~\kbd{y}.

\fun{ulong}{umodsu}{long x, ulong y} computes the true Euclidean
remainder of the \kbd{long}~\kbd{x} by a \kbd{ulong}~\kbd{y}.

\fun{ulong}{umodiu}{GEN x, ulong y} computes the true Euclidean
remainder of the \typ{INT}~\kbd{x} by the \kbd{ulong}~\kbd{y}.

\fun{ulong}{umodui}{ulong x, GEN y} computes the true Euclidean
remainder of the \kbd{ulong}~\kbd{x} by the \typ{INT}~\kbd{|y|}.

The routine \tet{smodsi} does not exist, since it would not always be
defined: for a \emph{negative} \kbd{x}, if the quotient is $\pm1$, the result
\kbd{x + |y|} would in general not fit into a \kbd{long}. Use either
\kbd{umodui} or \kbd{modsi}.

These functions directly access the binary data and are thus much faster than
the generic modulo functions:

\fun{int}{mpodd}{GEN x} which is 1 if \kbd{x} is odd, and 0 otherwise.

\fun{ulong}{Mod2}{GEN x}

\fun{ulong}{Mod4}{GEN x}

\fun{ulong}{Mod8}{GEN x}

\fun{ulong}{Mod16}{GEN x}

\fun{ulong}{Mod32}{GEN x}

\fun{ulong}{Mod64}{GEN x} give the residue class of $x$ modulo the
corresponding power of $2$.

\fun{ulong}{umodi2n}{GEN x, long n} give the residue class of $x$ modulo
$2^n$, $0 \leq n < BITS\_IN\_LONG$.

The following functions assume that $x\neq 0$ and in fact disregard the
sign of $x$. There are about $10\%$ faster than the safer variants above:

\fun{long}{mod2}{GEN x}

\fun{long}{mod4}{GEN x}

\fun{long}{mod8}{GEN x}

\fun{long}{mod16}{GEN x}

\fun{long}{mod32}{GEN x}

\fun{long}{mod64}{GEN x} give the residue class of $|x|$ modulo the
corresponding power of 2, for \emph{non-zero}~\kbd{x}. As well,

\fun{ulong}{mod2BIL}{GEN x} returns the least significant word of $|x|$, still
assuming that $x\neq 0$.

\subsec{Powering, Square root}

\fun{GEN}{powii}{GEN x, GEN n}, assumes $x$ and $n$ are \typ{INT}s and
returns $x^n$.

\fun{GEN}{powuu}{ulong x, ulong n}, returns $x^n$.

\fun{GEN}{powiu}{GEN x, ulong n}, assumes $x$ is a \typ{INT} and returns $x^n$.

\fun{GEN}{powis}{GEN x, long n}, assumes $x$ is a \typ{INT} and returns $x^n$
(possibly a \typ{FRAC} if $n < 0$).

\fun{GEN}{powrs}{GEN x, long n}, assumes $x$ is a \typ{REAL} and returns
$x^n$. This is considered as a sequence of \kbd{mulrr}, possibly empty:
as such the result has type \typ{REAL}, even if $n = 0$.
Note that the generic function \kbd{gpowgs(x,0)} would return \kbd{gen\_1},
see the technical note in \secref{se:genbinop}.

\fun{GEN}{powru}{GEN x, ulong n}, assumes $x$ is a \typ{REAL} and returns $x^n$
(always a \typ{REAL}, even if $n = 0$).

\fun{GEN}{powersr}{GEN e, long n}. Given a \typ{REAL} $e$, return the vector
$v$ of all $e^i$, $0 \leq i \leq n$, where $v[i] = e^{i-1}$.

\fun{GEN}{powrshalf}{GEN x, long n}, assumes $x$ is a \typ{REAL} and returns
$x^{n/2}$ (always a \typ{REAL}, even if $n = 0$).

\fun{GEN}{powruhalf}{GEN x, ulong n}, assumes $x$ is a \typ{REAL} and returns
$x^{n/2}$ (always a \typ{REAL}, even if $n = 0$).

\fun{GEN}{powrfrac}{GEN x, long n, long d}, assumes $x$ is a \typ{REAL} and
returns $x^{n/d}$ (always a \typ{REAL}, even if $n = 0$).

\fun{GEN}{powIs}{long n} returns $I^n\in\{1,I,-1,-I\}$ (\typ{INT} for even $n$,
\typ{COMPLEX} otherwise).

\fun{ulong}{upowuu}{ulong x, ulong n}, returns $x^n$ when $< 2^\B$, and $0$
otherwise (overflow).

\fun{GEN}{sqrtremi}{GEN N, GEN *r}, returns the integer square root $S$ of
the non-negative \typ{INT}~\kbd{N} (rounded towards 0) and puts the remainder
$R$ into~\kbd{*r}. Precisely, $N = S^2 + R$ with $0\leq R \leq 2S$. If
\kbd{r} is equal to \kbd{NULL}, the remainder is not created. In the generic
case, the remainder is created after the quotient and can be disposed of
individually with \kbd{cgiv(R)}. If the remainder is $0$ set \kbd{R = gen\_0}.

Uses a divide and conquer algorithm (discrete variant of Newton iteration)
due to Paul Zimmermann (``Karatsuba Square Root'', INRIA Research Report 3805
(1999)).

\fun{GEN}{sqrti}{GEN N}, returns the integer square root $S$ of
the non-negative \typ{INT}~\kbd{N} (rounded towards 0). This is identical
to \kbd{sqrtremi(N, NULL)}.

\fun{long}{logintall}{GEN B, GEN y, GEN *ptq}
returns the floor $e$ of $\log_y B$, where $B > 0$ and $y > 1$ are integers.
If \kbd{ptq} is not \kbd{NULL}, set it to $y^e$. (Analogous to \kbd{logint0},
whithout sanity checks.)

\fun{long}{logint}{GEN B, GEN y} returns the floor $e$ of $\log_y B$, where
$B > 0$ and $y > 1$ are integers.

\subsec{GCD, extended GCD and LCM}

\fun{long}{cgcd}{long x, long y} returns the GCD of \kbd{x} and \kbd{y}.

\fun{ulong}{ugcd}{ulong x, ulong y} returns the GCD of \kbd{x} and \kbd{y}.

\fun{long}{clcm}{long x, long y} returns the LCM of \kbd{x} and \kbd{y},
provided it fits into a \kbd{long}. Silently overflows otherwise.

\fun{GEN}{gcdii}{GEN x, GEN y}, returns the GCD of the \typ{INT}s \kbd{x} and
\kbd{y}.

\fun{GEN}{lcmii}{GEN x, GEN y}, returns the LCM of the \typ{INT}s \kbd{x} and
\kbd{y}.

\fun{GEN}{bezout}{GEN a,GEN b, GEN *u,GEN *v}, returns the GCD $d$ of
\typ{INT}s \kbd{a} and \kbd{b} and sets \kbd{u}, \kbd{v} to the Bezout
coefficients such that $\kbd{au} + \kbd{bv} = d$.

\fun{long}{cbezout}{long a,long b, long *u,long *v}, returns the GCD
$d$ of \kbd{a} and \kbd{b} and sets \kbd{u}, \kbd{v} to the Bezout coefficients
such that $\kbd{au} + \kbd{bv} = d$.

\fun{GEN}{ZV_extgcd}{GEN A} given a vector of $n$ integers $A$, returns $[d,
U]$, where $d$ is the GCD of the $A[i]$ and $U$ is a matrix
in $\text{GL}_n(\Z)$ such that $AU = [0,\dots,0,D]$.

\subsec{Continued fractions and convergents}

\fun{GEN}{ZV_allpnqn}{GEN x} given $x = [a_0, ..., a_n]$ a
continued fraction from \tet{gboundcf}, $n\geq0$, return all
convergents as $[P,Q]$, where $P = [p_0,\dots,p_n]$ and $Q =
[q_0,\dots,q_n]$.

\subsec{Pseudo-random integers}
These routine return pseudo-random integers uniformly distributed in some
interval. The all use the same underlying generator which can be seeded and
restarted using \tet{getrand} and \tet{setrand}.

\fun{void}{setrand}{GEN seed} reseeds the random number generator using the
seed $n$. The seed is either a technical array output by \kbd{getrand}
or a small positive integer, used to generate deterministically a suitable
state array. For instance, running a randomized computation starting by
\kbd{setrand(1)} twice will generate the exact same output.

\fun{GEN}{getrand}{void} returns the current value of the seed used by the
pseudo-random number generator \tet{random}. Useful mainly for debugging
purposes, to reproduce a specific chain of computations. The returned value
is technical (reproduces an internal state array of type \typ{VECSMALL}),
and can only be used as an argument to \tet{setrand}.

\fun{ulong}{pari_rand}{void} returns a random $0 \leq x < 2^\B$.

\fun{long}{random_bits}{long k} returns a random $0 \leq x < 2^k$. Assumes
that $0 \leq k \leq \B$.

\fun{ulong}{random_Fl}{ulong p} returns a pseudo-random integer
in $0, 1, \dots p-1$.

\fun{GEN}{randomi}{GEN n} returns a random \typ{INT} between $0$ and $\kbd{n}
- 1$.

\fun{GEN}{randomr}{long prec} returns a random \typ{REAL} in $[0,1[$, with
precision \kbd{prec}.

\subsec{Modular operations} In this subsection, all \kbd{GEN}s are
\typ{INT}.

\fun{GEN}{Fp_red}{GEN a, GEN m} returns \kbd{a} modulo \kbd{m} (smallest
non-negative residue). (This is identical to modii).

\fun{GEN}{Fp_neg}{GEN a, GEN m} returns $-$\kbd{a} modulo \kbd{m} (smallest
non-negative residue).

\fun{GEN}{Fp_add}{GEN a, GEN b, GEN m} returns the sum of \kbd{a} and
\kbd{b} modulo \kbd{m} (smallest non-negative residue).

\fun{GEN}{Fp_sub}{GEN a, GEN b, GEN m} returns the difference of \kbd{a} and
\kbd{b} modulo \kbd{m} (smallest non-negative residue).

\fun{GEN}{Fp_center}{GEN a, GEN p, GEN pov2} assuming that \kbd{pov2} is
\kbd{shifti(p,-1)} and that \kbd{a} is between $0$ and $\kbd{p} - 1$ and,
returns the representative of \kbd{a} in the symmetric residue system.

\fun{GEN}{Fp_mul}{GEN a, GEN b, GEN m} returns the product of \kbd{a} by
\kbd{b} modulo \kbd{m} (smallest non-negative residue).

\fun{GEN}{Fp_addmul}{GEN x, GEN y, GEN z, GEN p} returns $x + yz$.

\fun{GEN}{Fp_mulu}{GEN a, ulong b, GEN m} returns the product of \kbd{a} by
\kbd{b} modulo \kbd{m} (smallest non-negative residue).

\fun{GEN}{Fp_muls}{GEN a, long b, GEN m} returns the product of \kbd{a} by
\kbd{b} modulo \kbd{m} (smallest non-negative residue).

\fun{GEN}{Fp_halve}{GEN x, GEN m} returns $z$ such that $2\*z = x$ modulo
$m$ assuming such $z$ exists.

\fun{GEN}{Fp_sqr}{GEN a, GEN m} returns $\kbd{a}^2$ modulo \kbd{m} (smallest
non-negative residue).

\fun{ulong}{Fp_powu}{GEN x, ulong n, GEN m} raises \kbd{x} to the \kbd{n}-th
power modulo \kbd{m} (smallest non-negative residue). Not memory-clean, but
suitable for \kbd{gerepileupto}.

\fun{ulong}{Fp_pows}{GEN x, long n, GEN m} raises \kbd{x} to the \kbd{n}-th
power modulo \kbd{m} (smallest non-negative residue). A negative \kbd{n} is
allowed Not memory-clean, but suitable for \kbd{gerepileupto}.

\fun{GEN}{Fp_pow}{GEN x, GEN n, GEN m} returns $\kbd{x}^\kbd{n}$
modulo \kbd{m} (smallest non-negative residue).

\fun{GEN}{Fp_powers}{GEN x, long n, GEN m} returns
$[\kbd{x}^0, \dots, \kbd{x}^\kbd{n}]$ modulo \kbd{m} as a \typ{VEC}
 (smallest non-negative residue).

\fun{GEN}{Fp_inv}{GEN a, GEN m} returns an inverse of \kbd{a} modulo \kbd{m}
(smallest non-negative residue). Raise an error if \kbd{a} is not invertible.

\fun{GEN}{Fp_invsafe}{GEN a, GEN m} as \kbd{Fp\_inv}, but return
\kbd{NULL} if \kbd{a} is not invertible.

\fun{GEN}{FpV_inv}{GEN x, GEN m} $x$ being a vector of \typ{INT}s, return
the vector of inverses of the $x[i]$ mod $m$. The routine uses Montgomery's
trick, and involves a single inversion mod $m$, plus $3(N-1)$ multiplications
for $N$ entries. The routine is not stack-clean: $2N$ integers mod $m$
are left on stack, besides the $N$ in the result.

\fun{GEN}{Fp_div}{GEN a, GEN b, GEN m} returns the quotient of \kbd{a} by
\kbd{b} modulo \kbd{m} (smallest non-negative residue). Raise an error if
\kbd{b} is not invertible.

\fun{int}{invmod}{GEN a, GEN m, GEN *g},  return $1$ if \kbd{a}
modulo \kbd{m} is invertible, else return $0$ and set
$\kbd{g} = \gcd(\kbd{a},\kbd{m})$.

In the following three functions the integer parameter \kbd{ord} can be given
either as a positive \typ{INT} $N$, or as its factorization matrix $\var{faN}$,
 or as a pair $[N,\var{faN}]$. The parameter may be omitted by setting it to
\kbd{NULL} (the value is then $p-1$).

\fun{GEN}{Fp_log}{GEN a, GEN g, GEN ord, GEN p} Let $g$ such that
$g^{ord} \equiv 1 \pmod{p}$. Return an integer $e$ such that
$a^e \equiv g \pmod{p}$. If $e$ does not exist, the result is undefined.

\fun{GEN}{Fp_order}{GEN a, GEN ord, GEN p} returns the order of the
\kbd{Fp} \kbd{a}. Assume that \kbd{ord} is a multiple of the order of
\kbd{a}.

\fun{GEN}{Fp_factored_order}{GEN a, GEN ord, GEN p} returns $[o,F]$, where $o$
is the multiplicative order of the \kbd{Fp} $a$ in $\F_p^*$, and $F$ is the
factorization of $o$. Assume that \kbd{ord} is a multiple of the order of
\kbd{a}.

\fun{int}{Fp_issquare}{GEN x, GEN p} returns $1$ if \kbd{x} is a square
modulo \kbd{p}, and $0$ otherwise.

\fun{int}{Fp_ispower}{GEN x, GEN n, GEN p} returns $1$ if \kbd{x} is an
$n$-th power modulo \kbd{p}, and $0$ otherwise.

\fun{GEN}{Fp_sqrt}{GEN x, GEN p} returns a square root of \kbd{x} modulo
\kbd{p} (the smallest non-negative residue), where \kbd{x}, \kbd{p} are
\typ{INT}s, and \kbd{p} is assumed to be prime. Return \kbd{NULL}
if \kbd{x} is not a quadratic residue modulo \kbd{p}.

\fun{GEN}{Fp_sqrtn}{GEN a, GEN n, GEN p, GEN *zn}
returns \kbd{NULL} if $a$ is not an $n$-th power residue mod $p$.
Otherwise, returns an $n$-th root of $a$; if \kbd{zn} is non-\kbd{NULL}
set it to a primitive $m$-th root of 1, $m = \gcd(p-1,n)$ allowing to compute
all $m$ solutions in $\F_p$ of the equation $x^n = a$.

\fun{GEN}{Zn_sqrt}{GEN x, GEN n} returns one of the square roots of \kbd{x}
modulo \kbd{n} (possibly not prime), where \kbd{x} is a \typ{INT} and \kbd{n}
is either a \typ{INT} or is given by its factorisation matrix.  Return
\kbd{NULL} if no such square root exist.

\fun{long}{kross}{long x, long y} returns the \idx{Kronecker symbol} $(x|y)$,
i.e.$-1$, $0$ or $1$. If \kbd{y} is an odd prime, this is the \idx{Legendre
symbol}. (Contrary to \kbd{krouu}, \kbd{kross} also supports $\kbd{y} = 0$)

\fun{long}{krouu}{ulong x, ulong y} returns the \idx{Kronecker symbol}
$(x|y)$, i.e.~$-1$, $0$ or $1$. Assumes \kbd{y} is non-zero. If \kbd{y} is an
odd prime, this is the \idx{Legendre symbol}.

\fun{long}{krois}{GEN x, long y} returns the \idx{Kronecker symbol} $(x|y)$
of \typ{INT}~x and \kbd{long}~\kbd{y}. As \kbd{kross} otherwise.

\fun{long}{kroiu}{GEN x, ulong y} returns the \idx{Kronecker symbol} $(x|y)$
of \typ{INT}~x and non-zero \kbd{ulong}~\kbd{y}. As \kbd{krouu} otherwise.

\fun{long}{krosi}{long x, GEN y} returns the \idx{Kronecker symbol} $(x|y)$
of \kbd{long}~x and \typ{INT}~\kbd{y}. As \kbd{kross} otherwise.

\fun{long}{kroui}{ulong x, GEN y} returns the \idx{Kronecker symbol} $(x|y)$
of \kbd{long}~x and \typ{INT}~\kbd{y}. As \kbd{kross} otherwise.

\fun{long}{kronecker}{GEN x, GEN y} returns the \idx{Kronecker symbol} $(x|y)$
of \typ{INT}s~x and~\kbd{y}. As \kbd{kross} otherwise.

\fun{GEN}{pgener_Fp}{GEN p} returns the smallest primitive root modulo
\kbd{p}, assuming \kbd{p} is prime.

\fun{GEN}{pgener_Zp}{GEN p} returns the smallest primitive root modulo $p^k$,
$k > 1$, assuming \kbd{p} is an odd prime.

\fun{long}{Zp_issquare}{GEN x, GEN p} returns 1 if the \typ{INT} $x$ is
a $p$-adic square, $0$ otherwise.

\fun{long}{Zn_issquare}{GEN x, GEN n} returns 1 if \typ{INT} $x$ is
a square modulo \kbd{n} (possibly not prime), where $n$ is either a \typ{INT}
or is given by its factorisation matrix. Return $0$ otherwise.

\fun{long}{Zn_ispower}{GEN x, GEN n, GEN K, GEN *py} returns 1 if \typ{INT}
$x$ is a $K$-th power modulo \kbd{n} (possibly not prime), where $n$ is
either a \typ{INT} or is given by its factorisation matrix. Return $0$
otherwise. If \kbd{py} is not \kbd{NULL}, set it to $y$ such that $y^K = x$
modulo $n$.

\fun{GEN}{pgener_Fp_local}{GEN p, GEN L}, \kbd{L} being a vector of
primes dividing $p - 1$, returns the smallest integer $x > 1$ which is a
generator of the $\ell$-Sylow of $\F_p^*$ for every $\ell$ in \kbd{L}. In
other words, $x^{(p-1)/\ell} \neq 1$ for all such $\ell$. In particular,
returns \kbd{pgener\_Fp(p)} if \kbd{L} contains all primes dividing $p - 1$.
It is not necessary, and in fact slightly inefficient, to include $\ell=2$,
since 2 is treated separately in any case, i.e. the generator obtained is
never a square.

\fun{GEN}{rootsof1_Fp}{GEN n, GEN p} returns a primitive $n$-th root modulo
the prime $p$.

\fun{GEN}{rootsof1u_Fp}{ulong n, GEN p} returns a primitive $n$-th root modulo
the prime $p$.

\fun{ulong}{rootsof1_Fl}{ulong n, ulong p} returns a primitive $n$-th root
modulo the prime $p$.

\subsec{Extending functions to vector inputs}

The following functions apply $f$ to the given arguments, recursively
if they are of vector / matrix type:

\fun{GEN}{map_proto_G}{GEN (*f)(GEN), GEN x} For instance, if $x$ is a
\typ{VEC}, return a \typ{VEC} whose components are the $f(x[i])$.

\fun{GEN}{map_proto_lG}{long (*f)(GEN), GEN x} As above, applying the
function \kbd{stoi( f() )}.

\fun{GEN}{map_proto_GL}{GEN (*f)(GEN,long), GEN x, long y}

\fun{GEN}{map_proto_lGL}{long (*f)(GEN,long), GEN x, long y}

In the last function, $f$ implements an associative binary operator, which we
extend naturally to an $n$-ary operator $f_n$ for any $n$: by convention,
$f_0() = 1$, $f_1(x) = x$, and
$$ f_n(x_1,\dots,x_n) = f( f_{n-1}(x_1,\dots,x_{n-1}), x_n)),$$
for $n \geq 2$.

\fun{GEN}{gassoc_proto}{GEN (*f)(GEN,GEN),GEN x, GEN y} If $y$ is not
\kbd{NULL}, return $f(x,y)$. Otherwise, $x$ must be of vector type, and we
return the result of $f$ applied to its components, computed using a
divide-and-conquer algorithm. More precisely, return
$$f( f(x_1,\kbd{NULL}), f(x_2,\kbd{NULL}) ),$$
where $x_1$, $x_2$ are the two halves of $x$.

\subsec{Miscellaneous arithmetic functions}

\fun{long}{bigomegau}{ulong n} returns the number of prime divisors of $n >
0$, counted with multiplicity.

\fun{ulong}{coreu}{ulong n}, unique squarefree integer $d$ dividing $n$ such
that $n/d$ is a square.

\fun{ulong}{corediscs}{long d, ulong *pt_f}, $d$ (possibly negative)
being congruent to $0$ or $1$ modulo $4$, return the fundamental
discriminant $D$ such that $d=D*f^2$ and set \kbd{*pt\_f} to $f$
(if \kbd{*pt\_f} not \kbd{NULL}).

\fun{ulong}{eulerphiu}{ulong n}, Euler's totient function of $n$.

\fun{ulong}{eulerphiu_fact}{GEN fa}, Euler's totient function of the
\kbd{ulong} $n$, where \kbd{fa} is \kbd{factoru(n)}.

\fun{long}{moebiusu}{ulong n}, Moebius $\mu$-function of $n$.

\fun{GEN}{divisorsu}{ulong n}, returns the divisors of $n$ in a
\typ{VECSMALL}, sorted by increasing order.

\fun{ulong}{divisorsu_fact}{GEN fa}, as \kbd{divisorsu(n)}
where \kbd{fa} is \kbd{factoru(n)}.

\fun{long}{omegau}{ulong n} returns the number of prime divisors of $n > 0$.

\fun{long}{uissquarefree}{ulong n} returns $1$ if \kbd{n}
is square-free, and $0$ otherwise.

\fun{ulong}{uissquarefree_fact}{GEN fa} returns \kbd{uissquarefree(n)}, where
\kbd{fa} is \kbd{factoru(n)}.

\fun{long}{uposisfundamental}{ulong x} return $1$ if $x$ is a fundamental
discriminant, and $0$ otherwise.

\fun{long}{unegisfundamental}{ulong x} return $1$ if $-x$ is a fundamental
discriminant, and $0$ otherwise.

\fun{long}{sisfundamental}{long x} return $1$ if $x$ is a fundamental
discriminant, and $0$ otherwise.

\fun{int}{uis_357_power}{ulong x, ulong *pt, ulong *mask} as \tet{is_357_power}
for \kbd{ulong} $x$.

\fun{int}{uis_357_powermod}{ulong x, ulong *mask} as \tet{uis_357_power}, but
only check for 3rd, 5th or 7th powers modulo
$211\times209\times61\times203\times117\times31\times43\times71$.

\fun{long}{uisprimepower}{ulong n, ulong *p} as \tet{isprimepower}, for
\kbd{ulong} $n$.

\fun{int}{uislucaspsp}{ulong n} returns $1$ if the \kbd{ulong} $n$ fails Lucas
compositeness test (it thus may be prime or composite), and $0$ otherwise
(proving that $n$ is composite).

\fun{ulong}{sumdigitsu}{ulong n} returns the sum of decimal digits of $u$.

\fun{GEN}{usumdivkvec}{ulong n, GEN K} $K$ being a \typ{VECSMALL} of
positive integers. Returns the vector of \kbd{sumdivk}$(n, K[i])$.

\fun{GEN}{usumdiv_fact}{GEN fa}, sum of divisors of \kbd{ulong} $n$, where
\kbd{fa} is \kbd{factoru(n)}.

\fun{GEN}{usumdivk_fact}{GEN fa, ulong k}, sum of $k$-th powers of divisors
of \kbd{ulong} $n$, where \kbd{fa} is \kbd{factoru(n)}.

\fun{GEN}{hilbertii}{GEN x, GEN y, GEN p}, returns the Hilbert symbol
$(x,y)$ at the prime $p$ (\kbd{NULL} for the place at infinity); $x$ and $y$
are \typ{INT}s.

\fun{GEN}{sumdedekind}{GEN h, GEN k} returns the Dedekind sum attached to
the \typ{INT} $h$ and $k$, $k > 0$.

\fun{GEN}{sumdedekind_coprime}{GEN h, GEN k} as \kbd{sumdedekind}, except
that $h$ and $k$ are assumed to be coprime \typ{INT}s.

\fun{GEN}{u_sumdedekind_coprime}{long h, long k}
Let $k > 0$, $0 \leq h < k$, $(h,k) = 1$. Returns $[s_1,s_2]$
in a \typ{VECSMALL}, such that $s(h,k) = (s_2 + k s_1) / (12k)$.
Requires $\max(h + k/2, k) < \kbd{LONG\_MAX}$
to avoid overflow, in particular $k \leq (2/3)\kbd{LONG\_MAX}$ is fine.

\newpage
\chapter{Level 2 kernel}

These functions deal with modular arithmetic, linear algebra and polynomials
where assumptions can be made about the types of the coefficients.

\section{Naming scheme}\label{se:level2names}
A function name is built in the following way:
$A_1\kbd{\_}\dots\kbd{\_}A_n\var{fun}$ for an operation \var{fun} with $n$
arguments of class $A_1$,\dots, $A_n$. A class name is given by a base ring
followed by a number of code letters. Base rings are among

  \kbd{Fl}: $\Z/l\Z$ where $l < 2^{\B}$ is not necessarily prime. Implemented
            using \kbd{ulong}s

  \kbd{Fp}: $\Z/p\Z$ where $p$ is a \typ{INT}, not necessarily prime.
Implemented as \typ{INT}s $z$, preferably satisfying $0 \leq z < p$.
More precisely, any \typ{INT} can be used as an \kbd{Fp}, but reduced
inputs are treated more efficiently. Outputs from \kbd{Fp}xxx routines are
reduced.

  \kbd{Fq}: $\Z[X]/(p,T(X))$, $p$ a \typ{INT}, $T$ a \typ{POL} with \kbd{Fp}
coefficients or \kbd{NULL} (in which case no reduction modulo \kbd{T} is
performed). Implemented as \typ{POL}s $z$ with \kbd{Fp} coefficients,
$\deg(z) < \deg \kbd{T}$, although $z$ a \typ{INT} is allowed for elements in
the prime field.

  \kbd{Z}:  the integers $\Z$, implemented as \typ{INT}s.

  \kbd{Zp}: the $p$-adic integers $\Z_p$, implemented as \typ{INT}s, for arbitrary $p$

  \kbd{Zl}: the $p$-adic integers $\Z_p$, implemented as \typ{INT}s, for $p< 2^{\B}$

  \kbd{z}:  the integers $\Z$, implemented using (signed) \kbd{long}s.

  \kbd{Q}:  the rational numbers $\Q$, implemented as \typ{INT}s and
\typ{FRAC}s.

  \kbd{Rg}:  a commutative ring, whose elements can be
\kbd{gadd}-ed, \kbd{gmul}-ed, etc.

\noindent Possible letters are:

  \kbd{X}: polynomial in $X$ (\typ{POL} in a fixed variable), e.g. \kbd{FpX}
           means $\Z/p\Z[X]$

  \kbd{Y}: polynomial in $Y\neq X$. This is used to resolve ambiguities.
           E.g. \kbd{FpXY} means $((\Z/p\Z)[X])[Y]$.

  \kbd{V}: vector (\typ{VEC} or \typ{COL}), treated as a line vector
  (independently of the actual type). E.g. \kbd{ZV} means $\Z^k$ for some $k$.

  \kbd{C}: vector (\typ{VEC} or \typ{COL}), treated as a column vector
  (independently of the actual type). The difference with \kbd{V} is purely
  semantic: if the result is a vector, it will be of type \typ{COL} unless
  mentioned otherwise. For instance the function \kbd{ZC\_add} receives two
  integral vectors (\typ{COL} or \typ{VEC}, possibly different types) of the
  same length and returns a \typ{COL} whose entries are the sums of the input
  coefficients.

  \kbd{M}: matrix (\typ{MAT}). E.g. \kbd{QM} means a matrix with rational
  entries

  \kbd{T}: Trees. Either a leaf or a \typ{VEC} of trees.

  \kbd{E}: point over an elliptic curve, represented
  as two-component vectors \kbd{[x,y]}, except for the  represented by the
  one-component vector \kbd{[0]}. Not all curve models are supported.

  \kbd{Q}: representative (\typ{POL}) of a class in a polynomial quotient ring.
  E.g.~an \kbd{FpXQ} belongs to $(\Z/p\Z)[X]/(T(X))$, \kbd{FpXQV} means a
  vector of such elements, etc.

  \kbd{n}: a polynomial representative (\typ{POL}) for a truncated power
  series modulo $X^n$. E.g.~an \kbd{FpXn} belongs to $(\Z/p\Z)[X]/(X^n)$,
  \kbd{FpXnV} means a vector of such elements, etc.

  \kbd{x}, \kbd{y}, \kbd{m}, \kbd{v}, \kbd{c}, \kbd{q}: as their uppercase
  counterpart, but coefficient arrays are implemented using \typ{VECSMALL}s,
  which coefficient understood as \kbd{ulong}s.

  \kbd{x} and \kbd{y} (and \kbd{q}) are implemented by a \typ{VECSMALL} whose
  first coefficient is used as a code-word and the following are the
  coefficients , similarly to a \typ{POL}. This is known as a 'POLSMALL'.

  \kbd{m} are implemented by a \typ{MAT} whose components (columns) are
  \typ{VECSMALL}s. This is known as a 'MATSMALL'.

  \kbd{v} and \kbd{c} are regular \typ{VECSMALL}s. Difference between the
  two is purely semantic.

\noindent Omitting the letter means the argument is a scalar in the base
ring. Standard functions \var{fun} are

  \kbd{add}: add

  \kbd{sub}: subtract

  \kbd{mul}: multiply

  \kbd{sqr}: square

  \kbd{div}: divide (Euclidean quotient)

  \kbd{rem}: Euclidean remainder

  \kbd{divrem}: return Euclidean quotient, store remainder in a pointer
argument. Three special values of that pointer argument modify the default
behavior: \kbd{NULL} (do not store the remainder, used to implement
\kbd{div}), \tet{ONLY_REM} (return the remainder, used to implement
\kbd{rem}), \tet{ONLY_DIVIDES} (return the quotient if the division is exact,
and \kbd{NULL} otherwise).

  \kbd{gcd}: GCD

  \kbd{extgcd}: return GCD, store Bezout coefficients in pointer arguments

  \kbd{pow}: exponentiate

  \kbd{eval}: evaluation / composition


\section{Modular arithmetic}

\noindent These routines implement univariate polynomial arithmetic and
linear algebra over finite fields, in fact over finite rings of the form
$(\Z/p\Z)[X]/(T)$, where $p$ is not necessarily prime and $T\in(\Z/p\Z)[X]$ is
possibly reducible; and finite extensions thereof. All this can be emulated
with \typ{INTMOD} and \typ{POLMOD} coefficients and using generic routines,
at a considerable loss of efficiency. Also, specialized routines are
available that have no obvious generic equivalent.

\subsec{\kbd{FpC} / \kbd{FpV}, \kbd{FpM}} A \kbd{ZV}
(resp.~a~\kbd{ZM}) is a \typ{VEC} or \typ{COL} (resp.~\typ{MAT}) with
\typ{INT} coefficients. An \kbd{FpV} or \kbd{FpM}, with respect to a given
\typ{INT}~\kbd{p}, is the same with \kbd{Fp} coordinates; operations are
understood over $\Z/p\Z$.

\subsubsec{Conversions}

\fun{int}{Rg_is_Fp}{GEN z, GEN *p}, checks if \kbd{z} can be mapped to
$\Z/p\Z$: a \typ{INT} or a \typ{INTMOD} whose modulus is equal to \kbd{*p},
(if \kbd{*p} not \kbd{NULL}), in that case return $1$, else $0$. If a modulus
is found it is put in \kbd{*p}, else \kbd{*p} is left unchanged.

\fun{int}{RgV_is_FpV}{GEN z, GEN *p}, \kbd{z} a \typ{VEC} (resp. \typ{COL}),
checks if it can be mapped to a \kbd{FpV} (resp. \kbd{FpC}), by checking
\kbd{Rg\_is\_Fp} coefficientwise.

\fun{int}{RgM_is_FpM}{GEN z, GEN *p}, \kbd{z} a \typ{MAT},
checks if it can be mapped to a \kbd{FpM}, by checking \kbd{RgV\_is\_FpV}
columnwise.

\fun{GEN}{Rg_to_Fp}{GEN z, GEN p}, \kbd{z} a scalar which can be mapped to
$\Z/p\Z$: a \typ{INT}, a \typ{INTMOD} whose modulus is divisible by $p$,
a \typ{FRAC} whose denominator is coprime to $p$, or a \typ{PADIC} with
underlying prime $\ell$ satisfying $p = \ell^n$ for some $n$ (less than the
accuracy of the input). Returns \kbd{lift(z * Mod(1,p))}, normalized.

\fun{GEN}{padic_to_Fp}{GEN x, GEN p} special case of \tet{Rg_to_Fp},
for a $x$ a \typ{PADIC}.

\fun{GEN}{RgV_to_FpV}{GEN z, GEN p}, \kbd{z} a \typ{VEC} or \typ{COL},
returns the \kbd{FpV} (as a \typ{VEC}) obtained by applying \kbd{Rg\_to\_Fp}
coefficientwise.

\fun{GEN}{RgC_to_FpC}{GEN z, GEN p}, \kbd{z} a \typ{VEC} or \typ{COL},
returns the \kbd{FpC} (as a \typ{COL}) obtained by applying \kbd{Rg\_to\_Fp}
coefficientwise.

\fun{GEN}{RgM_to_FpM}{GEN z, GEN p}, \kbd{z} a \typ{MAT},
returns the \kbd{FpM} obtained by applying \kbd{RgC\_to\_FpC}
columnwise.

\fun{GEN}{RgM_Fp_init}{GEN z, GEN p, ulong *pp}, given an \kbd{RgM} $z$,
whose entries can be mapped to $\F_p$ (as per \tet{Rg_to_Fp}), and a prime
number $p$. This routine returns a normal form of $z$: either an
\kbd{F2m} ($p = 2$), an \kbd{Flm} ($p$ fits into an \kbd{ulong})
or an \kbd{FpM}. In the first two cases, \kbd{pp} is set to \kbd{itou}$(p)$,
and to $0$ in the last.


The functions above are generally used as follow:
\bprog
GEN add(GEN x, GEN y)
{
  GEN p = NULL;
  if (Rg_is_Fp(x, &p) && Rg_is_Fp(y, &p) && p)
  {
    x = Rg_to_Fp(x, p); y = Rg_to_Fp(y, p);
    z = Fp_add(x, y, p);
    return Fp_to_mod(z);
  }
  else return gadd(x, y);
}
@eprog

\fun{GEN}{FpC_red}{GEN z, GEN p}, \kbd{z} a \kbd{ZC}. Returns \kbd{lift(Col(z) *
Mod(1,p))}, hence a \typ{COL}.

\fun{GEN}{FpV_red}{GEN z, GEN p}, \kbd{z} a \kbd{ZV}. Returns \kbd{lift(Vec(z) *
Mod(1,p))}, hence a \typ{VEC}

\fun{GEN}{FpM_red}{GEN z, GEN p}, \kbd{z} a \kbd{ZM}. Returns \kbd{lift(z *
Mod(1,p))}, which is an \kbd{FpM}.

\subsubsec{Basic operations}

\fun{GEN}{FpC_center}{GEN z, GEN p, GEN pov2} returns a \typ{COL} whose
entries are the \kbd{Fp\_center} of the \kbd{gel(z,i)}.

\fun{GEN}{FpM_center}{GEN z, GEN p, GEN pov2} returns a matrix whose
entries are the \kbd{Fp\_center} of the \kbd{gcoeff(z,i,j)}.

\fun{void}{FpC_center_inplace}{GEN z, GEN p, GEN pov2}
in-place version of \kbd{FpC\_center}, using \kbd{affii}.

\fun{void}{FpM_center_inplace}{GEN z, GEN p, GEN pov2}
in-place version of \kbd{FpM\_center}, using \kbd{affii}.

\fun{GEN}{FpC_add}{GEN x, GEN y, GEN p} adds the \kbd{ZC} $x$ and $y$
and reduce modulo $p$ to obtain an \kbd{FpC}.

\fun{GEN}{FpV_add}{GEN x, GEN y, GEN p} same as \kbd{FpC\_add}, returning and
\kbd{FpV}.

\fun{GEN}{FpM_add}{GEN x, GEN y, GEN p} adds the two \kbd{ZM}s~\kbd{x}
and \kbd{y} (assumed to have compatible dimensions), and reduce modulo
\kbd{p} to obtain an \kbd{FpM}.

\fun{GEN}{FpC_sub}{GEN x, GEN y, GEN p} subtracts the \kbd{ZC} $y$ to
the \kbd{ZC} $x$ and reduce modulo $p$ to obtain an \kbd{FpC}.

\fun{GEN}{FpV_sub}{GEN x, GEN y, GEN p} same as \kbd{FpC\_sub}, returning and
\kbd{FpV}.

\fun{GEN}{FpM_sub}{GEN x, GEN y, GEN p} subtracts the two \kbd{ZM}s~\kbd{x}
and \kbd{y} (assumed to have compatible dimensions), and reduce modulo
\kbd{p} to obtain an \kbd{FpM}.

\fun{GEN}{FpC_Fp_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{ZC}~\kbd{x}
(seen as a column vector) by the \typ{INT}~\kbd{y} and reduce modulo \kbd{p} to
obtain an \kbd{FpC}.

\fun{GEN}{FpM_Fp_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{ZM}~\kbd{x}
(seen as a column vector) by the \typ{INT}~\kbd{y} and reduce modulo \kbd{p} to
obtain an \kbd{FpM}.

\fun{GEN}{FpC_FpV_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{ZC}~\kbd{x}
(seen as a column vector) by the \kbd{ZV}~\kbd{y} (seen as a row vector,
assumed to have compatible dimensions), and reduce modulo \kbd{p} to obtain
an \kbd{FpM}.

\fun{GEN}{FpM_mul}{GEN x, GEN y, GEN p} multiplies the two \kbd{ZM}s~\kbd{x}
and \kbd{y} (assumed to have compatible dimensions), and reduce modulo
\kbd{p} to obtain an \kbd{FpM}.

\fun{GEN}{FpM_powu}{GEN x, ulong n, GEN p} computes $x^n$ where $x$ is a
square \kbd{FpM}.

\fun{GEN}{FpM_FpC_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{ZM}~\kbd{x}
by the \kbd{ZC}~\kbd{y} (seen as a column vector, assumed to have compatible
dimensions), and reduce modulo \kbd{p} to obtain an \kbd{FpC}.

\fun{GEN}{FpM_FpC_mul_FpX}{GEN x, GEN y, GEN p, long v} is a memory-clean
version of
\bprog
  GEN tmp = FpM_FpC_mul(x,y,p);
  return RgV_to_RgX(tmp, v);
@eprog

\fun{GEN}{FpV_FpC_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{ZV}~\kbd{x}
(seen as a row vector) by the \kbd{ZC}~\kbd{y} (seen as a column vector,
assumed to have compatible dimensions), and reduce modulo \kbd{p} to obtain
an \kbd{Fp}.

\fun{GEN}{FpV_dotproduct}{GEN x,GEN y,GEN p} scalar product of
$x$ and $y$ (assumed to have the same length).

\fun{GEN}{FpV_dotsquare}{GEN x, GEN p} scalar product of $x$ with itself.
has \typ{INT} entries.

\fun{GEN}{FpV_factorback}{GEN L, GEN e, GEN p} given an \kbd{FpV} $L$
and a \kbd{ZV} $e$ of the same length, return $\prod_i L_i^{e_i}$ modulo $p$.

\subsubsec{\kbd{Fp}-linear algebra} The implementations are not
asymptotically efficient ($O(n^3)$ standard algorithms).

\fun{GEN}{FpM_deplin}{GEN x, GEN p} returns a non-trivial kernel vector,
or \kbd{NULL} if none exist.

\fun{GEN}{FpM_det}{GEN x, GEN p} as \kbd{det}

\fun{GEN}{FpM_gauss}{GEN a, GEN b, GEN p} as \kbd{gauss}, where $b$ is a
\kbd{FpM}.

\fun{GEN}{FpM_FpC_gauss}{GEN a, GEN b, GEN p} as \kbd{gauss}, where $b$
is a \kbd{FpC}.

\fun{GEN}{FpM_image}{GEN x, GEN p} as \kbd{image}

\fun{GEN}{FpM_intersect}{GEN x, GEN y, GEN p} as \kbd{intersect}

\fun{GEN}{FpM_inv}{GEN x, GEN p} returns a left inverse of \kbd{x}
(the inverse if $x$ is square), or \kbd{NULL} if \kbd{x} is not invertible.

\fun{GEN}{FpM_FpC_invimage}{GEN A, GEN y, GEN p}
 given an \kbd{FpM} $A$ and an \kbd{FpC} $y$, returns an $x$ such that $Ax =
 y$, or \kbd{NULL} if no such vector exist.

\fun{GEN}{FpM_invimage}{GEN A, GEN y, GEN p}
given two \kbd{FpM} $A$ and $y$, returns $x$ such that $Ax = y$, or \kbd{NULL}
if no such matrix exist.

\fun{GEN}{FpM_ker}{GEN x, GEN p} as \kbd{ker}

\fun{long}{FpM_rank}{GEN x, GEN p} as \kbd{rank}

\fun{GEN}{FpM_indexrank}{GEN x, GEN p} as \kbd{indexrank}

\fun{GEN}{FpM_suppl}{GEN x, GEN p} as \kbd{suppl}

\fun{GEN}{FpM_hess}{GEN x, GEN p} upper Hessenberg form of $x$ over $\F_p$.

\fun{GEN}{FpM_charpoly}{GEN x, GEN p} characteristic polynomial of $x$.

\subsubsec{\kbd{FqC}, \kbd{FqM} and \kbd{Fq}-linear algebra}

An \kbd{FqM} (resp. \kbd{FqC}) is a matrix (resp a \typ{COL}) with
\kbd{Fq} coefficients (with respect to given \kbd{T}, \kbd{p}), not necessarily
reduced (i.e arbitrary \typ{INT}s and \kbd{ZX}s in the same variable as
\kbd{T}).

\fun{GEN}{FqC_add}{GEN a, GEN b, GEN T, GEN p}

\fun{GEN}{FqC_sub}{GEN a, GEN b, GEN T, GEN p}

\fun{GEN}{FqC_Fq_mul}{GEN a, GEN b, GEN T, GEN p}

\fun{GEN}{FqM_deplin}{GEN x, GEN T, GEN p} returns a non-trivial kernel vector,
or \kbd{NULL} if none exist.

\fun{GEN}{FqM_gauss}{GEN a, GEN b, GEN T, GEN p}
as \kbd{gauss}, where $b$ is a \kbd{FqM}.

\fun{GEN}{FqM_FqC_gauss}{GEN a, GEN b, GEN T, GEN p}
as \kbd{gauss}, where $b$ is a \kbd{FqC}.

\fun{GEN}{FqM_FqC_mul}{GEN a, GEN b, GEN T, GEN p}

\fun{GEN}{FqM_ker}{GEN x, GEN T, GEN p} as \kbd{ker}

\fun{GEN}{FqM_image}{GEN x, GEN T, GEN p} as \kbd{image}

\fun{GEN}{FqM_inv}{GEN x, GEN T, GEN p} returns the inverse of \kbd{x}, or
\kbd{NULL} if \kbd{x} is not invertible.

\fun{GEN}{FqM_mul}{GEN a, GEN b, GEN T, GEN p}

\fun{long}{FqM_rank}{GEN x, GEN T, GEN p} as \kbd{rank}

\fun{GEN}{FqM_suppl}{GEN x, GEN T, GEN p} as \kbd{suppl}

\fun{GEN}{FqM_det}{GEN x, GEN T, GEN p} as \kbd{det}


\subsec{\kbd{Flc} / \kbd{Flv}, \kbd{Flm}} See \kbd{FpV}, \kbd{FpM}
operations.

\fun{GEN}{Flv_copy}{GEN x} returns a copy of \kbd{x}.

\fun{GEN}{Flv_center}{GEN z, ulong p, ulong ps2}

\fun{GEN}{Flm_copy}{GEN x} returns a copy of \kbd{x}.

\fun{GEN}{matid_Flm}{long n} returns an \kbd{Flm} which is an $n \times n$
identity matrix.

\fun{GEN}{scalar_Flm}{long s, long n} returns an \kbd{Flm} which is $s$ times
the $n \times n$ identity matrix.

\fun{GEN}{Flm_center}{GEN z, ulong p, ulong ps2}

\fun{GEN}{Flm_Fl_add}{GEN x, ulong y, ulong p} returns $x + y*\text{Id}$
($x$ must be square).

\fun{GEN}{Flm_Flc_mul}{GEN x, GEN y, ulong p} multiplies  \kbd{x} and \kbd{y}
(assumed to have compatible dimensions).

\fun{GEN}{Flm_Flc_mul_pre}{GEN x, GEN y, ulong p, ulong pi} multiplies  \kbd{x}
and \kbd{y} (assumed to have compatible dimensions), assuming $pi$ is the
pseudo inverse of $p$.

\fun{GEN}{Flm_Flc_mul_pre_Flx}{GEN x, GEN y, ulong p, ulong pi, long sv}
return \kbd{Flv\_to\_Flx(Flm\_Flc\_mul\_pre(x, y, p, pi), sv)}.

\fun{GEN}{Flm_Fl_mul}{GEN x, ulong y, ulong p} multiplies the \kbd{Flm}
\kbd{x} by \kbd{y}.

\fun{GEN}{Flm_neg}{GEN x, ulong p} negates the \kbd{Flm} \kbd{x}.

\fun{void}{Flm_Fl_mul_inplace}{GEN x, ulong y, ulong p} replaces
the \kbd{Flm} \kbd{x} by $\kbd{x}*\kbd{y}$.

\fun{GEN}{Flv_Fl_mul}{GEN x, ulong y, ulong p} multiplies the \kbd{Flv}
\kbd{x} by \kbd{y}.

\fun{void}{Flv_Fl_mul_inplace}{GEN x, ulong y, ulong p} replaces
the \kbd{Flc} \kbd{x} by $\kbd{x}*\kbd{y}$.

\fun{void}{Flv_Fl_mul_part_inplace}{GEN x, ulong y, ulong p, long l}
multiplies $x[1..l]$ by $y$ modulo $p$. In place.

\fun{GEN}{Flv_Fl_div}{GEN x, ulong y, ulong p} divides the \kbd{Flv}
\kbd{x} by \kbd{y}.

\fun{void}{Flv_Fl_div_inplace}{GEN x, ulong y, ulong p} replaces
the \kbd{Flv} \kbd{x} by $\kbd{x}/\kbd{y}$.

\fun{void}{Flc_lincomb1_inplace}{GEN X, GEN Y, ulong v, ulong q}
sets $X\leftarrow X + vY$, where $X,Y$ are \kbd{Flc}. Memory efficient (e.g.
no-op if $v = 0$), and gerepile-safe.

\fun{GEN}{Flv_add}{GEN x, GEN y, ulong p} adds two \kbd{Flv}.

\fun{void}{Flv_add_inplace}{GEN x, GEN y, ulong p} replaces
$x$ by $x+y$.

\fun{GEN}{Flv_neg}{GEN x, ulong p} returns $-x$.

\fun{void}{Flv_neg_inplace}{GEN x, ulong p} replaces $x$ by $-x$.

\fun{GEN}{Flv_sub}{GEN x, GEN y, ulong p} subtracts \kbd{y} to \kbd{x}.

\fun{void}{Flv_sub_inplace}{GEN x, GEN y, ulong p} replaces $x$ by $x-y$.

\fun{ulong}{Flv_dotproduct}{GEN x, GEN y, ulong p} returns the scalar product
of \kbd{x} and \kbd{y}

\fun{ulong}{Flv_dotproduct_pre}{GEN x, GEN y, ulong p} returns the scalar product
of \kbd{x} and \kbd{y} assuming $pi$ is the pseudo inverse of $p$.

\fun{ulong}{Flv_sum}{GEN x, ulong p} returns the sum of the components of $x$.

\fun{ulong}{Flv_prod}{GEN x, ulong p} returns the product of the components of
$x$.

\fun{ulong}{Flv_prod_pre}{GEN x, ulong p, ulong pi} as \kbd{Flv\_prod}
assuming $pi$ is the pseudo inverse of $p$.

\fun{GEN}{Flv_inv}{GEN x, ulong p} returns the vector of inverses of the elements
of $x$ (as a \kbd{Flv}). Use Montgomery trick.

\fun{void}{Flv_inv_inplace}{GEN x, ulong p} in place variant of \kbd{Flv\_inv}.

\fun{GEN}{Flv_inv_pre}{GEN x, ulong p, ulong pi} as \kbd{Flv\_inv}
assuming $pi$ is the pseudo inverse of $p$.

\fun{void}{Flv_inv_pre_inplace}{GEN x, ulong p, ulong pi} in place variant of
\kbd{Flv\_inv}.

\fun{GEN}{zero_Flm}{long m, long n} creates a \kbd{Flm} with \kbd{m} x \kbd{n}
components set to $0$. Note that the result allocates a
\emph{single} column, so modifying an entry in one column modifies it in
all columns.

\fun{GEN}{zero_Flm_copy}{long m, long n} creates a \kbd{Flm} with \kbd{m} x
\kbd{n} components set to $0$.

\fun{GEN}{zero_Flv}{long n} creates a \kbd{Flv} with \kbd{n} components set to
$0$.

\fun{GEN}{Flm_row}{GEN A, long x0} return $A[i,]$, the $i$-th row of the
\kbd{Flm} $A$.

\fun{GEN}{Flm_add}{GEN x, GEN y, ulong p} adds \kbd{x} and \kbd{y}
(assumed to have compatible dimensions).

\fun{GEN}{Flm_sub}{GEN x, GEN y, ulong p} subtracts \kbd{x} and \kbd{y}
(assumed to have compatible dimensions).

\fun{GEN}{Flm_mul}{GEN x, GEN y, ulong p} multiplies  \kbd{x} and \kbd{y}
(assumed to have compatible dimensions).

\fun{GEN}{Flm_powu}{GEN x, ulong n, ulong p} computes $x^n$ where $x$ is a
square \kbd{Flm}.

\fun{GEN}{Flm_charpoly}{GEN x, ulong p} return the characteristic polynomial of
the square \kbd{Flm} $x$, as a \kbd{Flx}.

\fun{GEN}{Flm_deplin}{GEN x, ulong p}

\fun{ulong}{Flm_det}{GEN x, ulong p}

\fun{ulong}{Flm_det_sp}{GEN x, ulong p}, as \kbd{Flm\_det}, in place
(destroys~\kbd{x}).

\fun{GEN}{Flm_gauss}{GEN a, GEN b, ulong p} as \kbd{gauss}, where $b$ is a
\kbd{Flm}.

\fun{GEN}{Flm_Flc_gauss}{GEN a, GEN b, ulong p} as \kbd{gauss}, where $b$ is
a \kbd{Flc}.

\fun{GEN}{Flm_indexrank}{GEN x, ulong p}

\fun{GEN}{Flm_inv}{GEN x, ulong p}

\fun{GEN}{Flm_Flc_invimage}{GEN A, GEN y, ulong p} given an \kbd{Flm}
$A$ and an \kbd{Flc} $y$, returns an $x$ such that $Ax = y$, or \kbd{NULL}
if no such vector exist.

\fun{GEN}{Flm_invimage}{GEN A, GEN y, ulong p}
given two \kbd{Flm} $A$ and $y$, returns $x$ such that $Ax = y$, or \kbd{NULL}
if no such matrix exist.

\fun{GEN}{Flm_ker}{GEN x, ulong p}

\fun{GEN}{Flm_ker_sp}{GEN x, ulong p, long deplin}, as \kbd{Flm\_ker} (if
\kbd{deplin=0}) or \kbd{Flm\_deplin} (if \kbd{deplin=1}) , in place
(destroys~\kbd{x}).

\fun{long}{Flm_rank}{GEN x, ulong p}

\fun{long}{Flm_suppl}{GEN x, ulong p}

\fun{GEN}{Flm_image}{GEN x, ulong p}

\fun{GEN}{Flm_intersect}{GEN x, GEN y, ulong p}

\fun{GEN}{Flm_transpose}{GEN x}

\fun{GEN}{Flm_hess}{GEN x, ulong p} upper Hessenberg form of $x$ over $\F_p$.

\subsec{\kbd{F2c} / \kbd{F2v}, \kbd{F2m}}  An \kbd{F2v}~\kbd{v} is a
\typ{VECSMALL} representing a vector over $\F_2$. Specifically \kbd{z[0]} is
the usual codeword, \kbd{z[1]} is the number of components of $v$ and the
coefficients are given by the bits of remaining words by increasing indices.

\fun{ulong}{F2v_coeff}{GEN x, long i} returns the coefficient $i\ge 1$ of $x$.

\fun{void}{F2v_clear}{GEN x, long i} sets the coefficient $i\ge 1$ of $x$ to
$0$.

\fun{void}{F2v_flip}{GEN x, long i} adds $1$ to the coefficient $i\ge 1$ of $x$.

\fun{void}{F2v_set}{GEN x, long i} sets the coefficient $i\ge 1$ of $x$ to $1$.

\fun{void}{F2v_copy}{GEN x} returns a copy of $x$.

\fun{GEN}{F2v_slice}{GEN x, long a, long b} returns the \kbd{F2v} with
entries $x[a]$, \dots, $x[b]$. Assumes $a \leq b$.

\fun{ulong}{F2m_coeff}{GEN x, long i, long j} returns the coefficient $(i,j)$
of $x$.

\fun{void}{F2m_clear}{GEN x, long i, long j} sets the coefficient $(i,j)$ of $x$
to $0$.

\fun{void}{F2m_flip}{GEN x, long i, long j} adds $1$ to the coefficient $(i,j)$
of $x$.

\fun{void}{F2m_set}{GEN x, long i, long j} sets the coefficient $(i,j)$ of $x$
to $1$.

\fun{void}{F2m_copy}{GEN x} returns a copy of $x$.

\fun{GEN}{F2m_rowslice}{GEN x, long a, long b} returns the \kbd{F2m} built
from the $a$-th to $b$-th rows of the \kbd{F2m} $x$. Assumes $a \leq b$.

\fun{GEN}{F2m_F2c_mul}{GEN x, GEN y} multiplies  \kbd{x} and \kbd{y} (assumed
to have compatible dimensions).

\fun{GEN}{F2m_image}{GEN x} gives a subset of the columns of $x$ that generate
the image of $x$.

\fun{GEN}{F2m_invimage}{GEN A, GEN B}

\fun{GEN}{F2m_F2c_invimage}{GEN A, GEN y}

\fun{GEN}{F2m_gauss}{GEN a, GEN b}
as \kbd{gauss}, where $b$ is a \kbd{F2m}.

\fun{GEN}{F2m_F2c_gauss}{GEN a, GEN b}
as \kbd{gauss}, where $b$ is a \kbd{F2c}.


\fun{GEN}{F2m_indexrank}{GEN x} $x$ being a matrix of rank $r$, returns a
vector with two \typ{VECSMALL} components $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 two vectors using \kbd{vecextract}$(x,y,z)$ is
invertible.

\fun{GEN}{F2m_mul}{GEN x, GEN y} multiplies  \kbd{x} and \kbd{y} (assumed to
have compatible dimensions).

\fun{GEN}{F2m_powu}{GEN x, ulong n} computes $x^n$ where $x$ is a square
\kbd{F2m}.

\fun{long}{F2m_rank}{GEN x} as \kbd{rank}.

\fun{long}{F2m_suppl}{GEN x} as \kbd{suppl}.

\fun{GEN}{matid_F2m}{long n} returns an \kbd{F2m} which is an $n \times n$
identity matrix.

\fun{GEN}{zero_F2v}{long n} creates a \kbd{F2v} with \kbd{n} components set to
$0$.

\fun{GEN}{const_F2v}{long n} creates a \kbd{F2v} with \kbd{n} components set to
$1$.

\fun{GEN}{F2v_ei}{long n, long i} creates a \kbd{F2v} with \kbd{n} components
set to $0$, but for the $i$-th one, which is set to $1$ ($i$-th vector in the
canonical basis).

\fun{GEN}{zero_F2m}{long m, long n} creates a \kbd{Flm} with \kbd{m} x \kbd{n}
components set to $0$. Note that the result allocates a
\emph{single} column, so modifying an entry in one column modifies it in
all columns.

\fun{GEN}{zero_F2m_copy}{long m, long n} creates a \kbd{F2m} with \kbd{m} x
\kbd{n} components set to $0$.

\fun{GEN}{F2v_to_Flv}{GEN x}

\fun{GEN}{F2c_to_ZC}{GEN x}

\fun{GEN}{ZV_to_F2v}{GEN x}

\fun{GEN}{RgV_to_F2v}{GEN x}

\fun{GEN}{F2m_to_Flm}{GEN x}

\fun{GEN}{F2m_to_ZM}{GEN x}

\fun{GEN}{Flv_to_F2v}{GEN x}

\fun{GEN}{Flm_to_F2m}{GEN x}

\fun{GEN}{ZM_to_F2m}{GEN x}

\fun{GEN}{RgM_to_F2m}{GEN x}

\fun{void}{F2v_add_inplace}{GEN x, GEN y} replaces $x$ by $x+y$. It is
allowed for $y$ to be shorter than $x$.

\fun{ulong}{F2m_det}{GEN x}

\fun{ulong}{F2m_det_sp}{GEN x}, as \kbd{F2m\_det}, in place (destroys~\kbd{x}).

\fun{GEN}{F2m_deplin}{GEN x}

\fun{ulong}{F2v_dotproduct}{GEN x, GEN y} returns the scalar product of \kbd{x}
and \kbd{y}

\fun{GEN}{F2m_inv}{GEN x}

\fun{GEN}{F2m_ker}{GEN x}

\fun{GEN}{F2m_ker_sp}{GEN x, long deplin}, as \kbd{F2m\_ker} (if
\kbd{deplin=0}) or \kbd{F2m\_deplin} (if \kbd{deplin=1}), in place
(destroys~\kbd{x}).

\subsec{\kbd{FlxqV}, \kbd{FlxqM}} See \kbd{FqV}, \kbd{FqM} operations.

\fun{GEN}{FlxqV_dotproduct}{GEN x, GEN y, GEN T, ulong p} as
\kbd{FpV\_dotproduct}.

\fun{GEN}{FlxM_Flx_add_shallow}{GEN x, GEN y, ulong p} as
\kbd{RgM\_Rg\_add\_shallow}.

\fun{GEN}{FlxqM_gauss}{GEN a, GEN b, GEN T, ulong p}

\fun{GEN}{FlxqM_FlxqC_gauss}{GEN a, GEN b, GEN T, ulong p}

\fun{GEN}{FlxqM_FlxqC_mul}{GEN a, GEN b, GEN T, ulong p}

\fun{GEN}{FlxqM_ker}{GEN x, GEN T, ulong p}

\fun{GEN}{FlxqM_image}{GEN x, GEN T, ulong p}

\fun{GEN}{FlxqM_det}{GEN a, GEN T, ulong p}

\fun{GEN}{FlxqM_inv}{GEN x, GEN T, ulong p}

\fun{GEN}{FlxqM_mul}{GEN a, GEN b, GEN T, ulong p}

\fun{long}{FlxqM_rank}{GEN x, GEN T, ulong p}

\fun{GEN}{matid_FlxqM}{long n, GEN T, ulong p}

\subsec{\kbd{FpX}} Let \kbd{p} an understood \typ{INT}, to be given in
the function arguments; in practice \kbd{p} is not assumed to be prime, but
be wary. Recall than an \kbd{Fp} object is a \typ{INT}, preferably belonging
to $[0, \kbd{p}-1]$; an \kbd{FpX} is a \typ{POL} in a fixed variable whose
coefficients are \kbd{Fp} objects. Unless mentioned otherwise, all outputs in
this section are \kbd{FpX}s. All operations are understood to take place in
$(\Z/\kbd{p}\Z)[X]$.

\subsubsec{Conversions} In what follows \kbd{p} is always a \typ{INT},
not necessarily prime.

\fun{int}{RgX_is_FpX}{GEN z, GEN *p}, \kbd{z} a \typ{POL},
checks if it can be mapped to a \kbd{FpX}, by checking \kbd{Rg\_is\_Fp}
coefficientwise.

\fun{GEN}{RgX_to_FpX}{GEN z, GEN p}, \kbd{z} a \typ{POL}, returns the
\kbd{FpX} obtained by applying \kbd{Rg\_to\_Fp} coefficientwise.

\fun{GEN}{FpX_red}{GEN z, GEN p}, \kbd{z} a \kbd{ZX}, returns \kbd{lift(z *
Mod(1,p))}, normalized.

\fun{GEN}{FpXV_red}{GEN z, GEN p}, \kbd{z} a \typ{VEC} of \kbd{ZX}. Applies
\kbd{FpX\_red} componentwise and returns the result (and we obtain a vector
of \kbd{FpX}s).

\fun{GEN}{FpXT_red}{GEN z, GEN p}, \kbd{z} a tree of \kbd{ZX}. Applies
\kbd{FpX\_red} to each leaf and returns the result (and we obtain a tree
of \kbd{FpX}s).

\subsubsec{Basic operations} In what follows \kbd{p} is always a \typ{INT},
not necessarily prime.

\noindent Now, except for \kbd{p}, the operands and outputs are all \kbd{FpX}
objects. Results are undefined on other inputs.

\fun{GEN}{FpX_add}{GEN x,GEN y, GEN p} adds \kbd{x} and \kbd{y}.

\fun{GEN}{FpX_neg}{GEN x,GEN p} returns $-\kbd{x}$, the components are
between $0$ and $p$ if this is the case for the components of $x$.

\fun{GEN}{FpX_renormalize}{GEN x, long l}, as \kbd{normalizepol}, where
$\kbd{l} = \kbd{lg(x)}$, in place.

\fun{GEN}{FpX_sub}{GEN x,GEN y,GEN p} returns $x-y$.

\fun{GEN}{FpX_halve}{GEN x, GEN m} returns $z$ such that $2\*z = x$ modulo
$m$ assuming such $z$ exists.

\fun{GEN}{FpX_mul}{GEN x,GEN y,GEN p} returns $x\*y$.

\fun{GEN}{FpX_mulspec}{GEN a, GEN b, GEN p, long na, long nb}
see \kbd{ZX\_mulspec}

\fun{GEN}{FpX_sqr}{GEN x,GEN p} returns $\kbd{x}^2$.

\fun{GEN}{FpX_powu}{GEN x, ulong n, GEN p} returns $x^n$.

\fun{GEN}{FpX_divrem}{GEN x, GEN y, GEN p, GEN *pr} returns the quotient
of \kbd{x} by \kbd{y}, and sets \kbd{pr} to the remainder.

\fun{GEN}{FpX_div}{GEN x, GEN y, GEN p} returns the quotient of \kbd{x} by
\kbd{y}.

\fun{GEN}{FpX_div_by_X_x}{GEN A, GEN a, GEN p, GEN *r} returns the
quotient of the \kbd{FpX}~\kbd{A} by $(X - \kbd{a})$, and sets \kbd{r} to the
remainder $\kbd{A}(\kbd{a})$.

\fun{GEN}{FpX_rem}{GEN x, GEN y, GEN p} returns the remainder \kbd{x} mod
\kbd{y}.

\fun{long}{FpX_valrem}{GEN x, GEN t, GEN p, GEN *r} The arguments \kbd{x} and
\kbd{e} being non-zero \kbd{FpX} returns the highest exponent $e$ such that
$\kbd{t}^{e}$ divides~\kbd{x}. The quotient $\kbd{x}/\kbd{t}^{e}$ is returned
in~\kbd{*r}. In particular, if \kbd{t} is irreducible, this returns the
valuation at \kbd{t} of~\kbd{x}, and \kbd{*r} is the prime-to-\kbd{t} part
of~\kbd{x}.

\fun{GEN}{FpX_deriv}{GEN x, GEN p} returns the derivative of \kbd{x}.
This function is not memory-clean, but nevertheless suitable for
\kbd{gerepileupto}.

\fun{GEN}{FpX_digits}{GEN x, GEN B, GEN p} returns a vector of \kbd{FpX}
$[c_0,\ldots,c_n]$ of degree less than the degree of $B$ and such that
$x=\sum_{i=0}^{n}{c_i\*B^i}$.

\fun{GEN}{FpX_fromdigits}{GEN v, GEN B, GEN p} where $v=[c_0,\ldots,c_n]$
is a vector of \kbd{FpX}, returns $\sum_{i=0}^{n}{c_i\*B^i}$.

\fun{GEN}{FpX_translate}{GEN P, GEN c, GEN p} let $c$ be an \kbd{Fp} and let
$P$ be an \kbd{FpX}; returns the translated \kbd{FpX} of $P(X+c)$.

\fun{GEN}{FpX_gcd}{GEN x, GEN y, GEN p} returns a (not necessarily monic)
greatest common divisor of $x$  and $y$.

\fun{GEN}{FpX_halfgcd}{GEN x, GEN y, GEN p} returns a two-by-two \kbd{FpXM}
$M$ with determinant $\pm 1$ such that the image $(a,b)$ of $(x,y)$ by $M$
has the property that $\deg a \geq {\deg x \over 2} > \deg b$.

\fun{GEN}{FpX_extgcd}{GEN x, GEN y, GEN p, GEN *u, GEN *v} returns
$d = \text{GCD}(\kbd{x},\kbd{y})$ (not necessarily monic), and sets \kbd{*u},
\kbd{*v} to the Bezout coefficients such that $\kbd{*ux} + \kbd{*vy} = d$.
If \kbd{*u} is set to \kbd{NULL}, it is not computed which is a bit faster.
This is useful when computing the inverse of $y$ modulo $x$.

\fun{GEN}{FpX_center}{GEN z, GEN p, GEN pov2} returns the polynomial whose
coefficient belong to the symmetric residue system. Assumes the coefficients
already belong to $[0,\kbd{p}-1]$) and \kbd{pov2} is \kbd{shifti(p,-1)}.

\fun{GEN}{FpX_Frobenius}{GEN T, GEN p} returns $X^{p}\pmod{T(X)}$.

\fun{GEN}{FpX_matFrobenius}{GEN T, GEN p} returns the matrix of the
Frobenius automorphism $x\mapsto x^p$ over the power basis of $\F_p[X]/(T)$.

\subsubsec{Mixed operations}
The following functions implement arithmetic operations between \kbd{FpX}
and \kbd{Fp} operands, the result being of type \kbd{FpX}. The integer
\kbd{p} need not be prime.

\fun{GEN}{Z_to_FpX}{GEN x, GEN p, long v} converts a \typ{INT} to a scalar
polynomial in variable $v$, reduced modulo $p$.

\fun{GEN}{FpX_Fp_add}{GEN y, GEN x, GEN p} add the \kbd{Fp}~\kbd{x} to the
\kbd{FpX}~\kbd{y}.

\fun{GEN}{FpX_Fp_add_shallow}{GEN y, GEN x, GEN p} add the \kbd{Fp}~\kbd{x}
to the \kbd{FpX}~\kbd{y}, using a shallow copy (result not suitable for
\kbd{gerepileupto})

\fun{GEN}{FpX_Fp_sub}{GEN y, GEN x, GEN p} subtract the \kbd{Fp}~\kbd{x} from
the \kbd{FpX}~\kbd{y}.

\fun{GEN}{FpX_Fp_sub_shallow}{GEN y, GEN x, GEN p} subtract the
\kbd{Fp}~\kbd{x} from the \kbd{FpX}~\kbd{y}, using a shallow copy (result not
suitable for \kbd{gerepileupto})

\fun{GEN}{Fp_FpX_sub}{GEN x,GEN y,GEN p} returns $x - y$, where $x$ is
a \typ{INT} and $y$ an \kbd{FpX}.

\fun{GEN}{FpX_Fp_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{FpX}~\kbd{x}
by the \kbd{Fp}~\kbd{y}.

\fun{GEN}{FpX_Fp_mulspec}{GEN x, GEN y, GEN p, long lx} see \kbd{ZX\_mulspec}

\fun{GEN}{FpX_mulu}{GEN x, ulong y, GEN p} multiplies the \kbd{FpX}~\kbd{x}
by \kbd{y}.

\fun{GEN}{FpX_Fp_mul_to_monic}{GEN y,GEN x,GEN p} returns $y\*x$ assuming the
result is monic of the same degree as $y$ (in particular $x\neq 0$).

\subsubsec{Miscellaneous operations}

\fun{GEN}{FpX_normalize}{GEN z, GEN p} divides the \kbd{FpX}~\kbd{z} by its
leading coefficient. If the latter is~$1$, \kbd{z} itself is returned, not a
copy. If not, the inverse remains uncollected on the stack.

\fun{GEN}{FpX_invBarrett}{GEN T, GEN p}, returns the Barrett inverse
$M$ of $T$ defined by $M(x)\*x^n\*T(1/x)\equiv 1\pmod{x^{n-1}}$ where $n$ is
the degree of $T$.

\fun{GEN}{FpX_rescale}{GEN P, GEN h, GEN p} returns $h^{\deg(P)} P(x/h)$.
\kbd{P} is an \kbd{FpX} and \kbd{h} is a non-zero \kbd{Fp} (the routine would
work with any non-zero \typ{INT} but is not efficient in this case).

\fun{GEN}{FpX_eval}{GEN x, GEN y, GEN p} evaluates the \kbd{FpX}~\kbd{x}
at the \kbd{Fp}~\kbd{y}. The result is an~\kbd{Fp}.

\fun{GEN}{FpX_FpV_multieval}{GEN P, GEN v, GEN p} returns the vector
$[P(v[1]),\ldots,P(v[n])]$ as a \kbd{FpV}.

\fun{GEN}{FpX_dotproduct}{GEN x, GEN y, GEN p} return the scalar product
$\sum_{i\geq 0} x_i\*y_i$ of the coefficients of $x$ and $y$.

\fun{GEN}{FpXV_FpC_mul}{GEN V, GEN W, GEN p} multiplies a non-empty line
vector of\kbd{FpX} by a column vector of \kbd{Fp} of compatible dimensions.
The result is an~\kbd{FpX}.

\fun{GEN}{FpXV_prod}{GEN V, GEN p}, \kbd{V} being a vector of \kbd{FpX},
returns their product.

\fun{GEN}{FpV_roots_to_pol}{GEN V, GEN p, long v}, \kbd{V} being a vector
of \kbd{INT}s, returns the monic \kbd{FpX}
$\prod_i (\kbd{pol\_x[v]} - \kbd{V[i]})$.

\fun{GEN}{FpX_chinese_coprime}{GEN x,GEN y, GEN Tx,GEN Ty, GEN Tz, GEN p}:
returns an \kbd{FpX}, congruent to \kbd{x} mod \kbd{Tx} and to \kbd{y} mod
\kbd{Ty}. Assumes \kbd{Tx} and \kbd{Ty} are coprime, and \kbd{Tz = Tx * Ty}
or \kbd{NULL} (in which case it is computed within).

\fun{GEN}{FpV_polint}{GEN x, GEN y, GEN p, long v} returns the \kbd{FpX}
interpolation polynomial with value \kbd{y[i]} at \kbd{x[i]}. Assumes lengths
are the same, components are \typ{INT}s, and the \kbd{x[i]} are distinct
modulo \kbd{p}.

\fun{GEN}{FpV_FpM_polint}{GEN x, GEN V, GEN p, long v} equivalent (but
faster) to applying \kbd{FpV\_polint(x,$\ldots$)} to all the elements of the
vector $V$ (thus, returns a \kbd{FpXV}).

\fun{GEN}{FpV_invVandermonde}{GEN L, GEN d, GEN p} $L$ being a \kbd{FpV}
of length $n$, return the inverse $M$ of the Vandermonde matrix attached to
the elements of $L$, eventually multiplied by \kbd{d} if it is not
\kbd{NULL}. If $A$ is a \kbd{FpV} and $B=M\*A$, then the polynomial
$P=\sum_{i=1}^n B[i]\*X^{i-1}$ verifies $P(L[i])=d\*A[i]$ for
$1 \leq i \leq n$.

\fun{int}{FpX_is_squarefree}{GEN f, GEN p} returns $1$ if the
\kbd{FpX}~\kbd{f} is squarefree, $0$ otherwise.

\fun{int}{FpX_is_irred}{GEN f, GEN p} returns $1$ if the \kbd{FpX}~\kbd{f}
is irreducible, $0$ otherwise. Assumes that \kbd{p} is prime. If~\kbd{f} has
few factors, \kbd{FpX\_nbfact(f,p) == 1} is much faster.

\fun{int}{FpX_is_totally_split}{GEN f, GEN p} returns $1$ if the
\kbd{FpX}~\kbd{f} splits into a product of distinct linear factors, $0$
otherwise. Assumes that \kbd{p} is prime.

\fun{GEN}{FpX_factor}{GEN f, GEN p}, factors the \kbd{FpX}~\kbd{f}. Assumes
that \kbd{p} is prime. The returned value \kbd{v} is a \typ{VEC} with two
components: \kbd{v[1]} is a vector of distinct irreducible (\kbd{FpX})
factors, and \kbd{v[2]} is a \typ{VECSMALL} of corresponding exponents. The
order of the factors is deterministic (the computation is not).

\fun{GEN}{FpX_factor_squarefree}{GEN f, GEN p} returns the squarefree
factorization of $f$ modulo $p$. This is a vector $[u_1,\dots,u_k]$
of pairwise coprime \kbd{FpX} such that $u_k \neq 1$ and $f = \prod u_i^i$.
Shallow function.

\fun{long}{FpX_nbfact}{GEN f, GEN p}, assuming the \kbd{FpX}~f is squarefree,
returns the number of its irreducible factors. Assumes that \kbd{p} is prime.

\fun{long}{FpX_nbfact_Frobenius}{GEN f, GEN XP, GEN p}, as
\kbd{FpX\_nbfact(f, p)} but faster,
where \kbd{XP} is \kbd{FpX\_Frobenius(f, p)}.

\fun{long}{FpX_degfact}{GEN f, GEN p}, as \kbd{FpX\_factor}, but the
degrees of the irreducible factors are returned instead of the factors
themselves (as a \typ{VECSMALL}). Assumes that \kbd{p} is prime.

\fun{long}{FpX_nbroots}{GEN f, GEN p} returns the number of distinct
roots in \kbd{\Z/p\Z} of the \kbd{FpX}~\kbd{f}. Assumes that \kbd{p} is prime.

\fun{GEN}{FpX_oneroot}{GEN f, GEN p} returns one root in \kbd{\Z/p\Z} of
the \kbd{FpX}~\kbd{f}. Return \kbd{NULL} if no root exists.
Assumes that \kbd{p} is prime.

\fun{GEN}{FpX_roots}{GEN f, GEN p} returns the roots in \kbd{\Z/p\Z} of
the \kbd{FpX}~\kbd{f} (without multiplicity, as a vector of \kbd{Fp}s).
Assumes that \kbd{p} is prime.

\fun{GEN}{FpX_split_part}{GEN f, GEN p} returns the largest totally split
squarefree factor of $f$.

\fun{GEN}{random_FpX}{long d, long v, GEN p} returns a random \kbd{FpX}
in variable \kbd{v}, of degree less than~\kbd{d}.

\fun{GEN}{FpX_resultant}{GEN x, GEN y, GEN p} returns the resultant
of \kbd{x} and \kbd{y}, both \kbd{FpX}. The result is a \typ{INT}
belonging to $[0,p-1]$.

\fun{GEN}{FpX_disc}{GEN x, GEN p} returns the discriminant
of the \kbd{FpX} \kbd{x}. The result is a \typ{INT} belonging to $[0,p-1]$.

\fun{GEN}{FpX_FpXY_resultant}{GEN a, GEN b, GEN p}, \kbd{a} a \typ{POL} of
\typ{INT}s (say in variable $X$), \kbd{b} a \typ{POL} (say in variable $X$)
whose coefficients are either \typ{POL}s in $\Z[Y]$ or \typ{INT}s.
Returns $\text{Res}_X(a, b)$ in $\F_p[Y]$ as an \kbd{FpY}. The function
assumes that $X$ has lower priority than $Y$.

\subsec{\kbd{FpXQ}, \kbd{Fq}} Let \kbd{p} a \typ{INT} and \kbd{T} an
\kbd{FpX} for \kbd{p}, both to be given in the function arguments; an \kbd{FpXQ}
object is an \kbd{FpX} whose degree is strictly less than the degree of
\kbd{T}. An \kbd{Fq} is either an \kbd{FpXQ} or an \kbd{Fp}. Both represent
a class in $(\Z/\kbd{p}\Z)[X] / (T)$, in which all operations below take
place. In addition, \kbd{Fq} routines also allow $\kbd{T} = \kbd{NULL}$, in
which case no reduction mod \kbd{T} is performed on the result.

For efficiency, the routines in this section may leave small unused objects
behind on the stack (their output is still suitable for \kbd{gerepileupto}).
Besides \kbd{T} and \kbd{p}, arguments are either \kbd{FpXQ} or \kbd{Fq}
depending on the function name. (All \kbd{Fq} routines accept \kbd{FpXQ}s by
definition, not the other way round.)

\subsubsec{Preconditioned reduction}

For faster reduction, the modulus \kbd{T} can be replaced by an extended
modulus, which is an \kbd{FpXT}, in all \kbd{FpXQ}- and \kbd{Fq}-classes
functions, and in \kbd{FpX\_rem} and \kbd{FpX\_divrem}.

\fun{GEN}{FpX_get_red}{GEN T, GEN p} returns the extended modulus \kbd{eT}.

To write code that works both with plain and extended moduli, the following
accessors are defined:

\fun{GEN}{get_FpX_mod}{GEN eT} returns the underlying modulus \kbd{T}.

\fun{GEN}{get_FpX_var}{GEN eT} returns the variable number of the modulus.

\fun{GEN}{get_FpX_degree}{GEN eT} returns the degree of the modulus.

Furthermore, \kbd{ZXT\_to\_FlxT} allows to convert an extended modulus for
a \kbd{FpX} to an extended modulus for the corresponding \kbd{Flx}.

\subsubsec{Conversions}

\fun{GEN}{Rg_is_FpXQ}{GEN z, GEN *T, GEN *p}, checks if \kbd{z} is a \kbd{GEN}
which can be mapped to $\F_p[X]/(T)$: anything for which \kbd{Rg\_is\_Fp} return
$1$, a \typ{POL} for which \kbd{RgX\_to\_FpX} return $1$, a \typ{POLMOD}
whose modulus is equal to \kbd{*T} if \kbd{*T} is not \kbd{NULL} (once mapped
to a \kbd{FpX}), or a \typ{FFELT} $z$ such that $z^0$ is equal to \kbd{*T}
if \kbd{*T} is not \kbd{NULL}.

If an integer modulus is found it is put in \kbd{*p}, else \kbd{*p} is left
unchanged. If a polynomial modulus is found it is put in \kbd{*T},
if a \typ{FFELT} $z$ is found, $z^0$ is put in \kbd{*T}, else
\kbd{*T} is left unchanged.

\fun{int}{RgX_is_FpXQX}{GEN z, GEN *T, GEN *p}, \kbd{z} a \typ{POL},
checks if it can be mapped to a \kbd{FpXQX}, by checking \kbd{Rg\_is\_FpXQ}
coefficientwise.

\fun{GEN}{Rg_to_FpXQ}{GEN z, GEN T, GEN p}, \kbd{z} a \kbd{GEN} which can be
mapped to $\F_p[X]/(T)$: anything \kbd{Rg\_to\_Fp} can be applied to,
a \typ{POL} to which \kbd{RgX\_to\_FpX} can be applied to, a \typ{POLMOD}
whose modulus is divisible by $T$ (once mapped to a \kbd{FpX}), a suitable
\typ{RFRAC}. Returns \kbd{z} as an \kbd{FpXQ}, normalized.

\fun{GEN}{RgX_to_FpXQX}{GEN z, GEN T, GEN p}, \kbd{z} a \typ{POL}, returns the
\kbd{FpXQ} obtained by applying \kbd{Rg\_to\_FpXQ} coefficientwise.

\fun{GEN}{RgX_to_FqX}{GEN z, GEN T, GEN p}: let \kbd{z} be a \typ{POL};
returns the \kbd{FqX} obtained by applying \kbd{Rg\_to\_FpXQ}
coefficientwise and simplifying scalars to \typ{INT}s.

\fun{GEN}{Fq_to_FpXQ}{GEN z, GEN T, GEN p /*unused*/}
if $z$ is a \typ{INT}, convert it to a constant polynomial in the variable of
$T$, otherwise return $z$ (shallow function).

\fun{GEN}{Fq_red}{GEN x, GEN T, GEN p}, \kbd{x} a \kbd{ZX} or \typ{INT},
reduce it to an \kbd{Fq} ($\kbd{T} = \kbd{NULL}$ is allowed iff \kbd{x} is a
\typ{INT}).

\fun{GEN}{FqX_red}{GEN x, GEN T, GEN p}, \kbd{x} a \typ{POL}
whose coefficients are \kbd{ZX}s or \typ{INT}s, reduce them to \kbd{Fq}s. (If
$\kbd{T} = \kbd{NULL}$, as \kbd{FpXX\_red(x, p)}.)

\fun{GEN}{FqV_red}{GEN x, GEN T, GEN p}, \kbd{x} a vector of \kbd{ZX}s or
\typ{INT}s, reduce them to \kbd{Fq}s. (If $\kbd{T} = \kbd{NULL}$, only
reduce components mod \kbd{p} to \kbd{FpX}s or \kbd{Fp}s.)

\fun{GEN}{FpXQ_red}{GEN x, GEN T,GEN p} \kbd{x} a \typ{POL}
whose coefficients are \typ{INT}s, reduce them to \kbd{FpXQ}s.

\subsec{\kbd{FpXQ}}

\fun{GEN}{FpXQ_add}{GEN x, GEN y, GEN T,GEN p}

\fun{GEN}{FpXQ_sub}{GEN x, GEN y, GEN T,GEN p}

\fun{GEN}{FpXQ_mul}{GEN x, GEN y, GEN T,GEN p}

\fun{GEN}{FpXQ_sqr}{GEN x, GEN T, GEN p}

\fun{GEN}{FpXQ_div}{GEN x, GEN y, GEN T,GEN p}

\fun{GEN}{FpXQ_inv}{GEN x, GEN T, GEN p} computes the inverse of \kbd{x}

\fun{GEN}{FpXQ_invsafe}{GEN x,GEN T,GEN p}, as \kbd{FpXQ\_inv}, returning
\kbd{NULL} if \kbd{x} is not invertible.

\fun{GEN}{FpXQ_pow}{GEN x, GEN n, GEN T, GEN p} computes $\kbd{x}^\kbd{n}$.

\fun{GEN}{FpXQ_powu}{GEN x, ulong n, GEN T, GEN p} computes $\kbd{x}^\kbd{n}$
for small $n$.

In the following three functions the integer parameter \kbd{ord} can be given
either as a positive \typ{INT} $N$, or as its factorization matrix $\var{faN}$,
or as a pair $[N,\var{faN}]$. The parameter may be omitted by setting it to
\kbd{NULL} (the value is then $p^d-1$, $d = \deg T$).

\fun{GEN}{FpXQ_log}{GEN a, GEN g, GEN ord, GEN T, GEN p} Let \kbd{g} be of
order \kbd{ord} in the finite field $\F_p[X]/(T)$, return $e$ such that
$a^e=g$. If $e$ does not exists, the result is undefined. Assumes
that \kbd{T} is irreducible mod \kbd{p}.

\fun{GEN}{Fp_FpXQ_log}{GEN a, GEN g, GEN ord, GEN T, GEN p} As
\kbd{FpXQ\_log}, \kbd{a} being a \kbd{Fp}.

\fun{GEN}{FpXQ_order}{GEN a, GEN ord, GEN T, GEN p} returns the order of the
\kbd{FpXQ} \kbd{a}. Assume that \kbd{ord} is a multiple of the order of
\kbd{a}. Assume that \kbd{T} is irreducible mod \kbd{p}.

\fun{int}{FpXQ_issquare}{GEN x, GEN T, GEN p} returns $1$ if $x$ is a square
and $0$ otherwise. Assumes that \kbd{T} is irreducible mod \kbd{p}.

\fun{GEN}{FpXQ_sqrt}{GEN x, GEN T, GEN p} returns a square root of \kbd{x}.
Return \kbd{NULL} if \kbd{x} is not a square.

\fun{GEN}{FpXQ_sqrtn}{GEN x, GEN n, GEN T, GEN p, GEN *zn}
Let $T$be irreducible mod $p$ and $q = p^{\deg T}$; returns \kbd{NULL} if $a$
is not an $n$-th power residue mod $p$. Otherwise, returns an $n$-th root of
$a$; if \kbd{zn} is non-\kbd{NULL} set it to a primitive $m$-th root of $1$
in $\F_q$, $m = \gcd(q-1,n)$ allowing to compute all $m$ solutions in $\F_q$
of the equation $x^n = a$.

\subsec{\kbd{Fq}}

\fun{GEN}{Fq_add}{GEN x, GEN y, GEN T/*unused*/, GEN p}

\fun{GEN}{Fq_sub}{GEN x, GEN y, GEN T/*unused*/, GEN p}

\fun{GEN}{Fq_mul}{GEN x, GEN y, GEN T, GEN p}

\fun{GEN}{Fq_Fp_mul}{GEN x, GEN y, GEN T, GEN p} multiplies the \kbd{Fq} $x$
by the \typ{INT} $y$.

\fun{GEN}{Fq_mulu}{GEN x, ulong y, GEN T, GEN p} multiplies the \kbd{Fq} $x$
by the scalar $y$.

\fun{GEN}{Fq_halve}{GEN x, GEN T, GEN p} returns $z$ such that $2\*z = x$
assuming such $z$ exists.

\fun{GEN}{Fq_sqr}{GEN x, GEN T, GEN p}

\fun{GEN}{Fq_neg}{GEN x, GEN T, GEN p}

\fun{GEN}{Fq_neg_inv}{GEN x, GEN T, GEN p} computes $-\kbd{x}^{-1}$

\fun{GEN}{Fq_inv}{GEN x, GEN pol, GEN p} computes $\kbd{x}^{-1}$, raising an
error if \kbd{x} is not invertible.

\fun{GEN}{Fq_invsafe}{GEN x, GEN pol, GEN p} as \kbd{Fq\_inv}, but returns
\kbd{NULL} if \kbd{x} is not invertible.

\fun{GEN}{Fq_div}{GEN x, GEN y, GEN T, GEN p}

\fun{GEN}{FqV_inv}{GEN x, GEN T, GEN p} $x$ being a vector of \kbd{Fq}s,
return the vector of inverses of the $x[i]$. The routine uses Montgomery's
trick, and involves a single inversion, plus $3(N-1)$ multiplications for
$N$ entries. The routine is not stack-clean: $2N$ \kbd{FpXQ} are left on
stack, besides the $N$ in the result.

\fun{GEN}{Fq_pow}{GEN x, GEN n, GEN pol, GEN p} returns $\kbd{x}^\kbd{n}$.

\fun{GEN}{Fq_powu}{GEN x, ulong n, GEN pol, GEN p} returns $\kbd{x}^\kbd{n}$
for small $n$.

\fun{GEN}{Fq_log}{GEN a, GEN g, GEN ord, GEN T, GEN p} as
\tet{Fp_log} or \tet{FpXQ_log}.

\fun{int}{Fq_issquare}{GEN x, GEN T, GEN p} returns $1$ if $x$ is a square
and $0$ otherwise. Assumes that \kbd{T} is irreducible mod \kbd{p} and that
$p$ is prime; $T = \kbd{NULL}$ is forbidden unless $x$ is an \kbd{Fp}.

\fun{long}{Fq_ispower}{GEN x, GEN n, GEN T, GEN p} returns $1$ if $x$
is a $n$-th power and $0$ otherwise. Assumes that \kbd{T} is irreducible mod
\kbd{p} and that $p$ is prime; $T = \kbd{NULL}$ is forbidden unless $x$ is an
\kbd{Fp}.

\fun{GEN}{Fq_sqrt}{GEN x, GEN T, GEN p} returns a square root of \kbd{x}.
Return \kbd{NULL} if \kbd{x} is not a square.

\fun{GEN}{Fq_sqrtn}{GEN a, GEN n, GEN T, GEN p, GEN *zn}
as \tet{FpXQ_sqrtn}.

\fun{GEN}{FpXQ_charpoly}{GEN x, GEN T, GEN p} returns the characteristic
polynomial of \kbd{x}

\fun{GEN}{FpXQ_minpoly}{GEN x, GEN T, GEN p} returns the minimal polynomial
of \kbd{x}

\fun{GEN}{FpXQ_norm}{GEN x, GEN T, GEN p} returns the norm of \kbd{x}

\fun{GEN}{FpXQ_trace}{GEN x, GEN T, GEN p} returns the trace of \kbd{x}

\fun{GEN}{FpXQ_conjvec}{GEN x, GEN T, GEN p} returns the vector of conjugates
$[x,x^p,x^{p^2},\ldots,x^{p^{n-1}}]$ where $n$ is the degree of $T$.

\fun{GEN}{gener_FpXQ}{GEN T, GEN p, GEN *po} returns a primitive root modulo
$(T,p)$. $T$ is an \kbd{FpX} assumed to be irreducible modulo the prime
$p$. If \kbd{po} is not \kbd{NULL} it is set to $[o,\var{fa}]$, where $o$ is
the order of the multiplicative group of the finite field, and \var{fa} is
its factorization.

\fun{GEN}{gener_FpXQ_local}{GEN T, GEN p, GEN L}, \kbd{L} being a vector of
primes dividing $p^{\deg T} - 1$, returns an element of $G:=\F_p[x]/(T)$
which is a generator of the $\ell$-Sylow of $G$ for every $\ell$ in
\kbd{L}. It is not necessary, and in fact slightly inefficient, to include
$\ell=2$, since 2 is treated separately in any case, i.e. the generator
obtained is never a square if $p$ is odd.

\fun{GEN}{gener_Fq_local}{GEN T, GEN p, GEN L} as
\kbd{pgener\_Fp\_local(p, L)} if $T$ is \kbd{NULL},
or \kbd{gener\_FpXQ\_local} (otherwise).


\fun{GEN}{FpXQ_powers}{GEN x, long n, GEN T, GEN p} returns $[\kbd{x}^0,
\dots, \kbd{x}^\kbd{n}]$ as a \typ{VEC} of \kbd{FpXQ}s.

\fun{GEN}{FpXQ_matrix_pow}{GEN x, long m, long n, GEN T, GEN p}, as
\kbd{FpXQ\_powers}$(x, n-1, T, p)$, but returns the powers as a an
$m\times n$ matrix. Usually, we have $m = n = \deg T$.

\fun{GEN}{FpXQ_autpow}{GEN a, ulong n, GEN T, GEN p} computes $\sigma^n(X)$
assuming $a=\sigma(X)$ where $\sigma$ is an automorphism of the algebra
$\F_p[X]/T(X)$.

\fun{GEN}{FpXQ_autsum}{GEN a, ulong n, GEN T, GEN p}
$a$ being a two-component vector,
$\sigma$ being the automorphism defined by $\sigma(X)=a[1]\pmod{T(X)}$,
returns the vector $[\sigma^n(X),b\sigma(b)\ldots\sigma^{n-1}(b)]$
where $b=a[2]$.

\fun{GEN}{FpXQ_auttrace}{GEN a, ulong n, GEN T, GEN p}
$a$ being a two-component vector,
$\sigma$ being the automorphism defined by $\sigma(X)=a[1]\pmod{T(X)}$,
returns the vector $[\sigma^n(X),b+\sigma(b)+\ldots+\sigma^{n-1}(b)]$
where $b=a[2]$.

\fun{GEN}{FpXQ_autpowers}{GEN S, long n, GEN T, GEN p} returns
$[x,S(x),S(S(x)),\dots,S^{(n)}(x)]$ as a \typ{VEC} of \kbd{FpXQ}s.

\fun{GEN}{FpXQM_autsum}{GEN a, long n, GEN T, GEN p}
$\sigma$ being the automorphism defined by $\sigma(X)=a[1]\pmod{T(X)}$,
returns the vector $[\sigma^n(X),b\sigma(b)\ldots\sigma^{n-1}(b)]$
where $b=a[2]$ is a square matrix.

\fun{GEN}{FpX_FpXQ_eval}{GEN f, GEN x, GEN T, GEN p} returns
$\kbd{f}(\kbd{x})$.

\fun{GEN}{FpX_FpXQV_eval}{GEN f, GEN V, GEN T, GEN p} returns
$\kbd{f}(\kbd{x})$, assuming that \kbd{V} was computed by
$\kbd{FpXQ\_powers}(\kbd{x}, n, \kbd{T}, \kbd{p})$.

\fun{GEN}{FpXC_FpXQV_eval}{GEN C, GEN V,GEN T,GEN p} applies
\kbd{FpX\_FpXQV\_eval} to all elements of the vector $C$
and returns a \typ{COL}.

\fun{GEN}{FpXM_FpXQV_eval}{GEN M, GEN V,GEN T,GEN p} applies
\kbd{FpX\_FpXQV\_eval} to all elements of the matrix $M$.

\subsec{\kbd{FpXX}, \kbd{FpXY}}
Contrary to what the name implies, an \kbd{FpXX} is a \typ{POL} whose
coefficients are either \typ{INT}s or \kbd{FpX}s. This reduces memory
overhead at the expense of consistency. The prefix \kbd{FpXY} is an
alias for \kbd{FpXX} when variables matters.

\fun{GEN}{FpXX_red}{GEN z, GEN p}, \kbd{z} a \typ{POL} whose coefficients are
either \kbd{ZX}s or \typ{INT}s. Returns the \typ{POL} equal to \kbd{z} with
all components reduced modulo \kbd{p}.

\fun{GEN}{FpXX_renormalize}{GEN x, long l}, as \kbd{normalizepol}, where
$\kbd{l} = \kbd{lg(x)}$, in place.

\fun{GEN}{FpXX_add}{GEN x, GEN y, GEN p} adds \kbd{x} and \kbd{y}.

\fun{GEN}{FpXX_sub}{GEN x, GEN y, GEN p} returns $\kbd{x}-\kbd{y}$.

\fun{GEN}{FpXX_neg}{GEN x, GEN p} returns $-\kbd{x}$.

\fun{GEN}{FpXX_Fp_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{FpXX}~\kbd{x}
by the \kbd{Fp}~\kbd{y}.

\fun{GEN}{FpXX_FpX_mul}{GEN x, GEN y, GEN p} multiplies the coefficients of the
\kbd{FpXX}~\kbd{x} by the \kbd{FpX}~\kbd{y}.

\fun{GEN}{FpXX_mulu}{GEN x, GEN y, GEN p} multiplies the \kbd{FpXX}~\kbd{x}
by the scalar \kbd{y}.

\fun{GEN}{FpXX_deriv}{GEN P, GEN p} differentiates \kbd{P} with respect of
the main variable.

\fun{GEN}{FpXY_eval}{GEN Q, GEN y, GEN x, GEN p} $Q$ being an \kbd{FpXY},
i.e.~a \typ{POL} with \kbd{Fp} or \kbd{FpX} coefficients representing an
element of $\F_p[X][Y]$. Returns the \kbd{Fp} $Q(x,y)$.

\fun{GEN}{FpXY_evalx}{GEN Q, GEN x, GEN p} $Q$ being an \kbd{FpXY}, returns the
\kbd{FpX} $Q(x,Y)$, where $Y$ is the main variable of $Q$.

\fun{GEN}{FpXY_evaly}{GEN Q, GEN y, GEN p, long vx} $Q$ an \kbd{FpXY}, returns
the \kbd{FpX} $Q(X,y)$, where $X$ is the second variable of $Q$, and \kbd{vx}
is the variable number of $X$.

\fun{GEN}{FpXY_Fq_evaly}{GEN Q, GEN y, GEN T, GEN p, long vx} $Q$ an \kbd{FpXY}
and $y$ being an \kbd{Fq}, returns the \kbd{FqX} $Q(X,y)$, where $X$ is the
second variable of $Q$, and \kbd{vx} is the variable number of $X$.

\fun{GEN}{FpXY_FpXQ_evalx}{GEN Q, GEN x, ulong p} $Q$ an \kbd{FpXY} and
$x$ being an \kbd{FpXQ}, returns the \kbd{FpXQX} $Q(x,Y)$, where $Y$ is the
first variable of $Q$.

\fun{GEN}{FpXY_FpXQV_evalx}{GEN Q, GEN V, ulong p} $Q$ an \kbd{FpXY} and
$x$ being an \kbd{FpXQ}, returns the \kbd{FpXQX} $Q(x,Y)$, where $Y$ is the
first variable of $Q$, assuming that \kbd{V} was computed by
$\kbd{FpXQ\_powers}(\kbd{x}, n, \kbd{T}, \kbd{p})$.

\fun{GEN}{FpXYQQ_pow}{GEN x, GEN n, GEN S, GEN T, GEN p}, \kbd{x} being a
\kbd{FpXY}, \kbd{T} being a \kbd{FpX} and \kbd{S} being a \kbd{FpY},
return $x^n \pmod{S,T,p}$.

\subsec{\kbd{FpXQX}, \kbd{FqX}}
Contrary to what the name implies, an \kbd{FpXQX} is a \typ{POL} whose
coefficients are \kbd{Fq}s. So the only difference between \kbd{FqX} and
\kbd{FpXQX} routines is that $\kbd{T} = \kbd{NULL}$ is not allowed in the
latter. (It was thought more useful to allow \typ{INT} components than to
enforce strict consistency, which would not imply any efficiency gain.)

\subsubsec{Basic operations}

\fun{GEN}{FqX_add}{GEN x,GEN y,GEN T,GEN p}

\fun{GEN}{FqX_Fq_add}{GEN x, GEN y, GEN T, GEN p} adds the
\kbd{Fq}~\kbd{y} to the \kbd{FqX}~\kbd{x}.

\fun{GEN}{FqX_neg}{GEN x,GEN T,GEN p}

\fun{GEN}{FqX_sub}{GEN x,GEN y,GEN T,GEN p}

\fun{GEN}{FqX_mul}{GEN x, GEN y, GEN T, GEN p}

\fun{GEN}{FqX_Fq_mul}{GEN x, GEN y, GEN T, GEN p} multiplies the
\kbd{FqX}~\kbd{x} by the \kbd{Fq}~\kbd{y}.

\fun{GEN}{FqX_mulu}{GEN x, ulong y, GEN T, GEN p} multiplies the
\kbd{FqX}~\kbd{x} by the scalar~\kbd{y}.

\fun{GEN}{FqX_Fp_mul}{GEN x, GEN y, GEN T, GEN p} multiplies the
\kbd{FqX}~\kbd{x} by the \typ{INT}~\kbd{y}.

\fun{GEN}{FqX_Fq_mul_to_monic}{GEN x, GEN y, GEN T, GEN p}
returns $x\*y$ assuming the result is monic of the same degree as $x$ (in
particular $y\neq 0$).

\fun{GEN}{FpXQX_normalize}{GEN z, GEN T, GEN p}

\fun{GEN}{FqX_normalize}{GEN z, GEN T, GEN p} divides the \kbd{FqX}~\kbd{z}
by its leading term. The leading coefficient becomes $1$ as a \typ{INT}.

\fun{GEN}{FqX_sqr}{GEN x, GEN T, GEN p}

\fun{GEN}{FqX_powu}{GEN x, ulong n, GEN T, GEN p}

\fun{GEN}{FqX_divrem}{GEN x, GEN y, GEN T, GEN p, GEN *z}

\fun{GEN}{FqX_div}{GEN x, GEN y, GEN T, GEN p}

\fun{GEN}{FqX_div_by_X_x}{GEN a, GEN x, GEN T, GEN p, GEN *r}

\fun{GEN}{FqX_rem}{GEN x, GEN y, GEN T, GEN p}

\fun{GEN}{FqX_deriv}{GEN x, GEN T, GEN p} returns the derivative of \kbd{x}.
(This function is suitable for \kbd{gerepilupto} but not memory-clean.)

\fun{GEN}{FqX_translate}{GEN P, GEN c, GEN T, GEN p} let $c$ be an \kbd{Fq}
defined modulo $(p, T)$, and let $P$ be an \kbd{FqX}; returns the translated
\kbd{FqX} of $P(X+c)$.

\fun{GEN}{FqX_gcd}{GEN P, GEN Q, GEN T, GEN p} returns a (not necessarily
monic) greatest common divisor of $x$  and $y$.

\fun{GEN}{FqX_extgcd}{GEN x, GEN y, GEN T, GEN p, GEN *ptu, GEN *ptv}
returns $d = \text{GCD}(\kbd{x},\kbd{y})$ (not necessarily monic), and sets
\kbd{*u}, \kbd{*v} to the Bezout coefficients such that $\kbd{*ux} +
\kbd{*vy} = d$.

\fun{GEN}{FqX_halfgcd}{GEN x, GEN y, GEN T, GEN p} returns a two-by-two
\kbd{FqXM} $M$ with determinant $\pm 1$ such that the image $(a,b)$ of $(x,y)$
by $M$ has the property that $\deg a \geq {\deg x \over 2} > \deg b$.

\fun{GEN}{FqX_eval}{GEN x, GEN y, GEN T, GEN p} evaluates the \kbd{FqX}~\kbd{x}
at the \kbd{Fq}~\kbd{y}. The result is an~\kbd{Fq}.

\fun{GEN}{FqXY_eval}{GEN Q, GEN y, GEN x, GEN T, GEN p} $Q$ an \kbd{FqXY},
i.e.~a \typ{POL} with \kbd{Fq} or \kbd{FqX} coefficients representing an
element of $\F_q[X][Y]$. Returns the \kbd{Fq} $Q(x,y)$.

\fun{GEN}{FqXY_evalx}{GEN Q, GEN x, GEN T, GEN p} $Q$ being an \kbd{FqXY},
returns the \kbd{FqX} $Q(x,Y)$, where $Y$ is the main variable of $Q$.

\fun{GEN}{random_FpXQX}{long d, long v, GEN T, GEN p} returns a random
\kbd{FpXQX} in variable \kbd{v}, of degree less than~\kbd{d}.

\fun{GEN}{FpXQX_renormalize}{GEN x, long lx}

\fun{GEN}{FpXQX_red}{GEN z, GEN T, GEN p} \kbd{z} a \typ{POL} whose
coefficients are \kbd{ZX}s or \typ{INT}s, reduce them to \kbd{FpXQ}s.

\fun{GEN}{FpXQX_mul}{GEN x, GEN y, GEN T, GEN p}

\fun{GEN}{Kronecker_to_FpXQX}{GEN z, GEN T, GEN p}. Let $n = \deg T$ and let
$P(X,Y)\in \Z[X,Y]$ lift a polynomial in $K[Y]$, where $K := \F_p[X]/(T)$ and
$\deg_X P < 2n-1$ --- such as would result from multiplying minimal degree
lifts of two polynomials in $K[Y]$. Let $z = P(t,t^{2*n-1})$ be a Kronecker
form of $P$, this function returns $Q\in \Z[X,t]$ such that $Q$ is congruent to
$P(X,t)$ mod $(p, T(X))$, $\deg_X Q < n$, and all coefficients are in $[0,p[$.
Not stack-clean. Note that $t$ need not be the same variable as $Y$!

\fun{GEN}{FpXQX_FpXQ_mul}{GEN x, GEN y, GEN T, GEN p}

\fun{GEN}{FpXQX_sqr}{GEN x, GEN T, GEN p}

\fun{GEN}{FpXQX_divrem}{GEN x, GEN y, GEN T, GEN p, GEN *pr}

\fun{GEN}{FpXQX_div}{GEN x, GEN y, GEN T, GEN p}

\fun{GEN}{FpXQX_div_by_X_x}{GEN a, GEN x, GEN T, GEN p, GEN *r}

\fun{GEN}{FpXQX_rem}{GEN x, GEN y, GEN T, GEN p}

\fun{GEN}{FpXQX_powu}{GEN x, ulong n, GEN T, GEN p} returns $x^n$.

\fun{GEN}{FpXQX_digits}{GEN x, GEN B, GEN T, GEN p}

\fun{GEN}{FpXQX_fromdigits}{GEN v, GEN B, GEN T, GEN p}

\fun{GEN}{FpXQX_invBarrett}{GEN y, GEN T, GEN p} returns the Barrett inverse of
the \kbd{FpXQX} $y$, namely a lift of $1/\kbd{polrecip}(y)+O(x^{\deg(y)-1})$.

\fun{GEN}{FpXQXV_prod}{GEN V, GEN T, GEN p}, \kbd{V} being a vector of
\kbd{FpXQX}, returns their product.

\fun{GEN}{FpXQX_gcd}{GEN x, GEN y, GEN T, GEN p}

\fun{GEN}{FpXQX_extgcd}{GEN x, GEN y, GEN T, GEN p, GEN *ptu, GEN *ptv}

\fun{GEN}{FpXQX_halfgcd}{GEN x, GEN y, GEN T, GEN p}

\fun{GEN}{FpXQX_FpXQXQ_eval}{GEN f,GEN x,GEN S, GEN T,GEN p} returns
$\kbd{f}(\kbd{x})$.

\subsec{\kbd{FpXQXQ}, \kbd{FqXQ}}

A \kbd{FpXQXQ} is a \typ{FpXQX} which represents an element of the ring
$(Fp[X]/T(X))[Y]/S(X,Y)$, where $T$ is a \kbd{FpX} and $S$ a \kbd{FpXQX}
modulo $T$.  A \kbd{FqXQ} is identical except that $T$ is allowed to be
\kbd{NULL} in which case $S$ must be a \kbd{FpX}.

\subsubsec{Preconditioned reduction}

For faster reduction, the modulus \kbd{S} can be replaced by an extended
modulus, which is an \kbd{FpXQXT}, in all \kbd{FpXQXQ}- and \kbd{FqXQ}-classes
functions, and in \kbd{FpXQX\_rem} and \kbd{FpXQX\_divrem}.

\fun{GEN}{FpXQX_get_red}{GEN S, GEN T, GEN p} returns the extended modulus
\kbd{eS}.

\fun{GEN}{FqX_get_red}{GEN S, GEN T, GEN p} identical, but allow $T$ to
be \kbd{NULL}, in which case it returns \kbd{FpX\_get\_red(S,p)}.

To write code that works both with plain and extended moduli, the following
accessors are defined:

\fun{GEN}{get_FpXQX_mod}{GEN eS} returns the underlying modulus \kbd{S}.

\fun{GEN}{get_FpXQX_var}{GEN eS} returns the variable number of the modulus.

\fun{GEN}{get_FpXQX_degree}{GEN eS} returns the degree of the modulus.

Furthermore, \kbd{ZXXT\_to\_FlxXT} allows to convert an extended modulus for
a \kbd{FpXQX} to an extended modulus for the corresponding \kbd{FlxqX}.

\subsubsec{basic operations}

\fun{GEN}{FpXQX_FpXQXQV_eval}{GEN f,GEN V,GEN S,GEN T,GEN p} returns
$\kbd{f}(\kbd{x})$, assuming that \kbd{V} was computed by
$\kbd{FpXQXQ\_powers}(\kbd{x}, n, \kbd{S}, \kbd{T}, \kbd{p})$.

\fun{GEN}{FpXQXQ_div}{GEN x, GEN y, GEN S, GEN T, GEN p}, \kbd{x}, \kbd{y} and
\kbd{S} being \kbd{FpXQX}s, returns $\kbd{x}*\kbd{y}^{-1}$ modulo \kbd{S}.

\fun{GEN}{FpXQXQ_inv}{GEN x, GEN S, GEN T, GEN p}, \kbd{x} and
\kbd{S} being \kbd{FpXQX}s, returns $\kbd{x}^{-1}$ modulo \kbd{S}.

\fun{GEN}{FpXQXQ_invsafe}{GEN x, GEN S, GEN T,GEN p}, as \kbd{FpXQXQ\_inv},
returning \kbd{NULL} if \kbd{x} is not invertible.

\fun{GEN}{FpXQXQ_mul}{GEN x, GEN y, GEN S, GEN T, GEN p}, \kbd{x}, \kbd{y} and
\kbd{S} being \kbd{FpXQX}s, returns $\kbd{x}\*\kbd{y}$ modulo \kbd{S}.

\fun{GEN}{FpXQXQ_sqr}{GEN x, GEN S, GEN T, GEN p}, \kbd{x} and
\kbd{S} being \kbd{FpXQX}s, returns $\kbd{x}^2$ modulo \kbd{S}.

\fun{GEN}{FpXQXQ_pow}{GEN x, GEN n, GEN S, GEN T, GEN p}, \kbd{x} and
\kbd{S} being \kbd{FpXQX}s, returns $\kbd{x}^\kbd{n}$ modulo \kbd{S}.

\fun{GEN}{FpXQXQ_powers}{GEN x, long n, GEN S, GEN T, GEN p}, \kbd{x} and
\kbd{S} being \kbd{FpXQX}s, returns $[\kbd{x}^0, \dots, \kbd{x}^\kbd{n}]$ as a
\typ{VEC} of \kbd{FpXQXQ}s.

\fun{GEN}{FpXQXQ_matrix_pow}{GEN x, long m, long n, GEN S, GEN T, GEN p}
returns the same powers of \kbd{x} as \kbd{FpXQXQ\_powers}$(x, n-1,S, T, p)$,
but as an $m\times n$ matrix.

\fun{GEN}{FpXQXQV_autpow}{GEN a, long n, GEN S, GEN T, GEN p}
$\sigma$ being the automorphism defined by $\sigma(X)=a[1]\pmod{T(X)}$,
$\sigma(Y)=a[2]\pmod{S(X,Y),T(X)}$, returns $[\sigma^n(X),\sigma^n(Y)]$.

\fun{GEN}{FpXQXQV_autsum}{GEN a, long n, GEN S, GEN T, GEN p}
$\sigma$ being the automorphism defined by $\sigma(X)=a[1]\pmod{T(X)}$,
$\sigma(Y)=a[2]\pmod{S(X,Y),T(X)}$, returns the vector
$[\sigma^n(X),\sigma^n(Y),b\sigma(b)\ldots\sigma^{n-1}(b)]$
where $b=a[3]$.

\fun{GEN}{FpXQXQV_auttrace}{GEN a, long n, GEN S, GEN T, GEN p}
$\sigma$ being the automorphism defined by $\sigma(X)=a[1]\pmod{T(X)}$,
$\sigma(Y)=a[2]\pmod{S(X,Y),T(X)}$, returns the vector
$[\sigma^n(X),\sigma^n(Y),b+\sigma(b)+\ldots+\sigma^{n-1}(b)]$
where $b=a[3]$.

% FqXQ

\fun{GEN}{FqXQ_add}{GEN x, GEN y, GEN S, GEN T, GEN p}, \kbd{x}, \kbd{y} and
\kbd{S} being \kbd{FqX}s, returns $\kbd{x} + \kbd{y}$ modulo \kbd{S}.

\fun{GEN}{FqXQ_sub}{GEN x, GEN y, GEN S, GEN T, GEN p}, \kbd{x}, \kbd{y} and
\kbd{S} being \kbd{FqX}s, returns $\kbd{x} - \kbd{y}$ modulo \kbd{S}.

\fun{GEN}{FqXQ_mul}{GEN x, GEN y, GEN S, GEN T, GEN p}, \kbd{x}, \kbd{y} and
\kbd{S} being \kbd{FqX}s, returns $\kbd{x}\*\kbd{y}$ modulo \kbd{S}.

\fun{GEN}{FqXQ_div}{GEN x, GEN y, GEN S, GEN T, GEN p}, \kbd{x} and
\kbd{S} being \kbd{FqX}s, returns $\kbd{x}/\kbd{y}$ modulo \kbd{S}.

\fun{GEN}{FqXQ_inv}{GEN x, GEN S, GEN T, GEN p}, \kbd{x} and
\kbd{S} being \kbd{FqX}s, returns $\kbd{x}^{-1}$ modulo \kbd{S}.

\fun{GEN}{FqXQ_invsafe}{GEN x, GEN S, GEN T, GEN p} , as \kbd{FqXQ\_inv},
returning \kbd{NULL} if \kbd{x} is not invertible.

\fun{GEN}{FqXQ_sqr}{GEN x, GEN S, GEN T, GEN p}, \kbd{x} and
\kbd{S} being \kbd{FqX}s, returns $\kbd{x}^2$ modulo \kbd{S}.

\fun{GEN}{FqXQ_pow}{GEN x, GEN n, GEN S, GEN T, GEN p}, \kbd{x} and
\kbd{S} being \kbd{FqX}s, returns $\kbd{x}^\kbd{n}$ modulo \kbd{S}.

\fun{GEN}{FqXQ_powers}{GEN x, long n, GEN S, GEN T, GEN p}, \kbd{x} and
\kbd{S} being \kbd{FqX}s, returns $[\kbd{x}^0, \dots, \kbd{x}^\kbd{n}]$ as a
\typ{VEC} of \kbd{FqXQ}s.

\fun{GEN}{FqXQ_matrix_pow}{GEN x, long m, long n, GEN S, GEN T, GEN p}
returns the same powers of \kbd{x} as \kbd{FqXQ\_powers}$(x, n-1,S, T, p)$,
but as an $m\times n$ matrix.

\fun{GEN}{FqV_roots_to_pol}{GEN V, GEN T, GEN p, long v},
\kbd{V} being a vector of \kbd{Fq}s, returns the monic \kbd{FqX}
$\prod_i (\kbd{pol\_x[v]} - \kbd{V[i]})$.

\subsubsec{Miscellaneous operations}

\fun{GEN}{init_Fq}{GEN p, long n, long v} returns an irreducible polynomial
of degree $\kbd{n} > 0$ over $\F_p$, in variable \kbd{v}.

\fun{int}{FqX_is_squarefree}{GEN P, GEN T, GEN p}

\fun{GEN}{FpXQX_roots}{GEN x, GEN T, GEN p} return the roots of \kbd{x} in
$\F_p[X]/(T)$. Assumes \kbd{p} is prime and \kbd{T} irreducible in $\F_p[X]$.

\fun{GEN}{FqX_roots}{GEN x, GEN T, GEN p} same but allow $\kbd{T} = \kbd{NULL}$.

\fun{GEN}{FpXQX_factor}{GEN x, GEN T, GEN p} same output convention as
\kbd{FpX\_factor}. Assumes \kbd{p} is prime and \kbd{T} irreducible
in $\F_p[X]$.

\fun{GEN}{FqX_factor}{GEN x, GEN T, GEN p} same but allow $\kbd{T} = \kbd{NULL}$.

\fun{GEN}{FpXQX_split_part}{GEN f, GEN T, GEN p} returns the largest totally
split squarefree factor of $f$.

\fun{long}{FqX_ispower}{GEN f, ulong k, GEN T, GEN p, GEN *pt} return
returns 1 if \kbd{FqX} $f$ is a $K$-th power Return $0$
otherwise. If \kbd{py} is not \kbd{NULL}, set it to $g$ such that $g^K = f$.

\fun{GEN}{FpX_factorff}{GEN P, GEN T, GEN p}. Assumes \kbd{p} prime
and \kbd{T} irreducible in $\F_p[X]$. Factor the \kbd{FpX} \kbd{P}
over the finite field $\F_p[Y]/(T(Y))$. See \kbd{FpX\_factorff\_irred}
if \kbd{P} is known to be irreducible of $\F_p$.

\fun{GEN}{FpX_rootsff}{GEN P, GEN T, GEN p}. Assumes \kbd{p} prime
and \kbd{T} irreducible in $\F_p[X]$. Returns the roots of the \kbd{FpX}
\kbd{P} belonging to the finite field $\F_p[Y]/(T(Y))$.

\fun{GEN}{FpX_factorff_irred}{GEN P, GEN T, GEN p}. Assumes \kbd{p} prime
and \kbd{T} irreducible in $\F_p[X]$. Factors the \emph{irreducible}
\kbd{FpX} \kbd{P} over the finite field $\F_p[Y]/(T(Y))$ and returns the
vector of irreducible \kbd{FqX}s factors (the exponents, being all equal to
$1$, are not included).

\fun{GEN}{FpX_ffisom}{GEN P, GEN Q, GEN p}. Assumes \kbd{p} prime,
\kbd{P}, \kbd{Q} are \kbd{ZX}s, both irreducible mod \kbd{p}, and
$\deg(P) \mid \deg Q$. Outputs a monomorphism between $\F_p[X]/(P)$ and
$\F_p[X]/(Q)$, as a polynomial $R$ such that $\kbd{Q} \mid \kbd{P}(R)$ in
$\F_p[X]$. If \kbd{P} and \kbd{Q} have the same degree, it is of course an
isomorphism.

\fun{void}{FpX_ffintersect}{GEN P, GEN Q, long n, GEN p, GEN *SP,GEN *SQ, GEN
MA,GEN MB}\hfil\break
Assumes \kbd{p} is prime, \kbd{P}, \kbd{Q} are \kbd{ZX}s, both
irreducible mod \kbd{p}, and \kbd{n} divides both the degree of \kbd{P} and
\kbd{Q}. Compute \kbd{SP} and \kbd{SQ} such that the subfield of
$\F_p[X]/(P)$ generated by \kbd{SP} and the subfield of $\F_p[X]/(Q)$
generated by \kbd{SQ} are isomorphic of degree \kbd{n}. The polynomials
\kbd{P} and \kbd{Q} do not need to be of the same variable. If \kbd{MA}
(resp. \kbd{MB}) is not \kbd{NULL}, it must be the matrix of the Frobenius
map in $\F_p[X]/(P)$ (resp.~$\F_p[X]/(Q)$).

\fun{GEN}{FpXQ_ffisom_inv}{GEN S, GEN T, GEN p}. Assumes \kbd{p} is prime,
\kbd{T} a \kbd{ZX}, which is irreducible modulo \kbd{p}, \kbd{S} a
\kbd{ZX} representing an automorphism of $\F_q := \F_p[X]/(\kbd{T})$.
($\kbd{S}(X)$ is the image of $X$ by the automorphism.) Returns the
inverse automorphism of \kbd{S}, in the same format, i.e.~an \kbd{FpX}~$H$
such that $H(\kbd{S}) \equiv X$ modulo $(\kbd{T}, \kbd{p})$.

\fun{long}{FpXQX_nbfact}{GEN S, GEN T, GEN p} returns the number of
irreducible factors of the polynomial $S$ over the finite field $\F_q$
defined by $T$ and $p$.

\fun{long}{FqX_nbfact}{GEN S, GEN T, GEN p} as above but accept \kbd{T=NULL}.

\fun{long}{FpXQX_nbroots}{GEN S, GEN T, GEN p} returns the number of roots of
the polynomial $S$ over the finite field $\F_q$ defined by $T$ and $p$.

\fun{long}{FqX_nbroots}{GEN S, GEN T, GEN p} as above but accept \kbd{T=NULL}.

\fun{GEN}{FpXQX_Frobenius}{GEN S, GEN T, GEN p} returns
$X^{q}\pmod{S(X)}$ over the finite field $\F_q$ defined by $T$ and $p$, thus
$q=p^n$ where $n$ is the degree of $T$.

\fun{GEN}{FpXQXQ_halfFrobenius}{GEN A, GEN S, GEN T, GEN p} returns
$A(X)^{(q-1)/2}\pmod{S(X)}$ over the finite field $\F_q$ defined by $T$
and $p$, thus $q=p^n$ where $n$ is the degree of $T$.

\subsec{\kbd{Flx}} Let \kbd{p} an understood \kbd{ulong}, assumed to be
prime, to be given the function arguments; an \kbd{Fl} is an \kbd{ulong}
belonging to $[0,\kbd{p}-1]$, an \kbd{Flx}~\kbd{z} is a \typ{VECSMALL}
representing a polynomial with small integer coefficients. Specifically
\kbd{z[0]} is the usual codeword, \kbd{z[1] = evalvarn($v$)} for some
variable $v$, then the coefficients by increasing degree. An \kbd{FlxX} is a
\typ{POL} whose coefficients are \kbd{Flx}s.

\noindent In the following, an argument called \kbd{sv} is of the form
\kbd{evalvarn}$(v)$ for some variable number~$v$.

\subsubsec{Preconditioned reduction}

For faster reduction, the modulus \kbd{T} can be replaced by an extended
modulus, which is an \kbd{FlxT}, in all \kbd{Flxq}-classes functions, and in
\kbd{Flx\_divrem}.

\fun{GEN}{Flx_get_red}{GEN T, ulong p} returns the extended modulus \kbd{eT}.

To write code that works both with plain and extended moduli, the following
accessors are defined:

\fun{GEN}{get_Flx_mod}{GEN eT} returns the underlying modulus \kbd{T}.

\fun{GEN}{get_Flx_var}{GEN eT} returns the variable number of the modulus.

\fun{GEN}{get_Flx_degree}{GEN eT} returns the degree of the modulus.

Furthermore, \kbd{ZXT\_to\_FlxT} allows to convert an extended modulus for
a \kbd{FpX} to an extended modulus for the corresponding \kbd{Flx}.

\subsubsec{Basic operations}

\fun{ulong}{Flx_lead}{GEN x} returns the leading coefficient of $x$ as a
\kbd{ulong} (return $0$ for the zero polynomial).

\fun{GEN}{Flx_red}{GEN z, ulong p} converts from \kbd{zx} with
non-negative coefficients to \kbd{Flx} (by reducing them mod \kbd{p}).

\fun{int}{Flx_equal1}{GEN x} returns 1 (true) if the \kbd{Flx} $x$ is equal
to~1, 0~(false) otherwise.

\fun{int}{Flx_equal}{GEN x, GEN y} returns 1 (true) if the \kbd{Flx} $x$
and $y$ are equal, and 0~(false) otherwise.

\fun{GEN}{Flx_copy}{GEN x} returns a copy of \kbd{x}.

\fun{GEN}{Flx_add}{GEN x, GEN y, ulong p}

\fun{GEN}{Flx_Fl_add}{GEN y, ulong x, ulong p}

\fun{GEN}{Flx_neg}{GEN x, ulong p}

\fun{GEN}{Flx_neg_inplace}{GEN x, ulong p}, same as \kbd{Flx\_neg}, in place
(\kbd{x} is destroyed).

\fun{GEN}{Flx_sub}{GEN x, GEN y, ulong p}

\fun{GEN}{Flx_halve}{GEN x, ulong p} returns $z$ such that $2\*z = x$ modulo
$p$ assuming such $z$ exists.

\fun{GEN}{Flx_mul}{GEN x, GEN y, ulong p}

\fun{GEN}{Flx_Fl_mul}{GEN y, ulong x, ulong p}

\fun{GEN}{Flx_double}{GEN y, ulong p} returns $2\*y$.

\fun{GEN}{Flx_triple}{GEN y, ulong p} returns $3\*y$.

\fun{GEN}{Flx_mulu}{GEN y, ulong x, ulong p} as \kbd{Flx\_Fl\_mul} but do not
assume that $x<p$.

\fun{GEN}{Flx_Fl_mul_to_monic}{GEN y, ulong x, ulong p} returns $y\*x$
assuming the result is monic of the same degree as $y$ (in particular $x\neq
0$).

\fun{GEN}{Flx_sqr}{GEN x, ulong p}

\fun{GEN}{Flx_powu}{GEN x, ulong n, ulong p} returns $x^n$.

\fun{GEN}{Flx_divrem}{GEN x, GEN y, ulong p, GEN *pr}

\fun{GEN}{Flx_div}{GEN x, GEN y, ulong p}

\fun{GEN}{Flx_rem}{GEN x, GEN y, ulong p}

\fun{GEN}{Flx_deriv}{GEN z, ulong p}

\fun{GEN}{Flx_Frobenius}{GEN T, ulong p}

\fun{GEN}{Flx_matFrobenius}{GEN T, ulong p}

\fun{GEN}{Flx_gcd}{GEN a, GEN b, ulong p} returns a (not necessarily monic)
greatest common divisor of $x$  and $y$.

\fun{GEN}{Flx_halfgcd}{GEN x, GEN y, GEN p} returns a two-by-two \kbd{FlxM}
$M$ with determinant $\pm 1$ such that the image $(a,b)$ of $(x,y)$ by $M$
has the property that $\deg a \geq {\deg x \over 2} > \deg b$.

\fun{GEN}{Flx_extgcd}{GEN a, GEN b, ulong p, GEN *ptu, GEN *ptv}

\fun{GEN}{Flx_roots}{GEN f, ulong p} returns the vector of roots
of $f$ (without multiplicity, as a \typ{VECSMALL}). Assumes that $p$ is
prime.

\fun{ulong}{Flx_oneroot}{GEN f, ulong p} returns one root $0 \leq r < p$ of
the \kbd{Flx}~\kbd{f} in \kbd{\Z/p\Z}. Return $p$ if no root exists. Assumes
that \kbd{p} is prime.

\fun{ulong}{Flx_oneroot_split}{GEN f, ulong p} as \kbd{Flx\_oneroot} but
assume $f$ is totally split.

\fun{GEN}{Flx_roots_naive}{GEN f, ulong p} returns the vector of roots
of $f$ as a \typ{VECSMALL} (multiple roots are not repeated), found
by an exhaustive search. Efficient for very small $p$ !

\fun{GEN}{Flx_factor}{GEN f, ulong p}

\fun{GEN}{Flx_factor_squarefree}{GEN f, ulong p} returns the squarefree
factorization of $f$ modulo $p$. This is a vector $[u_1,\dots,u_k]$
of pairwise coprime \kbd{Flx} such that $u_k \neq 1$ and $f = \prod u_i^i$.
Shallow function.

\fun{GEN}{Flx_mod_Xn1}{GEN T, ulong n, ulong p} return $T$ modulo
$(X^n + 1, p)$. Shallow function.

\fun{GEN}{Flx_mod_Xnm1}{GEN T, ulong n, ulong p} return $T$ modulo
$(X^n - 1, p)$. Shallow function.

\fun{GEN}{Flx_degfact}{GEN f, ulong p} as \tet{FpX_degfact}.

\fun{GEN}{Flx_factorff_irred}{GEN P, GEN Q, ulong p} as
\tet{FpX_factorff_irred}.

\fun{GEN}{Flx_rootsff}{GEN P, GEN T, ulong p} as \tet{FpX_rootsff}.

\fun{GEN}{Flx_ffisom}{GEN P,GEN Q,ulong l} as \tet{FpX_ffisom}.

\subsubsec{Miscellaneous operations}

\fun{GEN}{pol0_Flx}{long sv} returns a zero \kbd{Flx} in variable $v$.

\fun{GEN}{zero_Flx}{long sv} alias for \kbd{pol0\_Flx}

\fun{GEN}{pol1_Flx}{long sv} returns the unit \kbd{Flx} in variable $v$.

\fun{GEN}{polx_Flx}{long sv} returns the variable $v$ as degree~1~\kbd{Flx}.

\fun{GEN}{monomial_Flx}{ulong a, long d, long sv} returns the \kbd{Flx}
$a\*X^d$ in variable $v$.

\fun{GEN}{Flx_normalize}{GEN z, ulong p}, as \kbd{FpX\_normalize}.

\fun{GEN}{Flx_rescale}{GEN P, ulong h, ulong p} returns $h^{\deg(P)} P(x/h)$,
\kbd{P} is a \kbd{Flx} and \kbd{h} is a non-zero integer.

\fun{GEN}{random_Flx}{long d, long sv, ulong p} returns a random \kbd{Flx}
in variable \kbd{v}, of degree less than~\kbd{d}.

\fun{GEN}{Flx_recip}{GEN x}, returns the reciprocal polynomial

\fun{ulong}{Flx_resultant}{GEN a, GEN b, ulong p}, returns the resultant
of \kbd{a} and \kbd{b}

\fun{ulong}{Flx_extresultant}{GEN a, GEN b, ulong p, GEN *ptU, GEN *ptV}
given two \kbd{Flx} \kbd{a} and \kbd{b},
returns their resultant and sets Bezout coefficients (if the resultant is 0,
the latter are not set).

\fun{GEN}{Flx_invBarrett}{GEN T, ulong p}, returns the Barrett inverse
$M$ of $T$ defined by $M(x)\*x^n\*T(1/x)\equiv 1\pmod{x^{n-1}}$ where $n$ is
the degree of $T$.

\fun{GEN}{Flx_renormalize}{GEN x, long l}, as \kbd{FpX\_renormalize}, where
$\kbd{l} = \kbd{lg(x)}$, in place.

\fun{GEN}{Flx_shift}{GEN T, long n} returns $\kbd{T} * x^n$ if $n\geq 0$,
and $\kbd{T} \bs x^{-n}$ otherwise.

\fun{long}{Flx_val}{GEN x} returns the valuation of \kbd{x}, i.e. the
multiplicity of the $0$ root.

\fun{long}{Flx_valrem}{GEN x, GEN *Z} as \kbd{RgX\_valrem}, returns the
valuation of \kbd{x}. In particular, if the valuation is $0$, set \kbd{*Z}
to $x$, not a copy.

\fun{GEN}{Flx_div_by_X_x}{GEN A, ulong a, ulong p, ulong *rem}, returns the
Euclidean quotient of the \kbd{Flx}~\kbd{A} by $X - \kbd{a}$, and sets
\kbd{rem} to the remainder $ \kbd{A}(\kbd{a})$.

\fun{ulong}{Flx_eval}{GEN x, ulong y, ulong p}, as \kbd{FpX\_eval}.

\fun{ulong}{Flx_eval_pre}{GEN x, ulong y, ulong p, ulong pi}, as \kbd{Flx\_eval},
assuming $pi$ is the pseudo inverse of $p$.

\fun{ulong}{Flx_eval_powers_pre}{GEN P, GEN y, ulong p, ulong pi}. Let $y$ be
the \typ{VECSMALL} $(1,a,\dots,a^n)$, where $n$ is the degree of the
\kbd{Flx} $P$, return $P(a)$, assuming $pi$ is the pseudo inverse of $p$.

\fun{GEN}{Flx_Flv_multieval}{GEN P, GEN v, ulong p} returns the vector
$[P(v[1]),\ldots,P(v[n])]$ as a \kbd{Flv}.

\fun{ulong}{Flx_dotproduct}{GEN x, GEN y, ulong p} returns the scalar product
of the coefficients of $x$ and $y$.

\fun{GEN}{Flx_deflate}{GEN P, long d} assuming $P$ is a polynomial of the
form $Q(X^d)$, return $Q$.

\fun{GEN}{Flx_splitting}{GEN p, long k}, as \tet{RgX_splitting}.

\fun{GEN}{Flx_inflate}{GEN P, long d} returns $P(X^d)$.

\fun{int}{Flx_is_squarefree}{GEN z, ulong p}

\fun{int}{Flx_is_irred}{GEN f, ulong p}, as \kbd{FpX\_is\_irred}.

\fun{int}{Flx_is_smooth}{GEN f, long r, ulong p} return $1$ if all
irreducible factors of $f$ are of degree at most $r$, $0$ otherwise.

\fun{long}{Flx_nbroots}{GEN f, ulong p}, as \kbd{FpX\_nbroots}.

\fun{long}{Flx_nbfact}{GEN z, ulong p}, as \kbd{FpX\_nbfact}.

\fun{long}{Flx_nbfact_Frobenius}{GEN f, GEN XP, ulong p},
as \kbd{FpX\_nbfact\_Frobenius}.

\fun{GEN}{Flx_degfact}{GEN f, ulong p}, as \kbd{FpX\_degfact}.

\fun{GEN}{Flx_nbfact_by_degree}{GEN z, long *nb, ulong p} Assume
that the \kbd{Flx} $z$ is squarefree mod the prime $p$. Returns a
\typ{VECSMALL} $D$ with $\deg z$ entries, such that $D[i]$ is the number of
irreducible factors of degree $i$. Set \kbd{nb} to the total number of
irreducible factors (the sum of the $D[i]$).

\fun{void}{Flx_ffintersect}{GEN P,GEN Q, long n, ulong p, GEN*SP, GEN*SQ, GEN
MA,GEN MB},\hfil\break
as \kbd{FpX\_ffintersect}

\fun{GEN}{Flv_polint}{GEN x, GEN y, ulong p, long sv} as \kbd{FpV\_polint},
returning an \kbd{Flx} in variable $v$.

\fun{GEN}{Flv_Flm_polint}{GEN x, GEN V, ulong p, long sv} equivalent (but
faster) to applying \kbd{Flv\_polint(x,$\ldots$)} to all the elements of the
vector $V$ (thus, returns a \kbd{FlxV}).

\fun{GEN}{Flv_invVandermonde}{GEN L, ulong d, ulong p} $L$ being a \kbd{Flv}
of length $n$, return the inverse $M$ of the Vandermonde matrix attached to
the elements of $L$, multiplied by \kbd{d}.
If $A$ is a \kbd{Flv} and $B=M\*A$, then the polynomial
$P=\sum_{i=1}^n B[i]\*X^{i-1}$ verifies $P(L[i])=d\*A[i]$ for
$1 \leq i \leq n$.

\fun{GEN}{Flv_roots_to_pol}{GEN a, ulong p, long sv} as
\kbd{FpV\_roots\_to\_pol} returning an \kbd{Flx} in variable $v$.

\subsec{\kbd{FlxV}} See \kbd{FpXV} operations.

\fun{GEN}{FlxV_Flc_mul}{GEN V, GEN W, ulong p}, as \kbd{FpXV\_FpC\_mul}.

\fun{GEN}{FlxV_red}{GEN V, ulong p} reduces each components with \kbd{Flx\_red}.

\fun{GEN}{FlxV_prod}{GEN V, ulong p}, \kbd{V} being a vector of \kbd{Flx},
returns their product.

\subsec{\kbd{FlxT}} See \kbd{FpXT} operations.

\fun{GEN}{FlxT_red}{GEN V, ulong p} reduces each leaf with \kbd{Flx\_red}.

\subsec{\kbd{Flxq}} See \kbd{FpXQ} operations.

\fun{GEN}{Flxq_add}{GEN x, GEN y, GEN T, ulong p}

\fun{GEN}{Flxq_sub}{GEN x, GEN y, GEN T, ulong p}

\fun{GEN}{Flxq_mul}{GEN x, GEN y, GEN T, ulong p}

\fun{GEN}{Flxq_sqr}{GEN y, GEN T, ulong p}

\fun{GEN}{Flxq_inv}{GEN x, GEN T, ulong p}

\fun{GEN}{Flxq_invsafe}{GEN x, GEN T, ulong p}

\fun{GEN}{Flxq_div}{GEN x, GEN y, GEN T, ulong p}

\fun{GEN}{Flxq_pow}{GEN x, GEN n, GEN T, ulong p}

\fun{GEN}{Flxq_powu}{GEN x, ulong n, GEN T, ulong p}

\fun{GEN}{Flxq_powers}{GEN x, long n, GEN T, ulong p}

\fun{GEN}{Flxq_matrix_pow}{GEN x, long m, long n, GEN T, ulong p},
see \kbd{FpXQ\_matrix\_pow}.

\fun{GEN}{Flxq_autpow}{GEN a, long n, GEN T, ulong p}
see \kbd{FpXQ\_autpow}.

\fun{GEN}{Flxq_autsum}{GEN a, long n, GEN T, GEN p}
see \kbd{FpXQ\_autsum}.

\fun{GEN}{Flxq_auttrace}{GEN a, ulong n, GEN T, ulong p}
see \kbd{FpXQ\_auttrace}.

\fun{GEN}{Flxq_ffisom_inv}{GEN S, GEN T, ulong p}, as \kbd{FpXQ\_ffisom\_inv}.

\fun{GEN}{Flx_Flxq_eval}{GEN f, GEN x, GEN T, ulong p} returns
$\kbd{f}(\kbd{x})$.

\fun{GEN}{Flx_FlxqV_eval}{GEN f, GEN x, GEN T, ulong p},
see \kbd{FpX\_FpXQV\_eval}.

\fun{GEN}{FlxqV_roots_to_pol}{GEN V, GEN T, ulong p, long v} as
\kbd{FqV\_roots\_to\_pol} returning an \kbd{FlxqX} in variable $v$.

\fun{int}{Flxq_issquare}{GEN x, GEN T, ulong p} returns $1$ if $x$ is a square
and $0$ otherwise. Assume that \kbd{T} is irreducible mod \kbd{p}.

\fun{int}{Flxq_is2npower}{GEN x, long n, GEN T, ulong p} returns $1$ if $x$ is
a $2^n$-th power and $0$ otherwise. Assume that \kbd{T} is irreducible mod
\kbd{p}.

\fun{GEN}{Flxq_order}{GEN a, GEN ord, GEN T, ulong p}
as \tet{FpXQ_order}.

\fun{GEN}{Flxq_log}{GEN a, GEN g, GEN ord, GEN T, ulong p}
as \tet{FpXQ_log}

\fun{GEN}{Flxq_sqrtn}{GEN x, GEN n, GEN T, ulong p, GEN *zn} as
\tet{FpXQ_sqrtn}.

\fun{GEN}{Flxq_sqrt}{GEN x, GEN T, ulong p} returns a square root of \kbd{x}.
Return \kbd{NULL} if \kbd{x} is not a square.

\fun{GEN}{Flxq_lroot}{GEN a, GEN T, ulong p} returns $x$ such that $x^p = a$.

\fun{GEN}{Flxq_lroot_fast}{GEN a, GEN V, GEN T, ulong p} assuming that
\kbd{V=Flxq\_powers(s,p-1,T,p)} where $s(x)^p \equiv x\pmod{T(x),p}$,
returns $b$ such that $b^p=a$. Only useful if $p$ is less than the degree of
$T$.

\fun{GEN}{Flxq_charpoly}{GEN x, GEN T, ulong p} returns the characteristic
polynomial of \kbd{x}

\fun{GEN}{Flxq_minpoly}{GEN x, GEN T, ulong p} returns the minimal polynomial
of \kbd{x}

\fun{ulong}{Flxq_norm}{GEN x, GEN T, ulong p} returns the norm of \kbd{x}

\fun{ulong}{Flxq_trace}{GEN x, GEN T, ulong p} returns the trace of \kbd{x}

\fun{GEN}{Flxq_conjvec}{GEN x, GEN T, ulong p} returns the conjugates
$[x,x^p,x^{p^2},\ldots,x^{p^{n-1}}]$ where $n$ is the degree of $T$.

\fun{GEN}{gener_Flxq}{GEN T, ulong p, GEN *po} returns a primitive root modulo
$(T,p)$. $T$ is an \kbd{Flx} assumed to be irreducible modulo the prime
$p$. If \kbd{po} is not \kbd{NULL} it is set to $[o,\var{fa}]$, where $o$ is the
order of the multiplicative group of the finite field, and \var{fa} is
its factorization.

\subsec{\kbd{FlxX}} See \kbd{FpXX} operations.

\fun{GEN}{pol1_FlxX}{long vX, long sx} returns the unit \kbd{FlxX} as a
\typ{POL} in variable \kbd{vX} which only coefficient is \kbd{pol1\_Flx(sx)}.

\fun{GEN}{polx_FlxX}{long vX, long sx} returns the variable $X$ as a
degree~1~\typ{POL} with \kbd{Flx} coefficients in the variable $x$.

\fun{long}{FlxY_degreex}{GEN P} return the degree of $P$ with respect to
the secondary variable.

\fun{GEN}{FlxX_add}{GEN P, GEN Q, ulong p}

\fun{GEN}{FlxX_sub}{GEN P, GEN Q, ulong p}

\fun{GEN}{FlxX_Fl_mul}{GEN x, ulong y, ulong p}

\fun{GEN}{FlxX_double}{GEN x, ulong p}

\fun{GEN}{FlxX_triple}{GEN x, ulong p}

\fun{GEN}{FlxX_neg}{GEN x, ulong p}

\fun{GEN}{FlxX_Flx_add}{GEN y, GEN x, ulong p}

\fun{GEN}{FlxX_Flx_mul}{GEN x, GEN y, ulong p}

\fun{GEN}{FlxY_Flx_div}{GEN x, GEN y, ulong p} divides the coefficients of $x$
by $y$ using \kbd{Flx\_div}.

\fun{GEN}{FlxX_deriv}{GEN P, ulong p} returns the derivative of \kbd{P} with
respect to the main variable.

\fun{GEN}{FlxY_evalx}{GEN P, ulong z, ulong p} $P$ being an \kbd{FlxY}, returns
the \kbd{Flx} $P(z,Y)$, where $Y$ is the main variable of $P$.

\fun{GEN}{FlxY_Flx_translate}{GEN P, GEN f, ulong p} $P$ being an \kbd{FlxY} and $f$
being an \kbd{Flx}, return $(P(x,Y+f(x))$, where $Y$ is the main variable of $P$.

\fun{ulong}{FlxY_evalx_powers_pre}{GEN P, GEN xp, ulong p, ulong pi}, \kbd{xp}
being the vector $[1,x,\dots,x^n]$, where $n$ is larger or equal to the degree
of $P$ in $X$, return $P(x,Y)$, where $Y$ is the main variable of $Q$, assuming
$pi$ is the pseudo inverse of $p$.

\fun{ulong}{FlxY_eval_powers_pre}{GEN P, GEN xp, GEN yp, ulong p, ulong pi},
\kbd{xp} being the vector $[1,x,\dots,x^n]$, where $n$ is larger or equal to the degree
of $P$ in $X$ and \kbd{yp} being the vector $[1,y,\dots,y^m]$, where $m$ is larger or equal to the degree of $P$ in $Y$ return $P(x,y)$, assuming
$pi$ is the pseudo inverse of $p$.

\fun{GEN}{FlxY_Flxq_evalx}{GEN x, GEN y, GEN T, ulong p} as \kbd{FpXY\_FpXQ\_evalx}.

\fun{GEN}{FlxY_FlxqV_evalx}{GEN x, GEN V, GEN T, ulong p} as \kbd{FpXY\_FpXQV\_evalx}.

\fun{GEN}{FlxX_renormalize}{GEN x, long l}, as \kbd{normalizepol}, where
$\kbd{l} = \kbd{lg(x)}$, in place.

\fun{GEN}{FlxX_resultant}{GEN u, GEN v, ulong p, long sv} Returns
$\text{Res}_X(u, v)$, which is an \kbd{Flx}. The coefficients of \kbd{u}
and \kbd{v} are assumed to be in the variable $v$.

\fun{GEN}{Flx_FlxY_resultant}{GEN a, GEN b, ulong p}
Returns $\text{Res}_x(a, b)$, which is an \kbd{Flx}
in the main variable of \kbd{b}.

\fun{GEN}{FlxX_shift}{GEN a, long n}

\fun{GEN}{FlxX_swap}{GEN x, long n, long ws}, as \kbd{RgXY\_swap}.

\fun{GEN}{FlxYqq_pow}{GEN x, GEN n, GEN S, GEN T, ulong p}, as
\kbd{FpXYQQ\_pow}.

\subsec{\kbd{FlxqX}} See \kbd{FpXQX} operations.

\subsubsec{Preconditioned reduction}

For faster reduction, the modulus \kbd{S} can be replaced by an extended
modulus, which is an \kbd{FlxqXT}, in all \kbd{FlxqXQ}-classes
functions, and in \kbd{FlxqX\_rem} and \kbd{FlxqX\_divrem}.

\fun{GEN}{FlxqX_get_red}{GEN S, GEN T, ulong p} returns the extended modulus
\kbd{eS}.

To write code that works both with plain and extended moduli, the following
accessors are defined:

\fun{GEN}{get_FlxqX_mod}{GEN eS} returns the underlying modulus \kbd{S}.

\fun{GEN}{get_FlxqX_var}{GEN eS} returns the variable number of the modulus.

\fun{GEN}{get_FlxqX_degree}{GEN eS} returns the degree of the modulus.

\subsubsec{basic functions}

\fun{GEN}{random_FlxqX}{long d, long v, GEN T, ulong p} returns a random
\kbd{FlxqX} in variable \kbd{v}, of degree less than~\kbd{d}.

\fun{GEN}{zxX_to_Kronecker}{GEN P, GEN Q} assuming $P(X,Y)$ is a polynomial
of degree in $X$ strictly less than $n$, returns $P(X,X^{2*n-1})$, the
Kronecker form of $P$.

\fun{GEN}{Kronecker_to_FlxqX}{GEN z, GEN T, ulong p}. Let $n = \deg T$ and let
$P(X,Y)\in \Z[X,Y]$ lift a polynomial in $K[Y]$, where $K := \F_p[X]/(T)$ and
$\deg_X P < 2n-1$ --- such as would result from multiplying minimal degree
lifts of two polynomials in $K[Y]$. Let $z = P(t,t^{2*n-1})$ be a Kronecker
form of $P$, this function returns $Q\in \Z[X,t]$ such that $Q$ is congruent to
$P(X,t)$ mod $(p, T(X))$, $\deg_X Q < n$, and all coefficients are in $[0,p[$.
Not stack-clean. Note that $t$ need not be the same variable as $Y$!

\fun{GEN}{FlxqX_red}{GEN z, GEN T, ulong p}

\fun{GEN}{FlxqX_normalize}{GEN z, GEN T, ulong p}

\fun{GEN}{FlxqX_mul}{GEN x, GEN y, GEN T, ulong p}

\fun{GEN}{FlxqX_Flxq_mul}{GEN P, GEN U, GEN T, ulong p}

\fun{GEN}{FlxqX_Flxq_mul_to_monic}{GEN P, GEN U, GEN T, ulong p}
returns $P*U$ assuming the result is monic of the same degree as $P$ (in
particular $U\neq 0$).

\fun{GEN}{FlxqX_sqr}{GEN x, GEN T, ulong p}

\fun{GEN}{FlxqX_powu}{GEN x, ulong n, GEN T, ulong p}

\fun{GEN}{FlxqX_divrem}{GEN x, GEN y, GEN T, ulong p, GEN *pr}

\fun{GEN}{FlxqX_div}{GEN x, GEN y, GEN T, ulong p}

\fun{GEN}{FlxqX_rem}{GEN x, GEN y, GEN T, ulong p}

\fun{GEN}{FlxqX_invBarrett}{GEN T, GEN Q, ulong p}

\fun{GEN}{FlxqX_gcd}{GEN x, GEN y, ulong p} returns a (not necessarily monic)
greatest common divisor of $x$  and $y$.

\fun{GEN}{FlxqX_extgcd}{GEN x, GEN y, GEN T, ulong p, GEN *ptu, GEN *ptv}

\fun{GEN}{FlxqX_halfgcd}{GEN x, GEN y, GEN T, ulong p}, see \kbd{FpX\_halfgcd}.

\fun{GEN}{FlxqXV_prod}{GEN V, GEN T, ulong p}

\fun{GEN}{FlxqX_safegcd}{GEN P, GEN Q, GEN T, ulong p} Returns the \emph{monic}
GCD of $P$ and $Q$ if Euclid's algorithm succeeds and \kbd{NULL} otherwise. In
particular, if $p$ is not prime or $T$ is not irreducible over $\F_p[X]$, the
routine may still be used (but will fail if non-invertible leading terms
occur).

\fun{GEN}{FlxqX_Frobenius}{GEN S, GEN T, GEN p}, as \kbd{FpXQX\_Frobenius}

\fun{GEN}{FlxqXQ_halfFrobenius}{GEN A, GEN S, GEN T, GEN p}, as
\kbd{FpXQXQ\_halfFrobenius}

\fun{GEN}{FlxqX_roots}{GEN f, GEN T, ulong p} return the roots of \kbd{f} in
$\F_p[X]/(T)$. Assumes \kbd{p} is prime and \kbd{T} irreducible in $\F_p[X]$.

\fun{GEN}{FlxqX_factor}{GEN f, GEN T, ulong p} return the factorization of
\kbd{f} over $\F_p[X]/(T)$. Assumes \kbd{p} is prime and \kbd{T} irreducible
in $\F_p[X]$.

\fun{long}{FlxqX_nbroots}{GEN S, GEN T, GEN p}, as \kbd{FpX\_nbroots}.

\fun{GEN}{FlxqX_FlxqXQ_eval}{GEN Q, GEN x, GEN S, GEN T, ulong p} as
\kbd{FpX\_FpXQ\_eval}.

\fun{GEN}{FlxqX_FlxqXQV_eval}{GEN P, GEN V, GEN S, GEN T, ulong p} as
\kbd{FpX\_FpXQV\_eval}.

\subsec{\kbd{FlxqXQ}} See \kbd{FpXQXQ} operations.

\fun{GEN}{FlxqXQ_mul}{GEN x, GEN y, GEN S, GEN T, ulong p}

\fun{GEN}{FlxqXQ_sqr}{GEN x, GEN S, GEN T, ulong p}

\fun{GEN}{FlxqXQ_inv}{GEN x, GEN S, GEN T, ulong p}

\fun{GEN}{FlxqXQ_invsafe}{GEN x, GEN S, GEN T, ulong p}

\fun{GEN}{FlxqXQ_div}{GEN x, GEN y, GEN S, GEN T, ulong p}

\fun{GEN}{FlxqXQ_pow}{GEN x, GEN n, GEN S, GEN T, ulong p}

\fun{GEN}{FlxqXQ_powu}{GEN x, ulong n, GEN S, GEN T, ulong p}

\fun{GEN}{FlxqXQ_powers}{GEN x, long n, GEN S, GEN T, ulong p}

\fun{GEN}{FlxqXQ_matrix_pow}{GEN x, long n, long m, GEN S, GEN T, ulong p}

\fun{GEN}{FlxqXQV_autpow}{GEN a, long n, GEN S, GEN T, ulong p}
as \kbd{FpXQXQV\_autpow}

\fun{GEN}{FlxqXQV_autsum}{GEN a, long n, GEN S, GEN T, ulong p}
as \kbd{FpXQXQV\_autsum}

\subsec{\kbd{F2x}} An \kbd{F2x}~\kbd{z} is a \typ{VECSMALL}
representing a polynomial over $\F_2[X]$. Specifically
\kbd{z[0]} is the usual codeword, \kbd{z[1] = evalvarn($v$)} for some
variable $v$ and the coefficients are given by the bits of remaining
words by increasing degree.

\subsubsec{Basic operations}

\fun{ulong}{F2x_coeff}{GEN x, long i} returns the coefficient $i\ge 0$ of $x$.

\fun{void}{F2x_clear}{GEN x, long i} sets the coefficient $i\ge 0$ of $x$ to
$0$.

\fun{void}{F2x_flip}{GEN x, long i} adds $1$ to the coefficient $i\ge 0$ of $x$.

\fun{void}{F2x_set}{GEN x, long i} sets the coefficient $i\ge 0$ of $x$ to $1$.

\fun{GEN}{F2x_copy}{GEN x}

\fun{GEN}{Flx_to_F2x}{GEN x}

\fun{GEN}{Z_to_F2x}{GEN x, long v}

\fun{GEN}{ZX_to_F2x}{GEN x}

\fun{GEN}{F2v_to_F2x}{GEN x, long sv}

\fun{GEN}{F2x_to_Flx}{GEN x}

\fun{GEN}{F2x_to_ZX}{GEN x}

\fun{GEN}{pol0_F2x}{long sv} returns a zero \kbd{F2x} in variable $v$.

\fun{GEN}{zero_F2x}{long sv} alias for \kbd{pol0\_F2x}.

\fun{GEN}{pol1_F2x}{long sv} returns the \kbd{F2x} in variable $v$ constant to
$1$.

\fun{GEN}{polx_F2x}{long sv} returns the variable $v$ as degree~1~\kbd{F2x}.

\fun{GEN}{monomial_F2x}{long d, long sv} returns the \kbd{F2x}
$X^d$ in variable $v$.

\fun{GEN}{random_F2x}{long d, long sv} returns a random \kbd{F2x}
in variable \kbd{v}, of degree less than~\kbd{d}.

\fun{long}{F2x_degree}{GEN x} returns the degree of the \kbd{F2x x}. The
degree of $0$ is defined as $-1$.

\fun{int}{F2x_equal1}{GEN x}

\fun{int}{F2x_equal}{GEN x, GEN y}

\fun{GEN}{F2x_1_add}{GEN y} returns \kbd{y+1} where \kbd{y} is a \kbd{Flx}.

\fun{GEN}{F2x_add}{GEN x, GEN y}

\fun{GEN}{F2x_mul}{GEN x, GEN y}

\fun{GEN}{F2x_sqr}{GEN x}

\fun{GEN}{F2x_divrem}{GEN x, GEN y, GEN *pr}

\fun{GEN}{F2x_rem}{GEN x, GEN y}

\fun{GEN}{F2x_div}{GEN x, GEN y}

\fun{GEN}{F2x_renormalize}{GEN x, long lx}

\fun{GEN}{F2x_deriv}{GEN x}

\fun{GEN}{F2x_deflate}{GEN x, long d}

\fun{ulong}{F2x_eval}{GEN P, ulong u} returns $P(u)$.

\fun{void}{F2x_shift}{GEN x, long d} as \tet{RgX_shift}

\fun{void}{F2x_even_odd}{GEN p, GEN *pe, GEN *po} as \tet{RgX_even_odd}

\fun{long}{F2x_valrem}{GEN x, GEN *Z}

\fun{GEN}{F2x_extgcd}{GEN a, GEN b, GEN *ptu, GEN *ptv}

\fun{GEN}{F2x_gcd}{GEN a, GEN b}

\fun{GEN}{F2x_halfgcd}{GEN a, GEN b}

\fun{int}{F2x_issquare}{GEN x} returns $1$ if $x$ is a square of a \kbd{F2x}
and $0$ otherwise.

\fun{int}{F2x_is_irred}{GEN f}, as \tet{FpX_is_irred}.

\fun{GEN}{F2x_degfact}{GEN f} as \tet{FpX_degfact}.

\fun{GEN}{F2x_sqrt}{GEN x} returns the squareroot of $x$, assuming $x$ is a
square of a \kbd{F2x}.

\fun{GEN}{F2x_Frobenius}{GEN T}

\fun{GEN}{F2x_matFrobenius}{GEN T}

\fun{GEN}{F2x_factor}{GEN f}

\fun{GEN}{F2x_factor_squarefree}{GEN f}

\subsec{\kbd{F2xq}} See \kbd{FpXQ} operations.

\fun{GEN}{F2xq_mul}{GEN x, GEN y, GEN pol}

\fun{GEN}{F2xq_sqr}{GEN x,GEN pol}

\fun{GEN}{F2xq_div}{GEN x,GEN y,GEN T}

\fun{GEN}{F2xq_inv}{GEN x, GEN T}

\fun{GEN}{F2xq_invsafe}{GEN x, GEN T}

\fun{GEN}{F2xq_pow}{GEN x, GEN n, GEN pol}

\fun{GEN}{F2xq_powu}{GEN x, ulong n, GEN pol}

\fun{ulong}{F2xq_trace}{GEN x, GEN T}

\fun{GEN}{F2xq_conjvec}{GEN x, GEN T} returns the vector of conjugates
$[x,x^2,x^{2^2},\ldots,x^{2^{n-1}}]$ where $n$ is the degree of $T$.

\fun{GEN}{F2xq_log}{GEN a, GEN g, GEN ord, GEN T}

\fun{GEN}{F2xq_order}{GEN a, GEN ord, GEN T}

\fun{GEN}{F2xq_Artin_Schreier}{GEN a, GEN T} returns a solution of $x^2+x=a$,
assuming it exists.

\fun{GEN}{F2xq_sqrt}{GEN a, GEN T}

\fun{GEN}{F2xq_sqrt_fast}{GEN a, GEN s, GEN T} assuming that
$s^2 \equiv x\pmod{T(x)}$, computes $b \equiv a(s)\pmod{T}$ so that $b^2=a$.

\fun{GEN}{F2xq_sqrtn}{GEN a, GEN n, GEN T, GEN *zeta}

\fun{GEN}{gener_F2xq}{GEN T, GEN *po}

\fun{GEN}{F2xq_powers}{GEN x, long n, GEN T}

\fun{GEN}{F2xq_matrix_pow}{GEN x, long m, long n, GEN T}

\fun{GEN}{F2x_F2xq_eval}{GEN f, GEN x, GEN T}

\fun{GEN}{F2x_F2xqV_eval}{GEN f, GEN x, GEN T}, see \kbd{FpX\_FpXQV\_eval}.

\fun{GEN}{F2xq_autpow}{GEN a, long n, GEN T} computes $\sigma^n(X)$ assuming
$a=\sigma(X)$ where $\sigma$ is an automorphism of the algebra $\F_2[X]/T(X)$.

\subsec{\kbd{F2xqV}, \kbd{F2xqM}}. See \kbd{FqV}, \kbd{FqM} operations.

\fun{GEN}{F2xqM_F2xqC_mul}{GEN a, GEN b, GEN T}

\fun{GEN}{F2xqM_ker}{GEN x, GEN T}

\fun{GEN}{F2xqM_det}{GEN a, GEN T}

\fun{GEN}{F2xqM_image}{GEN x, GEN T}

\fun{GEN}{F2xqM_inv}{GEN a, GEN T}

\fun{GEN}{F2xqM_mul}{GEN a, GEN b, GEN T}

\fun{long}{F2xqM_rank}{GEN x, GEN T}

\fun{GEN}{matid_F2xqM}{long n, GEN T}

\subsec{\kbd{F2xX}}. See \kbd{FpXX} operations.

\fun{GEN}{ZXX_to_F2xX}{GEN x, long v}

\fun{GEN}{FlxX_to_F2xX}{GEN x}

\fun{GEN}{F2xX_to_ZXX}{GEN B}

\fun{GEN}{F2xX_renormalize}{GEN x, long lx}

\fun{long}{F2xY_degreex}{GEN P} return the degree of $P$ with respect to
the secondary variable.

\fun{GEN}{pol1_F2xX}{long v, long sv}

\fun{GEN}{polx_F2xX}{long v, long sv}

\fun{GEN}{F2xX_add}{GEN x, GEN y}

\fun{GEN}{F2xX_F2x_mul}{GEN x, GEN y}

\fun{GEN}{F2xX_deriv}{GEN P} returns the derivative of \kbd{P} with respect to
the main variable.

\fun{GEN}{Kronecker_to_F2xqX}{GEN z, GEN T}

\fun{GEN}{F2xX_to_Kronecker}{GEN z, GEN T}

\fun{GEN}{F2xY_F2xq_evalx}{GEN x, GEN y, GEN T} as \kbd{FpXY\_FpXQ\_evalx}.

\fun{GEN}{F2xY_F2xqV_evalx}{GEN x, GEN V, GEN T} as \kbd{FpXY\_FpXQV\_evalx}.

\subsec{\kbd{F2xXV/F2xXC}}. See \kbd{FpXXV} operations.

\fun{GEN}{FlxXC_to_F2xXC}{GEN B}

\fun{GEN}{F2xXC_to_ZXXC}{GEN B}

\subsec{\kbd{F2xqX}}. See \kbd{FlxqX} operations.

\fun{GEN}{random_F2xqX}{long d, long v, GEN T, ulong p} returns a random
\kbd{F2xqX} in variable \kbd{v}, of degree less than~\kbd{d}.

\fun{GEN}{F2xqX_red}{GEN z, GEN T}

\fun{GEN}{F2xqX_normalize}{GEN z, GEN T}

\fun{GEN}{F2xqX_F2xq_mul}{GEN P, GEN U, GEN T}

\fun{GEN}{F2xqX_F2xq_mul_to_monic}{GEN P, GEN U, GEN T}

\fun{GEN}{F2xqX_mul}{GEN x, GEN y, GEN T}

\fun{GEN}{F2xqX_sqr}{GEN x, GEN T}

\fun{GEN}{F2xqX_rem}{GEN x, GEN y, GEN T}

\fun{GEN}{F2xqX_div}{GEN x, GEN y, GEN T}

\fun{GEN}{F2xqX_divrem}{GEN x, GEN y, GEN T, GEN *pr}

\fun{GEN}{F2xqX_gcd}{GEN x, GEN y, GEN T}

\fun{GEN}{F2xqX_F2xqXQ_eval}{GEN Q, GEN x, GEN S, GEN T} as
\kbd{FpX\_FpXQ\_eval}.

\fun{GEN}{F2xqX_F2xqXQV_eval}{GEN P, GEN V, GEN S, GEN T} as
\kbd{FpX\_FpXQV\_eval}.

\fun{GEN}{F2xqX_roots}{GEN f, GEN T} return the roots of \kbd{f} in
$\F_2[X]/(T)$. Assumes \kbd{T} irreducible in $\F_2[X]$.

\fun{GEN}{F2xqX_factor}{GEN f, GEN T} return the factorisation of \kbd{f} over
$\F_2[X]/(T)$. Assumes \kbd{T} irreducible in $\F_2[X]$.

\subsec{\kbd{F2xqXQ}}. See \kbd{FlxqXQ} operations.

\fun{GEN}{F2xqXQ_mul}{GEN x, GEN y, GEN S, GEN T}

\fun{GEN}{F2xqXQ_sqr}{GEN x, GEN S, GEN T}

\fun{GEN}{F2xqXQ_pow}{GEN x, GEN n, GEN S, GEN T}

\fun{GEN}{F2xqXQ_powers}{GEN x, long n, GEN S, GEN T}

\fun{GEN}{F2xqXQV_autpow}{GEN a, long n, GEN S, GEN T}
as \kbd{FpXQXQV\_autpow}

\fun{GEN}{F2xqXQV_auttrace}{GEN a, long n, GEN S, GEN T}. Let
$\sigma$ be the automorphism defined by $\sigma(X)=a[1]\pmod{T(X)}$ and
$\sigma(Y)=a[2]\pmod{S(X,Y),T(X)}$; returns the vector
$[\sigma^n(X),\sigma^n(Y),b+\sigma(b)+\ldots+\sigma^{n-1}(b)]$
where $b=a[3]$.

\subsec{Functions returning objects with \typ{INTMOD} coefficients}

Those functions are mostly needed for interface reasons: \typ{INTMOD}s should
not be used in library mode since the modular kernel is more flexible and more
efficient, but GP users do not have access to the modular kernel.
We document them for completeness:

\fun{GEN}{Fp_to_mod}{GEN z, GEN p}, \kbd{z} a \typ{INT}. Returns \kbd{z *
Mod(1,p)}, normalized. Hence the returned value is a \typ{INTMOD}.

\fun{GEN}{FpX_to_mod}{GEN z, GEN p}, \kbd{z} a \kbd{ZX}. Returns \kbd{z *
Mod(1,p)}, normalized. Hence the returned value has \typ{INTMOD} coefficients.

\fun{GEN}{FpC_to_mod}{GEN z, GEN p}, \kbd{z} a \kbd{ZC}. Returns \kbd{Col(z) *
Mod(1,p)}, a \typ{COL} with \typ{INTMOD} coefficients.

\fun{GEN}{FpV_to_mod}{GEN z, GEN p}, \kbd{z} a \kbd{ZV}. Returns \kbd{Vec(z) *
Mod(1,p)}, a \typ{VEC} with \typ{INTMOD} coefficients.

\fun{GEN}{FpVV_to_mod}{GEN z, GEN p}, \kbd{z} a \kbd{ZVV}. Returns \kbd{Vec(z) *
Mod(1,p)}, a \typ{VEC} of \typ{VEC} with \typ{INTMOD} coefficients.

\fun{GEN}{FpM_to_mod}{GEN z, GEN p}, \kbd{z} a \kbd{ZM}. Returns \kbd{z *
Mod(1,p)}, with \typ{INTMOD} coefficients.

\fun{GEN}{F2c_to_mod}{GEN x}

\fun{GEN}{F2m_to_mod}{GEN x}

\fun{GEN}{Flc_to_mod}{GEN z}

\fun{GEN}{Flm_to_mod}{GEN z}

\fun{GEN}{FpXQC_to_mod}{GEN V, GEN T, GEN p} $V$ being a vector of \kbd{FpXQ},
converts each entry to a \typ{POLMOD} with \typ{INTMOD} coefficients, and return
a \typ{COL}.

\fun{GEN}{QXQV_to_mod}{GEN V, GEN T} $V$ a vector of \kbd{QXQ}, which
are lifted representatives of elements of $\Q[X]/(T)$ (number field elements
in most applications) and $T$ is in $\Z[X]$. Return a vector where all
non-rational entries are converted to \typ{POLMOD} modulo $T$; no reduction
mod $T$ is attempted: the representatives should be already reduced. Used to
normalize the output of \kbd{nfroots}.

\fun{GEN}{QXQXV_to_mod}{GEN V, GEN T} $V$ a vector of polynomials whose
coefficients are \kbd{QXQ}. Analogous to \kbd{QXQV\_to\_mod}.
Used to normalize the output of \kbd{nffactor}.

\fun{GEN}{QXQX_to_mod_shallow}{GEN z, GEN T} $v$ a polynomial with \kbd{QXQ}
coefficients; replace them by \kbd{mkpolmod(.,T)}. Shallow function.

The following functions are obsolete and should not be used: they receive a
polynomial with arbitrary coefficients, apply \kbd{RgX\_to\_FpX}, a function
from the modular kernel, then \kbd{*\_to\_mod}:

\fun{GEN}{rootmod}{GEN f, GEN p}, applies \kbd{FpX\_roots}.

\fun{GEN}{rootmod2}{GEN f, GEN p}, applies \kbd{ZX\_to\_flx} then
\kbd{Flx\_roots\_naive}.

\fun{GEN}{factmod}{GEN f, GEN p} applies \kbd{FpX\_factor}.

\fun{GEN}{simplefactmod}{GEN f, GEN p} applies \kbd{FpX\_degfact}.

\subsec{Chinese remainder theorem over $\Z$}

\fun{GEN}{Z_chinese}{GEN a, GEN b, GEN A, GEN B} returns the integer
in $[0, \lcm(A,B)[$ congruent to $a$ mod $A$ and $b$ mod $B$, assuming it
exists; in other words, that $a$ and $b$ are congruent mod $\gcd(A,B)$.

\fun{GEN}{Z_chinese_all}{GEN a, GEN b, GEN A, GEN B, GEN *pC} as
\kbd{Z\_chinese}, setting \kbd{*pC} to the lcm of $A$ and $B$.

\fun{GEN}{Z_chinese_coprime}{GEN a, GEN b, GEN A, GEN B, GEN C}, as
\kbd{Z\_chinese}, assuming that $\gcd(A,B) = 1$ and that $C = \lcm(A,B) = AB$.

\fun{void}{Z_chinese_pre}{GEN A, GEN B, GEN *pC, GEN *pU, GEN *pd}
initializes chinese remainder computations modulo $A$ and $B$. Sets
\kbd{*pC} to $\lcm(A,B)$, \kbd{*pd} to $\gcd(A,B)$,
\kbd{*pU} to an integer congruent to $0$ mod $(A/d)$ and $1$ mod $(B/d)$.
It is allowed to set \kbd{pd = NULL}, in which case, $d$ is still
computed, but not saved.

\fun{GEN}{Z_chinese_post}{GEN a, GEN b, GEN C, GEN U, GEN d} returns
the solution to the chinese remainder problem $x$ congruent
to $a$ mod $A$ and $b$ mod $B$, where $C, U, d$ were set in
\kbd{Z\_chinese\_pre}. If $d$ is \kbd{NULL}, assume the problem has a
solution. Otherwise, return \kbd{NULL} if it has no solution.

\medskip

\fun{GEN}{ZV_producttree}{GEN x} where $x$ are vectors of integer (or
\typ{VECSMALL}s) of length $n\ge 1$, return the vector of \typ{VEC}s
$[f(x),f^2(x),\ldots,f^k(x)]$ where $f$ is the transformation
$[a_1,a_2,\ldots,a_m] \mapsto [a_1\*a_2,a_3\*a_4,\ldots,a_{m-1}\*a_m]$ if $m$
is even and $[a_1\*a_2,a_3\*a4,\ldots,a_{m-2}\*a_{m-1},a_m]$ if $m$ is odd,
and $k$ is chosen so that $f^k(x)$ is of length $1$ (This is the vector
$[a_1\*a_2\*ldots\*a_m]$).

\fun{GEN}{ZV_chinese}{GEN A, GEN P, GEN *pt_mod}
where $A$ and $P$ are vectors of integer (or \typ{VECSMALL}s) of the same
length $n\ge 1$, the elements of $P$ being pairwise coprime, and $M$ being the
product of the elements of $P$, returns the integer in $[0, M[$ congruent to
$A[i]$ mod $P[i]$ for all $1\leq i\leq n$.  If \kbd{pt\_mod} is not \kbd{NULL},
set \kbd{*pt\_mod} to $M$

\fun{GEN}{ZV_chinese_tree}{GEN A, GEN P, GEN T, GEN *pt_mod}
as \kbd{ZV\_chinese}, where $T$ is assumed to be the tree created by
\kbd{ZV\_producttree(P)}.

\fun{GEN}{ncV_chinese_center}{GEN A, GEN P, GEN *pt_mod}
where $A$ is a vector of \kbd{VECSMALL}s (seen as vectors of unsigned integers)
and $P$ a \typ{VECSMALL} of the same length $n\ge 1$, the elements of $P$
being pairwise coprime, and $M$ being the product of the elements of $P$,
returns the \typ{COL} whose entries are integers in $[-M/2, M/2[$ congruent to $A[i]$
mod $P[i]$ for all $1\leq i\leq n$.
If \kbd{pt\_mod} is not \kbd{NULL}, set \kbd{*pt\_mod} to $M$.

\fun{GEN}{nmV_chinese_center}{GEN A, GEN P, GEN *pt_mod}
where $A$ is a vector of \kbd{MATSMALL}s (seen as matrices of unsigned integers)
 and $P$ a \typ{VECSMALL} of the same length $n\ge 1$, the elements of $P$
being pairwise coprime, and $M$ being the product of the elements of $P$,
returns the matrix whose entries are integers in $[-M/2, M/2[$ congruent to $A[i]$
mod $P[i]$ for all $1\leq i\leq n$.
If \kbd{pt\_mod} is not \kbd{NULL}, set \kbd{*pt\_mod} to $M$.
NB: this function uses the parallel GP interface.

\fun{GEN}{Z_ZV_mod}{GEN A, GEN P}
$P$ being a vector of integers of length $n\ge 1$, the elements of $P$ being
pairwise coprime, return a vector $B$ of the same length such that
$B[i]=A\pmod{P[i]}$ and $0\leq B[i] < P[i]$ for all $1\leq i\leq n$.

\fun{GEN}{Z_nv_mod}{GEN A, GEN P}
$P$ being a \typ{VECSMALL} of length $n\ge 1$, the elements of $P$ being
pairwise coprime, return a \typ{VECSMALL} $B$ of the same length such that
$B[i]=A\pmod{P[i]}$ and $0\leq B[i] < P[i]$ for all $1\leq i\leq n$.
The entries of $P$ and $B$ are treated as \kbd{ulong}s.

\fun{GEN}{ZX_nv_mod_tree}{GEN A, GEN P, GEN T} $A$ being a \kbd{ZX}
and $P$ a \typ{VECSMALL} of length $n\ge 1$, the elements of $P$ being
pairwise coprime, return the vector of \kbd{Flx}
$[A \pmod{P[1]},\ldots,A \pmod{P[n]}]$,
where $T$ is assumed to be the tree created by \kbd{ZV\_producttree(P)}.

\medskip

The following pair of functions is used in homomorphic imaging schemes,
when reconstructing an integer from its images modulo pairwise coprime
integers. The idea is as follows: we want to discover an integer $H$ which
satisfies $|H| < B$ for some known bound $B$; we are given pairs $(H_p, p)$
with $H$ congruent to $H_p$ mod $p$ and all $p$ pairwise coprime.

Given \kbd{H} congruent to $H_p$ modulo a number of $p$, whose product is
$q$, and a new pair $(\kbd{Hp}, \kbd{p})$, \kbd{p} coprime to $q$, the
following incremental functions use the chinese remainder theorem (CRT) to
find a new \kbd{H}, congruent to the preceding one modulo $q$, but also to
\kbd{Hp} modulo \kbd{p}. It is defined uniquely modulo $qp$, and we choose
the centered representative. When $P$ is larger than $2B$, we have $\kbd{H} =
H$, but of course, the value of \kbd{H} may stabilize sooner. In many
applications it is possible to directly check that such a partial result is
correct.

\fun{GEN}{Z_init_CRT}{ulong Hp, ulong p} given a \kbd{Fl} \kbd{Hp} in
$[0, p-1]$, returns the centered representative \kbd{H} congruent to \kbd{Hp}
modulo \kbd{p}.

\fun{int}{Z_incremental_CRT}{GEN *H, ulong Hp, GEN *q, ulong p}
given a \typ{INT} \kbd{*H}, centered modulo \kbd{*q}, a new pair $(\kbd{Hp},
\kbd{p})$ with \kbd{p} coprime to \kbd{q}, this function updates \kbd{*H} so
that it also becomes congruent to $(\kbd{Hp}, \kbd{p})$, and \kbd{*q} to the
product$\kbd{qp} = \kbd{p} \cdot \kbd{*q}$. It returns $1$ if the new value
is equal to the old one, and $0$ otherwise.

\fun{GEN}{chinese1_coprime_Z}{GEN v} an alternative divide-and-conquer
implementation: $v$ is a vector of \typ{INTMOD} with pairwise coprime moduli.
Return the \typ{INTMOD} solving the corresponding chinese remainder problem.
This is a streamlined version of

\fun{GEN}{chinese1}{GEN v}, which solves a general chinese remainder problem
(not necessarily over $\Z$, moduli not assumed coprime).


As above, for $H$ a \kbd{ZM}: we assume that $H$ and all \kbd{Hp} have
dimension $> 0$. The original \kbd{*H} is destroyed.

\fun{GEN}{ZM_init_CRT}{GEN Hp, ulong p}

\fun{int}{ZM_incremental_CRT}{GEN *H, GEN Hp, GEN *q, ulong p}

As above for $H$ a \kbd{ZX}: note that the degree may increase or decrease.
The original \kbd{*H} is destroyed.

\fun{GEN}{ZX_init_CRT}{GEN Hp, ulong p, long v}

\fun{int}{ZX_incremental_CRT}{GEN *H, GEN Hp, GEN *q, ulong p}

\subsec{Rational reconstruction}

\fun{int}{Fp_ratlift}{GEN x, GEN m, GEN amax, GEN bmax, GEN *a, GEN *b}.
Assuming that $0 \leq x < m$, $\kbd{amax} \geq 0$, and
$\kbd{bmax} > 0$ are \typ{INT}s, and that $2 \kbd{amax} \kbd{bmax} < m$,
attempts to recognize $x$ as a rational $a/b$, i.e. to find \typ{INT}s $a$
and $b$ such that

\item $a \equiv b x$ modulo $m$,

\item $|a| \leq \kbd{amax}$, $0 < b \leq \kbd{bmax}$,

\item $\gcd(m,b) = \gcd(a,b)$.

\noindent If unsuccessful, the routine returns $0$ and leaves $a$, $b$
unchanged; otherwise it returns $1$ and sets $a$ and $b$.

In almost all applications, we actually know that a solution exists, as well
as a non-zero multiple $B$ of $b$, and $m = p^\ell$ is a prime power, for a
prime $p$ chosen coprime to $B$ hence to $b$. Under the single assumption
$\gcd(m,b) = 1$, if a solution $a,b$ exists satisfying the three conditions
above, then it is unique.

\fun{GEN}{FpM_ratlift}{GEN M, GEN m, GEN amax, GEN bmax, GEN denom}
given an \kbd{FpM} modulo $m$ with reduced or \kbd{Fp\_center}-ed entries,
reconstructs a matrix with rational coefficients by applying \kbd{Fp\_ratlift}
to all entries. Assume that all preconditions for \kbd{Fp\_ratlift} are
satisfied, as well $\gcd(m,b) = 1$ (so that the solution is unique if it
exists). Return \kbd{NULL} if the reconstruction fails, and the rational
matrix otherwise. If \kbd{denom} is not \kbd{NULL} check further that all
denominators divide \kbd{denom}.

The functions is not stack clean if one coefficients of $M$ is negative
(centered residues), but still suitable for \kbd{gerepileupto}.

\fun{GEN}{FpX_ratlift}{GEN P, GEN m, GEN amax, GEN bmax, GEN denom} as
\kbd{FpM\_ratlift}, where $P$ is an \kbd{FpX}.

\fun{GEN}{FpC_ratlift}{GEN P, GEN m, GEN amax, GEN bmax, GEN denom} as
\kbd{FpM\_ratlift}, where $P$ is an \kbd{FpC}.

\subsec{Zp}

\fun{GEN}{Zp_sqrt}{GEN b, GEN p, long e} $b$ and $p$ being \typ{INT}s, with $p$
a prime (possibly $2$), returns a \typ{INT} $a$ such that $a^2 \equiv b \mod
p^e$.

\fun{GEN}{Z2_sqrt}{GEN b, long e} $b$ being a \typ{INT}s
returns a \typ{INT} $a$ such that $a^2 \equiv b \mod 2^e$.

\fun{GEN}{Zp_sqrtlift}{GEN b, GEN a, GEN p, long e} let
$a,b,p$ be \typ{INT}s, with $p > 1$ odd, such that $a^2\equiv b\mod p$.
Returns a \typ{INT} $A$ such that $A^2 \equiv b \mod p^e$. Special case
of \tet{Zp_sqrtnlift}.

\fun{GEN}{Zp_sqrtnlift}{GEN b, GEN n, GEN a, GEN p, long e} let
$a,b,n,p$ be \typ{INT}s, with $n,p > 1$, and $p$ coprime to $n$,
such that $a^n \equiv b \mod p$. Returns a \typ{INT} $A$ such that
$A^n \equiv b \mod p^e$. Special case of \tet{ZpX_liftroot}.

\fun{GEN}{Zp_teichmuller}{GEN x, GEN p, long e, GEN pe} for $p$ an odd prime,
$x$ a \typ{INT} coprime to $p$, and $pe = p^e$, returns the $(p-1)$-th root of
$1$ congruent to $x$ modulo $p$, modulo $p^e$. For convenience, $p = 2$ is
also allowed and we return $1$ ($x$ is $1$ mod $4$) or $2^e - 1$ ($x$ is $3$
mod $4$).

\fun{GEN}{teichmullerinit}{long p, long n} returns the values of
\tet{Zp_teichmuller} at all $x = 1, \dots, p-1$.

\subsec{ZpX}

\fun{GEN}{ZpX_roots}{GEN f, GEN p, long e} $f$ a \kbd{ZX} with leading
term prime to $p$, and without multiple roots mod $p$. Return a vector
of \typ{INT}s which are the roots of $f$ mod $p^e$.

\fun{GEN}{ZpX_liftroot}{GEN f, GEN a, GEN p, long e} $f$ a \kbd{ZX} with
leading term prime to $p$, and $a$ a root mod $p$ such that
$v_p(f'(a))=0$.  Return a \typ{INT} which is the root of $f$ mod $p^e$
congruent to $a$ mod $p$.

\fun{GEN}{ZX_Zp_root}{GEN f, GEN a, GEN p, long e} same as \tet{ZpX_liftroot}
without the assumption $v_p(f'(a)) = 0$. Return a \typ{VEC} of \typ{INT}s,
which are the $p$-adic roots of $f$ congruent to $a$ mod $p$ (given modulo
$p^e$).

\fun{GEN}{ZpX_liftroots}{GEN f, GEN S, GEN p, long e} $f$ a \kbd{ZX} with
leading term prime to $p$, and $S$ a vector of simple roots mod $p$. Return a
vector of \typ{INT}s which are the root of $f$ mod $p^e$ congruent to the
$S[i]$ mod $p$.

\fun{GEN}{ZpX_liftfact}{GEN A, GEN B, GEN pe, GEN p, long e} is
the routine underlying \tet{polhensellift}. Here, $p$ is prime
defines a finite field $\F_p$. $A$ is a polynomial in
$\Z[X]$, whose leading coefficient is non-zero in $\F_q$. $B$ is a vector of
monic \kbd{FpX}, pairwise coprime in $\F_p[X]$, whose product is congruent to
$A/\text{lc}(A)$ in $\F_p[X]$. Lifts the elements of $B$ mod $\kbd{pe} = p^e$.

\fun{GEN}{ZpX_Frobenius}{GEN T, GEN p, ulong e} returns the $p$-adic lift
of the Frobenius automorphism of $\F_p[X]/(T)$ to precision $e$.

\fun{long}{ZpX_disc_val}{GEN f, GEN p} returns the valuation at $p$ of the
discriminant of $f$. Assume that $f$ is a monic \emph{separable} \kbd{ZX}
and that $p$ is a prime number. Proceeds by dynamically increasing the
$p$-adic accuracy; infinite loop if the discriminant of $f$ is
$0$.

\fun{long}{ZpX_resultant_val}{GEN f, GEN g, GEN p, long M} returns the
valuation at $p$ of $\text{Res}(f,g)$. Assume $f,g$ are both \kbd{ZX},
and that $p$ is a prime number coprime to the leading coefficient of $f$.
Proceeds by dynamically increasing the $p$-adic accuracy.
To avoid an infinite loop when the resultant is $0$, we return $M$ if
the Sylvester matrix mod $p^M$ still does not have maximal rank.

\fun{GEN}{ZpX_gcd}{GEN f,GEN g, GEN p, GEN pm} $f$ a monic \kbd{ZX},
$g$ a \kbd{ZX}, $\kbd{pm} = p^m$ a prime power. There is a unique integer
$r\geq 0$ and a monic $h\in \Q_p[X]$ such that
$$p^rh\Z_p[X] + p^m\Z_p[X] = f\Z_p[X] + g\Z_p[X] + p^m\Z_p[X].$$
Return the $0$ polynomial if $r\geq m$ and a monic $h\in\Z[1/p][X]$ otherwise
(whose valuation at $p$ is $> -m$).

\fun{GEN}{ZpX_reduced_resultant}{GEN f, GEN g, GEN p, GEN pm} $f$ a monic
\kbd{ZX}, $g$ a \kbd{ZX}, $\kbd{pm} = p^m$ a prime power. The $p$-adic
\emph{reduced resultant}\varsidx{resultant (reduced)} of $f$ and $g$ is
$0$ if $f$, $g$ not coprime in $\Z_p[X]$, and otherwise the generator of the
form $p^d$ of
$$ (f\Z_p[X] + g\Z_p[X])\cap \Z_p. $$
Return the reduced resultant modulo $p^m$.

\fun{GEN}{ZpX_reduced_resultant_fast}{GEN f, GEN g, GEN p, long M} $f$
a monic \kbd{ZX}, $g$ a \kbd{ZX}, $p$ a prime. Returns
the $p$-adic reduced resultant of $f$ and $g$ modulo $p^M$. This function
computes resultants for a sequence of increasing $p$-adic accuracies
(up to $M$ $p$-adic digits), returning as soon as it obtains a non-zero
result. It is very inefficient when the resultant is $0$, but otherwise
usually more efficient than computations using a priori bounds.

\fun{GEN}{ZpX_monic_factor}{GEN f, GEN p, long M} $f$ a monic
\kbd{ZX}, $p$ a primer, return the $p$-adic factorization of $f$, modulo
$p^M$. This is the underlying low-level recursive function behind
\kbd{factorpadic} (using a combination of Round 4 factorization and Hensel
lifting); the factors are not sorted and the function is not
\kbd{gerepile}-clean.

\subsec{ZpXQ}

\fun{GEN}{ZpXQ_invlift}{GEN b, GEN a, GEN T, GEN p, long e} let
$p$ be a prime \typ{INT} and $a,b$ be \kbd{FpXQ}s (modulo $T$) such that $a\*b
\equiv 1 \mod (p,T)$.  Returns an \kbd{FpXQ} $A$ such that
$A\*b \equiv 1 \mod (p^e, T)$.  Special case of \tet{ZpXQ_liftroot}.

\fun{GEN}{ZpXQ_inv}{GEN b, GEN T, GEN p, long e} let
$p$ be a prime \typ{INT} and $b$ be a \kbd{FpXQ} (modulo $T, p^e$).
Returns an \kbd{FpXQ} $A$ such that $A\*b \equiv 1 \mod (p^e, T)$.

\fun{GEN}{ZpXQ_div}{GEN a, GEN b, GEN T, GEN q, GEN p, long e} let
$p$ be a prime \typ{INT} and $a$ and $b$ be a \kbd{FpXQ} (modulo $T, p^e$).
Returns an \kbd{FpXQ} $c$ such that $c\*b \equiv a \mod (p^e, T)$.
The parameter $q$ must be equal to $p^e$.

\fun{GEN}{ZpXQ_sqrtnlift}{GEN b, GEN n, GEN a, GEN T, GEN p, long e} let
$n,p$ be \typ{INT}s, with $n,p > 1$ and $p$ coprime to $n$, and $a,b$
be \kbd{FpXQ}s (modulo $T$) such that $a^n \equiv b \mod (p,T)$.
Returns an \kbd{Fq} $A$ such that $A^n \equiv b \mod (p^e, T)$.
Special case of \tet{ZpXQ_liftroot}.

\fun{GEN}{ZpXQ_sqrt}{GEN b, GEN T, GEN p, long e} let
$p$ being a odd prime and $b$ be a \kbd{FpXQ} (modulo $T, p^e$),
returns $a$ such that $a^2 \equiv b \mod (p^e, T)$.

\fun{GEN}{ZpX_ZpXQ_liftroot}{GEN f, GEN a, GEN T, GEN p, long e}
as \tet{ZpXQX_liftroot}, but $f$ is a polynomial in $\Z[X]$.

\fun{GEN}{ZpX_ZpXQ_liftroot_ea}{GEN f, GEN a, GEN T, GEN p, long e,
                     void *E, int early(void *E, GEN x, GEN q)}
as \tet{ZpX_ZpXQ_liftroot} with early abort: the function \kbd{early(E,x,q)}
will be called with $x$ is a root of $f$ modulo $q=p^n$ for some $n$. If
\kbd{early} returns a non-zero value, the function returns $x$ immediately.

\fun{GEN}{ZpXQ_log}{GEN a, GEN T, GEN p, long e} $T$ being a \kbd{ZpX}
irreducible modulo $p$, return the logarithm of $a$ in $\Z_p[X]/(T)$ to
precision $e$, assuming that $a\equiv 1 \pmod{p\Z_p[X]}$ if $p$ odd or
$a\equiv 1 \pmod{4\Z_2[X]}$ if $p=2$.

\subsec{Zq}

\fun{GEN}{Zq_sqrtnlift}{GEN b, GEN n, GEN a, GEN T, GEN p, long e}

\subsec{ZpXQM}

\fun{GEN}{ZpXQM_prodFrobenius}{GEN M, GEN T, GEN p, long e}
returns the product of matrices $M\*\sigma(M)\*\sigma^2(M)\ldots\sigma^{n-1}(M)$
to precision $e$ where $\sigma$ is the lift of the Frobenius automorphism
over $\Z_p[X]/(T)$ and $n$ is the degree of $T$.

\subsec{ZpXQX}

\fun{GEN}{ZpXQX_liftfact}{GEN A, GEN B, GEN T, GEN pe, GEN p, long e} is the
routine underlying \tet{polhensellift}. Here, $p$ is prime, $T(Y)$ defines a
finite field $\F_q$. $A$ is a polynomial in $\Z[X,Y]$, whose leading
coefficient is non-zero in $\F_q$. $B$ is a vector of monic or \kbd{FqX},
pairwise coprime in $\F_q[X]$, whose product is congruent to $A/\text{lc}(A)$
in $\F_q[X]$. Lifts the elements of $B$ mod $\kbd{pe} = p^e$, such that the
congruence now holds mod $(T,p^e)$.

\fun{GEN}{ZpXQX_liftroot}{GEN f, GEN a, GEN T, GEN p, long e} as
\tet{ZpX_liftroot}, but $f$ is now a polynomial in $\Z[X,Y]$ and lift the
root $a$ in the unramified extension of $\Q_p$ with residue field $\F_p[Y]/(T)$,
assuming $v_p(f(a))>0$ and $v_p(f'(a))=0$.

\fun{GEN}{ZpXQX_liftroot_vald}{GEN f, GEN a, long v, GEN T, GEN p, long e}
returns the foots of $f$ as \tet{ZpXQX_liftroot}, where $v$ is the valuation
of the content of $f'$ and it is required that $v_p(f(a))>v$ and
$v_p(f'(a))=v$.

\fun{GEN}{ZpXQX_roots}{GEN F, GEN T, GEN p, long e}

\fun{GEN}{ZpXQX_divrem}{GEN x, GEN Sp, GEN T,GEN q,GEN p,long e, GEN *pr}
as \kbd{FpXQX\_divrem}. The parameter $q$ must be equal to $p^e$.

\fun{GEN}{ZpXQX_digits}{GEN x, GEN B, GEN T, GEN q, GEN p, long e}
As \kbd{FpXQX\_digits}. The parameter $q$ must be equal to $p^e$.

\subsec{ZqX}

\fun{GEN}{ZqX_roots}{GEN F, GEN T, GEN p, long e}

\fun{GEN}{ZqX_liftfact}{GEN A, GEN B, GEN T, GEN pe, GEN p, long e}

\fun{GEN}{ZqX_liftroot}{GEN f, GEN a, GEN T, GEN p, long e}

\subsec{Other $p$-adic functions}

\fun{GEN}{ZpM_echelon}{GEN M, long early_abort, GEN p, GEN pm} given a
\kbd{ZM} $M$, a prime $p$ and $\kbd{pm} = p^m$, returns an echelon form
$E$ for $M$ mod $p^m$. I.e. there exist a square integral matrix $U$ with
$\det U$ coprime to $p$ such that $E = MU$ modulo $p^m$. I
\kbd{early\_abort} is non-zero, return NULL as soon as one pivot in
the echelon form is divisible by $p^m$. The echelon form is an upper
triangular HNF, we do not waste time to reduce it to Gauss-Jordan form.

\fun{GEN}{zlm_echelon}{GEN M, long early_abort, ulong p, ulong pm}
variant of \kbd{ZpM\_echelon}, for a \kbd{Zlm} $M$.

\fun{GEN}{ZlM_gauss}{GEN a, GEN b, ulong p, long e, GEN C} as \kbd{gauss}
with the following peculiarities: $a$ and $b$ are \kbd{ZM}, such that $a$ is
invertible modulo $p$. Optional $C$ is an \kbd{Flm} that is an inverse of
$a\mod p$ or \kbd{NULL}. Return the matrix $x$ such that $ax=b\mod p^e$ and
all elements of $x$ are in $[0,p^e-1]$. For efficiency, it is better
to reduce $a$ and $b$ mod $p^e$ first.

\fun{GEN}{padic_to_Q}{GEN x} truncate the \typ{PADIC} to a \typ{INT} or
\typ{FRAC}.

\fun{GEN}{padic_to_Q_shallow}{GEN x} shallow version of \tet{padic_to_Q}

\fun{GEN}{QpV_to_QV}{GEN v} apply \tet{padic_to_Q_shallow}

\fun{long}{padicprec}{GEN x, GEN p} returns the absolute $p$-adic precision of
the object $x$, by definition the minimum precision of the components of $x$.
For a non-zero \typ{PADIC}, this returns \kbd{valp(x) + precp(x)}.

\fun{long}{padicprec_relative}{GEN x} returns the relative $p$-adic
precision of the \typ{INT}, \typ{FRAC}, or \typ{PADIC} $x$ (minimum precision
of the components of $x$ for \typ{POL} or vector/matrices).
For a \typ{PADIC}, this returns \kbd{precp(x)} if $x\neq0$, and $0$ for $x=0$.

\subsubsec{low-level}

The following technical function returns an optimal sequence of $p$-adic
accuracies, for a given target accuracy:

\fun{ulong}{quadratic_prec_mask}{long n} we want to reach accuracy
$n\geq 1$, starting from accuracy 1, using a quadratically convergent,
self-correcting, algorithm; in other words, from inputs correct to accuracy
$l$ one iteration outputs a result correct to accuracy $2l$.
For instance, to reach $n = 9$, we want to use accuracies
$[1,2,3,5,9]$ instead of $[1,2,4,8,9]$. The idea is to essentially double
the accuracy at each step, and not overshoot in the end.

Let $a_0$ = 1, $a_1 = 2, \ldots, a_k = n$, be the desired sequence of
accuracies. To obtain it, we work backwards and set
$$ a_k = n,\quad a_{i-1} = (a_i + 1)\,\bs\, 2.$$
This is in essence what the function returns.
But we do not want to store the $a_i$ explicitly, even as a \typ{VECSMALL},
since this would leave an object on the stack. Instead, we store $a_i$
implicitly in a bitmask \kbd{MASK}: let $a_0 = 1$, if the $i$-th bit of the
mask is set, set $a_{i+1} = 2a_i - 1$, and $2a_i$ otherwise; in short the
bits indicate the places where we do something special and do not quite
double the accuracy (which would be the straightforward thing to do).

In fact, to avoid returning separately the mask and the sequence length
$k+1$, the function returns $\kbd{MASK} + 2^{k+1}$, so the highest bit of
the mask indicates the length of the sequence, and the following ones give
an algorithm to obtain the accuracies. This is much simpler than it sounds,
here is what it looks like in practice:
\bprog
  ulong mask = quadratic_prec_mask(n);
  long l = 1;
  while (mask > 1) {            /* here, the result is known to accuracy l */
    l = 2*l; if (mask & 1) l--; /* new accuracy l for the iteration */
    mask >>= 1;                 /* pop low order bit */
    /* ... lift to the new accuracy ... */
  }
  /* we are done. At this point l = n */
@eprog\noindent We just pop the bits in \kbd{mask} starting from the low
order bits, stop when \kbd{mask} is $1$ (that last bit corresponds to the
$2^{k+1}$ that we added to the mask proper). Note that there is nothing
specific to Hensel lifts in that function: it would work equally well for
an Archimedean Newton iteration.

Note that in practice, we rather use an infinite loop, and insert an
\bprog
  if (mask == 1) break;
@eprog\noindent in the middle of the loop: the loop body usually includes
preparations for the next iterations (e.g. lifting Bezout coefficients
in a quadratic Hensel lift), which are costly and useless in the \emph{last}
iteration.

\subsec{Conversions involving single precision objects}

\subsubsec{To single precision}

\fun{ulong}{Rg_to_Fl}{GEN z, ulong p}, \kbd{z} which can be mapped to
$\Z/p\Z$: a \typ{INT}, a \typ{INTMOD} whose modulus is divisible by $p$,
a \typ{FRAC} whose denominator is coprime to $p$, or a \typ{PADIC} with
underlying prime $\ell$ satisfying $p = \ell^n$ for some $n$ (less than the
accuracy of the input). Returns \kbd{lift(z * Mod(1,p))}, normalized, as an
\kbd{Fl}.

\fun{ulong}{Rg_to_F2}{GEN z}, as \tet{Rg_to_Fl} for $p = 2$.

\fun{ulong}{padic_to_Fl}{GEN x, ulong p} special case of \tet{Rg_to_Fl},
for a $x$ a \typ{PADIC}.

\fun{GEN}{RgX_to_F2x}{GEN x}, \kbd{x} a \typ{POL}, returns the
\kbd{F2x} obtained by applying \kbd{Rg\_to\_Fl} coefficientwise.

\fun{GEN}{RgX_to_Flx}{GEN x, ulong p}, \kbd{x} a \typ{POL}, returns the
\kbd{Flx} obtained by applying \kbd{Rg\_to\_Fl} coefficientwise.

\fun{GEN}{Rg_to_F2xq}{GEN z, GEN T}, \kbd{z} a \kbd{GEN} which can be
mapped to $\F_2[X]/(T)$: anything \kbd{Rg\_to\_Fl} can be applied to,
a \typ{POL} to which \kbd{RgX\_to\_F2x} can be applied to, a \typ{POLMOD}
whose modulus is divisible by $T$ (once mapped to a \kbd{F2x}), a suitable
\typ{RFRAC}. Returns \kbd{z} as an \kbd{F2xq}, normalized.

\fun{GEN}{Rg_to_Flxq}{GEN z, GEN T, ulong p}, \kbd{z} a \kbd{GEN} which can be
mapped to $\F_p[X]/(T)$: anything \kbd{Rg\_to\_Fl} can be applied to,
a \typ{POL} to which \kbd{RgX\_to\_Flx} can be applied to, a \typ{POLMOD}
whose modulus is divisible by $T$ (once mapped to a \kbd{Flx}), a suitable
\typ{RFRAC}. Returns \kbd{z} as an \kbd{Flxq}, normalized.

\fun{GEN}{ZX_to_Flx}{GEN x, ulong p} reduce \kbd{ZX}~\kbd{x} modulo \kbd{p}
(yielding an \kbd{Flx}). Faster than \kbd{RgX\_to\_Flx}.

\fun{GEN}{ZV_to_Flv}{GEN x, ulong p} reduce \kbd{ZV}~\kbd{x} modulo \kbd{p}
(yielding an \kbd{Flv}).

\fun{GEN}{ZXV_to_FlxV}{GEN v, ulong p}, as \kbd{ZX\_to\_Flx}, repeatedly
called on the vector's coefficients.

\fun{GEN}{ZXT_to_FlxT}{GEN v, ulong p}, as \kbd{ZX\_to\_Flx}, repeatedly
called on the tree leaves.

\fun{GEN}{ZXX_to_FlxX}{GEN B, ulong p, long v}, as \kbd{ZX\_to\_Flx},
repeatedly called on the polynomial's coefficients.

\fun{GEN}{zxX_to_FlxX}{GEN z, ulong p} as \kbd{zx\_to\_Flx},
repeatedly called on the polynomial's coefficients.

\fun{GEN}{ZXXV_to_FlxXV}{GEN V, ulong p, long v}, as \kbd{ZXX\_to\_FlxX},
repeatedly called on the vector's coefficients.

\fun{GEN}{ZXXT_to_FlxXT}{GEN V, ulong p, long v}, as \kbd{ZXX\_to\_FlxX},
repeatedly called on the tree leaves.

\fun{GEN}{RgV_to_Flv}{GEN x, ulong p} reduce the \typ{VEC}/\typ{COL}
$x$ modulo $p$, yielding a \typ{VECSMALL}.

\fun{GEN}{RgM_to_Flm}{GEN x, ulong p} reduce the \typ{MAT} $x$ modulo $p$.

\fun{GEN}{ZM_to_Flm}{GEN x, ulong p} reduce \kbd{ZM}~$x$ modulo $p$
(yielding an \kbd{Flm}).

\fun{GEN}{ZV_to_zv}{GEN z}, converts coefficients using \kbd{itos}

\fun{GEN}{ZV_to_nv}{GEN z}, converts coefficients using \kbd{itou}

\fun{GEN}{ZM_to_zm}{GEN z}, converts coefficients using \kbd{itos}

\fun{GEN}{FqC_to_FlxC}{GEN x, GEN T, GEN p}, converts coefficients in \kbd{Fq}
to coefficient in Flx, result being a column vector.

\fun{GEN}{FqV_to_FlxV}{GEN x, GEN T, GEN p}, converts coefficients in \kbd{Fq}
to coefficient in Flx, result being a line vector.


\fun{GEN}{FqM_to_FlxM}{GEN x, GEN T, GEN p}, converts coefficients in \kbd{Fq}
to coefficient in Flx.

\subsubsec{From single precision}

\fun{GEN}{Flx_to_ZX}{GEN z}, converts to \kbd{ZX} (\typ{POL} of non-negative
\typ{INT}s in this case)

\fun{GEN}{Flx_to_FlxX}{GEN z}, converts to \kbd{FlxX} (\typ{POL} of constant
\kbd{Flx} in this case).

\fun{GEN}{Flx_to_ZX_inplace}{GEN z}, same as \kbd{Flx\_to\_ZX}, in place
(\kbd{z} is destroyed).

\fun{GEN}{FlxX_to_ZXX}{GEN B}, converts an \kbd{FlxX} to a polynomial with
\kbd{ZX} or \typ{INT} coefficients (repeated calls to \kbd{Flx\_to\_ZX}).

\fun{GEN}{FlxXC_to_ZXXC}{GEN B}, converts an \kbd{FlxXC} to a \typ{COL} with
\kbd{ZXX} coefficients (repeated calls to \kbd{FlxX\_to\_ZXX}).

\fun{GEN}{FlxXM_to_ZXXM}{GEN B}, converts an \kbd{FlxXM} to a \typ{MAT} with
\kbd{ZXX} coefficients (repeated calls to \kbd{FlxX\_to\_ZXX}).

\fun{GEN}{FlxC_to_ZXC}{GEN x}, converts a vector of \kbd{Flx} to a column
vector of polynomials with \typ{INT} coefficients (repeated calls to

\kbd{Flx\_to\_ZX}).

\fun{GEN}{FlxV_to_ZXV}{GEN x}, as above but return a \typ{VEC}.

\fun{void}{F2xV_to_FlxV_inplace}{GEN v} v is destroyed.

\fun{void}{F2xV_to_ZXV_inplace}{GEN v} v is destroyed.

\fun{void}{FlxV_to_ZXV_inplace}{GEN v} v is destroyed.

\fun{GEN}{FlxM_to_ZXM}{GEN z}, converts a matrix of \kbd{Flx} to a matrix of
polynomials with \typ{INT} coefficients (repeated calls to \kbd{Flx\_to\_ZX}).

\fun{GEN}{zx_to_ZX}{GEN z}, as \kbd{Flx\_to\_ZX}, without assuming
the coefficients to be non-negative.

\fun{GEN}{zx_to_Flx}{GEN z, ulong p} as \kbd{Flx\_red} without assuming
the coefficients to be non-negative.

\fun{GEN}{Flc_to_ZC}{GEN z}, converts to \kbd{ZC} (\typ{COL} of non-negative
\typ{INT}s in this case)

\fun{GEN}{Flv_to_ZV}{GEN z}, converts to \kbd{ZV} (\typ{VEC} of non-negative
\typ{INT}s in this case)

\fun{GEN}{Flm_to_ZM}{GEN z}, converts to \kbd{ZM} (\typ{MAT} with
non-negative \typ{INT}s coefficients in this case)

\fun{GEN}{zc_to_ZC}{GEN z} as \kbd{Flc\_to\_ZC}, without assuming
coefficients are non-negative.

\fun{GEN}{zv_to_ZV}{GEN z} as \kbd{Flv\_to\_ZV}, without assuming
coefficients are non-negative.

\fun{GEN}{zm_to_ZM}{GEN z} as \kbd{Flm\_to\_ZM}, without assuming
coefficients are non-negative.

\fun{GEN}{zv_to_Flv}{GEN z, ulong p}

\fun{GEN}{zm_to_Flm}{GEN z, ulong p}

\subsubsec{Mixed precision linear algebra} Assumes dimensions are compatible.
Multiply a multiprecision object by a single-precision one.

\fun{GEN}{RgM_zc_mul}{GEN x, GEN y}

\fun{GEN}{RgMrow_zc_mul}{GEN x, GEN y, long i}

\fun{GEN}{RgM_zm_mul}{GEN x, GEN y}

\fun{GEN}{RgV_zc_mul}{GEN x, GEN y}

\fun{GEN}{RgV_zm_mul}{GEN x, GEN y}

\fun{GEN}{ZM_zc_mul}{GEN x, GEN y}

\fun{GEN}{zv_ZM_mul}{GEN x, GEN y}

\fun{GEN}{ZV_zc_mul}{GEN x, GEN y}

\fun{GEN}{ZM_zm_mul}{GEN x, GEN y}

\fun{GEN}{ZC_z_mul}{GEN x, long y}

\fun{GEN}{ZM_nm_mul}{GEN x, GEN y} the entries of $y$ are \kbd{ulong}s.

\fun{GEN}{nm_Z_mul}{GEN y, GEN c} the entries of $y$ are \kbd{ulong}s.

\subsubsec{Miscellaneous involving Fl}

\fun{GEN}{Fl_to_Flx}{ulong x, long evx} converts a \kbd{unsigned long} to a
scalar \kbd{Flx}. Assume that \kbd{evx = evalvarn(vx)} for some variable
number \kbd{vx}.

\fun{GEN}{Z_to_Flx}{GEN x, ulong p, long sv} converts a \typ{INT} to a scalar
\kbd{Flx} polynomial. Assume that \kbd{sv = evalvarn(v)} for some variable
number \kbd{v}.

\fun{GEN}{Flx_to_Flv}{GEN x, long n} converts from \kbd{Flx} to \kbd{Flv}
with \kbd{n} components (assumed larger than the number of coefficients of
\kbd{x}).

\fun{GEN}{zx_to_zv}{GEN x, long n} as \kbd{Flx\_to\_Flv}.

\fun{GEN}{Flv_to_Flx}{GEN x, long sv} converts from vector (coefficient
array) to (normalized) polynomial in variable $v$.

\fun{GEN}{zv_to_zx}{GEN x, long n} as \kbd{Flv\_to\_Flx}.

\fun{GEN}{Flm_to_FlxV}{GEN x, long sv} converts the columns of
\kbd{Flm}~\kbd{x} to an array of \kbd{Flx} in the variable $v$
(repeated calls to \kbd{Flv\_to\_Flx}).

\fun{GEN}{zm_to_zxV}{GEN x, long n} as \kbd{Flm\_to\_FlxV}.

\fun{GEN}{Flm_to_FlxX}{GEN x, long sw, long sv} same as
\kbd{Flm\_to\_FlxV(x,sv)} but returns the result as a (normalized) polynomial
in variable $w$.

\fun{GEN}{FlxV_to_Flm}{GEN v, long n} reverse \kbd{Flm\_to\_FlxV}, to obtain
an \kbd{Flm} with \kbd{n} rows (repeated calls to \kbd{Flx\_to\_Flv}).

\fun{GEN}{FlxX_to_Flm}{GEN v, long n} reverse \kbd{Flm\_to\_FlxX}, to obtain
an \kbd{Flm} with \kbd{n} rows (repeated calls to \kbd{Flx\_to\_Flv}).

\fun{GEN}{FlxX_to_FlxC}{GEN B, long n, long sv} see \kbd{RgX\_to\_RgV}.
The coefficients of \kbd{B} are assumed to be in the variable $v$.

\fun{GEN}{FlxXV_to_FlxM}{GEN V, long n, long sv} see \kbd{RgXV\_to\_RgM}.
The coefficients of \kbd{V[i]} are assumed to be in the variable $v$.

\fun{GEN}{Fly_to_FlxY}{GEN a, long sv} convert coefficients of \kbd{a} to
constant \kbd{Flx} in variable $v$.

\subsubsec{Miscellaneous involving \kbd{F2x}}

\fun{GEN}{F2x_to_F2v}{GEN x, long n} converts from \kbd{F2x} to \kbd{F2v}
with \kbd{n} components (assumed larger than the number of coefficients of
\kbd{x}).

\fun{GEN}{F2xC_to_ZXC}{GEN x}, converts a vector of \kbd{F2x} to a column
vector of polynomials with \typ{INT} coefficients (repeated calls to
\kbd{F2x\_to\_ZX}).

\fun{GEN}{F2xC_to_FlxC}{GEN x}

\fun{GEN}{FlxC_to_F2xC}{GEN x}

\fun{GEN}{F2xV_to_F2m}{GEN v, long n} \kbd{F2x\_to\_F2v} to each polynomial
to get an \kbd{F2m} with \kbd{n} rows.

\section{Higher arithmetic over $\Z$: primes, factorization}

\subsec{Pure powers}

\fun{long}{Z_issquare}{GEN n} returns $1$ if the \typ{INT} $n$ is
a square, and $0$ otherwise. This is tested first modulo small prime
powers, then \kbd{sqrtremi} is called.

\fun{long}{Z_issquareall}{GEN n, GEN *sqrtn} as \kbd{Z\_issquare}. If
$n$ is indeed a square, set \kbd{sqrtn} to its integer square root.
Uses a fast congruence test mod $64\times 63\times 65\times 11$ before
computing an integer square root.

\fun{long}{Z_ispow2}{GEN x} returns $1$ if the \typ{INT} $x$ is a power of
$2$, and $0$ otherwise.

\fun{long}{uissquare}{ulong n} as \kbd{Z\_issquare},
for an \kbd{ulong} operand \kbd{n}.

\fun{long}{uissquareall}{ulong n, ulong *sqrtn} as \kbd{Z\_issquareall},
for an \kbd{ulong} operand \kbd{n}.

\fun{ulong}{usqrt}{ulong a} returns the floor of the square root of $a$.

\fun{ulong}{usqrtn}{ulong a, ulong n} returns the floor of the $n$-th root
of $a$.

\fun{long}{Z_ispower}{GEN x, ulong k} returns $1$ if the \typ{INT} $n$ is a
$k$-th power, and $0$ otherwise; assume that $k > 1$.

\fun{long}{Z_ispowerall}{GEN x, ulong k, GEN *pt} as \kbd{Z\_ispower}. If
$n$ is indeed a $k$-th power, set \kbd{*pt} to its integer $k$-th root.

\fun{long}{Z_isanypower}{GEN x, GEN *ptn} returns the maximal $k\geq 2$  such
that the \typ{INT} $x = n^k$ is a perfect power, or $0$ if no such $k$ exist;
in particular \kbd{ispower(1)}, \kbd{ispower(0)}, \kbd{ispower(-1)} all
return 0. If the return value $k$ is not $0$ (so that $x = n^k$) and
\kbd{ptn} is not \kbd{NULL}, set \kbd{*ptn} to $n$.

The following low-level functions are called by \tet{Z_isanypower} but can
be directly useful:

\fun{int}{is_357_power}{GEN x, GEN *ptn, ulong *pmask} tests whether the
integer $x > 0$ is a $3$-rd, $5$-th or $7$-th power. The bits of \kbd{*mask}
initially indicate which test is to be performed;
bit $0$: $3$-rd,
bit $1$: $5$-th,
bit $2$: $7$-th (e.g.~$\kbd{*pmask} = 7$ performs all tests). They are
updated during the call: if the ``$i$-th power'' bit is set to $0$
then $x$ is not a $k$-th power. The function returns $0$
(not a
$3$-rd,
$5$-th or
$7$-th power),
$3$
($3$-rd power,
not a $5$-th or
$7$-th power),
$5$
($5$-th power,
not a $7$-th power),
or $7$
($7$-th power); if an $i$-th power bit is initially set to $0$, we take it
at face value and assume $x$ is not an $i$-th power without performing any
test. If the return value $k$ is non-zero, set \kbd{*ptn} to $n$ such that $x
= n^k$.

\fun{int}{is_pth_power}{GEN x, GEN *ptn, forprime_t *T, ulong cutoff}
let $x > 0$ be an integer, $\kbd{cutoff} > 0$ and $T$ be an iterator over
primes $\geq 11$, we look for the smallest prime $p$ such that $x = n^p$
(advancing $T$ as we go along). The $11$ is due to the fact that
\tet{is_357_power} and \kbd{issquare} are faster than the generic version for
$p < 11$.

Fail and return $0$ when the existence of $p$ would imply $2^{\kbd{cutoff}} >
x^{1/p}$, meaning that a possible $n$ is so small that it should have been
found by trial division; for maximal speed, you should start by a round of
trial division, but the cut-off may also be set to $1$ for a rigorous result
without any trial division.

Otherwise returns the smallest suitable prime power $p^i$ and set \kbd{*ptn}
to the $p^i$-th root of $x$ (which is now not a $p$-th power). We may
immediately recall the function with the same parameters after setting $x =
\kbd{*ptn}$: it will start at the next prime.

\subsec{Factorization}

\fun{GEN}{Z_factor}{GEN n} factors the \typ{INT} \kbd{n}. The ``primes''
in the factorization are actually strong pseudoprimes.

\fun{GEN}{absZ_factor}{GEN n} returns \kbd{Z\_factor(absi(n))}.

\fun{long}{Z_issmooth}{GEN n, ulong lim} returns $1$ if all the
prime factors of the \typ{INT} $n$ are less or equal to $lim$.

\fun{GEN}{Z_issmooth_fact}{GEN n, ulong lim} returns \kbd{NULL} if a prime
factor of the \typ{INT} $n$ is $> lim$, and returns the factorization
of $n$ otherwise, as a \typ{MAT} with \typ{VECSMALL} columns (word-size
primes and exponents). Neither memory-clean nor suitable for
\kbd{gerepileupto}.

\fun{GEN}{Z_factor_until}{GEN n, GEN lim} as \kbd{Z\_factor}, but stop the
factorization process as soon as the unfactored part is smaller than \kbd{lim}.
The resulting factorization matrix only contains the factors found. No other
assumptions can be made on the remaining factors.

\fun{GEN}{Z_factor_limit}{GEN n, ulong lim} trial divide $n$ by all primes $p
< \kbd{lim}$ in the precomputed list of prime numbers and return the
corresponding factorization matrix. In this case, the last ``prime'' divisor
in the first column of the factorization matrix may well be a proven
composite.

If $\kbd{lim} = 0$, the effect is the same as setting $\kbd{lim} =
\kbd{maxprime()} + 1$: use all precomputed primes.

\fun{GEN}{absZ_factor_limit}{GEN n, ulong all}returns
\kbd{Z\_factor\_limit(absi(n))}.

\fun{GEN}{boundfact}{GEN x, ulong lim} as \tet{Z_factor_limit}, applying to
\typ{INT} or \typ{FRAC} inputs.

\fun{GEN}{Z_smoothen}{GEN n, GEN L, GEN *pP, GEN *pE} given a \typ{VECSMALL}
$L$ containing a list of small primes and a \typ{INT} $n$, trial divide
$n$ by the elements of $L$ and return the cofactor. Return \kbd{NULL} if the
cofactor is $\pm 1$. \kbd{*P} and \kbd{*E} contain the list of prime divisors
found and their exponents, as \typ{VECSMALL}s. Neither memory-clean, nor
suitable for \tet{gerepileupto}.

\fun{GEN}{Z_factor_listP}{GEN N, GEN L} given a \typ{INT} $N$, a vector or
primes $L$ containing all prime divisors of $N$ (and possibly others). Return
\kbd{factor(N)}. Neither memory-clean, nor suitable for \tet{gerepileupto}.

\fun{GEN}{factor_pn_1}{GEN p, ulong n} returns the factorization of $p^n-1$,
where $p$ is prime and $n$ is a positive integer.

\fun{GEN}{factor_pn_1_limit}{GEN p, ulong n, ulong B} returns a partial
factorization of $p^n-1$, where $p$ is prime and $n$ is a positive integer.
Don't actively search for prime divisors $p > B$, but we may find still find
some due to Aurifeuillian factorizations. Any entry $> B^2$ in the output
factorization matrix is \emph{a priori} not a prime (but may well be).

\fun{GEN}{factor_Aurifeuille_prime}{GEN p, long n} an Aurifeuillian factor
of $\phi_n(p)$, assuming $p$ prime and an Aurifeuillian factor exists
($p \zeta_n$ is a square in $\Q(\zeta_n)$).

\fun{GEN}{factor_Aurifeuille}{GEN a, long d} an Aurifeuillian factor of
$\phi_n(a)$, assuming $a$ is a non-zero integer and $n > 2$. Returns $1$
if no Aurifeuillian factor exists.

\fun{GEN}{odd_prime_divisors}{GEN a} \typ{VEC} of all prime divisors of the
\typ{INT} $a$.

\fun{GEN}{factoru}{ulong n}, returns the factorization of $n$. The result
is a $2$-component vector $[P,E]$, where $P$ and $E$ are \typ{VECSMALL}
containing the prime divisors of $n$, and the $v_p(n)$.

\fun{GEN}{factoru_pow}{ulong n}, returns the factorization of $n$. The result
is a $3$-component vector $[P,E,C]$, where $P$, $E$ and $C$ are
\typ{VECSMALL} containing the prime divisors of $n$, the $v_p(n)$
and the $p^{v_p(n)}$.

\fun{ulong}{tridiv_bound}{GEN n} returns the trial division bound used by
\tet{Z_factor}$(n)$.

\subsec{Coprime factorization}

Given $a$ and $b$ two non-zero integers, let \teb{ppi}$(a,b)$, \teb{ppo}$(a,b)$,
\teb{ppg}$(a,b)$, \teb{pple}$(a,b)$ (powers in $a$ of primes inside $b$,
outside $b$, greater than thos in $b$, less than or equal to those in $b$) be
the integers defined by

\item $v_p(\text{ppi}) = v_p(a) [v_p(b) > 0]$,

\item $v_p(\text{ppo}) = v_p(a) [v_p(b) = 0]$,

\item $v_p(\text{ppg}) = v_p(a) [v_p(a) > v_p(b)]$,

\item $v_p(\text{pple}) = v_p(a) [v_p(a) \leq v_p(b)]$.

\fun{GEN}{Z_ppo}{GEN a, GEN b} returns $\text{ppo}(a,b)$; shallow function.

\fun{ulong}{u_ppo}{ulong a, ulong b} returns $\text{ppo}(a,b)$.

\fun{GEN}{Z_ppgle}{GEN a, GEN b} returns $[\text{ppg}(a,b), \text{pple}(a,b)]$;
shallow function.

\fun{GEN}{Z_ppio}{GEN a, GEN b} returns
$[\gcd(a,b), \text{ppi}(a,b), \text{ppo}(a,b)]$; shallow function.

\fun{GEN}{Z_cba}{GEN a, GEN b} fast natural coprime base algorithm. Returns a
vector of coprime divisors of $a$ and $b$ such that both $a$ and $b$ can
be multiplicatively generated from this set.

\subsec{Checks attached to arithmetic functions}

Arithmetic functions accept arguments of the following kind: a plain positive
integer $N$ (\typ{INT}), the factorization \var{fa} of a positive integer (a
\typ{MAT} with two columns containing respectively primes and exponents), or
a vector $[N,\var{fa}]$. A few functions accept non-zero
integers (e.g.~\tet{omega}), and some others arbitrary integers
(e.g.~\tet{factorint}, \dots).

\fun{int}{is_Z_factorpos}{GEN f} returns $1$ if $f$ looks like the
factorization of a positive integer, and $0$ otherwise. Useful for sanity
checks but not 100\% foolproof. Specifically, this routine checks that $f$ is
a two-column matrix all of whose entries are positive integers. It does
\emph{not} check that entries in the first column (``primes'') are prime,
or even pairwise coprime, nor that they are stricly increasing.

\fun{int}{is_Z_factornon0}{GEN f} returns $1$ if $f$ looks like the
factorization of a non-zero integer, and $0$ otherwise. Useful for sanity
checks but not 100\% foolproof, analogous to \tet{is_Z_factorpos}. (Entries
in the first column need only be non-zero integers.)

\fun{int}{is_Z_factor}{GEN f} returns $1$ if $f$ looks like the
factorization of an integer, and $0$ otherwise. Useful for sanity
checks but not 100\% foolproof. Specifically, this routine checks that $f$ is
a two-column matrix all of whose entries are integers. Entries in the second
column (``exponents'') are all positive. Either it encodes the
``factorization'' $0^e$, $e > 0$, or entries in the first column (``primes'')
are all non-zero.

\fun{GEN}{clean_Z_factor}{GEN f} assuming $f$ is the factorization of an
integer $n$, return the factorization of $|n|$, i.e.~remove $-1$ from the
factorization. Shallow function.

\fun{GEN}{fuse_Z_factor}{GEN f, GEN B} assuming $f$ is the
factorization of an integer $n$, return \kbd{boundfact(n, B)}, i.e.
return a factorization where all primary factors for $|p| \leq B$
are preserved, and all others are ``fused'' into a single composite
integer; if that remainder is trivial, i.e.~equal to 1, it is of course
not included. Shallow function.

In the following three routines, $f$ is the name of an arithmetic function,
and $n$ a supplied argument. They all raise exceptions if $n$ does not
correspond to an integer or an integer factorization of the expected shape.

\fun{GEN}{check_arith_pos}{GEN n, const char *f} check whether $n$
is attached to the factorization of a positive integer, and return
\kbd{NULL} (plain \typ{INT}) or a factorization extracted from $n$ otherwise.
May raise an \tet{e_DOMAIN} ($n \leq 0$) or an \tet{e_TYPE} exception (other
failures).

\fun{GEN}{check_arith_non0}{GEN n, const char *f} check whether $n$
is attached to the factorization of a non-$0$ integer, and return
\kbd{NULL} (plain \typ{INT}) or a factorization extracted from $n$ otherwise.
May raise an \tet{e_TYPE} exception.

\fun{GEN}{check_arith_all}{GEN n, const char *f}
is attached to the factorization of an integer, and return \kbd{NULL}
(plain \typ{INT}) or a factorization extracted from $n$ otherwise.

\subsec{Incremental integer factorization}

Routines attached to the dynamic factorization of an integer $n$, iterating
over successive prime divisors. This is useful to implement high-level
routines allowed to take shortcuts given enough partial information: e.g.
\kbd{moebius}$(n)$ can be trivially computed if we hit $p$ such that $p^2
\mid n$. For efficiency, trial division by small primes should have already
taken place. In any case, the functions below assume that no prime $< 2^{14}$
divides $n$.

\fun{GEN}{ifac_start}{GEN n, int moebius} schedules a new factorization
attempt for the integer $n$. If \kbd{moebius} is non-zero, the factorization
will be aborted as soon as a repeated factor is detected (Moebius mode).
The function assumes that $n > 1$ is a \emph{composite} \typ{INT} whose prime
divisors satisfy $p > 2^{14}$ \emph{and} that one can write to $n$ in place.

This function stores data on the stack, no \kbd{gerepile} call should
delete this data until the factorization is complete. Returns \kbd{partial},
a data structure recording the partial factorization state.

\fun{int}{ifac_next}{GEN *partial, GEN *p, long *e} deletes a primary factor
$p^e$ from \kbd{partial} and sets \kbd{p} (prime) and \kbd{e} (exponent), and
normally returns $1$. Whatever remains in the \kbd{partial} structure is now
coprime to $p$.

Returns $0$ if all primary factors have been used already, so we are done
with the factorization. In this case $p$ is set to \kbd{NULL}. If we ran in
Moebius mode and the factorization was in fact aborted, we have $e = 1$,
otherwise $e = 0$.

\fun{int}{ifac_read}{GEN part, GEN *k, long *e} peeks at the next integer
to be factored in the list $k^e$, where $k$ is not necessarily prime
and can be a perfect power as well, but will be factored by the next call to
\tet{ifac_next}. You can remove this factorization from the schedule by
calling:

\fun{void}{ifac_skip}{GEN part} removes the next scheduled factorization.

\fun{int}{ifac_isprime}{GEN n} given $n$ whose prime divisors are $> 2^{14}$,
returns the decision the factoring engine would take about the compositeness
of $n$: $0$ if $n$ is a proven composite, and $1$ if we believe it to be
prime; more precisely, $n$ is a proven prime if \tet{factor_proven} is
set, and only a BPSW-pseudoprime otherwise.

\subsec{Integer core, squarefree factorization}

\fun{long}{Z_issquarefree}{GEN n} returns $1$ if the \typ{INT} \kbd{n}
is square-free, and $0$ otherwise.

\fun{long}{Z_isfundamental}{GEN x} returns $1$ if the \typ{INT} \kbd{x}
is a fundamental discriminant, and $0$ otherwise.

\fun{GEN}{core}{GEN n} unique squarefree integer $d$ dividing $n$ such that
$n/d$ is a square. The core of $0$ is defined to be $0$.

\fun{GEN}{core2}{GEN n} return $[d,f]$ with $d$ squarefree and $n = df^2$.

\fun{GEN}{corepartial}{GEN n, long lim} as \kbd{core}, using
\kbd{boundfact(n,lim)} to partially factor \kbd{n}. The result is not
necessarily squarefree, but $p^2 \mid n$ implies $p > \kbd{lim}$.

\fun{GEN}{core2partial}{GEN n, long lim} as \kbd{core2}, using
\kbd{boundfact(n,lim)} to partially factor \kbd{n}. The resulting $d$ is not
necessarily squarefree, but $p^2 \mid n$ implies $p > \kbd{lim}$.



\subsec{Primes, primality and compositeness tests}

\subsubsec{Chebyshev's $\pi$ function, bounds}

\fun{ulong}{uprimepi}{ulong n}, returns the number of primes $p\leq n$
(Chebyshev's $\pi$ function).

\fun{double}{primepi_upper_bound}{double x} return a quick upper bound for
$\pi(x)$, using Dusart bounds.

\fun{GEN}{gprimepi_upper_bound}{GEN x} as \tet{primepi_upper_bound}, returns a
\typ{REAL}.

\fun{double}{primepi_lower_bound}{double x} return a quick lower bound for
$\pi(x)$, using Dusart bounds.

\fun{GEN}{gprimepi_lower_bound}{GEN x} as \tet{primepi_lower_bound}, returns
a \typ{REAL} or \kbd{gen\_0}.

\subsubsec{Primes, primes in intervals}

\fun{ulong}{unextprime}{ulong n}, returns the smallest prime $\geq n$. Return
$0$ if it cannot be represented as an \kbd{ulong} ($n$ bigger than $2^{64} -
59$ or $2^{32} - 5$ depending on the word size).

\fun{ulong}{uprecprime}{ulong n}, returns the largest prime $\leq n$. Return
$0$ if $n\leq 1$.

\fun{ulong}{uprime}{long n} returns the $n$-th prime, assuming it fits in an
\kbd{ulong} (overflow error otherwise).

\fun{GEN}{prime}{long n} same as \kbd{utoi(uprime(n))}.

\fun{GEN}{primes_zv}{long m} returns the first $m$ primes, in a
\typ{VECSMALL}.

\fun{GEN}{primes}{long m} return the first $m$ primes, as a \typ{VEC} of
\typ{INT}s.

\fun{GEN}{primes_interval}{GEN a, GEN b} return the primes in the interval
$[a,b]$, as a \typ{VEC} of \typ{INT}s.

\fun{GEN}{primes_interval_zv}{ulong a, ulong b} return the primes in the
interval $[a,b]$, as a \typ{VECSMALL} of \kbd{ulongs}s.

\fun{GEN}{primes_upto_zv}{ulong b} return the primes in the interval $[2,b]$,
as a \typ{VECSMALL} of \kbd{ulongs}s.

\subsubsec{Tests}

\fun{int}{uisprime}{ulong p}, returns $1$ if \kbd{p} is a prime number and
$0$ otherwise.

\fun{int}{uisprime_101}{ulong p}, assuming that $p$ has no divisor $\leq
101$, returns $1$ if \kbd{p} is a prime number and $0$ otherwise.

\fun{int}{uisprime_661}{ulong p}, assuming that $p$ has no divisor $\leq
661$, returns $1$ if \kbd{p} is a prime number and $0$ otherwise.

\fun{int}{isprime}{GEN n}, returns $1$ if the \typ{INT} \kbd{n} is a
(fully proven) prime number and $0$ otherwise.

\fun{long}{isprimeAPRCL}{GEN n}, returns $1$ if the \typ{INT} \kbd{n} is a
prime number and $0$ otherwise, using only the APRCL test --- not even trial
division or compositeness tests. The workhorse \kbd{isprime} should be
faster on average, especially if non-primes are included!

\fun{long}{BPSW_psp}{GEN n}, returns $1$ if the \typ{INT} \kbd{n} is a
Baillie-Pomerance-Selfridge-Wagstaff pseudoprime, and $0$ otherwise (proven
composite).

\fun{int}{BPSW_isprime}{GEN x} assuming $x$ is a BPSW-pseudoprime, rigorously
prove its primality. The function \tet{isprime} is currently implemented
as
\bprog
 BPSW_psp(x) && BPSW_isprime(x)
@eprog

\fun{long}{millerrabin}{GEN n, long k} performs $k$ strong Rabin-Miller
compositeness tests on the \typ{INT} $n$, using $k$ random bases. This
function also caches square roots of $-1$ that are encountered during the
successive tests and stops as soon as three distinct square roots have been
produced; we have in principle factored $n$ at this point, but
unfortunately, there is currently no way for the factoring machinery to
become aware of it. (It is highly implausible that hard to find factors
would be exhibited in this way, though.) This should be slower than
\tet{BPSW_psp} for $k\geq 4$ and we would expect it to be less reliable.

\subsec{Iterators over primes}

\fun{int}{forprime_init}{forprime_t *T, GEN a, GEN b} initialize an
iterator $T$ over primes in $[a,b]$; over primes $\geq a$ if $b =
\kbd{NULL}$. Return $0$ if the range is known to be empty from the start
(as if $b < a$ or $b < 0$), and return $1$ otherwise.

\fun{GEN}{forprime_next}{forprime_t *T} returns the next prime in the range,
assuming that $T$ was initialized by \tet{forprime_init}.

\fun{int}{u_forprime_init}{forprime_t *T, ulong a, ulong b}

\fun{ulong}{u_forprime_next}{forprime_t *T}

\fun{void}{u_forprime_restrict}{forprime_t *T, ulong c} let $T$ an iterator
over primes initialized via \kbd{u\_forprime\_init(\&T, a, b)}, possibly
followed by a number of calls to \tet{u_forprime_next}, and $a \leq c \leq
b$. Restrict the range of primes considered to $[a,c]$.

\fun{int}{u_forprime_arith_init}{forprime_t *T, ulong a,ulong b, ulong c,ulong q} initialize an iterator over primes in $[a,b]$, congruent to $c$
modulo $q$. Assume $0 \leq c < q$ and $(c,q) = 1$. Subsequent calls to
\tet{u_forprime_next} will only return primes congruent to $c$ modulo $q$.

\section{Integral, rational and generic linear algebra}
\subsec{\kbd{ZC} / \kbd{ZV}, \kbd{ZM}} A \kbd{ZV} (resp.~a~\kbd{ZM},
resp.~a~\kbd{ZX}) is a \typ{VEC} or \typ{COL} (resp.~\typ{MAT},
resp.~\typ{POL}) with \typ{INT} coefficients.

\subsubsec{\kbd{ZC} / \kbd{ZV}}

\fun{void}{RgV_check_ZV}{GEN x, const char *s} Assuming \kbd{x} is a \typ{VEC}
or \typ{COL} raise an error if it is not a \kbd{ZV} ($s$ should point to the
name of the caller).

\fun{int}{RgV_is_ZV}{GEN x} Assuming \kbd{x} is a \typ{VEC}
or \typ{COL} return $1$ if it is a \kbd{ZV}, and $0$ otherwise.

\fun{int}{RgV_is_QV}{GEN P} return 1 if the \kbd{RgV}~$P$ has only
\typ{INT} and \typ{FRAC} coefficients, and 0 otherwise.

\fun{int}{ZV_equal0}{GEN x} returns 1 if all entries of the \kbd{ZV} $x$ are
zero, and $0$ otherwise.

\fun{int}{ZV_cmp}{GEN x, GEN y} compare two \kbd{ZV}, which we assume have
the same length (lexicographic order, comparing absolute values).

\fun{int}{ZV_abscmp}{GEN x, GEN y} compare two \kbd{ZV}, which we assume have
the same length (lexicographic order).

\fun{int}{ZV_equal}{GEN x, GEN y} returns $1$ if the two \kbd{ZV} are equal
and $0$ otherwise. A \typ{COL} and a \typ{VEC} with the same entries are
declared equal.

\fun{GEN}{ZC_add}{GEN x, GEN y} adds \kbd{x} and \kbd{y}.

\fun{GEN}{ZC_sub}{GEN x, GEN y} subtracts \kbd{x} and \kbd{y}.

\fun{GEN}{ZC_Z_add}{GEN x, GEN y} adds \kbd{y} to \kbd{x[1]}.

\fun{GEN}{ZC_Z_sub}{GEN x, GEN y} subtracts \kbd{y} to \kbd{x[1]}.

\fun{GEN}{Z_ZC_sub}{GEN a, GEN x} returns the vector $[a - x_1,
-x_2,\dots,-x_n]$.

\fun{GEN}{ZC_copy}{GEN x} returns a (\typ{COL}) copy of \kbd{x}.

\fun{GEN}{ZC_neg}{GEN x} returns $-\kbd{x}$ as a \typ{COL}.

\fun{void}{ZV_neg_inplace}{GEN x} negates the \kbd{ZV} \kbd{x} in place, by
replacing each component by its opposite (the type of \kbd{x} remains the
same, \typ{COL} or \typ{COL}). If you want to save even more memory by
avoiding the implicit component copies, use \kbd{ZV\_togglesign}.

\fun{void}{ZV_togglesign}{GEN x} negates \kbd{x} in place, by toggling the
sign of its integer components. Universal constants \kbd{gen\_1},
\kbd{gen\_m1}, \kbd{gen\_2} and \kbd{gen\_m2} are handled specially and will
not be corrupted. (We use \tet{togglesign_safe}.)

\fun{GEN}{ZC_Z_mul}{GEN x, GEN y} multiplies the \kbd{ZC} or \kbd{ZV}~\kbd{x}
(which can be a column or row vector) by the \typ{INT}~\kbd{y}, returning a
\kbd{ZC}.

\fun{GEN}{ZC_Z_divexact}{GEN x, GEN y} returns $x/y$ assuming all divisions
are exact.

\fun{GEN}{ZC_Z_div}{GEN x, GEN y} returns $x/y$, where the resulting vector
has rational entries.

\fun{GEN}{ZV_dotproduct}{GEN x,GEN y} as \kbd{RgV\_dotproduct} assuming $x$
and $y$ have \typ{INT} entries.

\fun{GEN}{ZV_dotsquare}{GEN x} as \kbd{RgV\_dotsquare} assuming $x$
has \typ{INT} entries.

\fun{GEN}{ZC_lincomb}{GEN u, GEN v, GEN x, GEN y} returns $ux + vy$, where
$u$, $v$ are \typ{INT} and $x,y$ are \kbd{ZC} or \kbd{ZV}. Return a \kbd{ZC}

\fun{void}{ZC_lincomb1_inplace}{GEN X, GEN Y, GEN v} sets $X\leftarrow X +
vY$, where $v$ is a \typ{INT} and $X,Y$ are \kbd{ZC} or \kbd{ZV}. (The result
has the type of $X$.) Memory efficient (e.g. no-op if $v = 0$), but not
gerepile-safe.

\fun{GEN}{ZC_ZV_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{ZC}~\kbd{x}
(seen as a column vector) by the \kbd{ZV}~\kbd{y} (seen as a row vector,
assumed to have compatible dimensions).

\fun{GEN}{ZV_content}{GEN x} returns the GCD of all the components
of~\kbd{x}.

\fun{GEN}{ZV_extgcd}{GEN A} given a vector of $n$ integers $A$, returns $[d,
U]$, where $d$ is the content of $A$ and $U$ is a matrix
in $\text{GL}_n(\Z)$ such that $AU = [D,0, \dots,0]$.

\fun{GEN}{ZV_prod}{GEN x} returns the product of all the components
of~\kbd{x} ($1$ for the empty vector).

\fun{GEN}{ZV_sum}{GEN x} returns the sum of all the components
of~\kbd{x} ($0$ for the empty vector).

\fun{long}{ZV_max_lg}{GEN x} returns the effective length of the longest
entry in $x$.

\fun{int}{ZV_dvd}{GEN x, GEN y} assuming $x$, $y$ are two \kbd{ZV}s of the same
length, return $1$ if $y[i]$ divides $x[i]$ for all $i$ and $0$ otherwise.
Error if one of the $y[i]$ is $0$.

\fun{GEN}{ZV_sort}{GEN L} sort the \kbd{ZV} $L$.
Returns a vector with the same type as $L$.

\fun{GEN}{ZV_sort_uniq}{GEN L} sort the \kbd{ZV} $L$, removing duplicate
entries. Returns a vector with the same type as $L$.

\fun{long}{ZV_search}{GEN L, GEN y} look for the \typ{INT} $y$ in the sorted
\kbd{ZV} $L$. Return an index $i$ such that $L[i] = y$, and  $0$ otherwise.

\fun{GEN}{ZV_indexsort}{GEN L} returns the permutation which, applied to the
\kbd{ZV} $L$, would sort the vector. The result is a \typ{VECSMALL}.

\fun{GEN}{ZV_union_shallow}{GEN x, GEN y} given two \emph{sorted} ZV (as per
\tet{ZV_sort}, returns the union of $x$ and $y$. Shallow function. In case two
entries are equal in $x$ and $y$,  include the one from $x$.

\subsubsec{\kbd{ZM}}

\fun{void}{RgM_check_ZM}{GEN A, const char *s} Assuming \kbd{x} is a \typ{MAT}
raise an error if it is not a \kbd{ZM} ($s$ should point to the name of the
caller).

\fun{GEN}{ZM_copy}{GEN x} returns a copy of \kbd{x}.

\fun{int}{ZM_equal}{GEN A, GEN B} returns $1$ if the two \kbd{ZM} are equal
and $0$ otherwise.

\fun{GEN}{ZM_add}{GEN x, GEN y} returns $\kbd{x} + \kbd{y}$ (assumed to have
compatible dimensions).

\fun{GEN}{ZM_sub}{GEN x, GEN y} returns $\kbd{x} - \kbd{y}$ (assumed to have
compatible dimensions).

\fun{GEN}{ZM_neg}{GEN x} returns $-\kbd{x}$.

\fun{void}{ZM_togglesign}{GEN x} negates \kbd{x} in place, by toggling the
sign of its integer components. Universal constants \kbd{gen\_1},
\kbd{gen\_m1}, \kbd{gen\_2} and \kbd{gen\_m2} are handled specially and will
not be corrupted. (We use \tet{togglesign_safe}.)

\fun{GEN}{ZM_mul}{GEN x, GEN y} multiplies \kbd{x} and \kbd{y} (assumed to
have compatible dimensions).

\fun{GEN}{ZM_sqr}{GEN x} returns $x^2$, where $x$ is a square \kbd{ZM}.

\fun{GEN}{ZM_Z_mul}{GEN x, GEN y} multiplies the \kbd{ZM}~\kbd{x}
by the \typ{INT}~\kbd{y}.

\fun{GEN}{ZM_ZC_mul}{GEN x, GEN y} multiplies the \kbd{ZM}~\kbd{x}
by the \kbd{ZC}~\kbd{y} (seen as a column vector, assumed to have compatible
dimensions).

\fun{GEN}{ZM_diag_mul}{GEN d, GEN m} given a vector $d$ with integer entries
and a \kbd{ZM} $m$ of compatible dimensions, return \kbd{diagonal(d) * m}.

\fun{GEN}{ZM_mul_diag}{GEN m, GEN d} given a vector $d$ with integer entries
 and a \kbd{ZM} $m$ of compatible dimensions, return \kbd{m * diagonal(d)}.

\fun{GEN}{ZM_multosym}{GEN x, GEN y}

\fun{GEN}{ZM_transmultosym}{GEN x, GEN y}

\fun{GEN}{ZM_transmul}{GEN x, GEN y}

\fun{GEN}{ZMrow_ZC_mul}{GEN x, GEN y, long i} multiplies the $i$-th row
of \kbd{ZM}~\kbd{x} by the \kbd{ZC}~\kbd{y} (seen as a column vector, assumed
to have compatible dimensions). Assumes that $x$ is non-empty and
$0 < i < \kbd{lg(x[1])}$.

\fun{GEN}{ZV_ZM_mul}{GEN x, GEN y} multiplies the \kbd{ZV}~\kbd{x}
by the \kbd{ZM}~\kbd{y}. Returns a \typ{VEC}.

\fun{GEN}{ZM_Z_divexact}{GEN x, GEN y} returns $x/y$ assuming all divisions
are exact.

\fun{GEN}{ZM_Z_div}{GEN x, GEN y} returns $x/y$, where the resulting matrix
has rational entries.

\fun{GEN}{ZM_pow}{GEN x, GEN n} returns $\kbd{x}^\kbd{n}$, assuming \kbd{x}
is a square \kbd{ZM} and $\kbd{n}\geq 0$.

\fun{GEN}{ZM_powu}{GEN x, ulong n} returns $\kbd{x}^\kbd{n}$, assuming \kbd{x}
is a square \kbd{ZM} and $\kbd{n}\geq 0$.

\fun{GEN}{ZM_det}{GEN M} if \kbd{M} is a \kbd{ZM}, returns the determinant of
$M$. This is the function underlying \tet{matdet} whenever $M$ is a \kbd{ZM}.

\fun{GEN}{ZM_detmult}{GEN M} if \kbd{M} is a \kbd{ZM}, returns a multiple of
the determinant of the lattice generated by its columns. This is the function
underlying \tet{detint}.

\fun{GEN}{ZM_supnorm}{GEN x} return the sup norm of the \kbd{ZM} $x$.

\fun{GEN}{ZM_charpoly}{GEN M} returns the characteristic polynomial (in
variable $0$) of the \kbd{ZM} $M$.

\fun{GEN}{QM_charpoly_ZX}{GEN M} returns the characteristic polynomial
(in variable $0$) of the \kbd{QM} $M$, assuming that the result has integer
coefficients.

\fun{GEN}{QM_charpoly_ZX_bound}{GEN M, long b} as \tet{QM_charpoly_ZX}
assuming that the sup norm of the (integral) result is $\leq 2^b$.

\fun{GEN}{ZM_imagecompl}{GEN x} returns \kbd{matimagecompl(x)}.

\fun{long}{ZM_rank}{GEN x} returns \kbd{matrank(x)}.

\fun{GEN}{ZM_indexrank}{GEN x} returns \kbd{matindexrank(x)}.

\fun{GEN}{ZM_indeximage}{GEN x} returns \kbd{gel(ZM\_indexrank(x), 2)}.

\fun{long}{ZM_max_lg}{GEN x} returns the effective length of the longest
entry in $x$.

\fun{GEN}{ZM_inv}{GEN M, GEN d} if \kbd{M} is a \kbd{ZM} and \kbd{d}
is a \typ{INT} such that $M' := \kbd{d}\kbd{M}^{-1}$ is integral,
return $M'$. It is allowed to set \kbd{d = NULL}, in which case, the
determinant of \kbd{M} is used instead.

\fun{GEN}{ZM_inv_ratlift}{GEN M, GEN *pd} if \kbd{M} is a \kbd{ZM},
return a primitive matrix $H$ such that $M H$ is $d$ times the identity
and set \kbd{*pd} to $d$. To be used when you expect that the denominator
of $M^{-1}$ is much smaller than $\det M$ and no sharp multiplicative
bound is available; else use \kbd{ZM\_inv}.

\fun{GEN}{QM_inv}{GEN M, GEN d} as above, with \kbd{M} a \kbd{QM}. We
still assume that $M'$ has integer coefficients.

\fun{GEN}{ZM_det_triangular}{GEN x} returns the product of the diagonal
entries of $x$ (its determinant if it is indeed triangular).

\fun{int}{ZM_isidentity}{GEN x} return 1 if the \kbd{ZM} $x$ is the
identity matrix, and 0 otherwise.

\fun{int}{ZM_isscalar}{GEN x, GEN s} given a \kbd{ZM} $x$ and a
\typ{INT} $s$, return 1 if $x$ is equal to $s$ times the identity, and 0
otherwise. If $s$ is \kbd{NULL}, test whether $x$ is an arbitrary scalar
matrix.

\fun{long}{ZC_is_ei}{GEN x} return $i$ if the \kbd{ZC} $x$ has $0$ entries,
but for a $1$ at position $i$.

\fun{int}{ZM_ishnf}{GEN x} return $1$ if $x$ is in HNF form, i.e. is upper
triangular with positive diagonal coefficients, and  for $j>i$,
$x_{i,i}>x_{i,j} \ge 0$.

\fun{GEN}{Qevproj_init}{GEN M} let $M$ be a  $n\times d$ \kbd{ZM} of
maximal rank $d \leq n$, representing the basis of a $\Q$-subspace
$V$ of $\Q^n$. Return a projector on $V$, to be used by \tet{Qevproj_apply}.
The interface details may change in the future, but this function currently
returns $[M, B,D,p]$, where $p$ is a \typ{VECSMALL} with $d$ entries
such that the submatrix $A = \kbd{rowpermute}(M,p)$ is invertible, $B$ is a
\kbd{ZM} and $d$ a \typ{INT} such that $A B = D \Id_d$.

\fun{GEN}{Qevproj_apply}{GEN T, GEN pro} let $T$ be an $n\times n$
\kbd{QM}, stabilizing a $\Q$-subspace $V\subset \Q^n$ of dimension $d$, and
let \kbd{pro} be a projector on that subspace initialized by
\tet{Qevproj_init}$(M)$. Return the $d\times d$ matrix representing $T_{|V}$
on the basis given by the columns of $M$.

\fun{GEN}{Qevproj_apply_vecei}{GEN T, GEN pro, long k} as
\tet{Qevproj_apply}, return only the image of the $k$-th basis vector $M[k]$
(still on the basis given by the columns of $M$).

\subsec{\kbd{zv}, \kbd{zm}}

\fun{GEN}{zv_neg}{GEN x} return $-x$. No check for overflow is done, which
occurs in the fringe case where an entry is equal to $2^{\B-1}$.

\fun{GEN}{zv_neg_inplace}{GEN x} negates $x$ in place and return it. No check
for overflow is done, which occurs in the fringe case where an entry is equal
to $2^{\B-1}$.

\fun{GEN}{zm_zc_mul}{GEN x, GEN y}

\fun{GEN}{zm_mul}{GEN x, GEN y}

\fun{GEN}{zv_z_mul}{GEN x, long n} return $n\*x$. No check for overflow is
done.

\fun{long}{zv_content}{GEN x} returns the gcd of the entries of $x$.

\fun{long}{zv_dotproduct}{GEN x, GEN y}

\fun{long}{zv_prod}{GEN x} returns the product of all the components
of~\kbd{x} (assumes no overflow occurs).

\fun{GEN}{zv_prod_Z}{GEN x} returns the product of all the components
of~\kbd{x}; consider all $x[i]$ as \kbd{ulong}s.

\fun{long}{zv_sum}{GEN x} returns the sum of all the components
of~\kbd{x} (assumes no overflow occurs).

\fun{int}{zv_cmp0}{GEN x} returns 1 if all entries of the \kbd{zv} $x$ are $0$,
and $0$ otherwise.

\fun{int}{zv_equal}{GEN x, GEN y} returns $1$ if the two \kbd{zv} are equal
and $0$ otherwise.

\fun{int}{zv_equal0}{GEN x} returns $1$ if all entries are $0$, and return
$0$ otherwise.

\fun{long}{zv_search}{GEN L, long y} look for $y$ in the sorted
\kbd{zv} $L$. Return an index $i$ such that $L[i] = y$, and  $0$ otherwise.

\fun{GEN}{zv_copy}{GEN x} as \kbd{Flv\_copy}.

\fun{GEN}{zm_transpose}{GEN x} as \kbd{Flm\_transpose}.

\fun{GEN}{zm_copy}{GEN x} as \kbd{Flm\_copy}.

\fun{GEN}{zero_zm}{long m, long n} as \kbd{zero\_Flm}.

\fun{GEN}{zero_zv}{long n} as \kbd{zero\_Flv}.

\fun{GEN}{zm_row}{GEN A, long x0} as \kbd{Flm\_row}.

\fun{int}{zvV_equal}{GEN x, GEN y} returns $1$ if the two \kbd{zvV} (vectors
of \kbd{zv}) are equal and $0$ otherwise.

\subsec{\kbd{ZMV} / \kbd{zmV} (vectors of \kbd{ZM}/\kbd{zm})}

\fun{int}{RgV_is_ZMV}{GEN x} Assuming \kbd{x} is a \typ{VEC}
or \typ{COL} return $1$ if its components are \kbd{ZM}, and $0$ otherwise.

\fun{GEN}{ZMV_to_zmV}{GEN z}

\fun{GEN}{zmV_to_ZMV}{GEN z}

\fun{GEN}{ZMV_to_FlmV}{GEN z, ulong m}

\subsec{\kbd{RgC} / \kbd{RgV}, \kbd{RgM}}

\kbd{RgC} and \kbd{RgV} routines assume the inputs are \kbd{VEC} or \kbd{COL}
of the same dimension. \kbd{RgM} assume the inputs are \kbd{MAT} of
compatible dimensions.

\subsubsec{Matrix arithmetic}

\fun{void}{RgM_dimensions}{GEN}{x, long *m, long *n} sets $m$, resp.~$n$, to
the number of rows, resp.~columns of the \typ{MAT} $x$.

\fun{GEN}{RgC_add}{GEN x, GEN y} returns $x + y$ as a \typ{COL}.

\fun{GEN}{RgC_neg}{GEN x} returns $-x$ as a \typ{COL}.

\fun{GEN}{RgC_sub}{GEN x, GEN y} returns $x - y$ as a \typ{COL}.

\fun{GEN}{RgV_add}{GEN x, GEN y} returns $x + y$ as a \typ{VEC}.

\fun{GEN}{RgV_neg}{GEN x} returns $-x$ as a \typ{VEC}.

\fun{GEN}{RgV_sub}{GEN x, GEN y} returns $x - y$ as a \typ{VEC}.

\fun{GEN}{RgM_add}{GEN x, GEN y} return $x+y$.

\fun{GEN}{RgM_neg}{GEN x} returns $-x$.

\fun{GEN}{RgM_sub}{GEN x, GEN y} returns $x-y$.

\fun{GEN}{RgM_Rg_add}{GEN x, GEN y} assuming $x$ is a square matrix
and $y$ a scalar, returns the square matrix $x + y*\text{Id}$.

\fun{GEN}{RgM_Rg_add_shallow}{GEN x, GEN y} as \kbd{RgM\_Rg\_add} with much
fewer copies. Not suitable for \kbd{gerepileupto}.

\fun{GEN}{RgM_Rg_sub}{GEN x, GEN y} assuming $x$ is a square matrix
and $y$ a scalar, returns the square matrix $x - y*\text{Id}$.

\fun{GEN}{RgM_Rg_sub_shallow}{GEN x, GEN y} as \kbd{RgM\_Rg\_sub} with much
fewer copies. Not suitable for \kbd{gerepileupto}.

\fun{GEN}{RgC_Rg_add}{GEN x, GEN y} assuming $x$ is a non-empty column vector
and $y$ a scalar, returns the vector $[x_1 + y, x_2,\dots,x_n]$.

\fun{GEN}{RgC_Rg_sub}{GEN x, GEN y} assuming $x$ is a non-empty column vector
and $y$ a scalar, returns the vector $[x_1 - y, x_2,\dots,x_n]$.

\fun{GEN}{Rg_RgC_sub}{GEN a, GEN x} assuming $x$ is a non-empty column vector
and $a$ a scalar, returns the vector $[a - x_1, -x_2,\dots,-x_n]$.

\fun{GEN}{RgC_Rg_div}{GEN x, GEN y}

\fun{GEN}{RgM_Rg_div}{GEN x, GEN y} returns $x/y$ ($y$ treated as a scalar).

\fun{GEN}{RgC_Rg_mul}{GEN x, GEN y}

\fun{GEN}{RgV_Rg_mul}{GEN x, GEN y}

\fun{GEN}{RgM_Rg_mul}{GEN x, GEN y} returns $x\times y$ ($y$ treated as a
scalar).

\fun{GEN}{RgV_RgC_mul}{GEN x, GEN y} returns $x\times y$.

\fun{GEN}{RgV_RgM_mul}{GEN x, GEN y} returns $x\times y$.

\fun{GEN}{RgM_RgC_mul}{GEN x, GEN y} returns $x\times y$.

\fun{GEN}{RgM_mul}{GEN x, GEN y} returns $x\times y$.

\fun{GEN}{RgM_transmul}{GEN x, GEN y} returns $x\til \times y$.

\fun{GEN}{RgM_multosym}{GEN x, GEN y} returns $x\times y$, assuming
the result is a symmetric matrix (about twice faster than a generic matrix
multiplication).

\fun{GEN}{RgM_transmultosym}{GEN x, GEN y} returns $x\til \times y$, assuming
the result is a symmetric matrix (about twice faster than a generic matrix
multiplication).

\fun{GEN}{RgMrow_RgC_mul}{GEN x, GEN y, long i} multiplies the $i$-th row of
\kbd{RgM}~\kbd{x} by the \kbd{RgC}~\kbd{y} (seen as a column vector, assumed
to have compatible dimensions). Assumes that $x$ is non-empty and $0 < i <
\kbd{lg(x[1])}$.

\fun{GEN}{RgM_mulreal}{GEN x, GEN y} returns the real part of $x\times y$
(whose entries are \typ{INT}, \typ{FRAC}, \typ{REAL} or \typ{COMPLEX}).

\fun{GEN}{RgM_sqr}{GEN x} returns $x^2$.

\fun{GEN}{RgC_RgV_mul}{GEN x, GEN y} returns $x\times y$ (the square matrix
$(x_iy_j)$).

The following two functions are not well defined in general and only provided
for convenience in specific cases:

\fun{GEN}{RgC_RgM_mul}{GEN x, GEN y} returns $x\times y[1,]$ if $y$ is
a row matrix $1\times n$, error otherwise.

\fun{GEN}{RgM_RgV_mul}{GEN x, GEN y} returns $x\times y[,1]$ if $y$ is
a column matrix $n\times 1$, error otherwise.

\fun{GEN}{RgM_powers}{GEN x, long n} returns $[\kbd{x}^0,
\dots, \kbd{x}^\kbd{n}]$ as a \typ{VEC} of \kbd{RgM}s.

\smallskip

\fun{GEN}{RgV_sum}{GEN v} sum of the entries of $v$

\fun{GEN}{RgV_prod}{GEN v} product of the entries of $v$, using
a divide and conquer strategy

\fun{GEN}{RgV_sumpart}{GEN v, long n} returns the sum $v[1] + \dots + v[n]$
(assumes that \kbd{lg}$(v) > n$).

\fun{GEN}{RgV_sumpart2}{GEN v, long m, long n} returns the sum $v[m] + \dots +
v[n]$ (assumes that \kbd{lg}$(v) > n$ and $m > 0$). Returns \kbd{gen\_0}
when $m > n$.

\fun{GEN}{RgM_sumcol}{GEN v} returns a \typ{COL}, sum of the columns of the
\typ{MAT} $v$.

\fun{GEN}{RgV_dotproduct}{GEN x,GEN y} returns the scalar product of $x$ and $y$

\fun{GEN}{RgV_dotsquare}{GEN x} returns the scalar product of $x$ with itself.

\fun{GEN}{RgV_kill0}{GEN v} returns a shallow copy of $v$ where entries
matched by \kbd{gequal0} are replaced by \kbd{NULL}. The return value
is not a valid \kbd{GEN} and must be handled specially. The idea is
to pre-treat a vector of coefficients to speed up later linear combinations
or scalar products.

\fun{GEN}{gram_matrix}{GEN v} returns the \idx{Gram matrix} $(v_i\cdot v_j)$
attached to the entries of $v$ (matrix, or vector of vectors).

\fun{GEN}{RgV_polint}{GEN X, GEN Y, long v} $X$ and $Y$ being two vectors of
the same length, returns the polynomial $T$ in variable $v$ such that
$T(X[i]) = Y[i]$ for all $i$. The special case $X = \kbd{NULL}$
corresponds to $X = [1,2,\dots,n]$, where $n$ is the length of $Y$.

\subsubsec{Special shapes}

The following routines check whether matrices or vectors have a special
shape, using \kbd{gequal1} and \kbd{gequal0} to test components. (This makes
a difference when components are inexact.)

\fun{int}{RgV_isscalar}{GEN x} return 1 if all the entries of $x$ are $0$
(as per \kbd{gequal0}), except possibly the first one. The name comes from
vectors expressing polynomials on the standard basis $1,T,\dots, T^{n-1}$, or
on \kbd{nf.zk} (whose first element is $1$).

\fun{int}{QV_isscalar}{GEN x} as \kbd{RgV\_isscalar}, assuming $x$ is a
\kbd{QV} (\typ{INT} and \typ{FRAC} entries only).

\fun{int}{ZV_isscalar}{GEN x} as \kbd{RgV\_isscalar}, assuming $x$ is a
\kbd{ZV} (\typ{INT} entries only).

\fun{int}{RgM_isscalar}{GEN x, GEN s} return 1 if $x$ is the scalar matrix
equal to $s$ times the identity, and 0 otherwise. If $s$ is \kbd{NULL}, test
whether $x$ is an arbitrary scalar matrix.

\fun{int}{RgM_isidentity}{GEN x} return 1 if the \typ{MAT} $x$ is the
identity matrix, and 0 otherwise.

\fun{int}{RgM_isdiagonal}{GEN x} return 1 if the \typ{MAT} $x$ is a
diagonal matrix, and 0 otherwise.

\fun{long}{RgC_is_ei}{GEN x} return $i$ if the \typ{COL} $x$ has $0$ entries,
but for a $1$ at position $i$.

\fun{int}{RgM_is_ZM}{GEN x} return 1 if the \typ{MAT}~$x$ has only
\typ{INT} coefficients, and 0 otherwise.

\fun{long}{RgV_isin}{GEN v, GEN x} return the first index $i$ such that
$v[i] = x$ if it exists, and $0$ otherwise. Naive search in linear time, does
not assume that \kbd{v} is sorted.

\fun{GEN}{RgM_diagonal}{GEN m} returns the diagonal of $m$ as a \typ{VEC}.

\fun{GEN}{RgM_diagonal_shallow}{GEN m} shallow version of \kbd{RgM\_diagonal}

\subsubsec{Conversion to floating point entries}

\fun{GEN}{RgC_gtofp}{GEN x, GEN prec} returns the \typ{COL} obtained by
applying \kbd{gtofp(gel(x,i), prec)} to all coefficients of $x$.

\fun{GEN}{RgC_gtomp}{GEN x, long prec} returns the \typ{COL} obtained by
applying \kbd{gtomp(gel(x,i), prec)} to all coefficients of $x$.

\fun{GEN}{RgC_fpnorml2}{GEN x, long prec} returns (a stack-clean variant of)
\bprog
  gnorml2( RgC_gtofp(x, prec) )
@eprog

\fun{GEN}{RgM_gtofp}{GEN x, GEN prec} returns the \typ{MAT} obtained by
applying \kbd{gtofp(gel(x,i), prec)} to all coefficients of $x$.

\fun{GEN}{RgM_gtomp}{GEN x, long prec} returns the \typ{MAT} obtained by
applying \kbd{gtomp(gel(x,i), prec)} to all coefficients of $x$.

\fun{GEN}{RgM_fpnorml2}{GEN x, long prec} returns (a stack-clean variant of)
\bprog
  gnorml2( RgM_gtofp(x, prec) )
@eprog

\subsubsec{Linear algebra, linear systems}

\fun{GEN}{RgM_inv}{GEN a} returns a left inverse of $a$ (which needs not be
square), or \kbd{NULL} if this turns out to be impossible. The latter
happens when the matrix does not have maximal rank (or when rounding errors
make it appear so).

\fun{GEN}{RgM_inv_upper}{GEN a} as \kbd{RgM\_inv}, assuming that $a$ is a
non-empty invertible upper triangular matrix, hence a little faster.

\fun{GEN}{RgM_RgC_invimage}{GEN A, GEN B} returns a \typ{COL} $X$ such that
$A X = B$ if one such exists, and \kbd{NULL} otherwise.

\fun{GEN}{RgM_invimage}{GEN A, GEN B} returns a \typ{MAT} $X$ such that
$A X = B$ if one such exists, and \kbd{NULL} otherwise.

\fun{GEN}{RgM_Hadamard}{GEN a} returns a upper bound for the absolute
value of $\text{det}(a)$. The bound is a \typ{INT}.

\fun{GEN}{RgM_solve}{GEN a, GEN b} returns $a^{-1}b$ where $a$ is a square
\typ{MAT} and $b$ is a \typ{COL} or \typ{MAT}. Returns \kbd{NULL} if $a^{-1}$
cannot be computed, see \tet{RgM_inv}.

If $b = \kbd{NULL}$, the matrix $a$ need no longer be square, and we strive
to return a left inverse for $a$ (\kbd{NULL} if it does not exist).

\fun{GEN}{RgM_solve_realimag}{GEN M, GEN b} $M$ being a \typ{MAT}
with $r_1+r_2$ rows and $r_1+2r_2$ columns, $y$ a \typ{COL} or \typ{MAT}
such that the equation $Mx = y$ makes sense, returns $x$ under the following
simplifying assumptions: the first $r_1$ rows of $M$ and $y$ are real
(the $r_2$ others are complex), and $x$ is real. This is stabler and faster
than calling $\kbd{RgM\_solve}(M, b)$ over $\C$. In most applications,
$M$ approximates the complex embeddings of an integer basis in a number
field, and $x$ is actually rational.

\fun{GEN}{split_realimag}{GEN x, long r1, long r2} $x$ is a \typ{COL} or
\typ{MAT} with $r_1 + r_2$ rows, whose first $r_1$ rows have real entries
(the $r_2$ others are complex). Return an object of the same type as
$x$ and $r_1 + 2r_2$ rows, such that the first $r_1 + r_2$ rows contain
the real part of $x$, and the $r_2$ following ones contain the imaginary part
of the last $r_2$ rows of $x$. Called by \tet{RgM_solve_realimag}.

\fun{GEN}{RgM_det_triangular}{GEN x} returns the product of the diagonal
entries of $x$ (its determinant if it is indeed triangular).

\fun{GEN}{Frobeniusform}{GEN V, long n} given the vector $V$ of elementary
divisors for $M - x\text{Id}$, where $M$ is an $n\times n$ square matrix.
Returns the Frobenius form of $M$.

\fun{int}{RgM_QR_init}{GEN x, GEN *pB, GEN *pQ, GEN *pL, long prec}
QR-decomposition of a square invertible \typ{MAT} $x$ with real coefficients.
Sets \kbd{*pB} to the vector of squared lengths of the $x[i]$, \kbd{*pL} to
the Gram-Schmidt coefficients and \kbd{*pQ} to a vector of successive
Householder transforms. If $R$ denotes the transpose of $L$ and $Q$ is the
result of applying \kbd{*pQ} to the identity matrix, then $x = QR$ is the QR
decomposition of $x$. Returns $0$ is $x$ is not invertible or we hit a
precision problem, and $1$ otherwise.

\fun{int}{QR_init}{GEN x, GEN *pB, GEN *pQ, GEN *pL, long prec} as
\kbd{RgM\_QR\_init}, assuming further that $x$ has \typ{INT} or \typ{REAL}
coefficients.

\fun{GEN}{R_from_QR}{GEN x, long prec} assuming that $x$ is a square
invertible \typ{MAT} with \typ{INT} or \typ{REAL} coefficients, return
the upper triangular $R$ from the $QR$ docomposition of $x$. Not memory
clean. If the matrix is not known to have \typ{INT} or \typ{REAL}
coefficients, apply \tet{RgM_gtomp} first.

\fun{GEN}{gaussred_from_QR}{GEN x, long prec} assuming that $x$ is a square
invertible \typ{MAT} with \typ{INT} or \typ{REAL} coefficients, returns
\kbd{qfgaussred(x\til * x)}; this is essentially the upper triangular $R$
matrix from the $QR$ decomposition of $x$, renormalized to accomodate
\kbd{qfgaussred} conventions. Not memory clean.

\fun{GEN}{RgM_gram_schmidt}{GEN e, GEN *ptB} naive (unstable) Gram-Schmidt
orthogonalization of the basis $(e_i)$ given by the columns of \typ{MAT} $e$.
Return the $e_i^*$ (as columns of a \typ{MAT}) and set \kbd{*ptB} to the
vector of squared lengths $|e_i^*|^2$.

\fun{GEN}{RgM_Babai}{GEN M, GEN y} given an LLL-reduced \typ{MAT} $M$ and
a \typ{COL} $y$ of the same dimension, apply Babai's nearest plane algorithm
to return an \emph{integral} $x$ such that $y - Mx$ has small $L_2$ norm.
This yields an approximate solution to the closest vector problem.

\subsec{\kbd{ZG}}

Let $G$ be a multiplicative group with neutral element $1_G$ whose
multiplication is supported by \kbd{gmul} and where equality test is
performed using \tet{gidentical}, e.g. a matrix group. The following
routines implement basic computations in the group algebra $\Z[G]$. All of
them are shallow for efficiency reasons. A \kbd{ZG} is either

\item a \typ{INT} $n$, representing $n[1_G]$

\item or a ``factorization matrix'' with two columns $[g,e]$: the first one
contains group elements, sorted according to \tet{cmp_universal}, and the
second one contains integer ``exponents'', representing $\sum e_i [g_i]$.

Note that \tet{to_famat} and \tet{to_famat_shallow}$(g,e)$ allow to build
the \kbd{ZG} $e[g]$ from $e\in \Z$ and $g\in G$.

\fun{GEN}{ZG_normalize}{GEN x} given a \typ{INT} $x$ or a factorization
matrix \emph{without} assuming that the first column is properly sorted.
Return a valid (sorted) \kbd{ZG}. Shallow function.

\fun{GEN}{ZG_add}{GEN x, GEN y} return $x+y$; shallow function.

\fun{GEN}{ZG_neg}{GEN x} return $-x$; shallow function.

\fun{GEN}{ZG_sub}{GEN x, GEN y} return $x-y$; shallow function.

\fun{GEN}{ZG_mul}{GEN x, GEN y} return $xy$; shallow function.

\fun{GEN}{ZG_G_mul}{GEN x, GEN y} given a \kbd{ZG} $x$ and $y\in G$,
 return $xy$; shallow function.

\fun{GEN}{G_ZG_mul}{GEN x, GEN y} given a \kbd{ZG} $y$ and $x\in G$,
 return $xy$; shallow function.

\fun{GEN}{ZG_Z_mul}{GEN x, GEN n} given a \kbd{ZG} $x$ and $y\in \Z$,
 return $xy$; shallow function.

\fun{GEN}{ZGC_G_mul}{GEN v, GEN x} given $v$ a vector of \kbd{ZG} and $x\in
G$ return the vector (with the same type as $v$ with entries $v[i]\cdot x$.
Shallow function.

\fun{void}{ZGC_G_mul_inplace}{GEN v, GEN x} as \tet{ZGC_G_mul}, modifying
$v$ in place.

\fun{GEN}{ZGC_Z_mul}{GEN v, GEN n} given $v$ a vector of \kbd{ZG} and $n\in
Z$ return the vector (with the same type as $v$ with entries $n \cdot v[i]$.
Shallow function.

\fun{GEN}{G_ZGC_mul}{GEN x, GEN v} given $v$ a vector of \kbd{ZG} and $x\in
G$ return the vector of $x \cdot v[i]$. Shallow function.

\fun{GEN}{ZGCs_add}{GEN x, GEN y} add two sparse vectors of
\kbd{ZG} elements (see Blackbox linear algebra below).

\subsec{Blackbox linear algebra}

A sparse column \kbd{zCs} $v$ is a \typ{COL} with two components $C$ and $E$
which are \typ{VECSMALL} of the same length, representing $\sum_i
E[i]*e_{C[i]}$, where $(e_j)$ is the canonical basis. A sparse matrix
(\kbd{zMs}) is a \typ{VEC} of \kbd{zCs}.

\kbd{FpCs} and \kbd{FpMs} are identical to the above, but $E[i]$ is now
interpreted as a \emph{signed} C long integer representing an element of
$\F_p$. This is important since $p$ can be so large that $p+E[i]$ would not
fit in a C long.

\kbd{RgCs} and \kbd{RgMs} are similar, except that the type of the components
of $E$ is now unspecified. Functions handling those later objects
must not depend on the type of those components.

It is not possible to derive the space dimension (number of rows) from the
above data. Thus most functions take an argument \kbd{nbrow} which is the
number of rows of the corresponding column/matrix in dense representation.

\fun{GEN}{zCs_to_ZC}{GEN C, long nbrow} convert the sparse vector $C$
to a dense \kbd{ZC} of dimension \kbd{nbrow}.

\fun{GEN}{zMs_to_ZM}{GEN M, long nbrow} convert the sparse matrix $M$
to a dense \kbd{ZM} whose columns have dimension \kbd{nbrow}.

\fun{GEN}{FpMs_FpC_mul}{GEN M, GEN B, GEN p} multiply the sparse matrix $M$
(over $\F_p$) by the sparse vector $B$. The result is an \kbd{FpC}, i.e.~a
dense vector.

\fun{GEN}{zMs_ZC_mul}{GEN M, GEN B, GEN p} multiply the sparse matrix $M$
by the sparse vector $B$ (over $\Z$). The result is an \kbd{ZC}, i.e.~a
dense vector.

\fun{GEN}{FpV_FpMs_mul}{GEN B, GEN M, GEN p} multiply the sparse vector $B$
by the sparse matrix $M$ (over $\F_p$). The result is an \kbd{FpV}, i.e.~a
dense vector.

\fun{GEN}{ZV_zMs_mul}{GEN B, GEN M, GEN p} multiply the sparse vector $B$ (over
$\Z$) by the sparse matrix $M$. The result is an \kbd{ZV}, i.e.~a
dense vector.

\fun{void}{RgMs_structelim}{GEN M, long nbrow, GEN A, GEN *p_col, GEN *p_row}
$M$ being a RgMs with \kbd{nbrow} rows, $A$ being a list of row indices,
Perform structured elimination on $M$ by removing some rows and columns until
the number of effectively present rows is equal to the number of columns.
the result is stored in two \typ{VECSMALL}s, \kbd{*p\_col} and \kbd{*p\_row}:
\kbd{*p\_col} is a map from the new columns indices to the old one.
\kbd{*p\_row} is a map from the old rows indices to the new one ($0$ if removed).

\fun{GEN}{FpMs_leftkernel_elt}{GEN M, long nbrow, GEN p}
$M$ being a sparse matrix over $\F_p$, return a non-zero kbd{FpV} $X$ such
that $X\*M$ components are almost all $0$.

\fun{GEN}{FpMs_FpCs_solve}{GEN M, GEN B, long nbrow, GEN p}
solve the equation $M\*X = B$, where $M$ is a sparse matrix and $B$ is a sparse
vector, both over $\F_p$. Return either a solution as a \typ{COL} (dense
vector), the index of a column which is linearly dependent from the
others as a \typ{VECSMALL} with a single component, or \kbd{NULL}
(can happen if $B$ is not in the image of $M$).

\fun{GEN}{FpMs_FpCs_solve_safe}{GEN M, GEN B, long nbrow, GEN p}
as above, but in the event that $p$ is not a prime and an impossible division
occurs, return \kbd{NULL}.

\fun{GEN}{ZpMs_ZpCs_solve}{GEN M, GEN B, long nbrow, GEN p, long e}
solve the equation $MX = B$, where $M$ is a sparse matrix and $B$ is a sparse
vector, both over $\Z/p^e\Z$. Return either a solution as a \typ{COL} (dense
vector), or the index of a column which is linearly dependent from the
others as a \typ{VECSMALL} with a single component.

\fun{GEN}{gen_FpM_Wiedemann}{void *E, GEN (*f)(void*, GEN), GEN B, GEN p}
solve the equation $f(X) = B$ over $\F_p$, where $B$ is a \kbd{FpV}, and $f$
is a blackbox endomorphism, where $f(E, X)$ computes the value of $f$ at the
(dense) column vector $X$. Returns either a solution \typ{COL}, or a kernel
vector as a \typ{VEC}.

\fun{GEN}{gen_ZpM_Dixon}{void *E, GEN (*f)(void*, GEN), GEN B, GEN p, long e}
solve equation $f(X) = B$ over $\Z/p^e\Z$, where $B$ is a \kbd{ZV}, and $f$ is a
blackbox endomorphism, where $f(E, X)$ computes the value of $f$ at the
(dense) column vector $X$. Returns either a solution \typ{COL}, or a kernel
vector as a \typ{VEC}.

\subsec{Obsolete functions}

The functions in this section are kept for backward compatibility only
and will eventually disappear.

\fun{GEN}{image2}{GEN x} compute the image of $x$ using a very slow
algorithm. Use \tet{image} instead.

\section{Integral, rational and generic polynomial arithmetic}

\subsec{\kbd{ZX}}

\fun{void}{RgX_check_ZX}{GEN x, const char *s} Assuming \kbd{x} is a \typ{POL}
raise an error if it is not a \kbd{ZX} ($s$ should point to the name of the
caller).

\fun{GEN}{ZX_copy}{GEN x,GEN p} returns a copy of \kbd{x}.

\fun{long}{ZX_max_lg}{GEN x} returns the effective length of the longest
component in $x$.

\fun{GEN}{scalar_ZX}{GEN x, long v} returns the constant \kbd{ZX} in variable
$v$ equal to the \typ{INT} $x$.

\fun{GEN}{scalar_ZX_shallow}{GEN x, long v} returns the constant \kbd{ZX} in
variable $v$ equal to the \typ{INT} $x$. Shallow function not suitable for
\kbd{gerepile} and friends.

\fun{GEN}{ZX_renormalize}{GEN x, long l}, as \kbd{normalizepol}, where
$\kbd{l} = \kbd{lg(x)}$, in place.

\fun{int}{ZX_equal}{GEN x, GEN y} returns $1$ if the two \kbd{ZX} have
the same \kbd{degpol} and their coefficients are equal. Variable numbers are
not checked.

\fun{int}{ZX_equal1}{GEN x} returns $1$ if the \kbd{ZX} is equal to $1$
and $0$ otherwise.

\fun{GEN}{ZX_add}{GEN x,GEN y} adds \kbd{x} and \kbd{y}.

\fun{GEN}{ZX_sub}{GEN x,GEN y} subtracts \kbd{x} and \kbd{y}.

\fun{GEN}{ZX_neg}{GEN x,GEN p} returns $-\kbd{x}$.

\fun{GEN}{ZX_Z_add}{GEN x,GEN y} adds the integer \kbd{y} to the
\kbd{ZX}~\kbd{x}.

\fun{GEN}{ZX_Z_add_shallow}{GEN x,GEN y} shallow version of \tet{ZX_Z_add}.

\fun{GEN}{ZX_Z_sub}{GEN x,GEN y} subtracts the integer \kbd{y} to the
\kbd{ZX}~\kbd{x}.

\fun{GEN}{Z_ZX_sub}{GEN x,GEN y} subtracts the \kbd{ZX} \kbd{y} to the
integer \kbd{x}.

\fun{GEN}{ZX_Z_mul}{GEN x,GEN y} multiplies the \kbd{ZX} \kbd{x} by the
integer \kbd{y}.

\fun{GEN}{ZX_mulu}{GEN x, ulong y} multiplies \kbd{x} by the integer \kbd{y}.

\fun{GEN}{ZX_shifti}{GEN x, long n} shifts all coefficients of \kbd{x} by $n$
bits, which can be negative.

\fun{GEN}{ZX_Z_divexact}{GEN x, GEN y} returns $x/y$ assuming all divisions
are exact.

\fun{GEN}{ZX_remi2n}{GEN x, long n} reduces all coefficients of \kbd{x} to
$n$ bits, using \tet{remi2n}.

\fun{GEN}{ZX_mul}{GEN x,GEN y} multiplies \kbd{x} and \kbd{y}.

\fun{GEN}{ZX_sqr}{GEN x,GEN p} returns $\kbd{x}^2$.

\fun{GEN}{ZX_mulspec}{GEN a, GEN b, long na, long nb}. Internal routine:
\kbd{a} and \kbd{b} are arrays of coefficients representing polynomials
$\sum_{i = 0}^{\kbd{na-1}} \kbd{a}[i] X^i$ and
$\sum_{i = 0}^{\kbd{nb-1}} \kbd{b}[i] X^i$. Returns their product (as a true
\kbd{GEN}).

\fun{GEN}{ZX_sqrspec}{GEN a, long na}. Internal routine:
\kbd{a} is an array of coefficients representing polynomial
$\sum_{i = 0}^{\kbd{na-1}} \kbd{a}[i] X^i$. Return its square (as a true
\kbd{GEN}).

\fun{GEN}{ZX_rem}{GEN x, GEN y} returns the remainder of the Euclidean
division of $x$ mod $y$. Assume that $x$, $y$ are two \kbd{ZX} and that
$y$ is monic.

\fun{GEN}{ZX_mod_Xnm1}{GEN T, ulong n} return $T$ modulo $X^n - 1)$. Shallow
function.

\fun{GEN}{ZX_div_by_X_1}{GEN T, GEN *r} return the quotient of $T$ by $X-1$.
If $r$ is not \kbd{NULL} set it to $T(1)$.

\fun{GEN}{ZX_gcd}{GEN x,GEN y} returns a gcd of the \kbd{ZX} $x$ and $y$.
Not memory-clean, but suitable for \kbd{gerepileupto}.

\fun{GEN}{ZX_gcd_all}{GEN x, GEN y, GEN *pX}. returns a gcd $d$ of $x$ and
$y$. If \kbd{pX} is not \kbd{NULL}, set $\kbd{*pX}$ to a (non-zero) integer
multiple of $x/d$. If $x$ and $y$ are both monic, then $d$ is monic and
\kbd{*pX} is exactly $x/d$. Not memory clean if the gcd is $1$
(in that case \kbd{*pX} is set to $x$).

\fun{GEN}{ZX_content}{GEN x} returns the content of the \kbd{ZX} $x$.

\fun{long}{ZX_val}{GEN P} as \kbd{RgX\_val}, but assumes \kbd{P} has \typ{INT}
coefficients.

\fun{long}{ZX_valrem}{GEN P, GEN *z} as \kbd{RgX\_valrem}, but assumes
\kbd{P} has \typ{INT} coefficients.

\fun{GEN}{ZX_to_monic}{GEN q GEN *L} given $q$ a non-zero \kbd{ZX},
returns a monic integral polynomial $Q$ such that $Q(x) = C q(x/L)$, for some
rational $C$ and positive integer $L > 0$. If $\kbd{L}$ is not \kbd{NULL},
set \kbd{*L} to $L$; if $L = 1$, \kbd{*L} is set to \kbd{gen\_1}. Not
suitable for gerepileupto.

\fun{GEN}{ZX_primitive_to_monic}{GEN q, GEN *L} as \tet{ZX_to_monic} except
$q$ is assumed to have trivial content, which avoids recomputing it.
The result is suboptimal if $q$ is not primitive ($L$ larger than
necessary), but remains correct.

\fun{GEN}{ZX_Z_normalize}{GEN q, GEN *L} a restricted version of
\kbd{ZX\_primitive\_to\_monic}, where $q$ is a \emph{monic} \kbd{ZX}
of degree $> 0$. Finds the largest integer $L > 0$ such that
$Q(X) := L^{-\deg q} q(Lx)$ is integral and return $Q$; this is not
well-defined if $q$ is a monomial, in that case, set $L=1$ and $Q = q$. If
\kbd{L} is not \kbd{NULL}, set \kbd{*L} to $L$.

\fun{GEN}{ZX_Q_normalize}{GEN q, GEN *L} a variant of \tet{ZX_Z_normalize}
where $L > 0$ is allowed to be rational, the monic $Q\in \Z[X]$ has possibly
smaller coefficients.

\fun{long}{ZX_deflate_order}{GEN P} given a non-constant \kbd{ZX}
$P$, returns the largest exponent $d$ such that $P$ is of the form $P(x^d)$.

\fun{long}{ZX_deflate_max}{GEN P, long *d}. Given a non-constant
polynomial with integer coefficients $P$, sets \kbd{d} to
\kbd{ZX\_deflate\_order(P)} and returns \kbd{RgX\_deflate(P,d)}. Shallow
function.

\fun{GEN}{ZX_rescale}{GEN P, GEN h} returns $h^{\deg(P)} P(x/h)$.
\kbd{P} is a \kbd{ZX} and \kbd{h} is a non-zero integer. Neither memory-clean
nor suitable for \kbd{gerepileupto}.

\fun{GEN}{ZX_rescale2n}{GEN P, long n} returns $2^{n\deg(P)} P(x>>n)$ where
\kbd{P} is a \kbd{ZX}. Neither memory-clean nor suitable for
\kbd{gerepileupto}.

\fun{GEN}{ZX_rescale_lt}{GEN P} returns the monic integral polynomial
$h^{\deg(P)-1} P(x/h)$, where \kbd{P} is a non-zero \kbd{ZX} and \kbd{h} is
its leading coefficient. Neither memory-clean nor suitable for
\kbd{gerepileupto}.

\fun{GEN}{ZX_translate}{GEN P, GEN c} assume $P$ is a \kbd{ZX} and $c$ an
integer. Returns $P(X + c)$ (optimized for $c = \pm 1$).

\fun{GEN}{ZX_unscale}{GEN P, GEN h} given a \kbd{ZX} $P$ and a \typ{INT} $h$,
returns $P(hx)$. Not memory clean.

\fun{GEN}{ZX_unscale2n}{GEN P, long n} given a \kbd{ZX} $P$, returns
$P(x<<n)$. Not memory clean.

\fun{GEN}{ZX_unscale_div}{GEN P, GEN h} given a \kbd{ZX} $P$ and a \typ{INT} $h$
such that $h \mid P(0)$, returns $P(hx)/h$. Not memory clean.

\fun{GEN}{ZX_eval1}{GEN P} returns the integer $P(1)$.

\fun{GEN}{ZX_graeffe}{GEN p} returns the Graeffe transform of $p$, i.e. the
\kbd{ZX} $q$ such that $p(x)p(-x) = q(x^2)$.

\fun{GEN}{ZX_deriv}{GEN x} returns the derivative of \kbd{x}.

\fun{GEN}{ZX_resultant}{GEN A, GEN B} returns the resultant of the
\kbd{ZX}~\kbd{A} and \kbd{B}.

\fun{GEN}{ZX_disc}{GEN T} returns the discriminant of the \kbd{ZX}
\kbd{T}.

\fun{GEN}{ZX_factor}{GEN T} returns the factorization of the primitive part
of \kbd{T} over $\Q[X]$ (the content is lost).

\fun{int}{ZX_is_squarefree}{GEN T} returns $1$ if the
\kbd{ZX}~\kbd{T} is squarefree, $0$ otherwise.

\fun{long}{ZX_is_irred}{GEN T} returns 1 it \kbd{T} is irreducible, and
0 otherwise.

\fun{GEN}{ZX_squff}{GEN T, GEN *E} write $T$ as a product $\prod T_i^{e_i}$
with the $e_1 < e_2 < \cdots$ all distinct and the $T_i$ pairwise coprime.
Return the vector of the $T_i$, and set \kbd{*E} to the vector of the $e_i$,
as a \typ{VECSMALL}.

\fun{GEN}{ZX_Uspensky}{GEN P, GEN ab, long flag, long bitprec} let \kbd{P} be a
primitive \kbd{ZX} polynomial whose real roots are simple and \kbd{bitprec} is
the relative precision in bits.

\item If \kbd{flag} is 0 returns a list of intervals that isolate the real
roots of \kbd{P}. The return value is a column of elements which are either
vectors \kbd{[a,b]} meaning that there is a single root in the open interval
\kbd{(a,b)} or elements \kbd{x0} such that \kbd{x0} is a root of \kbd{P}.
There is no guarantee that all rational roots are found (at most those with
denominator a power of $2$ can be found and even those are not guaranteed).
Beware that the limits of the open intervals can be roots of the polynomial.

\item If \kbd{flag} is 1 returns an approximation of the real roots of \kbd{P}.

\item If \kbd{flag} is 2 returns the number of roots.

The argument \kbd{ab} specify the interval in which the roots
are searched. The default interval is $(-\infty,\infty)$. If \kbd{ab} is an
integer or fraction $a$ then the interval is $[a,\infty)$. If \kbd{ab} is
a vector $[a,b]$, where \typ{INT}, \typ{FRAC} or \typ{INFINITY} are allowed
for $a$ and $b$, the interval is $[a,b]$.

\fun{long}{ZX_sturm}{GEN P} number of real roots of the non-constant
squarefree \kbd{ZX} $P$. For efficiency, it is advised to make $P$ primitive
first.

\fun{long}{ZX_sturmpart}{GEN P, GEN ab} number of real roots of the
non-constant squarefree \kbd{ZX} $P$ in the interval specified by \kbd{ab}:
either \kbd{NULL} (no restriction) or a \typ{VEC} $[a,b]$ with two real
components (of type \typ{INT}, \typ{FRAC} or \typ{INFINITY}). For efficiency,
it is advised to make $P$ primitive first.

\subsec{\kbd{ZXQ}}

\fun{GEN}{ZXQ_mul}{GEN x,GEN y,GEN T} returns $x*y$ mod $T$, assuming
that all inputs are \kbd{ZX}s and that $T$ is monic.

\fun{GEN}{ZXQ_sqr}{GEN x,GEN T} returns $x^2$ mod $T$, assuming
that all inputs are \kbd{ZX}s and that $T$ is monic.

\fun{GEN}{ZXQ_charpoly}{GEN A, GEN T, long v}: let \kbd{T} and \kbd{A} be
\kbd{ZX}s, returns the characteristic polynomial of \kbd{Mod(A, T)}.
More generally, \kbd{A} is allowed to be a \kbd{QX}, hence possibly has
rational coefficients, \emph{assuming} the result is a \kbd{ZX}, i.e.~the
algebraic number \kbd{Mod(A,T)} is integral over \kbd{Z}.

\fun{GEN}{ZX_ZXY_resultant}{GEN A, GEN B}
under the assumption that \kbd{A} in $\Z[Y]$, \kbd{B} in $\Q[Y][X]$, and
$R = \text{Res}_Y(A, B) \in \Z[X]$, returns the resultant $R$.

\fun{GEN}{ZX_compositum_disjoint}{GEN A, GEN B} given two irreducible \kbd{ZX}
defining linearly disjoint extensions, returns a \kbd{ZX} defining their
compositum.

\fun{GEN}{ZX_ZXY_rnfequation}{GEN A, GEN B, long *lambda},
assume \kbd{A} in $\Z[Y]$, \kbd{B} in $\Q[Y][X]$, and $R =
\text{Res}_Y(A, B) \in \Z[X]$. If \kbd{lambda = NULL}, returns $R$
as in \kbd{ZY\_ZXY\_resultant}. Otherwise, \kbd{lambda} must point to
some integer, e.g. $0$ which is used as a seed. The function then finds a
small $\lambda \in \Z$ (starting from \kbd{*lambda}) such that
$R_\lambda(X) := \text{Res}_Y(A, B(X + \lambda Y))$ is squarefree, resets
\kbd{*lambda} to the chosen value and returns $R_{\lambda}$.

\subsec{\kbd{ZXV}}

\fun{GEN}{ZXV_equal}{GEN x,GEN y} returns $1$ if the two vectors of \kbd{ZX}
are equal, as per \tet{ZX_equal} (variables are not checked to be equal) and
$0$ otherwise.

\fun{GEN}{ZXV_Z_mul}{GEN x,GEN y} multiplies the vector of \kbd{ZX} \kbd{x}
by the integer \kbd{y}.

\fun{GEN}{ZXV_remi2n}{GEN x, long n} applies \kbd{ZX\_remi2n} to all
coefficients of \kbd{x}.

\fun{GEN}{ZXV_dotproduct}{GEN x,GEN y} as \kbd{RgV\_dotproduct} assuming $x$
and $y$ have \kbd{ZX} entries.

\subsec{\kbd{ZXT}}

\fun{GEN}{ZXT_remi2n}{GEN x, long n} applies \kbd{ZX\_remi2n} to all
leaves of the tree \kbd{x}.

\subsec{\kbd{ZXX}}

\fun{void}{RgX_check_ZXX}{GEN x, const char *s} Assuming \kbd{x} is a \typ{POL}
raise an error if it one of its coefficients is not an integer or a \kbd{ZX}
($s$ should point to the name of the caller).

\fun{GEN}{ZXX_renormalize}{GEN x, long l}, as \kbd{normalizepol}, where
$\kbd{l} = \kbd{lg(x)}$, in place.

\fun{long}{ZXX_max_lg}{GEN x} returns the effective length of the longest
component in $x$; assume all coefficients are \typ{INT} or \kbd{ZX}s.

\fun{GEN}{ZXX_Z_mul}{GEN x, GEN y} returns $x\*y$.

\fun{GEN}{ZXX_Z_add_shallow}{GEN x, GEN y} returns $x+y$. Shallow function.

\fun{GEN}{ZXX_Z_divexact}{GEN x, GEN y} returns $x/y$ assuming all integer
divisions are exact.

\fun{GEN}{ZXX_to_Kronecker}{GEN P, long n} Assuming $P(X,Y)$ is a polynomial
of degree in $X$ strictly less than $n$, returns $P(X,X^{2*n-1})$, the
Kronecker form of $P$. Shallow function.

\fun{GEN}{ZXX_to_Kronecker_spec}{GEN Q, long lQ, long n} return
\tet{ZXX_to_Kronecker}$(P, n)$, where $P$ is the polynomial
$\sum_{i = 0}^{\kbd{lQ} - 1} Q[i] x^i$. To be used when splitting
the coefficients of genuine polynomials into blocks. Shallow function.

\fun{GEN}{Kronecker_to_ZXX}{GEN z, long n, long v} recover $P(X,Y)$
from its Kronecker form $P(X,X^{2\*n-1})$, $v$ is the variable number
corresponding to $Y$. Shallow function.

\fun{GEN}{ZXX_mul_Kronecker}{GEN P, GEN Q, long n} return \tet{ZX_mul}
applied to the Kronecker forms $P(X,X^{2\*n-1})$ and $Q(X,X^{2\*n-1})$
of $P$ and $Q$. Not memory clean.

\fun{GEN}{ZXX_sqr_Kronecker}{GEN P, long n} return \tet{ZX_sqr}
applied to the Kronecker forms $P(X,X^{2\*n-1})$
of $P$. Not memory clean.

\subsec{\kbd{QX}}

\fun{void}{RgX_check_QX}{GEN x, const char *s} Assuming \kbd{x} is a \typ{POL}
raise an error if it is not a \kbd{QX} ($s$ should point to the name of the
caller).

\fun{GEN}{QX_gcd}{GEN x,GEN y} returns a gcd of the \kbd{QX} $x$ and $y$.

\fun{GEN}{QX_disc}{GEN T} returns the discriminant of the \kbd{QX}
\kbd{T}.

\fun{GEN}{QX_factor}{GEN T} as \kbd{ZX\_factor}.

\fun{GEN}{QX_resultant}{GEN A, GEN B} returns the resultant of the
\kbd{QX}~\kbd{A} and \kbd{B}.

\fun{GEN}{QX_complex_roots}{GEN p, long l} returns the complex roots of the
\kbd{QX} $p$ at accuracy $l$, where real roots are returned as \typ{REAL}s.
More efficient when $p$ is irreducible and primitive. Special case
of \tet{cleanroots}.

\subsec{\kbd{QXQ}}

\fun{GEN}{QXQ_norm}{GEN A, GEN B} $A$ being a \kbd{QX} and $B$ being a
\kbd{ZX}, returns the norm of the algebraic number $A \mod B$, using a
modular algorithm. To ensure that $B$ is a \kbd{ZX}, one may replace it by
\kbd{Q\_primpart(B)}, which of course does not change the norm.

If $A$ is not a \kbd{ZX} --- it has a denominator ---, but the result is
nevertheless known to be an integer, it is much more efficient to call
\tet{QXQ_intnorm} instead.

\fun{GEN}{QXQ_intnorm}{GEN A, GEN B} $A$ being a \kbd{QX} and $B$
being a \kbd{ZX}, returns the norm of the algebraic number $A \mod B$,
\emph{assuming} that the result is an integer, which is for instance the case
is $A\mod B$ is an algebraic integer, in particular if $A$ is a \kbd{ZX}. To
ensure that $B$ is a \kbd{ZX}, one may replace it by \kbd{Q\_primpart(B)}
(which of course does not change the norm).

If the result is not known to be an integer, you must use \tet{QXQ_norm}
instead, which is slower.

\fun{GEN}{QXQ_inv}{GEN A, GEN B} returns the inverse of $A$ modulo $B$
where $A$ is a \kbd{QX} and $B$ is a \kbd{ZX}. Should you need this for
a \kbd{QX} $B$, just use
\bprog
  QXQ_inv(A, Q_primpart(B));
@eprog\noindent But in all cases where modular arithmetic modulo $B$ is
desired, it is much more efficient to replace $B$ by \kbd{Q\_primpart$(B)$}
once and for all.

\fun{GEN}{QXQ_charpoly}{GEN A, GEN T, long v} where \kbd{A} is a \kbd{QX} and
\kbd{T} is a \kbd{ZX}, returns the characteristic polynomial of \kbd{Mod(A, T)}.
If the result is known to be a \kbd{ZX}, then calling \kbd{ZXQ\_charpoly} will
be faster.

\fun{GEN}{QXQ_powers}{GEN x, long n, GEN T} returns $[\kbd{x}^0, \dots,
\kbd{x}^\kbd{n}]$ as \kbd{RgXQ\_powers} would, but in a more efficient way when
$x$ has a huge integer denominator (we start by removing that denominator).
Meant to be used to precompute powers of algebraic integers in $\Q[t]/(T)$.
The current implementation does not require $x$ to be a \kbd{QX}: any
polynomial to which \kbd{Q\_remove\_denom} can be applied is fine.

\fun{GEN}{QXQ_reverse}{GEN f, GEN T} as \kbd{RgXQ\_reverse}, assuming $f$
is a \kbd{QX}.

\fun{GEN}{QX_ZXQV_eval}{GEN f, GEN nV, GEN dV} as \kbd{RgX\_RgXQV\_eval},
except that $f$ is assumed to be a \kbd{QX}, $V$ is given implicitly
by a numerator \kbd{nV} (\kbd{ZV}) and denominator \kbd{dV} (a positive
\typ{INT} or \kbd{NULL} for trivial denominator). Not memory clean, but
suitable for \kbd{gerepileupto}.

\fun{GEN}{QXV_QXQ_eval}{GEN v, GEN a, GEN T} $v$ is a vector of \kbd{QX}s
(possibly scalars, i.e.~rational numbers, for convenience), $a$ and $T$ both
\kbd{QX}. Return the vector of evaluations at $a$ modulo $T$.
Not memory clean, nor suitable for \kbd{gerepileupto}.

\fun{GEN}{QXX_QXQ_eval}{GEN P, GEN a, GEN T} $P(X,Y)$ is a \typ{POL} with
\kbd{QX} coefficients (possibly scalars, i.e.~rational numbers, for
convenience) , $a$ and $T$ both \kbd{QX}. Return the \kbd{QX} $P(X, a \mod
T)$. Not memory clean, nor suitable for \kbd{gerepileupto}.

\fun{GEN}{nfgcd}{GEN P, GEN Q, GEN T, GEN den} given $P$ and $Q$ in
$\Z[X,Y]$, $T$ monic irreducible in $\Z[Y]$, returns the primitive $d$ in
$\Z[X,Y]$ which is a gcd of $P$, $Q$ in $K[X]$, where $K$ is the number field
$\Q[Y]/(T)$. If not \kbd{NULL}, \kbd{den} is a multiple of the integral
denominator of the (monic) gcd of $P,Q$ in $K[X]$.

\fun{GEN}{nfgcd_all}{GEN P, GEN Q, GEN T, GEN den, GEN *Pnew} as \kbd{nfgcd}.
If \kbd{Pnew} is not \kbd{NULL}, set \kbd{*Pnew} to a non-zero integer
multiple of $P/d$. If $P$ and $Q$ are both monic, then $d$ is monic and
\kbd{*Pnew} is exactly $P/d$. Not memory clean if the gcd is $1$
(in that case \kbd{*Pnew} is set to $P$).

\subsec{\kbd{zx}}

\fun{GEN}{zero_zx}{long sv} returns a zero \kbd{zx} in variable $v$.

\fun{GEN}{polx_zx}{long sv} returns the variable $v$ as degree~1~\kbd{Flx}.

\fun{GEN}{zx_renormalize}{GEN x, long l}, as \kbd{Flx\_renormalize}, where
$\kbd{l} = \kbd{lg(x)}$, in place.

\fun{GEN}{zx_shift}{GEN T, long n} returns \kbd{T}
multiplied by $\kbd{x}^n$, assuming $n\geq 0$.

\subsec{\kbd{RgX}}

\subsubsec{Coefficient ring}

\fun{long}{RgX_type}{GEN x, GEN *ptp, GEN *ptpol, long *ptprec} returns
the ``natural'' base ring over which the polynomial $x$ is defined. Contrary
to what its name suggests, this function also works for scalar types,
\typ{SER} and \typ{MAT} $x$.

Raise an error if it detects consistency problems in modular objects:
incompatible rings (e.g. $\F_p$ and $\F_q$ for primes $p\neq q$,
$\F_p[X]/(T)$ and $\F_p[X]/(U)$ for $T\neq U$). Minor discrepancies are
supported if they make general sense (e.g. $\F_p$ and $\F_{p^k}$, but not
$\F_p$ and $\Q_p$); \typ{FFELT} and \typ{POLMOD} of \typ{INTMOD}s are
considered inconsistent, even if they define the same field: if you need to
use simultaneously these different finite field implementations, multiply the
polynomial by a \typ{FFELT} equal to $1$ first.

\item 0: none of the others (presumably multivariate, possibly inconsistent).

\item \typ{INT}: defined over $\Q$ (not necessarily $\Z$).

\item \typ{INTMOD}: defined over $\Z/p\Z$, where \kbd{*ptp} is set to $p$.
It is not checked whether $p$ is prime.

\item \typ{COMPLEX}: defined over $\C$ (at least one \typ{COMPLEX} with at
least one inexact floating point \typ{REAL} component). Set \kbd{*ptprec}
to the minimal accuracy (as per \kbd{precision}) of inexact components.

\item \typ{REAL}: defined over $\R$ (at least one inexact floating point
\typ{REAL} component). Set \kbd{*ptprec} to the minimal accuracy (as per
\kbd{precision}) of inexact components.

\item \typ{PADIC}: defined over $\Q_p$, where \kbd{*ptp} is set to $p$ and
\kbd{*ptprec} to the $p$-adic accuracy.

\item \typ{FFELT}: defined over a finite field $\F_{p^k}$, where \kbd{*ptp}
is set to the field characteristic $p$ and \kbd{*ptpol} is set to a
\typ{FFELT} belonging to the field.

\item other values are composite corresponding to quotients $R[X]/(T)$, with
one primary type \kbd{t1}, describing the form of the quotient,
and a secondary type \kbd{t2}, describing $R$. If \kbd{t} is the
\kbd{RgX\_type}, \kbd{t1} and \kbd{t2} are recovered using

\fun{void}{RgX_type_decode}{long t, long *t1, long *t2}

\kbd{t1} is one of

\typ{POLMOD}: at least one \typ{POLMOD} component,
set \kbd{*ppol} to the modulus,

\typ{QUAD}: no \typ{POLMOD}, at least one \typ{QUAD} component,
set \kbd{*ppol} to the modulus (\kbd{$-$.pol}) of the \typ{QUAD},

\typ{COMPLEX}: no \typ{POLMOD} or \typ{QUAD}, at least one \typ{COMPLEX}
component, set \kbd{*ppol} to $y^2 + 1$.

and the underlying base ring $R$ is given by \kbd{t2}, which
is one of \typ{INT}, \typ{INTMOD} (set \kbd{*ptp}) or \typ{PADIC}
(set \kbd{*ptp} and \kbd{*ptprec}), with the same meaning
as above.

\fun{int}{RgX_type_is_composite}{long t} $t$ as returned by \kbd{RgX\_type},
return 1 if $t$ is a composite type, and 0 otherwise.

\fun{GEN}{RgX_get_0}{GEN x} returns $0$ in the base ring over which $x$
is defined, to the proper accuracy (e.g. \kbd{0}, \kbd{Mod(0,3)},
\kbd{O(5\pow 10)}).

\fun{GEN}{RgX_get_1}{GEN x} returns $1$ in the base ring over which $x$
is defined, to the proper accuracy (e.g. \kbd{0}, \kbd{Mod(0,3)},

\subsubsec{Tests}

\fun{long}{RgX_degree}{GEN x, long v} $x$ being a \typ{POL} and $v \geq 0$,
returns the degree in $v$ of $x$. Error if $x$ is not a polynomial in $v$.

\fun{int}{RgX_isscalar}{GEN x} return 1 if $x$ all the coefficients of
$x$ of degree $> 0$ are $0$ (as per \kbd{gequal0}).

\fun{int}{RgX_is_rational}{GEN P} return 1 if the \kbd{RgX}~$P$ has only
rational coefficients (\typ{INT} and \typ{FRAC}), and 0 otherwise.

\fun{int}{RgX_is_QX}{GEN P} return 1 if the \kbd{RgX}~$P$ has only
\typ{INT} and \typ{FRAC} coefficients, and 0 otherwise.

\fun{int}{RgX_is_ZX}{GEN P} return 1 if the \kbd{RgX}~$P$ has only
\typ{INT} coefficients, and 0 otherwise.

\fun{int}{RgX_is_monomial}{GEN x} returns 1 (true) if \kbd{x} is a non-zero
monomial in its main variable, 0~otherwise.

\fun{long}{RgX_equal}{GEN x, GEN y} returns $1$ if the \typ{POL}s $x$ and $y$
have the same \kbd{degpol} and their coefficients are equal (as per
\tet{gequal}). Variable numbers are not checked. Note that this is more
stringent than \kbd{gequal(x,y)}, which only checks whether $x - y$ satisfies
\kbd{gequal0}; in particular, they may have different apparent degrees provided
the extra leading terms are $0$.

\fun{long}{RgX_equal_var}{GEN x, GEN y} returns $1$ if $x$ and $y$
have the same variable number and \kbd{RgX\_equal(x,y)} is $1$.

\subsubsec{Coefficients, blocks}

\fun{GEN}{RgX_coeff}{GEN P, long n} return the coefficient of $x^n$ in $P$,
defined as \kbd{gen\_0} if $n < 0$ or $n > \kbd{degpol}(P)$. Shallow
function.

\fun{int}{RgX_blocks}{GEN P, long n, long m} writes
$P(X)=a_0(X)+X^n*a_1(X)*X^n+\ldots+X^{n*(m-1)}\*a_{m-1}(X)$,
where the $a_i$ are polynomial of degree at most $n-1$
(except possibly for the last one) and returns
$[a_0(X),a_1(X),\ldots,a_{m-1}(X)]$.  Shallow function.

\fun{void}{RgX_even_odd}{GEN p, GEN *pe, GEN *po} write $p(X) = E(X^2) +
X O(X^2)$ and set \kbd{*pe = E}, \kbd{*po = O}.  Shallow function.

\fun{GEN}{RgX_splitting}{GEN P, long k} write
$P(X)=a_0(X^k)+X\*a_1(X^k)+\ldots+X^{k-1}\*a_{k-1}(X^k)$ and return
$[a_0(X),a_1(X),\ldots,a_{k-1}(X)]$.  Shallow function.

\fun{GEN}{RgX_copy}{GEN x} returns (a deep copy of) $\kbd{x}$.

\fun{GEN}{RgX_renormalize}{GEN x} remove leading terms in \kbd{x} which are
equal to (necessarily inexact) zeros.

\fun{GEN}{RgX_renormalize_lg}{GEN x, long lx} as \kbd{setlg(x, lx)}
followed by \kbd{RgX\_renormalize(x)}. Assumes that $\kbd{lx} \leq
\kbd{lg(x)}$.

\fun{GEN}{RgX_recip}{GEN P} returns the reverse of the polynomial
$P$, i.e. $X^{\deg P} P(1/X)$.

\fun{GEN}{RgX_recip_shallow}{GEN P} shallow function of \tet{RgX_recip}.

\fun{GEN}{RgX_deflate}{GEN P, long d} assuming $P$ is a polynomial of the
form $Q(X^d)$, return $Q$. Shallow function, not suitable for
\kbd{gerepileupto}.

\fun{long}{RgX_deflate_order}{GEN P} given a non-constant polynomial
$P$, returns the largest exponent $d$ such that $P$ is of the form $P(x^d)$
(use \kbd{gequal0} to check whether coefficients are 0).

\fun{long}{RgX_deflate_max}{GEN P, long *d} given a non-constant polynomial
$P$, sets \kbd{d} to \kbd{RgX\_deflate\_order(P)} and
returns \kbd{RgX\_deflate(P,d)}. Shallow function.

\fun{GEN}{RgX_inflate}{GEN P, long d} return $P(X^d)$. Shallow function, not
suitable for \kbd{gerepileupto}.

\subsubsec{Shifts, valuations}

\fun{GEN}{RgX_shift}{GEN x, long n} returns $\kbd{x} * t^n$ if $n\geq 0$,
and $\kbd{x} \bs t^{-n}$ otherwise.

\fun{GEN}{RgX_shift_shallow}{GEN x, long n} as \kbd{RgX\_shift}, but
shallow (coefficients are not copied).

\fun{GEN}{RgX_rotate_shallow}{GEN P, long k, long p} returns $\kbd{P} * X^k
\pmod {X^p-1}$, assuming the degree of $P$ is strictly less than $p$, and
$k\geq 0$.

\fun{void}{RgX_shift_inplace_init}{long v} $v \geq 0$, prepare for a later
call to \tet{RgX_shift_inplace}. Reserves $v$ words on the stack.

\fun{GEN}{RgX_shift_inplace}{GEN x, long v} $v \geq 0$, assume that
\tet{RgX_shift_inplace_init}$(v)$ has been called (reserving $v$ words on the
stack), immediately followed by a \typ{POL} $x$. Return \kbd{RgX\_shift}$(x,v)$
by shifting $x$ in place. To be used as follows
\bprog
  RgX_shift_inplace_init(v);
  av = avma;
  ...
  x = gerepileupto(av, ...); /* a t_POL */
  return RgX_shift_inplace(x, v);
@eprog

\fun{long}{RgX_valrem}{GEN P, GEN *pz} returns the valuation $v$ of the
\typ{POL}~\kbd{P} with respect to its main variable $X$. Check whether
coefficients are $0$ using \kbd{gequal0}. Set \kbd{*pz} to
$\kbd{RgX\_shift\_shallow}(P,-v)$.

\fun{long}{RgX_val}{GEN P} returns the valuation $v$ of the
\typ{POL}~\kbd{P} with respect to its main variable $X$. Check whether
coefficients are $0$ using \kbd{gequal0}.

\fun{long}{RgX_valrem_inexact}{GEN P, GEN *z} as \kbd{RgX\_valrem}, using
\kbd{isexactzero} instead of \kbd{gequal0}.

\subsubsec{Basic arithmetic}

\fun{GEN}{RgX_add}{GEN x,GEN y} adds \kbd{x} and \kbd{y}.

\fun{GEN}{RgX_sub}{GEN x,GEN y} subtracts \kbd{x} and \kbd{y}.

\fun{GEN}{RgX_neg}{GEN x} returns $-\kbd{x}$.

\fun{GEN}{RgX_Rg_add}{GEN y, GEN x} returns $x+y$.

\fun{GEN}{RgX_Rg_add_shallow}{GEN y, GEN x} returns $x+y$; shallow function.

\fun{GEN}{Rg_RgX_sub}{GEN x, GEN y}

\fun{GEN}{RgX_Rg_sub}{GEN y, GEN x} returns $x-y$

\fun{GEN}{RgX_Rg_mul}{GEN y, GEN x} multiplies the \kbd{RgX} \kbd{y}
by the scalar \kbd{x}.

\fun{GEN}{RgX_muls}{GEN y, long s} multiplies the \kbd{RgX} \kbd{y}
by the \kbd{long}~\kbd{s}.

\fun{GEN}{RgX_Rg_div}{GEN y, GEN x} divides the \kbd{RgX} \kbd{y}
by the scalar \kbd{x}.

\fun{GEN}{RgX_divs}{GEN y, long s} divides the \kbd{RgX} \kbd{y}
by the \kbd{long}~\kbd{s}.

\fun{GEN}{RgX_Rg_divexact}{GEN x, GEN y} exact division of the \kbd{RgX}
\kbd{y} by the scalar \kbd{x}.

\fun{GEN}{RgX_Rg_eval_bk}{GEN f, GEN x} returns $\kbd{f}(\kbd{x})$ using
Brent and Kung algorithm. (Use \tet{poleval} for Horner algorithm.)

\fun{GEN}{RgX_RgV_eval}{GEN f, GEN V} as \kbd{RgX\_Rg\_eval\_bk(f, x)},
assuming $V$ was output by \kbd{gpowers(x, n)} for some $n\geq 1$.

\fun{GEN}{RgXV_RgV_eval}{GEN f, GEN V} apply \kbd{RgX\_RgV\_eval\_bk(, V)}
to all the components of the vector $f$.

\fun{GEN}{RgX_normalize}{GEN x} divides $x$ by its
leading coefficient. If the latter is~$1$, $x$ itself is returned, not a
copy. Leading coefficients equal to $0$ are stripped, e.g.
\bprog
  0.*t^3 + Mod(0,3)*t^2 + 2*t
@eprog\noindent is normalized to $t$.

\fun{GEN}{RgX_mul}{GEN x, GEN y} multiplies the two \typ{POL} (in the same
variable) \kbd{x} and \kbd{y}. Uses Karatsuba algorithm.

\fun{GEN}{RgX_mul_normalized}{GEN A, long a, GEN B, long b}
returns $(X^a + A)(X^b + B) - X^(a+b)$, where we assume that $\deg A < a$
and $\deg B < b$ are polynomials in the same variable $X$.

\fun{GEN}{RgX_mulspec}{GEN a, GEN b, long na, long nb}. Internal routine:
\kbd{a} and \kbd{b} are arrays of coefficients representing polynomials
$\sum_{i = 0}^{\kbd{na-1}} \kbd{a}[i] X^i$ and
$\sum_{i = 0}^{\kbd{nb-1}} \kbd{b}[i] X^i$. Returns their product (as a true
\kbd{GEN}).

\fun{GEN}{RgX_sqr}{GEN x} squares the \typ{POL} \kbd{x}. Uses Karatsuba
algorithm.

\fun{GEN}{RgX_sqrspec}{GEN a, long na}. Internal routine:
\kbd{a} is an array of coefficients representing polynomial
$\sum_{i = 0}^{\kbd{na-1}} \kbd{a}[i] X^i$. Return its square (as a true
\kbd{GEN}).

\fun{GEN}{RgX_divrem}{GEN x, GEN y, GEN *r} by default, returns the Euclidean
quotient and store the remainder in $r$. Three special values of $r$ change
that behavior
\item \kbd{NULL}: do not store the remainder, used to implement \kbd{RgX\_div},

\item \tet{ONLY_REM}: return the remainder, used to implement \kbd{RgX\_rem},

\item \tet{ONLY_DIVIDES}: return the quotient if the division is exact, and
\kbd{NULL} otherwise.

\fun{GEN}{RgX_div}{GEN x, GEN y}

\fun{GEN}{RgX_div_by_X_x}{GEN A, GEN a, GEN *r} returns the
quotient of the \kbd{RgX}~\kbd{A} by $(X - \kbd{a})$, and sets \kbd{r} to the
remainder $\kbd{A}(\kbd{a})$.

\fun{GEN}{RgX_rem}{GEN x, GEN y}

\fun{GEN}{RgX_pseudodivrem}{GEN x, GEN y, GEN *ptr} compute a pseudo-quotient
$q$ and pseudo-remainder $r$ such that $\kbd{lc}(y)^{\deg(x) - \deg(y) + 1}x
= qy + r$. Return $q$ and set \kbd{*ptr} to $r$.

\fun{GEN}{RgX_pseudorem}{GEN x, GEN y} return the remainder
in the pseudo-division of $x$ by $y$.

\fun{GEN}{RgXQX_pseudorem}{GEN x, GEN y, GEN T} return the remainder
in the pseudo-division of $x$ by $y$ over $R[X]/(T)$.

\fun{int}{ZXQX_dvd}{GEN x, GEN y, GEN T} let $T$ be a monic irreducible
\kbd{ZX}, let $x, y$ be \typ{POL} whose coefficients are either \typ{INT}s or
\kbd{ZX} in the same variable as $T$. Assume further that the leading
coefficient of $y$ is an integer. Return $1$ if $y | x$ in $(\Z[Y]/(T))[X]$,
and $0$ otherwise.

\fun{GEN}{RgXQX_pseudodivrem}{GEN x, GEN y, GEN T, GEN *ptr} compute
a pseudo-quotient $q$ and pseudo-remainder $r$ such that
$\kbd{lc}(y)^{\deg(x) - \deg(y) + 1}x = qy + r$ in $R[X]/(T)$. Return $q$ and
set \kbd{*ptr} to $r$.

\fun{GEN}{RgX_mulXn}{GEN x, long n} returns $\kbd{x} * t^n$. This may
be a \typ{FRAC} if $n < 0$ and the valuation of \kbd{x} is not large
enough.

\subsubsec{GCD, Resultant}

\fun{GEN}{RgX_gcd}{GEN x, GEN y} returns the GCD of \kbd{x} and \kbd{y},
assumed to be \typ{POL}s in the same variable.

\fun{GEN}{RgX_gcd_simple}{GEN x, GEN y} as \tet{RgX_gcd} using a standard
extended Euclidean algorithm. Usually slower than \tet{RgX_gcd}.

\fun{GEN}{RgX_extgcd}{GEN x, GEN y, GEN *u, GEN *v} returns
$d = \text{GCD}(\kbd{x},\kbd{y})$, and sets \kbd{*u}, \kbd{*v} to the Bezout
coefficients such that $\kbd{*ux} + \kbd{*vy} = d$. Uses a generic
subresultant algorithm.

\fun{GEN}{RgX_extgcd_simple}{GEN x, GEN y, GEN *u, GEN *v} as
\tet{RgX_extgcd} using a standard extended Euclidean algorithm. Usually
slower than \tet{RgX_extgcd}.

\fun{GEN}{RgX_disc}{GEN x} returns the discriminant of the \typ{POL} \kbd{x}
with respect to its main variable.

\fun{GEN}{RgX_resultant_all}{GEN x, GEN y, GEN *sol} returns
\kbd{resultant(x,y)}. If \kbd{sol} is not \kbd{NULL}, sets it to the last
non-constant remainder in the polynomial remainder sequence if it exists and to
\kbd{gen\_0} otherwise (e.g. one polynomial has degree 0). Compared to
\kbd{resultant\_all}, this function always uses the generic subresultant
algorithm, hence always computes \kbd{sol}.

\subsubsec{Other operations}

\fun{GEN}{RgX_gtofp}{GEN x, GEN prec} returns the polynomial obtained by
applying
\bprog
  gtofp(gel(x,i), prec)
@eprog\noindent to all coefficients of $x$.

\fun{GEN}{RgX_fpnorml2}{GEN x, long prec} returns (a stack-clean variant of)
\bprog
  gnorml2( RgX_gtofp(x, prec) )
@eprog

\fun{GEN}{RgX_deriv}{GEN x} returns the derivative of \kbd{x} with respect to
its main variable.

\fun{GEN}{RgX_integ}{GEN x} returns the primitive of \kbd{x} vanishing at
$0$, with respect to its main variable.

\fun{GEN}{RgX_rescale}{GEN P, GEN h} returns $h^{\deg(P)} P(x/h)$.
\kbd{P} is an \kbd{RgX} and \kbd{h} is non-zero. (Leaves small objects on the
stack. Suitable but inefficient for \kbd{gerepileupto}.)

\fun{GEN}{RgX_unscale}{GEN P, GEN h} returns $P(h x)$. (Leaves small objects
on the stack. Suitable but inefficient for \kbd{gerepileupto}.)

\fun{GEN}{RgXV_unscale}{GEN v, GEN h} apply \kbd{RgX\_unscale} to a vector
of \kbd{RgX}.

\fun{GEN}{RgX_translate}{GEN P, GEN c} assume $c$ is a scalar or
a polynomials whose main variable has lower priority than the main variable
$X$ of $P$. Returns $P(X + c)$ (optimized for $c = \pm 1$).

\subsubsec{Function related to modular forms}

\fun{GEN}{RgX_act_Gl2Q}{GEN g, long k} let $R$ be a commutative ring
and $g = [a,b;c,d]$ be in $\text{GL}_2(\Q)$, $g$ acts (on the left)
on homogeneous polynomials of degree $k-2$ in $V := R[X,Y]_{k-2}$ via
$$ g\cdot P := P(dX-cY, -bX+aY) = (\det g)^{k-2} P((X,Y)\cdot g^{-1}).$$
This function returns the matrix in $M_{k-1}(R)$ of $P\mapsto g\cdot P$ in
the basis $(X^{k-2},\dots,Y^{k-2})$ of $V$.

\fun{GEN}{RgX_act_ZGl2Q}{GEN z, long k} let $G:=\text{GL}_2(\Q)$, acting
on $R[X,Y]_{k-2}$ and $z\in \Z[G]$. Return the matrix giving
$P\mapsto z\cdot P$ in the basis $(X^{k-2},\dots,Y^{k-2})$.

\subsec{\kbd{RgXn}}

\fun{GEN}{RgXn_red_shallow}{GEN x, long n} return $\kbd{x \% } t^n$,
where $n\geq 0$. Shallow function.

\fun{GEN}{RgXn_mul}{GEN a, GEN b, long n} returns $a b$ modulo $X^n$,
where $a,b$ are two \typ{POL} in the same variable $X$ and $n \geq 0$. Uses
Karatsuba algorithm (Mulders, Hanrot-Zimmermann variant).

\fun{GEN}{RgXn_sqr}{GEN a, long n} returns $a^2$ modulo $X^n$,
where $a$ is a \typ{POL} in the variable $X$ and $n \geq 0$. Uses
Karatsuba algorithm (Mulders, Hanrot-Zimmermann variant).

\fun{GEN}{RgXn_inv}{GEN a, long n} returns $a^{-1}$ modulo $X^n$,
where $a$ is a \typ{POL} in the variable $X$ and $n \geq 0$. Uses
Newton-Raphson algorithm.

\fun{GEN}{RgXn_powers}{GEN x, long m, long n} returns $[\kbd{x}^0,
\dots, \kbd{x}^\kbd{m}]$ modulo $X^n$ as a \typ{VEC} of \kbd{RgXn}s.

\fun{GEN}{RgXn_powu}{GEN x, ulong m, long n} returns $x^m$ modulo
$X^n$.

\fun{GEN}{RgXn_powu_i}{GEN x, ulong m, long n} as \tet{RgXn_powu},
not memory clean.

\fun{GEN}{RgXn_exp}{GEN a, long n} returns $exp(a)$ modulo $X^n$, assuming
$a = 0 \mod{X}$. Uses Hanrot-Zimmermann algorithm.

\fun{GEN}{RgXn_eval}{GEN Q, GEN x, long n} special case of
\tet{RgX_RgXQ_eval}, when the modulus is a monomial:
returns $\kbd{Q}(\kbd{x})$ modulo $t^n$, where $x \in R[t]$.

\fun{GEN}{RgX_RgXn_eval}{GEN f, GEN x, long n} returns $\kbd{f}(\kbd{x})$ modulo
$X^n$.

\fun{GEN}{RgX_RgXnV_eval}{GEN f, GEN V, long n} as \kbd{RgX\_RgXn\_eval(f, x, n)},
assuming $V$ was output by \kbd{RgXn\_powers(x, m, n)} for some $m\geq 1$.

\fun{GEN}{RgXn_reverse}{GEN f, GEN n} assuming that $f = a\*x \mod{x^2}$
with $a$ invertible, returns a \typ{POL} $g$ of degree $< n$ such that $(g
\circ f)(x) = x$ modulo $x^n$.

\subsec{\kbd{RgXnV}}

\fun{GEN}{RgXnV_red_shallow}{GEN x, long n} apply \kbd{RgXn\_red\_shallow}
to all the components of the vector $x$.

\subsec{\kbd{RgXQ}}

\fun{GEN}{RgXQ_mul}{GEN y, GEN x, GEN T} computes $xy$ mod $T$

\fun{GEN}{RgXQ_sqr}{GEN x, GEN T} computes $x^2$ mod $T$

\fun{GEN}{RgXQ_inv}{GEN x, GEN T} return the inverse of $x$ mod $T$.

\fun{GEN}{RgXQ_pow}{GEN x, GEN n, GEN T} computes $x^n$ mod $T$

\fun{GEN}{RgXQ_powu}{GEN x, ulong n, GEN T} computes $x^n$ mod $T$,
$n$ being an \kbd{ulong}.

\fun{GEN}{RgXQ_powers}{GEN x, long n, GEN T} returns $[\kbd{x}^0,
\dots, \kbd{x}^\kbd{n}]$ as a \typ{VEC} of \kbd{RgXQ}s.

\fun{GEN}{RgXQ_matrix_pow}{GEN y, long n, long m, GEN P} returns
\kbd{RgXQ\_powers(y,m-1,P)}, as a matrix of dimension $n \geq \deg P$.

\fun{GEN}{RgXQ_norm}{GEN x, GEN T} returns the norm of \kbd{Mod(x, T)}.

\fun{GEN}{RgXQ_charpoly}{GEN x, GEN T, long v} returns the characteristic
polynomial of \kbd{Mod(x, T)}, in variable $v$.

\fun{GEN}{RgX_RgXQ_eval}{GEN f, GEN x, GEN T} returns $\kbd{f}(\kbd{x})$ modulo
$T$.

\fun{GEN}{RgX_RgXQV_eval}{GEN f, GEN V, GEN T} as \kbd{RgX\_RgXQ\_eval(f, x, T)},
assuming $V$ was output by \kbd{RgXQ\_powers(x, n, T)} for some $n\geq 1$.

\fun{int}{RgXQ_ratlift}{GEN x, GEN T, long amax, long bmax, GEN *P, GEN *Q}
Assuming that $\kbd{amax}+\kbd{bmax}<\deg T$, attempts to recognize $x$ as a
rational function $a/b$, i.e. to find \typ{POL}s $P$ and $Q$ such that

\item $P \equiv Q x$ modulo $T$,

\item $\deg P \leq \kbd{amax}$, $\deg Q \leq \kbd{bmax}$,

\item $\gcd(T,P) = \gcd(P,Q)$.

\noindent If unsuccessful, the routine returns $0$ and leaves $P$, $Q$
unchanged; otherwise it returns $1$ and sets $P$ and $Q$.

\fun{GEN}{RgXQ_reverse}{GEN f, GEN T} returns a \typ{POL} $g$ of degree $< n
= \text{deg}~T$ such that $T(x)$ divides $(g \circ f)(x) - x$, by solving a
linear system. Low-level function underlying \tet{modreverse}: it returns a
lift of \kbd[modreverse(f,T)]; faster than the high-level function since it
needs not compute the characteristic polynomial of $f$ mod $T$ (often already
known in applications). In the trivial case where $n \leq 1$, returns a
scalar, not a constant \typ{POL}.

\subsec{\kbd{RgXQV, RgXQC}}

\fun{GEN}{RgXQC_red}{GEN z, GEN T} \kbd{z} a vector whose
coefficients are \kbd{RgX}s (arbitrary \kbd{GEN}s in fact), reduce them to
\kbd{RgXQ}s (applying \kbd{grem} coefficientwise) in a \typ{COL}.

\fun{GEN}{RgXQV_red}{GEN z, GEN T} \kbd{z} a \typ{POL} whose
coefficients are \kbd{RgX}s (arbitrary \kbd{GEN}s in fact), reduce them to
\kbd{RgXQ}s (applying \kbd{grem} coefficientwise) in a \typ{VEC}.

\fun{GEN}{RgXQV_RgXQ_mul}{GEN z, GEN x, GEN T} \kbd{z} multiplies the
 \kbd{RgXQV} \kbd{z} by the scalar (\kbd{RgXQ}) \kbd{x}.

\subsec{\kbd{RgXQX}}

\fun{GEN}{RgXQX_red}{GEN z, GEN T} \kbd{z} a \typ{POL} whose
coefficients are \kbd{RgX}s (arbitrary \kbd{GEN}s in fact), reduce them to
\kbd{RgXQ}s (applying \kbd{grem} coefficientwise).

\fun{GEN}{RgXQX_mul}{GEN x, GEN y, GEN T}

\fun{GEN}{RgXQX_RgXQ_mul}{GEN x, GEN y, GEN T} multiplies the \kbd{RgXQX}
\kbd{y} by the scalar (\kbd{RgXQ}) \kbd{x}.

\fun{GEN}{RgXQX_sqr}{GEN x, GEN T}

\fun{GEN}{RgXQX_divrem}{GEN x, GEN y, GEN T, GEN *pr}

\fun{GEN}{RgXQX_div}{GEN x, GEN y, GEN T, GEN *r}

\fun{GEN}{RgXQX_rem}{GEN x, GEN y, GEN T, GEN *r}

\fun{GEN}{RgXQX_translate}{GEN P, GEN c, GEN T} assume the main variable
$X$ of $P$ has higher priority than the main variable $Y$ of $T$ and $c$.
Return a lift of $P(X+\text{Mod}(c(Y), T(Y)))$.

\fun{GEN}{Kronecker_to_mod}{GEN z, GEN T} $z\in R[X]$ represents an element
$P(X,Y)$ in $R[X,Y]$ mod $T(Y)$ in Kronecker form, i.e. $z = P(X,X^{2*n-1})$

Let $R$ be some commutative ring, $n = \deg T$ and let $P(X,Y)\in R[X,Y]$ lift
a polynomial in $K[Y]$, where $K := R[X]/(T)$ and $\deg_X P < 2n-1$ --- such as
would result from multiplying minimal degree lifts of two polynomials in
$K[Y]$. Let $z = P(t,t^{2*n-1})$ be a Kronecker form of $P$, this function
returns the image of $P(X,t)$ in $K[t]$, with \typ{POLMOD} coefficients.
Not stack-clean. Note that $t$ need not be the same variable as $Y$!

\chapter{Black box algebraic structures}

The generic routines like \kbd{gmul} or \kbd{gadd} allow handling objects
belonging to a fixed list of basic types, with some natural polymorphism
(you can mix rational numbers and polynomials, etc.), at the expense of
efficiency and sometimes of clarity when the recursive structure becomes
complicated, e.g. a few levels of \typ{POLMOD}s attached to different
polynomials and variable numbers for quotient structures. This
is the only possibility in GP.

On the other hand, the Level 2 Kernel allows dedicated routines to handle
efficiently objects of a very specific type, e.g. polynomials with
coefficients in the same finite field. This is more efficient, but imvolves a
lot of code duplication since polymorphism is no longer possible.

A third and final option, still restricted to library programming, is to
define an arbitrary algebraic structure (currently groups, fields, rings,
algebras and $\Z_p$-modules) by providing suitable methods, then using generic
algorithms. For instance naive Gaussian pivoting applies over all base fields
and need only be implemented once. The difference with the first solution
is that we no longer depend on the way functions like \kbd{gmul} or
\kbd{gadd} will guess what the user is trying to do. We can then implement
independently various groups / fields / algebras in a clean way.

\section{Black box groups}

A black box group is defined by a \tet{bb_group} struct, describing methods
available to handle group elements:
\bprog
    struct bb_group
    {
      GEN (*mul)(void*, GEN, GEN);
      GEN (*pow)(void*, GEN, GEN);
      GEN (*rand)(void*);
      ulong (*hash)(GEN);
      int (*equal)(GEN, GEN);
      int (*equal1)(GEN);
      GEN (*easylog)(void *E, GEN, GEN, GEN);
    };
@eprog
\kbd{mul(E,x,y)} returns the product $x\*y$.

\kbd{pow(E,x,n)} returns $x^n$ ($n$ integer, possibly negative or zero).

\kbd{rand(E)} returns a random element in the group.

\kbd{hash(x)} returns a hash value for $x$ (\kbd{hash\_GEN} is suitable for this field).

\kbd{equal(x,y)} returns one if $x=y$ and zero otherwise.

\kbd{equal1(x)} returns one if $x$ is the neutral element in the group,
and zero otherwise.

\kbd{easylog(E,a,g,o)} (optional) returns either NULL or the discrete logarithm
$n$ such that $g^n=a$, the element $g$ being of order $o$. This provides a
short-cut in situation where a better algorithm than the generic one is known.

A group is thus described by a \kbd{struct bb\_group} as above and auxiliary
data typecast to \kbd{void*}. The following functions operate on black box
groups:

\fun{GEN}{gen_Shanks_log}{GEN x, GEN g, GEN N, void *E, const struct bb_group
*grp} \hbadness 10000\break
Generic baby-step/giant-step algorithm (Shanks's method). Assuming
that $g$ has order $N$, compute an integer $k$ such that $g^k = x$.
Return \kbd{cgetg(1, t\_VEC)} if there are no solutions. This requires
$O(\sqrt{N})$ group operations and uses an auxiliary table containing
$O(\sqrt{N})$ group elements.

The above is useful for a one-shot computation. If many discrete logs
are desired:
\fun{GEN}{gen_Shanks_init}{GEN g, long n, void *E, const struct bb_group *grp}
return an auxiliary data structure $T$ required to compute a discrete log in
base $g$. Compute and store all powers $g^i$,  $i < n$.

\fun{GEN}{gen_Shanks}{GEN T, GEN x, ulong N, void *E, const struct bb_group *grp}
Let $T$ be computed by \tet{gen_Shanks_init}$(g,n,\dots)$.
Return $k < n N$ such that  $g^k = x$ or \kbd{NULL} if no such index exist.
It uses $O(N)$ operation in the group and fast table lookups  (in time
$O(\log n)$). The interface is such that the function may be used when the
order of the base $g$ is unknown, and hence compute it given only an upper
bound $B$ for it: e.g. choose $n,N$ such that $nN \geq B$ and compute the
discrete log $l$ of $g^{-1}$ in base $g$, then use \tet{gen_order}
with multiple $N = l+1$.

\fun{GEN}{gen_Pollard_log}{GEN x, GEN g, GEN N, void *E, const struct bb_group
*grp} \hbadness 10000\break
Generic Pollard rho algorithm. Assuming that $g$ has order $N$, compute an
integer $k$ such that $g^k = x$. This requires $O(\sqrt{N})$ group operations
in average and $O(1)$ storage. Will enter an infinite loop if there are no
solutions.

\fun{GEN}{gen_plog}{GEN x, GEN g, GEN N, void *E, const struct bb_group}
Assuming that $g$ has prime order $N$, compute an integer $k$ such that
$g^k = x$, using either \kbd{gen\_Shanks\_log} or \kbd{gen\_Pollard\_log}.
Return \kbd{cgetg(1, t\_VEC)} if there are no solutions.

\fun{GEN}{gen_Shanks_sqrtn}{GEN a, GEN n, GEN N, GEN *zetan, void *E, const
struct bb_group *grp} \hbadness 10000 returns one solution of $x^n = a$ in a
black box cyclic group of order $N$. Return \kbd{NULL} if no solution exists.
If \kbd{zetan} is not \kbd{NULL} it is set to an element of exact order $n$.
This function uses \kbd{gen\_plog} for all prime divisors of $\gcd(n,N)$.

\fun{GEN}{gen_PH_log}{GEN a, GEN g, GEN N, void *E, const struct bb_group
*grp}
returns an integer $k$ such that $g^k = x$, assuming that $g$ has order $N$,
by Pohlig-Hellman algorithm. Return \kbd{cgetg(1, t\_VEC)} if there are no
solutions. This calls \tet{gen_plog} repeatedly for all prime divisors $p$ of
$N$.

In the following functions the integer parameter \kbd{ord} can be given
in all the formats recognized for the argument of arithmetic functions,
i.e.~either as a positive \typ{INT} $N$, or as its factorization matrix
$\var{faN}$, or (preferred) as a pair $[N,\var{faN}]$.

\fun{GEN}{gen_order}{GEN x, GEN ord, void *E, const struct bb_group *grp}
computes the order of $x$; \kbd{ord} is a multiple of the order, for instance
the group order.

\fun{GEN}{gen_factored_order}{GEN x, GEN ord, void *E, const struct bb_group
*grp} returns a pair $[o,F]$, where $o$ is the order of $x$ and $F$ is the
factorization of $o$; \kbd{ord} is as in \tet{gen_order}.

\fun{GEN}{gen_gener}{GEN ord, void *E, const struct bb_group *grp}
returns a random generator of the group, assuming it is of order exactly
\kbd{ord}.

\fun{GEN}{get_arith_Z}{GEN ord} given \kbd{ord} as above in one of the
formats recognized for arithmetic functions, i.e. a positive
\typ{INT} $N$, its factorization \var{faN}, or the pair $[N, \var{faN}]$,
return $N$.

\fun{GEN}{get_arith_ZZM}{GEN ord} given \kbd{ord} as above,
return the pair $[N, \var{faN}]$. This may require factoring $N$.

\fun{GEN}{gen_select_order}{GEN v, void *E, const struct bb_group *grp}
Let $v$ be a vector of possible orders for the group; try to find the true
order by checking orders of random points. This will not terminate if there
is an ambiguity.

\subsec{Black box groups with pairing}

Theses functions handle groups of rank at most $2$ equipped with a family of
bilinear pairings which behave like the Weil pairing on elliptic curves over
finite field. In the descriptions below, the function \kbd{pairorder(E, P, Q,
m, F)} must return the order of the $m$-pairing of $P$ and $Q$, both of order
dividing $m$, where $F$ is the factorisation matrix of a multiple of $m$.

\fun{GEN}{gen_ellgroup}{GEN o, GEN d, GEN *pt_m, void *E, const struct bb_group *grp,
             GEN pairorder(void *E, GEN P, GEN Q, GEN m, GEN F)}
returns the elementary divisors $[d_1, d_2]$ of the group, assuming it is of
order exactly $o>1$ (which can be given by a factorization matrix), and that
$d_2$ divides $d$. If $d_2=1$ then $[o]$ is returned, otherwise
\kbd{m=*pt\_m} is set to the order of the pairing required to verify a
generating set which is to be used with \kbd{gen\_ellgens}.

\fun{GEN}{gen_ellgens}{GEN d1, GEN d2, GEN m, void *E, const struct bb_group *grp,
             GEN pairorder(void *E, GEN P, GEN Q, GEN m, GEN F)}
the parameters $d_1$, $d_2$, $m$ being as returned by \kbd{gen\_ellgroup},
returns a pair of generators $[P,Q]$ such that $P$ is of order $d_1$ and the
$m$-pairing of $P$ and $Q$ is of order $m$. (Note: $Q$ needs not be of order
$d_2$).

\subsec{Functions returning black box groups}

\fun{const struct bb_group *}{get_Flxq_star}{void **E, GEN T, ulong p}

\fun{const struct bb_group *}{get_FpXQ_star}{void **E, GEN T, GEN p}
returns a pointer to the black box group $(\F_p[x]/(T))^*$.

\fun{const struct bb_group *}{get_FpE_group}{void **pE, GEN a4, GEN a6, GEN p}
returns a pointer to a black box group and set \kbd{*pE} to the necessary data for
computing in the group $E(\F_p)$ where $E$ is the elliptic curve $E:y^2=x^3+a_4\*x+a_6$,
with $a_4$ and $a_6$ in $\F_p$.

\fun{const struct bb_group *}{get_FpXQE_group}{void **pE, GEN a4, GEN a6, GEN T, GEN p}
returns a pointer to a black box group and set \kbd{*pE} to the necessary data for
computing in the group $E(\F_p[X]/(T))$ where $E$ is the elliptic curve $E:y^2=x^3+a_4\*x+a_6$,
with $a_4$ and $a_6$ in $\F_p[X]/(T)$.

\fun{const struct bb_group *}{get_FlxqE_group}{void **pE, GEN a4, GEN a6, GEN
T, ulong p} idem for small $p$.

\fun{const struct bb_group *}{get_F2xqE_group}{void **pE, GEN a2, GEN a6, GEN T}
idem for $p=2$.

\section{Black box finite fields}

A black box finite field is defined by a \tet{bb_field} struct, describing methods
available to handle field elements:
\bprog
  struct bb_field
  {
    GEN (*red)(void *E ,GEN);
    GEN (*add)(void *E ,GEN, GEN);
    GEN (*mul)(void *E ,GEN, GEN);
    GEN (*neg)(void *E ,GEN);
    GEN (*inv)(void *E ,GEN);
    int (*equal0)(GEN);
    GEN (*s)(void *E, long);
  };
@eprog\noindent In contrast of black box group, elements can have
non canonical forms, and only \kbd{red} is required to return a canonical form.

\kbd{red(E,x)} returns the canonical form of $x$.

\kbd{add(E,x,y)} returns the sum $x+y$.

\kbd{mul(E,x,y)} returns the product $x\*y$.

\kbd{neg(E,x)} returns $-x$.

\kbd{inv(E,x)} returns the inverse of $x$.

\kbd{equal0(x)} $x$ being in canonical form, returns one if $x=0$ and zero otherwise.

\kbd{s(n)} $n$ being a small signed integer, returns $n$ times the unit element.

\noindent A finite field is thus described by a \kbd{struct bb\_field} as
above and auxiliary data typecast to \kbd{void*}. The following functions
operate on black box fields:

\fun{GEN}{gen_Gauss}{GEN a, GEN b, void *E, const struct bb_field *ff}

\fun{GEN}{gen_Gauss_pivot}{GEN x, long *rr, void *E, const struct bb_field *ff}

\fun{GEN}{gen_det}{GEN a, void *E, const struct bb_field *ff}

\fun{GEN}{gen_ker}{GEN x, long deplin, void *E, const struct bb_field *ff}

\fun{GEN}{gen_matcolmul}{GEN a, GEN b, void *E, const struct bb_field *ff}

\fun{GEN}{gen_matid}{long n, void *E, const struct bb_field *ff}

\fun{GEN}{gen_matmul}{GEN a, GEN b, void *E, const struct bb_field *ff}

\subsec{Functions returning black box fields}

\fun{const struct bb_field *}{get_Fp_field}{void **pE, GEN p}

\fun{const struct bb_field *}{get_Fq_field}{void **pE, GEN T, GEN p}

\fun{const struct bb_field *}{get_Flxq_field}{void **pE, GEN T, ulong p}

\fun{const struct bb_field *}{get_F2xq_field}{void **pE, GEN T}

\fun{const struct bb_field *}{get_nf_field}{void **pE, GEN nf}

\section{Black box algebra}

A black box algebra is defined by a \tet{bb_algebra} struct, describing methods
available to handle algebra elements:
\bprog
struct bb_algebra
{
  GEN (*red)(void *E, GEN x);
  GEN (*add)(void *E, GEN x, GEN y);
  GEN (*sub)(void *E, GEN x, GEN y);
  GEN (*mul)(void *E, GEN x, GEN y);
  GEN (*sqr)(void *E, GEN x);
  GEN (*one)(void *E);
  GEN (*zero)(void *E);
};
@eprog\noindent In contrast with black box groups, elements can have non
canonical forms, but only \kbd{add} is allowed to return a non canonical
form.

\kbd{red(E,x)} returns the canonical form of $x$.

\kbd{add(E,x,y)} returns the sum $x+y$.

\kbd{sub(E,x,y)} returns the difference $x-y$.

\kbd{mul(E,x,y)} returns the product $x\*y$.

\kbd{sqr(E,x)} returns the square $x^2$.

\kbd{one(E)} returns the unit element.

\kbd{zero(E)} returns the zero element.

\noindent An algebra is thus described by a \kbd{struct bb\_algebra} as above
and auxiliary data typecast to \kbd{void*}. The following functions operate
on black box algebra:

\fun{GEN}{gen_bkeval}{GEN P, long d, GEN x, int use_sqr, void *E,
          const struct bb_algebra *ff, GEN cmul(void *E, GEN P, long a, GEN x)}
$x$ being an element of the black box algebra, and $P$ some black box
polynomial of degree $d$ over the base field,  returns $P(x)$. The function
\kbd{cmul(E,P,a,y)} must return the coefficient of degree $a$ of $P$
multiplied by $y$. \kbd{cmul} is allowed to return a non canonical form;
it is also allowed to return \kbd{NULL} instead of an exact $0$.

The flag \kbd{use\_sqr} has the same meaning as for \kbd{gen\_powers}. This
implements an algorithm of Brent and Kung (1978).

\fun{GEN}{gen_bkeval_powers}{GEN P, long d, GEN V, void *E,
 const struct bb_algebra *ff, GEN cmul(void *E, GEN P, long a, GEN x)}
as \tet{gen_RgX_bkeval} assuming $V$ was output by
\tet{gen_powers}$(x, l, E, \var{ff})$ for some $l\geq 1$. For optimal
performance, $l$ should be computed by \tet{brent_kung_optpow}.

\fun{long}{brent_kung_optpow}{long d, long n, long m} returns the optimal
parameter $l$ for the evaluation of $n/m$ polynomials of degree $d$.
Fractional values can be used if the evaluations are done with different
accuracies, and thus have different weights.

\subsec{Functions returning black box algebras}

\fun{const struct bb_algebra *}{get_FpX_algebra}{void **E, GEN p, long v}
return the algebra of polynomials over $\F_p$ in variable $v$.

\fun{const struct bb_algebra *}{get_FpXQ_algebra}{void **E, GEN T, GEN p}
return the algebra $\F_p[X]/(T(X))$.

\fun{const struct bb_algebra *}{get_FpXQX_algebra}{void **E, GEN T, GEN p, long v}
return the algebra of polynomials over $\F_p[X]/(T(X))$ in variable $v$.

\fun{const struct bb_algebra *}{get_FlxqXQ_algebra}{void **E, GEN S, GEN T, ulong p}
return the algebra $\F_p[X,Y]/(S(X,Y),T(X))$ (for \kbd{ulong} $p$).

\fun{const struct bb_algebra *}{get_FpXQXQ_algebra}{void **E, GEN S, GEN T, GEN p}
return the algebra $\F_p[X,Y]/(S(X,Y),T(X))$.

\fun{const struct bb_algebra *}{get_Rg_algebra}{void}
return the generic algebra.

\section{Black box ring}

A black box ring is defined by a \tet{bb_ring} struct, describing methods
available to handle ring elements:
\bprog
struct bb_ring
{
  GEN (*add)(void *E, GEN x, GEN y);
  GEN (*mul)(void *E, GEN x, GEN y);
  GEN (*sqr)(void *E, GEN x);
};
@eprog

\kbd{add(E,x,y)} returns the sum $x+y$.

\kbd{mul(E,x,y)} returns the product $x\*y$.

\kbd{sqr(E,x)} returns the square $x^2$.

\fun{GEN}{gen_fromdigits}{GEN v, GEN B, void *E, struct bb_ring *r}
where $B$ is a ring element and $v=[c_0,\ldots,c_{n-1}]$ a vector of ring elements,
return $\sum_{i=0}^n c_i\*B^i$ using binary splitting.

\fun{GEN}{gen_digits}{GEN x, GEN B, long n, void *E, struct bb_ring *r,
                          GEN (*div)(void *E, GEN x, GEN y, GEN *r)}

(Require the ring to be Euclidean)

\kbd{div(E,x,y,\&r)} performs the Euclidean division of $x$ by $y$ in the ring
$R$, returning the quotient $q$ and setting $r$ to the residue so that
$x=q\*y+r$ holds. The residue must belong to a fixed set of representatives of
$R/(y)$.

The argument $x$ being a ring element, \kbd{gen\_digits} returns a vector of
ring elements $[c_0,\ldots,c_{n-1}]$ such that $x = \sum_{i=0}^n c_i\*B^i$.
Furthermore for all $i\ne n-1$, the elements $c_i$ belonging to the fixed set
of representatives of $R/(B)$.

\section{Black box free $\Z_p$-modules}

(Very experimental)

\fun{GEN}{gen_ZpX_Dixon}{GEN F, GEN V, GEN q, GEN p, long N, void *E,
                            GEN lin(void *E, GEN F, GEN z, GEN q),
                            GEN invl(void *E, GEN z)}

Let $F$ be a \kbd{ZpXT} representing the coefficients of some abstract
linear mapping $f$ over $\Z_p[X]$ seen as a free $\Z_p$-module, let $V$ be
an element of $\Z_p[X]$ and let $q = p^N$.  Return $y\in\Z_p[X]$ such that
$f(y)=V\pmod{p^N}$ assuming the following holds for $n\leq N$:

\item $\kbd{lin}(E, \kbd{FpX\_red}(F, p^n), z, p^n) \equiv f(z) \pmod{p^n}$

\item $f(\kbd{invl}(E, z)) \equiv z \pmod{p}$

The rationale for the argument $F$ being that it allows \kbd{gen\_ZpX\_Dixon}
to reduce it to the required $p$-adic precision.

\fun{GEN}{gen_ZpX_Newton}{GEN x, GEN p, long n, void *E,
                          GEN eval(void *E, GEN a, GEN q),
                          GEN invd(void *E, GEN b, GEN v, GEN q, long N)}

Let $x$ be an element of $\Z_p[X]$ seen as a free  $\Z_p$-module, and $f$
some differentiable function over $\Z_p[X]$ such that $f(x) \equiv 0
\pmod{p}$. Return $y$ such that $f(y) \equiv 0\pmod{p^n}$, assuming the
following holds for all $a, b\in \Z_p[X]$ and $M\leq N$:

\item $v = \kbd{eval}(E,a,p^N)$ is a vector of elements of $\Z_p[X]$,

\item $w = \kbd{invd}(E,b,v,p^M,M)$ is an element in $\Z_p[X]$,

\item $v[1] \equiv f(a) \pmod{p^N\Z_p[X]}$,

\item $df_a(w) \equiv b \pmod{p^M\Z_p[X]}$

\noindent and $df_a$ denotes the differential of $f$ at $a$. Motivation:
\kbd{eval} allows to evaluate $f$ and \kbd{invd} allows to invert its
differential. Frequently, data useful to compute the differential appear as a
subproduct of computing the function. The vector $v$ allows \kbd{eval} to
provide these to \kbd{invd}. The implementation of \kbd{invd} will generally
involves the use of the function \kbd{gen\_ZpX\_Dixon}.


\newpage
\chapter{Operations on general PARI objects}

\section{Assignment}

It is in general easier to use a direct conversion,
e.g.~\kbd{y = stoi(s)}, than to allocate a target of correct type and
sufficient size, then assign to it:
\bprog
  GEN y = cgeti(3); affsi(s, y);
@eprog\noindent
These functions can still be moderately useful in complicated garbage
collecting scenarios but you will be better off not using them.

\fun{void}{gaffsg}{long s, GEN x} assigns the \kbd{long}~\kbd{s} into the
object~\kbd{x}.

\fun{void}{gaffect}{GEN x, GEN y} assigns the object \kbd{x} into the
object~\kbd{y}. Both \kbd{x} and \kbd{y} must be scalar types. Type
conversions (e.g.~from \typ{INT} to \typ{REAL} or \typ{INTMOD}) occur if
legitimate.

\fun{int}{is_universal_constant}{GEN x} returns $1$ if $x$ is a global PARI
constant you should never assign to (such as \kbd{gen\_1}), and $0$
otherwise.

\section{Conversions}

\subsec{Scalars}

\fun{double}{rtodbl}{GEN x} applied to a \typ{REAL}~\kbd{x}, converts \kbd{x}
into a \kbd{double} if possible.

\fun{GEN}{dbltor}{double x} converts the \kbd{double} \kbd{x} into a
\typ{REAL}.

\fun{long}{dblexpo}{double x} returns \kbd{expo(dbltor(x))}, but
faster and without cluttering the stack.

\fun{ulong}{dblmantissa}{double x} returns the most significant word
in the mantissa of \kbd{dbltor(x)}.

\fun{double}{gtodouble}{GEN x} if \kbd{x} is a real number (not necessarily
a~\typ{REAL}), converts \kbd{x} into a \kbd{double} if possible.

\fun{long}{gtos}{GEN x} converts the \typ{INT} \kbd{x} to a small
integer if possible, otherwise raise an exception. This function
is similar to \tet{itos}, slightly slower since it checks the type of \kbd{x}.

\fun{double}{dbllog2r}{GEN x} assuming that \kbd{x} is a non-zero \typ{REAL},
returns an approximation to \kbd{log2(|x|)}.

\fun{double}{dblmodulus}{GEN x} return an approximation to \kbd{|x|}.

\fun{long}{gtolong}{GEN x} if \kbd{x} is an integer (not necessarily
a~\typ{INT}), converts \kbd{x} into a \kbd{long} if possible.

\fun{GEN}{fractor}{GEN x, long l} applied to a \typ{FRAC}~\kbd{x}, converts
\kbd{x} into a \typ{REAL} of length \kbd{prec}.

\fun{GEN}{quadtofp}{GEN x, long l} applied to a \typ{QUAD}~\kbd{x}, converts
\kbd{x} into a \typ{REAL} or \typ{COMPLEX} depending on the sign of the
discriminant of~\kbd{x}, to precision \hbox{\kbd{l} \B-bit} words.
% forbid line brk at hyphen here [GN]

\fun{GEN}{cxtofp}{GEN x, long prec} converts the \typ{COMPLEX}~\kbd{x} to a
a complex whose real and imaginary parts are \typ{REAL} of length \kbd{prec}
(special case of~\kbd{gtofp}.

\fun{GEN}{cxcompotor}{GEN x, long prec} converts the
\typ{INT}, \typ{REAL} or \typ{FRAC} $x$ to a \typ{REAL} of length \kbd{prec}.
These are all the real types which may occur as components of a
\typ{COMPLEX}; special case of~\kbd{gtofp} (introduced so that the latter is
not recursive and can thus be inlined).

\fun{GEN}{gtofp}{GEN x, long prec} converts the complex number~\kbd{x}
(\typ{INT}, \typ{REAL}, \typ{FRAC}, \typ{QUAD} or \typ{COMPLEX}) to either
a \typ{REAL} or \typ{COMPLEX} whose components are \typ{REAL} of precision
\kbd{prec}; not necessarily of \emph{length} \kbd{prec}: a real $0$ may be
given as \kbd{real\_0(...)}). If the result is a \typ{COMPLEX} extra care is
taken so that its modulus really has accuracy \kbd{prec}: there is a problem
if the real part of the input is an exact $0$; indeed, converting it to
\kbd{real\_0(prec)} would be wrong if the imaginary part is tiny, since the
modulus would then become equal to $0$, as in $1.E-100 + 0.E-28 = 0.E-28$.

\fun{GEN}{gtomp}{GEN z, long prec} converts the real number~\kbd{x}
(\typ{INT}, \typ{REAL}, \typ{FRAC}, real \typ{QUAD}) to either
a \typ{INT} or a \typ{REAL} of precision \kbd{prec}. Not memory clean
if $x$ is a \typ{INT}: we return $x$ itself and not a copy.

\fun{GEN}{gcvtop}{GEN x, GEN p, long l} converts $x$ into a \typ{PADIC}
of precision~$l$. Works componentwise on recursive objects,
e.g.~\typ{POL} or \typ{VEC}. Converting $0$ yields $O(p^l)$; converting a
non-zero number yield a result well defined modulo $p^{v_p(x) + l}$.

\fun{GEN}{cvtop}{GEN x, GEN p, long l} as \kbd{gcvtop}, assuming that $x$
is a scalar.

\fun{GEN}{cvtop2}{GEN x, GEN y} $y$ being a $p$-adic, converts the scalar $x$
to a $p$-adic of the same accuracy. Shallow function.

\fun{GEN}{cvstop2}{long s, GEN y} $y$ being a $p$-adic, converts the scalar $s$
to a $p$-adic of the same accuracy. Shallow function.

\fun{GEN}{gprec}{GEN x, long l} returns a copy of $x$ whose precision is
changed to $l$ digits. The precision change is done recursively on all
components of $x$. Digits means \emph{decimal}, $p$-adic and $X$-adic digits
for \typ{REAL}, \typ{SER}, \typ{PADIC} components, respectively.

\fun{GEN}{gprec_w}{GEN x, long l} returns a shallow copy of $x$ whose
\typ{REAL} components have their precision changed to $l$ \emph{words}. This
is often more useful than \kbd{gprec}.

\fun{GEN}{gprec_wtrunc}{GEN x, long l} returns a shallow copy of $x$ whose
\typ{REAL} components have their precision \emph{truncated} to $l$
\emph{words}. Contrary to \kbd{gprec\_w}, this function may never increase
the precision of~$x$.

\subsec{Modular objects / lifts}

\fun{GEN}{gmodulo}{GEN x, GEN y} creates the object \kbd{\key{Mod}(x,y)} on
the PARI stack, where \kbd{x} and \kbd{y} are either both \typ{INT}s, and the
result is a \typ{INTMOD}, or \kbd{x} is a scalar or a \typ{POL} and \kbd{y} a
\typ{POL}, and the result is a \typ{POLMOD}.

\fun{GEN}{gmodulgs}{GEN x, long y} same as \key{gmodulo} except \kbd{y} is a
\kbd{long}.

\fun{GEN}{gmodulsg}{long x, GEN y} same as \key{gmodulo} except \kbd{x} is a
\kbd{long}.

\fun{GEN}{gmodulss}{long x, long y} same as \key{gmodulo} except both
\kbd{x} and \kbd{y} are \kbd{long}s.

\fun{GEN}{lift_shallow}{GEN x} shallow version of \tet{lift}

\fun{GEN}{liftall_shallow}{GEN x} shallow version of \tet{liftall}

\fun{GEN}{liftint_shallow}{GEN x} shallow version of \tet{liftint}

\fun{GEN}{liftpol_shallow}{GEN x} shallow version of \tet{liftpol}

\fun{GEN}{centerlift0}{GEN x,long v} DEPRECATED, kept for backward
compatibility only: use either \tet{lift0}$(x,v)$ or \tet{centerlift}$(x)$.

\subsec{Between polynomials and coefficient arrays}

\fun{GEN}{gtopoly}{GEN x, long v} converts or truncates the object~\kbd{x}
into a \typ{POL} with main variable number~\kbd{v}. A common application
would be the conversion of coefficient vectors (coefficients are given by
decreasing degree). E.g.~\kbd{[2,3]} goes to \kbd{2*v + 3}

\fun{GEN}{gtopolyrev}{GEN x, long v} converts or truncates the object~\kbd{x}
into a \typ{POL} with main variable number~\kbd{v}, but vectors are converted
in reverse order compared to \kbd{gtopoly} (coefficients are given by
increasing degree). E.g.~\kbd{[2,3]} goes to \kbd{3*v + 2}. In other words
the vector represents a polynomial in the basis $(1,v,v^2,v^3,\dots)$.

\fun{GEN}{normalizepol}{GEN x} applied to an unnormalized \typ{POL}~\kbd{x}
(with all coefficients correctly set except that \kbd{leading\_term(x)} might
be zero), normalizes \kbd{x} correctly in place and returns~\kbd{x}. For
internal use. Normalizing means deleting all leading \emph{exact} zeroes
(as per \kbd{isexactzero}), except if the polynomial turns out to be $0$,
in which case we try to find a coefficient $c$ which is a non-rational zero,
and return the constant polynomial $c$. (We do this so that information
about the base ring is not lost.)

\fun{GEN}{normalizepol_lg}{GEN x, long l} applies \kbd{normalizepol} to
\kbd{x}, pretending that \kbd{lg(x)} is $l$, which must be less than
or equal to \kbd{lg(x)}. If equal, the function is equivalent to
\kbd{normalizepol(x)}.

\fun{GEN}{normalizepol_approx}{GEN x, long lx} as \kbd{normalizepol\_lg},
with the difference that we just delete all leading zeroes (as per
\kbd{gequal0}). This rougher normalization is used when we have no other
choice, for instance before attempting a Euclidean division by $x$.

The following routines do \emph{not} copy coefficients on the stack (they
only move pointers around), hence are very fast but not suitable for
\kbd{gerepile} calls. Recall that an \kbd{RgV} (resp.~an \kbd{RgX}, resp.~an
\kbd{RgM}) is a \typ{VEC} or \typ{COL} (resp.~a \typ{POL}, resp.~a \typ{MAT})
with arbitrary components. Similarly, an \kbd{RgXV} is a \typ{VEC} or
\typ{COL} with \kbd{RgX} components, etc.

\fun{GEN}{RgV_to_RgX}{GEN x, long v} converts the \kbd{RgV}~\kbd{x} to a
(normalized) polynomial in variable~\kbd{v} (as \kbd{gtopolyrev}, without
copy).

\fun{GEN}{RgV_to_RgX_reverse}{GEN x, long v} converts the \kbd{RgV}~\kbd{x}
to a (normalized) polynomial in variable~\kbd{v} (as \kbd{gtopoly},
without copy).

\fun{GEN}{RgX_to_RgC}{GEN x, long N} converts the \typ{POL}~\kbd{x} to a
\typ{COL}~\kbd{v} with \kbd{N} components. Coefficients of \kbd{x} are listed
by increasing degree, so that \kbd{y[i]} is the coefficient of the term of
degree $i-1$ in \kbd{x}.

\fun{GEN}{Rg_to_RgC}{GEN x, long N} as \tet{RgX_to_RgV}, except that other
types than \typ{POL} are allowed for \kbd{x}, which is then considered as a
constant polynomial.

\fun{GEN}{RgM_to_RgXV}{GEN x, long v} converts the \kbd{RgM}~\kbd{x} to a
\typ{VEC} of \kbd{RgX}, by repeated calls to \kbd{RgV\_to\_RgX}.

\fun{GEN}{RgV_to_RgM}{GEN v, long N} converts the vector~\kbd{v} to
a~\typ{MAT} with \kbd{N}~rows, by repeated calls to \kbd{Rg\_to\_RgV}.

\fun{GEN}{RgXV_to_RgM}{GEN v, long N} converts the vector of \kbd{RgX}~\kbd{v}
to a~\typ{MAT} with \kbd{N}~rows, by repeated calls to \kbd{RgX\_to\_RgV}.

\fun{GEN}{RgM_to_RgXX}{GEN x, long v,long w} converts the \kbd{RgM}~\kbd{x} into
a \typ{POL} in variable~\kbd{v}, whose coefficients are \typ{POL}s in
variable~\kbd{w}. This is a shortcut for
\bprog
  RgV_to_RgX( RgM_to_RgXV(x, w), v );
@eprog\noindent
There are no consistency checks with respect to variable
priorities: the above is an invalid object if $\kbd{varncmp(v, w)} \geq 0$.

\fun{GEN}{RgXX_to_RgM}{GEN x, long N} converts the \typ{POL}~\kbd{x} with
\kbd{RgX} (or constant) coefficients to a matrix with \kbd{N} rows.

\fun{long}{RgXY_degreex}{GEN P} return the degree of $P$ with respect to
the secondary variable.

\fun{GEN}{RgXY_swap}{GEN P, long n, long w} converts the bivariate polynomial
$\kbd{P}(u,v)$ (a \typ{POL} with \typ{POL} or scalar coefficients) to
$P(\kbd{pol\_x[w]},u)$, assuming \kbd{n} is an upper bound for
$\deg_v(\kbd{P})$.

\fun{GEN}{RgXY_swapspec}{GEN C, long n, long w, long lP}
as \kbd{RgXY\_swap} where the coefficients of $P$ are given by
\kbd{gel(C,0),\dots,gel(C,lP-1)}.

\fun{GEN}{RgX_to_ser}{GEN x, long l} applied to a \typ{POL}~\kbd{x}, creates
a \emph{shallow} \typ{SER} of length~$l\geq 2$ starting with~\kbd{x}.
Unless the polynomial is an exact zero, the coefficient of lowest degree
$T^d$ of the result is not an exact zero (as per \kbd{isexactzero}). The
remainder is $O(T^{d+l})$.

\fun{GEN}{RgX_to_ser_inexact}{GEN x, long l} applied to a \typ{POL}~\kbd{x},
creates a \emph{shallow} \typ{SER} of length~\kbd{l} starting with~\kbd{x}.
Unless the polynomial is zero, the coefficient of lowest degree
$T^d$ of the result is not zero (as per \kbd{gequal0}). The
remainder is $O(T^{d+l})$.

\fun{GEN}{rfrac_to_ser}{GEN x, long l} applied to a \typ{RFRAC}~\kbd{x},
creates a \typ{SER} of length~\kbd{l} congruent to $x$. Not memory-clean
but suitable for \kbd{gerepileupto}.

\fun{GEN}{gtoser}{GEN s, long v, long d} converts the object~$s$ into
a \typ{SER} with main variable number~\kbd{v} and $d > 0$ significant terms.
More precisely

\item if $s$ is a scalar,  we return a constant power series with $d$
significant terms.

\item if $s$ is a \typ{POL}, it is truncated to $d$ terms if needed.

\item If $s$ is a vector, the coefficients of the vector  are understood to
be the coefficients of the power series starting from the constant term (as
in \tet{Polrev}), and the precision $d$ is \emph{ignored}.

\item If $s$ is already a power series in $v$, we retur a copy, and
the precision $d$ is again \emph{ignored}.

\fun{GEN}{gtocol}{GEN x} converts the object~\kbd{x} into a \typ{COL}

\fun{GEN}{gtomat}{GEN x} converts the object~\kbd{x} into a \typ{MAT}.

\fun{GEN}{gtovec}{GEN x} converts the object~\kbd{x} into a \typ{VEC}.

\fun{GEN}{gtovecsmall}{GEN x} converts the object~\kbd{x} into a
\typ{VECSMALL}.

\fun{GEN}{normalize}{GEN x} applied to an unnormalized \typ{SER}~\kbd{x}
(i.e.~type \typ{SER} with all coefficients correctly set except that \kbd{x[2]}
might be zero), normalizes \kbd{x} correctly in place. Returns~\kbd{x}.
For internal use.

\fun{GEN}{serchop0}{GEN s} given a \typ{SER} of the form $x^v s(x)$, with
$s(0)\neq 0$, return $x^v(s - s(0))$. Shallow function.

\section{Constructors}

\subsec{Clean constructors}\label{se:clean}

\fun{GEN}{zeropadic}{GEN p, long n} creates a $0$ \typ{PADIC} equal to
$O(\kbd{p}^\kbd{n})$.

\fun{GEN}{zeroser}{long v, long n} creates a $0$ \typ{SER} in variable
\kbd{v} equal to $O(X^\kbd{n})$.

\fun{GEN}{scalarser}{GEN x, long v, long prec} creates a constant \typ{SER}
in variable \kbd{v} and precision \kbd{prec}, whose constant coefficient is
(a copy of) \kbd{x}, in other words $\kbd{x} + O(\kbd{v}^\kbd{prec})$.
Assumes that $\kbd{prec}\geq 0$.

\fun{GEN}{pol_0}{long v} Returns the constant polynomial $0$ in variable $v$.

\fun{GEN}{pol_1}{long v} Returns the constant polynomial $1$ in variable $v$.

\fun{GEN}{pol_x}{long v} Returns the monomial of degree $1$ in variable $v$.

\fun{GEN}{pol_xn}{long n, long v} Returns the monomial of degree $n$
in variable $v$; assume that $n \geq 0$.

\fun{GEN}{pol_xnall}{long n, long v} Returns the Laurent monomial of degree $n$
in variable $v$; $n < 0$ is allowed.

\fun{GEN}{pol_x_powers}{long N, long v} returns the powers of
\kbd{pol\_x(v)}, of degree $0$ to $N-1$, in a vector with $N$ components.

\fun{GEN}{scalarpol}{GEN x, long v} creates a constant \typ{POL} in variable
\kbd{v}, whose constant coefficient is (a copy of) \kbd{x}.

\fun{GEN}{deg1pol}{GEN a, GEN b,long v} creates the degree 1 \typ{POL}
$a \kbd{pol\_x}(v) + b$

\fun{GEN}{zeropol}{long v} is identical \kbd{pol\_0}.

\fun{GEN}{zerocol}{long n} creates a \typ{COL} with \kbd{n} components set to
\kbd{gen\_0}.

\fun{GEN}{zerovec}{long n} creates a \typ{VEC} with \kbd{n} components set to
\kbd{gen\_0}.

\fun{GEN}{col_ei}{long n, long i} creates a \typ{COL} with \kbd{n} components
set to \kbd{gen\_0}, but for the \kbd{i}-th one which is set to \kbd{gen\_1}
(\kbd{i}-th vector in the canonical basis).

\fun{GEN}{vec_ei}{long n, long i} creates a \typ{VEC} with \kbd{n} components
set to \kbd{gen\_0}, but for the \kbd{i}-th one which is set to \kbd{gen\_1}
(\kbd{i}-th vector in the canonical basis).

\fun{GEN}{trivial_fact}{void} returns the trivial (empty) factorization
\kbd{Mat([]\til,[]\til)}

\fun{GEN}{prime_fact}{GEN x} returns the factorization
\kbd{Mat([x]\til, [1]\til)}

\fun{GEN}{Rg_col_ei}{GEN x, long n, long i} creates a \typ{COL} with \kbd{n}
components set to \kbd{gen\_0}, but for the \kbd{i}-th one which is set to
\kbd{x}.

\fun{GEN}{vecsmall_ei}{long n, long i} creates a \typ{VECSMALL} with \kbd{n}
components set to \kbd{0}, but for the \kbd{i}-th one which is set to
\kbd{1} (\kbd{i}-th vector in the canonical basis).

\fun{GEN}{scalarcol}{GEN x, long n} creates a \typ{COL} with \kbd{n}
components set to \kbd{gen\_0}, but the first one which is set to a copy
of \kbd{x}. (The name comes from \kbd{RgV\_isscalar}.)

\smallskip

\fun{GEN}{mkintmodu}{ulong x, ulong y} creates the \typ{INTMOD} \kbd{Mod(x, y)}.
The inputs must satisfy $x < y$.

\fun{GEN}{zeromat}{long m, long n} creates a \typ{MAT} with \kbd{m} x \kbd{n}
components set to \kbd{gen\_0}. Note that the result allocates a
\emph{single} column, so modifying an entry in one column modifies it in
all columns. To fully allocate a matrix initialized with zero entries,
use \kbd{zeromatcopy}.

\fun{GEN}{zeromatcopy}{long m, long n} creates a \typ{MAT} with \kbd{m} x
\kbd{n} components set to \kbd{gen\_0}.

\fun{GEN}{matid}{long n} identity matrix in dimension \kbd{n} (with
components \kbd{gen\_1} and\kbd{gen\_0}).

\fun{GEN}{scalarmat}{GEN x, long n} scalar matrix, \kbd{x} times the identity.

\fun{GEN}{scalarmat_s}{long x, long n} scalar matrix, \kbd{stoi(x)} times
the identity.

\fun{GEN}{vecrange}{GEN a, GEN b} returns the \typ{VEC} $[a..b]$.

\fun{GEN}{vecrangess}{long a, long b} returns the \typ{VEC} $[a..b]$.

\smallskip
See also next section for analogs of the following functions:

\fun{GEN}{mkfraccopy}{GEN x, GEN y} creates the \typ{FRAC} $x/y$. Assumes that
$y > 1$ and $(x,y) = 1$.

\fun{GEN}{mkrfraccopy}{GEN x, GEN y} creates the \typ{RFRAC} $x/y$.
Assumes that $y$ is a \typ{POL}, $x$ a compatible type whose variable has
lower or same priority, with $(x,y) = 1$.

\fun{GEN}{mkcolcopy}{GEN x} creates a 1-dimensional \typ{COL} containing
\kbd{x}.

\fun{GEN}{mkmatcopy}{GEN x} creates a 1-by-1 \typ{MAT} wrapping the \typ{COL}
\kbd{x}.

\fun{GEN}{mkveccopy}{GEN x} creates a 1-dimensional \typ{VEC} containing
\kbd{x}.

\fun{GEN}{mkvec2copy}{GEN x, GEN y} creates a 2-dimensional \typ{VEC} equal
to \kbd{[x,y]}.

\fun{GEN}{mkcols}{long x} creates a 1-dimensional \typ{COL}
containing \kbd{stoi(x)}.

\fun{GEN}{mkcol2s}{long x, long y} creates a 2-dimensional \typ{COL}
containing \kbd{[stoi(x), stoi(y)]~}.

\fun{GEN}{mkcol3s}{long x, long y, long z} creates a 3-dimensional \typ{COL}
containing \kbd{[stoi(x), stoi(y), stoi(z)]~}.

\fun{GEN}{mkcol4s}{long x, long y, long z, long t} creates a 4-dimensional
\typ{COL} containing \kbd{[stoi(x), stoi(y), stoi(z), stoi(t)]~}.

\fun{GEN}{mkvecs}{long x} creates a 1-dimensional \typ{VEC}
containing \kbd{stoi(x)}.

\fun{GEN}{mkvec2s}{long x, long y} creates a 2-dimensional \typ{VEC}
containing \kbd{[stoi(x), stoi(y)]}.

\fun{GEN}{mkvec3s}{long x, long y, long z} creates a 3-dimensional \typ{VEC}
containing \kbd{[stoi(x), stoi(y), stoi(z)]}.

\fun{GEN}{mkvec4s}{long x, long y, long z, long t} creates a 4-dimensional
\typ{VEC} containing \kbd{[stoi(x), stoi(y), stoi(z), stoi(t)]}.

\fun{GEN}{mkvecsmall}{long x} creates a 1-dimensional \typ{VECSMALL}
containing \kbd{x}.

\fun{GEN}{mkvecsmall2}{long x, long y} creates a 2-dimensional \typ{VECSMALL}
containing \kbd{[x, y]}.

\fun{GEN}{mkvecsmall3}{long x, long y, long z} creates a 3-dimensional
\typ{VECSMALL} containing \kbd{[x, y, z]}.

\fun{GEN}{mkvecsmall4}{long x, long y, long z, long t} creates a 4-dimensional
\typ{VECSMALL} containing \kbd{[x, y, z, t]}.

\fun{GEN}{mkvecsmalln}{long n, ...} returns the \typ{VECSMALL} whose $n$
coefficients (\kbd{long}) follow.
\emph{Warning:} since this is a variadic function, C type promotion is not
performed on the arguments by the compiler, thus you have to make sure that all
the arguments are of type \kbd{long}, in particular integer constants need to
be written with the \kbd{L} suffix: \kbd{mkvecsmalln(2, 1L, 2L)} is correct,
but \kbd{mkvecsmalln(2, 1, 2)} is not.

\subsec{Unclean constructors}\label{se:unclean}

Contrary to the policy of general PARI functions, the functions in this
subsection do \emph{not} copy their arguments, nor do they produce an object
a priori suitable for \tet{gerepileupto}. In particular, they are
faster than their clean equivalent (which may not exist). \emph{If} you
restrict their arguments to universal objects (e.g \kbd{gen\_0}),
then the above warning does not apply.

\fun{GEN}{mkcomplex}{GEN x, GEN y} creates the \typ{COMPLEX} $x + iy$.

\fun{GEN}{mulcxI}{GEN x} creates the \typ{COMPLEX} $ix$. The result in
general contains data pointing back to the original $x$. Use \kbd{gcopy} if
this is a problem. But in most cases, the result is to be used immediately,
before $x$ is subject to garbage collection.

\fun{GEN}{mulcxmI}{GEN x}, as \tet{mulcxI}, but returns the \typ{COMPLEX}
$-ix$.

\fun{GEN}{mkquad}{GEN n, GEN x, GEN y} creates the \typ{QUAD} $x + yw$,
where $w$ is a root of $n$, which is of the form \kbd{quadpoly(D)}.

\fun{GEN}{mkfrac}{GEN x, GEN y} creates the \typ{FRAC} $x/y$. Assumes that
$y > 1$ and $(x,y) = 1$.

\fun{GEN}{mkrfrac}{GEN x, GEN y} creates the \typ{RFRAC} $x/y$. Assumes
that $y$ is a \typ{POL}, $x$ a compatible type whose variable has lower
or same priority, with $(x,y) = 1$.

\fun{GEN}{mkcol}{GEN x} creates a 1-dimensional \typ{COL} containing \kbd{x}.

\fun{GEN}{mkcol2}{GEN x, GEN y} creates a 2-dimensional \typ{COL} equal to
\kbd{[x,y]}.

\fun{GEN}{mkcol3}{GEN x, GEN y, GEN z} creates a 3-dimensional \typ{COL}
equal to \kbd{[x,y,z]}.

\fun{GEN}{mkcol4}{GEN x, GEN y, GEN z, GEN t} creates a 4-dimensional \typ{COL}
equal to \kbd{[x,y,z,t]}.

\fun{GEN}{mkcol5}{GEN a1, GEN a2, GEN a3, GEN a4, GEN a5} creates the
5-dimensional \typ{COL} equal to $[a_1,a_2,a_3,a_4,a_5]$.

\fun{GEN}{mkcol6}{GEN x, GEN y, GEN z, GEN t, GEN u, GEN v}
creates the $6$-dimensional column vector \kbd{[x,y,z,t,u,v]~}.

\fun{GEN}{mkintmod}{GEN x, GEN y} creates the \typ{INTMOD} \kbd{Mod(x, y)}.
The inputs must be \typ{INT}s satisfying $0 \leq x < y$.

\fun{GEN}{mkpolmod}{GEN x, GEN y} creates the \typ{POLMOD} \kbd{Mod(x, y)}.
The input must satisfy $\deg x < \deg y$ with respect to the main variable of
the \typ{POL} $y$. $x$ may be a scalar.

\fun{GEN}{mkmat}{GEN x} creates a 1-column \typ{MAT} with column $x$
(a \typ{COL}).

\fun{GEN}{mkmat2}{GEN x, GEN y} creates a 2-column \typ{MAT} with columns
$x$, $y$ (\typ{COL}s of the same length).

\fun{GEN}{mkmat3}{GEN x, GEN y, GEN z} creates a 3-column \typ{MAT} with columns
$x$, $y$, $z$ (\typ{COL}s of the same length).

\fun{GEN}{mkmat4}{GEN x, GEN y, GEN z, GEN t} creates a 4-column \typ{MAT}
with columns $x$, $y$, $z$, $t$ (\typ{COL}s of the same length).

\fun{GEN}{mkmat5}{GEN x, GEN y, GEN z, GEN t, GEN u} creates a 5-column
\typ{MAT} with columns $x$, $y$, $z$, $t$, $u$ (\typ{COL}s of the same
length).

\fun{GEN}{mkvec}{GEN x} creates a 1-dimensional \typ{VEC} containing \kbd{x}.

\fun{GEN}{mkvec2}{GEN x, GEN y} creates a 2-dimensional \typ{VEC} equal to
\kbd{[x,y]}.

\fun{GEN}{mkvec3}{GEN x, GEN y, GEN z} creates a 3-dimensional \typ{VEC}
equal to \kbd{[x,y,z]}.

\fun{GEN}{mkvec4}{GEN x, GEN y, GEN z, GEN t} creates a 4-dimensional \typ{VEC}
equal to \kbd{[x,y,z,t]}.

\fun{GEN}{mkvec5}{GEN a1, GEN a2, GEN a3, GEN a4, GEN a5} creates the
5-dimensional \typ{VEC} equal to $[a_1,a_2,a_3,a_4,a_5]$.

\fun{GEN}{mkqfi}{GEN x, GEN y, GEN z} creates \typ{QFI} equal
to \kbd{Qfb(x,y,z)}, assuming that $y^2 - 4xz < 0$.

\fun{GEN}{mkerr}{long n} returns a \typ{ERROR} with error code $n$
(\kbd{enum err\_list}).

\smallskip

It is sometimes useful to return such a container whose entries are not
universal objects, but nonetheless suitable for \tet{gerepileupto}.
If the entries can be computed at the time the result is returned, the
following macros achieve this effect:

\fun{GEN}{retmkvec}{GEN x} returns a vector containing the single entry $x$,
where the vector root is created just before the function argument $x$ is
evaluated. Expands to
\bprog
  {
    GEN res = cgetg(2, t_VEC);
    gel(res, 1) = x; /* @Ccom or rather, the \emph{expansion} of $x$ */
    return res;
  }
@eprog\noindent For instance, the \kbd{retmkvec(gcopy(x))} returns a clean
object, just like \kbd{return mkveccopy(x)} would.

\fun{GEN}{retmkvec2}{GEN x, GEN y}
returns the $2$-dimensional \typ{VEC} \kbd{[x,y]}.

\fun{GEN}{retmkvec3}{GEN x, GEN y, GEN z}
returns the $3$-dimensional \typ{VEC} \kbd{[x,y,z]}.

\fun{GEN}{retmkvec4}{GEN x, GEN y, GEN z, GEN t}
returns the $4$-dimensional \typ{VEC} \kbd{[x,y,z,t]}.

\fun{GEN}{retmkvec5}{GEN x, GEN y, GEN z, GEN t, GEN u}
returns the $5$-dimensional row vector \kbd{[x,y,z,t,u]}.

\fun{GEN}{retconst_vec}{long n, GEN x}
returns the $n$-dimensional \typ{VEC} whose entries are constant and all
equal to $x$.

\fun{GEN}{retmkcol}{GEN x}
returns the $1$-dimensional \typ{COL} \kbd{[x]~}.

\fun{GEN}{retmkcol2}{GEN x, GEN y}
returns the $2$-dimensional \typ{COL} \kbd{[x,y]~}.

\fun{GEN}{retmkcol3}{GEN x, GEN y, GEN z}
returns the $3$-dimensional \typ{COL} \kbd{[x,y,z]~}.

\fun{GEN}{retmkcol4}{GEN x, GEN y, GEN z, GEN t}
returns the $4$-dimensional \typ{COL} \kbd{[x,y,z,t]~}.

\fun{GEN}{retmkcol5}{GEN x, GEN y, GEN z, GEN t, GEN u}
returns the $5$-dimensional column vector \kbd{[x,y,z,t,u]~}.

\fun{GEN}{retmkcol6}{GEN x, GEN y, GEN z, GEN t, GEN u, GEN v}
returns the $6$-dimensional column vector \kbd{[x,y,z,t,u,v]~}.

\fun{GEN}{retconst_col}{long n, GEN x}
returns the $n$-dimensional \typ{COL} whose entries are constant and all
equal to $x$.

\fun{GEN}{retmkmat}{GEN x}
returns the $1$-column \typ{MAT} with colum \kbd{x}.

\fun{GEN}{retmkmat2}{GEN x, GEN y}
returns the $2$-column \typ{MAT} with columns \kbd{x}, \kbd{y}.

\fun{GEN}{retmkmat3}{GEN x, GEN y, GEN z}
returns the $3$-dimensional \typ{MAT} with columns
\kbd{x}, \kbd{y}, \kbd{z}.

\fun{GEN}{retmkmat4}{GEN x, GEN y, GEN z, GEN t}
returns the $4$-dimensional \typ{MAT} with columns
\kbd{x}, \kbd{y}, \kbd{z}, \kbd{t}.

\fun{GEN}{retmkmat5}{GEN x, GEN y, GEN z, GEN t, GEN u}
returns the $5$-dimensional \typ{MAT} with columns
\kbd{x}, \kbd{y}, \kbd{z}, \kbd{t}, \kbd{u}.

\fun{GEN}{retmkcomplex}{GEN x, GEN y}
returns the \typ{COMPLEX} \kbd{x + I*y}.

\fun{GEN}{retmkfrac}{GEN x, GEN y}
returns the \typ{FRAC} \kbd{x / y}. Assume $x$ and $y$ are coprime and $y > 1$.

\fun{GEN}{retmkrfrac}{GEN x, GEN y}
returns the \typ{RFRAC} \kbd{x / y}. Assume $x$ and $y$ are coprime and more
generally that the rational function cannot be simplified.

\fun{GEN}{retmkintmod}{GEN x, GEN y}
returns the \typ{INTMOD} \kbd{Mod(x, y)}.

\fun{GEN}{retmkqfi}{GEN a, GEN b, GEN c}.

\fun{GEN}{retmkqfr}{GEN a, GEN b, GEN c, GEN d}.

\fun{GEN}{retmkquad}{GEN n, GEN a, GEN b}.

\fun{GEN}{retmkpolmod}{GEN x, GEN y}
returns the \typ{POLMOD} \kbd{Mod(x, y)}.

\smallskip

\fun{GEN}{mkintn}{long n, ...} returns the non-negative \typ{INT} whose
development in base $2^{32}$ is given by the following $n$ 32bit-words
(\kbd{unsigned int}).
\bprog
  mkintn(3, a2, a1, a0);
@eprog
\noindent returns $a_2 2^{64} + a_1 2^{32} + a_0$.

\fun{GEN}{mkpoln}{long n, ...} Returns the \typ{POL} whose $n$
coefficients (\kbd{GEN}) follow, in order of decreasing degree.
\bprog
  mkpoln(3, gen_1, gen_2, gen_0);
@eprog
\noindent returns the polynomial $X^2 + 2X$ (in variable $0$, use
\tet{setvarn} if you want other variable numbers). Beware that $n$ is the
number of coefficients, hence \emph{one more} than the degree.

\fun{GEN}{mkvecn}{long n, ...} returns the \typ{VEC} whose $n$
coefficients (\kbd{GEN}) follow.

\fun{GEN}{mkcoln}{long n, ...} returns the \typ{COL} whose $n$
coefficients (\kbd{GEN}) follow.

\fun{GEN}{scalarcol_shallow}{GEN x, long n} creates a \typ{COL} with \kbd{n}
components set to \kbd{gen\_0}, but the first one which is set to a shallow
copy of \kbd{x}. (The name comes from \kbd{RgV\_isscalar}.)

\fun{GEN}{scalarmat_shallow}{GEN x, long n} creates an $n\times n$
scalar matrix whose diagonal is set to shallow copies of the scalar \kbd{x}.

\fun{GEN}{diagonal_shallow}{GEN x} returns a diagonal matrix whose diagonal
is given by the vector $x$. Shallow function.

\fun{GEN}{scalarpol_shallow}{GEN a, long v} returns the degree 0
\typ{POL} $a \kbd{pol\_x}(v)^0$.

\fun{GEN}{deg1pol_shallow}{GEN a, GEN b,long v} returns the degree 1
\typ{POL} $a\kbd{pol\_x}(v) + b$

\fun{GEN}{zeropadic_shallow}{GEN p, long n} returns a (shallow) $0$
\typ{PADIC} equal to $O(\kbd{p}^\kbd{n})$.

\subsec{From roots to polynomials}

\fun{GEN}{deg1_from_roots}{GEN L, long v} given a vector $L$ of scalars,
returns the vector of monic linear polynomials in variable $v$ whose roots
are the $L[i]$, i.e. the $x - L[i]$.

\fun{GEN}{roots_from_deg1}{GEN L} given a vector $L$ of monic linear
polynomials, return their roots, i.e. the $- L[i](0)$.

\fun{GEN}{roots_to_pol}{GEN L, long v} given a vector of scalars $L$,
returns the monic polynomial in variable $v$ whose roots are the $L[i]$.
Leaves some garbage on stack, but suitable for \kbd{gerepileupto}.

\fun{GEN}{roots_to_pol_r1}{GEN L, long v, long r1} as \kbd{roots\_to\_pol}
assuming the first $r_1$ roots are ``real'', and the following ones are
representatives of conjugate pairs of ``complex'' roots. So if $L$ has $r_1 +
r_2$ elements, we obtain a polynomial of degree $r_1 + 2r_2$. In most
applications, the roots are indeed real and complex, but the implementation
assumes only that each ``complex'' root $z$ introduces a quadratic
factor $X^2 - \kbd{trace}(z) X + \kbd{norm}(z)$.
Leaves some garbage on stack, but suitable for \kbd{gerepileupto}.

\section{Integer parts}

\fun{GEN}{gfloor}{GEN x} creates the floor of~\kbd{x}, i.e.\ the (true)
integral part.

\fun{GEN}{gfrac}{GEN x} creates the fractional part of~\kbd{x}, i.e.\ \kbd{x}
minus the floor of~\kbd{x}.

\fun{GEN}{gceil}{GEN x} creates the ceiling of~\kbd{x}.

\fun{GEN}{ground}{GEN x} rounds towards~$+\infty$ the components of \kbd{x}
to the nearest integers.

\fun{GEN}{grndtoi}{GEN x, long *e} same as \kbd{ground}, but in addition sets
\kbd{*e} to the binary exponent of $x - \kbd{ground}(x)$. If this is
positive, all significant bits are lost. This kind of situation raises an
error message in \key{ground} but not in \key{grndtoi}.

\fun{GEN}{gtrunc}{GEN x} truncates~\kbd{x}. This is the false integer part
if \kbd{x} is a real number (i.e.~the unique integer closest to \kbd{x} among
those between 0 and~\kbd{x}). If \kbd{x} is a \typ{SER}, it is truncated
to a \typ{POL}; if \kbd{x} is a \typ{RFRAC}, this takes the polynomial part.

\fun{GEN}{gtrunc2n}{GEN x, long n} creates the floor of~$2^n$\kbd{x}, this is
only implemented for \typ{INT}, \typ{REAL}, \typ{FRAC} and \typ{COMPLEX} of
those.

\fun{GEN}{gcvtoi}{GEN x, long *e} analogous to \key{grndtoi} for
\typ{REAL} inputs except that rounding is replaced by truncation. Also applies
componentwise for vector or matrix inputs; otherwise, sets \kbd{*e} to
\kbd{-HIGHEXPOBIT} (infinite real accuracy) and return \kbd{gtrunc(x)}.

\section{Valuation and shift}

\fun{GEN}{gshift[z]}{GEN x, long n[, GEN z]} yields the result of shifting
(the components of) \kbd{x} left by \kbd{n} (if \kbd{n} is non-negative)
or right by $-\kbd{n}$ (if \kbd{n} is negative). Applies only to \typ{INT}
and vectors/matrices of such. For other types, it is simply multiplication
by~$2^{\kbd{n}}$.

\fun{GEN}{gmul2n[z]}{GEN x, long n[, GEN z]} yields the product of \kbd{x}
and~$2^{\kbd{n}}$. This is different from \kbd{gshift} when \kbd{n} is negative
and \kbd{x} is a \typ{INT}: \key{gshift} truncates, while \key{gmul2n}
creates a fraction if necessary.

\fun{long}{gvaluation}{GEN x, GEN p} returns the greatest exponent~$e$ such that
$\kbd{p}^e$ divides~\kbd{x}, when this makes sense.

\fun{long}{gval}{GEN x, long v} returns the highest power of the variable
number \kbd{v} dividing the \typ{POL}~\kbd{x}.

\section{Comparison operators}

\subsec{Generic}

\fun{long}{gcmp}{GEN x, GEN y} comparison of \kbd{x} with \kbd{y}: returns
$1$ ($x > y$), $0$ ($x = y$) or $-1$ ($x < y$). Two \typ{STR}
are compared using the standard lexicographic ordering; a \typ{STR}
is considered strictly larger than any non-string type. If neither
$x$ nor $y$ is a \typ{STR}, their allowed types are \typ{INT}, \typ{REAL}
or \typ{FRAC}. Used \tet{cmp_universal} to compare arbitrary \kbd{GEN}s.

\fun{long}{lexcmp}{GEN x, GEN y} comparison of \kbd{x} with \kbd{y} for the
lexicographic ordering; when comparing objects of different lengths whose
components are all equal up to the smallest of their length, consider that
the longest is largest. Consider scalars as $1$-component vectors. Return
\kbd{gcmp}$(x,y)$ if both arguments are scalars.

\fun{int}{gequalX}{GEN x} return 1 (true) if \kbd{x} is a variable
(monomial of degree $1$ with \typ{INT} coefficients equal to $1$ and $0$),
and $0$ otherwise

\fun{long}{gequal}{GEN x, GEN y} returns 1 (true) if \kbd{x} is equal
to~\kbd{y}, 0~otherwise. A priori, this makes sense only if \kbd{x} and
\kbd{y} have the same type, in which case they are recursively compared
componentwise. When the types are different, a \kbd{true} result
means that \kbd{x - y} was successfully computed and that
\kbd{gequal0} found it equal to $0$. In particular
\bprog
  gequal(cgetg(1, t_VEC), gen_0)
@eprog\noindent is true, and the relation is not transitive. E.g.~an empty
\typ{COL} and an empty \typ{VEC} are not equal but are both equal to
\kbd{gen\_0}.

\fun{long}{gidentical}{GEN x, GEN y} returns 1 (true) if \kbd{x} is identical
to~\kbd{y}, 0~otherwise. In particular, the types and length of \kbd{x} and
\kbd{y} must be equal. This test is much stricter than \tet{gequal}, in
particular, \typ{REAL} with different accuracies are tested different. This
relation is transitive.

\subsec{Comparison with a small integer}

\fun{int}{isexactzero}{GEN x} returns 1 (true) if \kbd{x} is exactly equal
to~0 (including \typ{INTMOD}s like \kbd{Mod(0,2)}), and 0~(false) otherwise.
This includes recursive objects, for instance vectors, whose components are $0$.

\fun{GEN}{gisexactzero}{GEN x} returns \kbd{NULL} unless \kbd{x} is exactly
equal to~0 (as per \kbd{isexactzero}). When \kbd{x} is an exact zero
return the attached scalar zero as a \typ{INT} (\kbd{gen\_0}),
a \typ{INTMOD} (\kbd{Mod(0,$N$)} for the largest possible $N$) or a
\typ{FFELT}.

\fun{int}{isrationalzero}{GEN x} returns 1 (true) if \kbd{x} is equal
to an integer~0 (excluding \typ{INTMOD}s like \kbd{Mod(0,2)}), and 0~(false)
otherwise. Contrary to \kbd{isintzero}, this includes recursive objects, for
instance vectors, whose components are $0$.

\fun{int}{ismpzero}{GEN x} returns 1 (true) if \kbd{x} is a \typ{INT} or
a \typ{REAL} equal to~0.

\fun{int}{isintzero}{GEN x} returns 1 (true) if \kbd{x} is a \typ{INT}
equal to~0.

\fun{int}{isint1}{GEN x} returns 1 (true) if \kbd{x} is a \typ{INT}
equal to~1.

\fun{int}{isintm1}{GEN x} returns 1 (true) if \kbd{x} is a \typ{INT}
equal to~$-1$.

\fun{int}{equali1}{GEN n}
Assuming that \kbd{x} is a \typ{INT}, return 1 (true) if \kbd{x} is equal to
$1$, and return 0~(false) otherwise.

\fun{int}{equalim1}{GEN n}
Assuming that \kbd{x} is a \typ{INT}, return 1 (true) if \kbd{x} is equal to
$-1$, and return 0~(false) otherwise.

\fun{int}{is_pm1}{GEN x}. Assuming that \kbd{x} is a
\emph{non-zero} \typ{INT}, return 1 (true) if \kbd{x} is equal to $-1$ or
$1$, and return 0~(false) otherwise.

\fun{int}{gequal0}{GEN x} returns 1 (true) if \kbd{x} is equal to~0, 0~(false)
otherwise.

\fun{int}{gequal1}{GEN x} returns 1 (true) if \kbd{x} is equal to~1, 0~(false)
otherwise.

\fun{int}{gequalm1}{GEN x} returns 1 (true) if \kbd{x} is equal to~$-1$,
0~(false) otherwise.


\fun{long}{gcmpsg}{long s, GEN x}

\fun{long}{gcmpgs}{GEN x, long s} comparison of \kbd{x} with the
\kbd{long}~\kbd{s}.

\fun{GEN}{gmaxsg}{long s, GEN x}

\fun{GEN}{gmaxgs}{GEN x, long s} returns the largest of \kbd{x} and
the \kbd{long}~\kbd{s} (converted to \kbd{GEN})

\fun{GEN}{gminsg}{long s, GEN x}

\fun{GEN}{gmings}{GEN x, long s} returns the smallest of \kbd{x} and the
\kbd{long}~\kbd{s} (converted to \kbd{GEN})

\fun{long}{gequalsg}{long s, GEN x}

\fun{long}{gequalgs}{GEN x, long s} returns 1 (true) if \kbd{x} is equal to
the \kbd{long}~\kbd{s}, 0~otherwise.

\section{Miscellaneous Boolean functions}

\fun{int}{isrationalzeroscalar}{GEN x} equivalent to, but faster than,
\bprog
  is_scalar_t(typ(x)) && isrationalzero(x)
@eprog

\fun{int}{isinexact}{GEN x} returns 1 (true) if $x$ has an inexact
component, and 0 (false) otherwise.

\fun{int}{isinexactreal}{GEN x} return 1 if $x$ has an inexact
\typ{REAL} component, and 0  otherwise.

\fun{int}{isrealappr}{GEN x, long e} applies (recursively) to complex inputs;
returns $1$ if $x$ is approximately real to the bit accuracy $e$, and 0
otherwise. This means that any \typ{COMPLEX} component must have imaginary part
$t$ satisfying $\kbd{gexpo}(t) < e$.

\fun{int}{isint}{GEN x, GEN *n} returns 0 (false) if \kbd{x} does not round
to an integer. Otherwise, returns 1 (true) and set \kbd{n} to the rounded
value.

\fun{int}{issmall}{GEN x, long *n} returns 0 (false) if \kbd{x} does not
round to a small integer (suitable for \kbd{itos}). Otherwise, returns 1
(true) and set \kbd{n} to the rounded value.

\fun{long}{iscomplex}{GEN x} returns 1 (true) if \kbd{x} is a complex number
(of component types embeddable into the reals) but is not itself real, 0~if
\kbd{x} is a real (not necessarily of type \typ{REAL}), or raises an error if
\kbd{x} is not embeddable into the complex numbers.

\subsec{Obsolete}

The following less convenient comparison functions and Boolean operators were
used by the historical GP interpreter. They are provided for backward
compatibility only and should not be used:

\fun{GEN}{gle}{GEN x, GEN y}

\fun{GEN}{glt}{GEN x, GEN y}

\fun{GEN}{gge}{GEN x, GEN y}

\fun{GEN}{ggt}{GEN x, GEN y}

\fun{GEN}{geq}{GEN x, GEN y}

\fun{GEN}{gne}{GEN x, GEN y}

\fun{GEN}{gor}{GEN x, GEN y}

\fun{GEN}{gand}{GEN x, GEN y}

\fun{GEN}{gnot}{GEN x, GEN y}

\section{Sorting}

\subsec{Basic sort}

\fun{GEN}{sort}{GEN x} sorts the vector \kbd{x} in ascending order using a
mergesort algorithm, and \kbd{gcmp} as the underlying comparison routine
(returns the sorted vector). This routine copies all components of $x$, use
\kbd{gen\_sort\_inplace} for a more memory-efficient function.

\fun{GEN}{lexsort}{GEN x}, as \kbd{sort}, using \kbd{lexcmp} instead of
\kbd{gcmp} as the underlying comparison routine.

\fun{GEN}{vecsort}{GEN x, GEN k}, as \kbd{sort}, but sorts the
vector \kbd{x} in ascending \emph{lexicographic} order, according to the
entries of the \typ{VECSMALL} \kbd{k}. For example,  if $\kbd{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.

\subsec{Indirect sorting}

\fun{GEN}{indexsort}{GEN x} as \kbd{sort}, but only returns the permutation
which, applied to \kbd{x}, would sort the vector. The result is a
\typ{VECSMALL}.

\fun{GEN}{indexlexsort}{GEN x}, as \kbd{indexsort}, using \kbd{lexcmp}
instead of \kbd{gcmp} as the underlying comparison routine.

\fun{GEN}{indexvecsort}{GEN x, GEN k}, as \kbd{vecsort}, but only
returns the permutation that would sort the vector \kbd{x}.

\fun{long}{vecindexmin}{GEN x} returns the index for a maximal element of $x$
(\typ{VEC}, \typ{COL} or \typ{VECSMALL}).

\fun{long}{vecindexmax}{GEN x} returns the index for a maximal element of $x$
(\typ{VEC}, \typ{COL} or \typ{VECSMALL}).

\fun{long}{vecindexmax}{GEN x}

\subsec{Generic sort and search} The following routines allow to use an
arbitrary comparison function \kbd{int (*cmp)(void* data, GEN x, GEN y)},
such that \kbd{cmp(data,x,y)} returns a negative result if $x
< y$, a positive one if $x > y$ and 0 if $x = y$. The \kbd{data} argument is
there in case your \kbd{cmp} requires additional context.

\fun{GEN}{gen_sort}{GEN x, void *data, int (*cmp)(void *,GEN,GEN)}, as
\kbd{sort}, with an explicit comparison routine.

\fun{GEN}{gen_sort_uniq}{GEN x, void *data, int (*cmp)(void *,GEN,GEN)}, as
\kbd{gen\_sort}, removing duplicate entries.

\fun{GEN}{gen_indexsort}{GEN x, void *data, int (*cmp)(void*,GEN,GEN)},
as \kbd{indexsort}.

\fun{GEN}{gen_indexsort_uniq}{GEN x, void *data, int (*cmp)(void*,GEN,GEN)},
as \kbd{indexsort}, removing duplicate entries.

\fun{void}{gen_sort_inplace}{GEN x, void *data, int (*cmp)(void*,GEN,GEN), GEN
*perm} sort \kbd{x} in place, without copying its components. If
\kbd{perm} is non-\kbd{NULL}, it is set to the permutation that would sort
the original \kbd{x}.

\fun{GEN}{gen_setminus}{GEN A, GEN B, int (*cmp)(GEN,GEN)} given two sorted
vectors $A$ and $B$, returns the vector of elements of $A$ not belonging to
$B$.

\fun{GEN}{sort_factor}{GEN y, void *data, int (*cmp)(void *,GEN,GEN)}:
assuming \kbd{y} is a factorization matrix, sorts its rows in place (no copy
is made) according to the comparison function \kbd{cmp} applied to its first
column.

\fun{GEN}{merge_sort_uniq}{GEN x,GEN y, void *data, int (*cmp)(void *,GEN,GEN)}
assuming \kbd{x} and \kbd{y} are sorted vectors, with respect to the \kbd{cmp}
comparison function, return a sorted concatenation, with duplicates removed.

\fun{GEN}{merge_factor}{GEN fx, GEN fy, void *data, int (*cmp)(void *,GEN,GEN)}
let \kbd{fx} and \kbd{fy} be factorization matrices for $X$ and $Y$
sorted with respect to the comparison function \kbd{cmp} (see
\tet{sort_factor}), returns the factorization of $X * Y$.

\fun{long}{gen_search}{GEN v, GEN y, long flag, void *data, int
(*cmp)(void*,GEN,GEN)}.\hfil\break
Let \kbd{v} be a vector sorted according to \kbd{cmp(data,a,b)}; look for an
index $i$ such that  \kbd{v[$i$]} is equal to \kbd{y}. \kbd{flag} has the
same meaning as in \kbd{setsearch}: if \kbd{flag} is 0, return $i$ if it
exists and 0 otherwise; if \kbd{flag} is non-zero, return $0$ if $i$ exists
and the index where \kbd{y} should be inserted otherwise.

\fun{long}{tablesearch}{GEN T, GEN x, int (*cmp)(GEN,GEN)} is a faster
implementation for the common case \kbd{gen\_search(T,x,0,cmp,cmp\_nodata)}.

\subsec{Further useful comparison functions}

\fun{int}{cmp_universal}{GEN x, GEN y} a somewhat arbitrary universal
comparison function, devoid of sensible mathematical meaning. It is
transitive, and returns 0 if and only if \kbd{gidentical(x,y)} is true.
Useful to sort and search vectors of arbitrary data.

\fun{int}{cmp_nodata}{void *data, GEN x, GEN y}. This function is a hack
used to pass an existing basic comparison function lacking the \kbd{data}
argument, i.e. with prototype \kbd{int (*cmp)(GEN x, GEN y)}. Instead of
\kbd{gen\_sort(x, NULL, cmp)} which may or may not work depending on how your
compiler handles typecasts between incompatible function pointers, one should
use \kbd{gen\_sort(x, (void*)cmp, cmp\_nodata)}.

Here are a few basic comparison functions, to be used with \kbd{cmp\_nodata}:

\fun{int}{ZV_cmp}{GEN x, GEN y} compare two \kbd{ZV}, which we assume have
the same length (lexicographic order).

\fun{int}{cmp_Flx}{GEN x, GEN y} compare two \kbd{Flx}, which we assume
have the same main variable (lexicographic order).

\fun{int}{cmp_RgX}{GEN x, GEN y} compare two polynomials, which we assume
have the same main variable (lexicographic order). The coefficients are
compared using \kbd{gcmp}.

\fun{int}{cmp_prime_over_p}{GEN x, GEN y} compare two prime ideals, which
we assume divide the same prime number. The comparison is ad hoc but orders
according to increasing residue degrees.

\fun{int}{cmp_prime_ideal}{GEN x, GEN y} compare two prime ideals in the same
\var{nf}. Orders by increasing primes, breaking ties using
\kbd{cmp\_prime\_over\_p}.

\fun{int}{cmp_padic}{GEN x, GEN y} compare two \typ{PADIC} (for the same
prime $p$).

Finally a more elaborate comparison function:

\fun{int}{gen_cmp_RgX}{void *data, GEN x, GEN y} compare two polynomials,
ordering first by increasing degree, then according to the coefficient
comparison function:
\bprog
  int (*cmp_coeff)(GEN,GEN) = (int(*)(GEN,GEN)) data;
@eprog

\section{Divisibility, Euclidean division}

\fun{GEN}{gdivexact}{GEN x, GEN y} returns the quotient $\kbd{x} / \kbd{y}$,
assuming $\kbd{y}$ divides $\kbd{x}$. Not stack clean if $y = 1$
(we return $x$, not a copy).

\fun{int}{gdvd}{GEN x, GEN y}  returns 1 (true) if \kbd{y} divides~\kbd{x},
0~otherwise.

\fun{GEN}{gdiventres}{GEN x, GEN y} creates a 2-component vertical
vector whose components are the true Euclidean quotient and remainder
of \kbd{x} and~\kbd{y}.

\fun{GEN}{gdivent[z]}{GEN x, GEN y[, GEN z]} yields the true Euclidean
quotient of \kbd{x} and the \typ{INT} or \typ{POL}~\kbd{y}, as per
the \kbd{\bs} GP operator.

\fun{GEN}{gdiventsg}{long s, GEN y[, GEN z]}, as \kbd{gdivent}
except that \kbd{x} is a \kbd{long}.

\fun{GEN}{gdiventgs[z]}{GEN x, long s[, GEN z]}, as \kbd{gdivent}
except that \kbd{y} is a \kbd{long}.

\fun{GEN}{gmod[z]}{GEN x, GEN y[, GEN z]} yields the remainder of \kbd{x}
modulo the \typ{INT} or \typ{POL}~\kbd{y}, as per the \kbd{\%} GP operator.
A \typ{REAL} or \typ{FRAC} \kbd{y} is also allowed, in which case the
remainder is the unique real $r$ such that $0 \leq r < |\kbd{y}|$ and
$\kbd{y} = q\kbd{x} + r$ for some (in fact unique) integer $q$.

\fun{GEN}{gmodsg}{long s, GEN y[, GEN z]} as \kbd{gmod}, except \kbd{x} is
a \kbd{long}.

\fun{GEN}{gmodgs}{GEN x, long s[, GEN z]} as \kbd{gmod}, except \kbd{y} is
a \kbd{long}.

\fun{GEN}{gdivmod}{GEN x, GEN y, GEN *r} If \kbd{r} is not equal to
\kbd{NULL} or \kbd{ONLY\_REM}, creates the (false) Euclidean quotient of
\kbd{x} and~\kbd{y}, and puts (the address of) the remainder into~\kbd{*r}.
If \kbd{r} is equal to \kbd{NULL}, do not create the remainder, and if
\kbd{r} is equal to \kbd{ONLY\_REM}, create and output only the remainder.
The remainder is created after the quotient and can be disposed of
individually with a \kbd{cgiv(r)}.

\fun{GEN}{poldivrem}{GEN x, GEN y, GEN *r} same as \key{gdivmod} but
specifically for \typ{POL}s~\kbd{x} and~\kbd{y}, not necessarily in the same
variable. Either of \kbd{x} and \kbd{y} may also be scalars, treated as
polynomials of degree $0$.

\fun{GEN}{gdeuc}{GEN x, GEN y} creates the Euclidean quotient of the
\typ{POL}s~\kbd{x} and~\kbd{y}. Either of \kbd{x} and \kbd{y} may also be
scalars, treated as polynomials of degree $0$.

\fun{GEN}{grem}{GEN x, GEN y} creates the Euclidean remainder of the
\typ{POL}~\kbd{x} divided by the \typ{POL}~\kbd{y}. Either of \kbd{x} and
\kbd{y} may also be scalars, treated as polynomials of degree $0$.


\fun{GEN}{gdivround}{GEN x, GEN y} if \kbd{x} and \kbd{y} are real
(\typ{INT}, \typ{REAL}, \typ{FRAC}), return the rounded Euclidean quotient of
$x$ and $y$ as per the \kbd{\bs/} GP operator. Operate componentwise if
\kbd{x} is a \typ{COL}, \typ{VEC} or \typ{MAT}. Otherwise as \key{gdivent}.

\fun{GEN}{centermod_i}{GEN x, GEN y, GEN y2}, as \kbd{centermodii},
componentwise.

\fun{GEN}{centermod}{GEN x, GEN y}, as \kbd{centermod\_i}, except that
\kbd{y2} is computed (and left on the stack for efficiency).

\fun{GEN}{ginvmod}{GEN x, GEN y} creates the inverse of \kbd{x} modulo \kbd{y}
when it exists. \kbd{y} must be of type \typ{INT} (in which case \kbd{x} is
of type \typ{INT}) or \typ{POL} (in which case \kbd{x} is either a scalar
type or a \typ{POL}).

\section{GCD, content and primitive part}

\subsec{Generic}

\fun{GEN}{resultant}{GEN x, GEN y} creates the resultant of the \typ{POL}s
\kbd{x} and~\kbd{y} computed using Sylvester's matrix (inexact inputs), a
modular algorithm (inputs in $\Q[X]$) or the subresultant algorithm, as
optimized by Lazard and Ducos. Either of \kbd{x} and \kbd{y} may also be
scalars (treated as polynomials of degree $0$)

\fun{GEN}{ggcd}{GEN x, GEN y} creates the GCD of \kbd{x} and~\kbd{y}.

\fun{GEN}{glcm}{GEN x, GEN y} creates the LCM of \kbd{x} and~\kbd{y}.

\fun{GEN}{gbezout}{GEN x,GEN y, GEN *u,GEN *v} returns the GCD of \kbd{x}
and~\kbd{y}, and puts (the addresses of) objects $u$ and~$v$ such that
$u\kbd{x}+v\kbd{y}=\gcd(\kbd{x},\kbd{y})$ into \kbd{*u} and~\kbd{*v}.

\fun{GEN}{subresext}{GEN x, GEN y, GEN *U, GEN *V} returns the resultant
of \kbd{x} and~\kbd{y}, and puts (the addresses of) polynomials $u$ and~$v$
such that $u\kbd{x}+v\kbd{y}=\text{Res}(\kbd{x},\kbd{y})$ into \kbd{*U}
and~\kbd{*V}.

\fun{GEN}{content}{GEN x} returns the GCD of all the components of~\kbd{x}.

\fun{GEN}{primitive_part}{GEN x, GEN *c} sets \kbd{c} to \kbd{content(x)}
and returns the primitive part \kbd{x} / \kbd{c}. A trivial content is set to
\kbd{NULL}.

\fun{GEN}{primpart}{GEN x} as above but the content is lost.
(For efficiency, the content remains on the stack.)

\subsec{Over the rationals}

\fun{long}{Q_pval}{GEN x, GEN p} valuation at the \typ{INT} \kbd{p}
of the \typ{INT} or \typ{FRAC}~\kbd{x}.

\fun{long}{Q_pvalrem}{GEN x, GEN p, GEN *r} returns the valuation $e$ at the
\typ{INT} \kbd{p} of the \typ{INT} or \typ{FRAC}~\kbd{x}. The quotient
$\kbd{x}/\kbd{p}^{e}$ is returned in~\kbd{*r}.

\fun{GEN}{Q_abs}{GEN x} absolute value of the \typ{INT} or
\typ{FRAC}~\kbd{x}.

\fun{GEN}{Qdivii}{GEN x, GEN y}, assuming $x$ and $y$
are both of type \typ{INT}, return the quotient $x/y$ as a \typ{INT} or
\typ{FRAC}; marginally faster than \kbd{gdiv}.

\fun{GEN}{Q_abs_shallow}{GEN x} $x$ being a \typ{INT} or a \typ{FRAC}, returns
a shallow copy of $|x|$, in particular returns $x$ itself when $x \geq 0$, and
\kbd{gneg($x$)} otherwise.

\fun{GEN}{Q_gcd}{GEN x, GEN y} gcd of the \typ{INT} or \typ{FRAC}~\kbd{x}
and~\kbd{y}.
\smallskip

In the following functions, arguments belong to a $M\otimes_\Z\Q$
for some natural $\Z$-module $M$, e.g. multivariate polynomials with integer
coefficients (or vectors/matrices recursively built from such objects), and
an element of $M$ is said to be \emph{integral}.
We are interested in contents, denominators, etc. with respect to this
canonical integral structure; in particular, contents belong to $\Q$,
denominators to $\Z$. For instance the $\Q$-content of $(1/2)xy$ is $(1/2)$,
and its $\Q$-denominator is $2$, whereas \kbd{content} would return $y/2$ and
\kbd{denom}~1.

\fun{GEN}{Q_content}{GEN x} the $\Q$-content of $x$

\fun{GEN}{Q_denom}{GEN x} the $\Q$-denominator of $x$. Shallow function.

\fun{GEN}{Q_primitive_part}{GEN x, GEN *c} sets \kbd{c} to the $\Q$-content
of \kbd{x} and returns \kbd{x / c}, which is integral.

\fun{GEN}{Q_primpart}{GEN x} as above but the content is lost. (For
efficiency, the content remains on the stack.)

\fun{GEN}{Q_remove_denom}{GEN x, GEN *ptd} sets \kbd{d} to the
$\Q$-denominator of \kbd{x} and returns \kbd{x * d}, which is integral.
Shallow function.

\fun{GEN}{Q_div_to_int}{GEN x, GEN c} returns \kbd{x / c}, assuming $c$
is a rational number (\typ{INT} or \typ{FRAC}) and the result is integral.

\fun{GEN}{Q_mul_to_int}{GEN x, GEN c} returns \kbd{x * c}, assuming $c$
is a rational number (\typ{INT} or \typ{FRAC}) and the result is integral.

\fun{GEN}{Q_muli_to_int}{GEN x, GEN d} returns \kbd{x * c}, assuming $c$
is a \typ{INT} and the result is integral.

\fun{GEN}{mul_content}{GEN cx, GEN cy}  \kbd{cx} and \kbd{cy} are
as set by \kbd{primitive\_part}: either a \kbd{GEN} or \kbd{NULL}
representing the trivial content $1$. Returns their product (either a
\kbd{GEN} or \kbd{NULL}).

\fun{GEN}{mul_denom}{GEN dx, GEN dy} \kbd{dx} and \kbd{dy} are
as set by \kbd{Q\_remove\_denom}: either a \typ{INT} or \kbd{NULL} representing
the trivial denominator $1$. Returns their product (either a \typ{INT} or
\kbd{NULL}).

\section{Generic arithmetic operators}

\subsec{Unary operators}

\fun{GEN}{gneg[z]}{GEN x[, GEN z]} yields $-\kbd{x}$.

\fun{GEN}{gneg_i}{GEN x} shallow function yielding $-\kbd{x}$.

\fun{GEN}{gabs[z]}{GEN x[, GEN z]} yields $|\kbd{x}|$.

\fun{GEN}{gsqr}{GEN x} creates the square of~\kbd{x}.

\fun{GEN}{ginv}{GEN x} creates the inverse of~\kbd{x}.

\subsec{Binary operators}

Let ``\op'' be a binary operation among

\op=\key{add}: addition (\kbd{x + y}).

\op=\key{sub}: subtraction (\kbd{x - y}).

\op=\key{mul}: multiplication (\kbd{x * y}).

\op=\key{div}: division (\kbd{x / y}).

\noindent The names and prototypes of the functions corresponding
to \op\ are as follows:

\funno{GEN}{g\op}{GEN x, GEN y}

\funno{GEN}{g\op gs}{GEN x, long s}

\funno{GEN}{g\op sg}{long s, GEN y}

\noindent Explicitly

\fun{GEN}{gadd}{GEN x, GEN y}, \fun{GEN}{gaddgs}{GEN x, long s},
\fun{GEN}{gaddsg}{long s, GEN x}

\fun{GEN}{gmul}{GEN x, GEN y}, \fun{GEN}{gmulgs}{GEN x, long s},
\fun{GEN}{gmulsg}{long s, GEN x}

\fun{GEN}{gsub}{GEN x, GEN y}, \fun{GEN}{gsubgs}{GEN x, long s},
\fun{GEN}{gsubsg}{long s, GEN x}

\fun{GEN}{gdiv}{GEN x, GEN y}, \fun{GEN}{gdivgs}{GEN x, long s},
\fun{GEN}{gdivsg}{long s, GEN x}


\fun{GEN}{gpow}{GEN x, GEN y, long l} creates $\kbd{x}^{\kbd{y}}$. If
\kbd{y} is a \typ{INT}, return \kbd{powgi(x,y)} (the precision \kbd{l} is not
taken into account). Otherwise, the result is $\exp(\kbd{y}*\log(\kbd{x}))$
where exact arguments are converted to floats of precision~\kbd{l} in case of
need; if there is no need, for instance if $x$ is a \typ{REAL}, $l$ is
ignored. Indeed, if $x$ is a \typ{REAL}, the accuracy of $\log x$ is
determined from the accuracy of $x$, it is no problem to multiply by $y$,
even if it is an exact type, and the accuracy of the exponential is
determined, exactly as in the case of the initial $\log x$.

\fun{GEN}{gpowgs}{GEN x, long n} creates $\kbd{x}^{\kbd{n}}$ using
binary powering. To treat the special case $n = 0$, we consider
\kbd{gpowgs} as a series of \kbd{gmul}, so we follow the rule of returning
result which is as exact as possible given the input. More precisely,
we return

\item \kbd{gen\_1} if $x$ has type \typ{INT}, \typ{REAL},  \typ{FRAC}, or
\typ{PADIC}

\item \kbd{Mod(1,N)} if $x$ is a \typ{INTMOD} modulo $N$.

\item \kbd{gen\_1} for \typ{COMPLEX}, \typ{QUAD} unless one component
is a \typ{INTMOD}, in which case we return \kbd{Mod(1, N)} for a suitable
$N$ (the gcd of the moduli that appear).

\item \kbd{FF\_1}$(x)$ for a \typ{FFELT}.

\item \kbd{RgX\_get\_1}$(x)$ for a \typ{POL}.

\item \kbd{qfi\_1}$(x)$ and \kbd{qfr\_1}$(x)$ for \typ{QFI} and \typ{QFR}.

\item the identity permutation for \typ{VECSMALL}.

\item etc.

Of course, the only practical use of this routine for $n = 0$ is
to obtain the multiplicative neutral element in the base ring (or to treat
marginal cases that should be special cased anyway if there is the slightest
doubt about what the result should be).

\fun{GEN}{powgi}{GEN x, GEN y} creates $\kbd{x}^{\kbd{y}}$, where \kbd{y} is a
\typ{INT}, using left-shift binary powering. The case where $y = 0$
(as all cases where $y$ is small) is handled by \kbd{gpowgs(x, 0)}.

\fun{GEN}{gpowers}{GEN x, long n} returns the vector $[1,x,\dots,x^n]$.

\fun{GEN}{grootsof1}{long n, long prec} returns the vector
$[1,x,\dots,x^{n-1}]$, where $x$ is the $n$-th root of unity $\exp(2i\pi/n)$.

\fun{GEN}{gsqrpowers}{GEN x, long n} returns the vector $[x,x^4,\dots,x^{n^2}]$.

In addition we also have the obsolete forms:

\fun{void}{gaddz}{GEN x, GEN y, GEN z}

\fun{void}{gsubz}{GEN x, GEN y, GEN z}

\fun{void}{gmulz}{GEN x, GEN y, GEN z}

\fun{void}{gdivz}{GEN x, GEN y, GEN z}

\section{Generic operators: product, powering, factorback}

To describe the following functions, we use the following private typedefs
to simplify the description:
\bprog
  typedef (*F0)(void *);
  typedef (*F1)(void *, GEN);
  typedef (*F2)(void *, GEN, GEN);
@eprog
\noindent They correspond to generic functions with one and two arguments
respectively (the \kbd{void*} argument provides some arbitrary evaluation
context).

\fun{GEN}{gen_product}{GEN v, void *D, F2 op}
Given two objects $x,y$, assume that \kbd{op(D, $x$, $y$)} implements an
associative binary operator. If $v$ has $k$ entries, return
$$v[1]~\var{op}~v[2]~\var{op}~\ldots ~\var{op}~v[k];$$
returns \kbd{gen\_1} if $k = 0$ and a copy of $v[1]$ if $k = 1$.
Use divide and conquer strategy. Leave some garbage on stack, but suitable for
\kbd{gerepileupto} if \kbd{mul} is.

\fun{GEN}{gen_pow}{GEN x, GEN n, void *D, F1 sqr, F2 mul} $n > 0$ a
\typ{INT}, returns $x^n$; \kbd{mul(D, $x$, $y$)} implements the multiplication
in the underlying monoid; \kbd{sqr} is a (presumably optimized) shortcut for
\kbd{mul(D, $x$, $x$)}.

\fun{GEN}{gen_powu}{GEN x, ulong n, void *D, F1 sqr, F2 mul} $n > 0$,
returns $x^n$. See \tet{gen_pow}.

\fun{GEN}{gen_pow_i}{GEN x, GEN n, void *E, F1 sqr, F2 mul}
internal variant of \tet{gen_pow}, not memory-clean.

\fun{GEN}{gen_powu_i}{GEN x, ulong n, void *E, F1 sqr, F2 mul}
internal variant of \tet{gen_powu}, not memory-clean.

\fun{GEN}{gen_pow_fold}{GEN x, GEN n, void *D, F1 sqr, F1 msqr} variant
of \tet{gen_pow}, where \kbd{mul} is replaced by \kbd{msqr}, with
\kbd{msqr(D, $y$)} returning $xy^2$. In particular \kbd{D} must implicitly
contain $x$.

\fun{GEN}{gen_pow_fold_i}{GEN x, GEN n, void *E, F1 sqr, F1 msqr}
internal variant of the function \tet{gen_pow_fold}, not memory-clean.

\fun{GEN}{gen_powu_fold}{GEN x, ulong n, void *D, F1 sqr, F1 msqr}, see
\tet{gen_pow_fold}.

\fun{GEN}{gen_powu_fold_i}{GEN x, ulong n, void *E, F1 sqr, F1 msqr}
see \tet{gen_pow_fold_i}.

\fun{GEN}{gen_powers}{GEN x, long n, long usesqr, void *D, F1 sqr, F2 mul, F0 one}
returns $[\kbd{x}^0, \dots, \kbd{x}^\kbd{n}]$ as a \typ{VEC}; \kbd{mul(D,
$x$, $y$)} implements the multiplication in the underlying monoid; \kbd{sqr}
is a (presumably optimized) shortcut for \kbd{mul(D, $x$, $x$)}; \kbd{one}
returns the monoid unit. The flag \kbd{usesqr} should be set to $1$ if
squaring are faster than multiplication by $x$.

\fun{GEN}{gen_factorback}{GEN L, GEN e, F2 mul, F2 pow, void *D} generic form
of \tet{factorback}. The pair $[L,e]$ is of the form

\item \kbd{[fa, NULL]}, \kbd{fa} a two-column factorization matrix: expand it.

\item  \kbd{[v, NULL]}, $v$ a vector of objects: return their
product.

\item or \kbd{[v, e]},  $v$ a vector of objects, $e$ a vector of integral
exponents: return the product of the $v[i]^{e[i]}$.

\noindent \kbd{mul(D, $x$, $y$)} and \kbd{pow(D, $x$, $n$)}
return $xy$ and $x^n$ respectively.

\section{Matrix and polynomial norms} This section concerns only standard norms
of $\R$ and $\C$ vector spaces, not algebraic norms given by the determinant of
some multiplication operator. We have already seen type-specific functions like
\tet{ZM_supnorm} or \tet{RgM_fpnorml2} and limit ourselves to generic functions
assuming nothing about their \kbd{GEN} argument; these functions allow
the following scalar types: \typ{INT}, \typ{FRAC}, \typ{REAL}, \typ{COMPLEX},
\typ{QUAD} and are defined recursively (in terms of norms of their components)
for the following ``container'' types: \typ{POL}, \typ{VEC}, \typ{COL} and
\typ{MAT}. They raise an error if some other type appears in the argument.

\fun{GEN}{gnorml2}{GEN x} The norm of a scalar is the square of its complex
modulus, the norm of a recursive type is the sum of the norms of its components.
For polynomials, vectors or matrices of complex numbers one recovers the
\emph{square} of the usual $L^2$ norm. In most applications, the missing square
root computation can be skipped.

\fun{GEN}{gnorml1}{GEN x, long prec} The norm of a scalar is its complex
modulus, the norm of a recursive type is the sum of the norms of its components.
For polynomials, vectors or matrices of complex numbers one recovers
the usual $L^1$ norm. One must include a real precision \kbd{prec} in case
the inputs include \typ{COMPLEX} or \typ{QUAD} with exact rational components:
a square root must be computed and we must choose an accuracy.

\fun{GEN}{gnorml1_fake}{GEN x} as \tet{gnorml1}, except that the norm
of a \typ{QUAD} $x + wy$ or \typ{COMPLEX} $x + Iy$ is defined as
$|x| + |y|$, where we use the ordinary real absolute value. This is still a norm
of $\R$ vector spaces, which is easier to compute than
\kbd{gnorml1} and can often be used in its place.

\fun{GEN}{gsupnorm}{GEN x, long prec} The norm of a scalar is its complex
modulus, the norm of a recursive type is the max of the norms of its
components. A precision \kbd{prec} must be included for the same reason as in
\kbd{gnorml1}.

\fun{void}{gsupnorm_aux}{GEN x, GEN *m, GEN *m2, long prec}
is the low-level function underlying
\kbd{gsupnorm}, used as follows:
\bprog
  GEN m = NULL, m2 = NULL;
  gsupnorm_aux(x, &m, &m2);
@eprog
After the call, the sup norm of $x$ is the min of \kbd{m} and the square root
of \kbd{m2};  one or both of \kbd{m}, \kbd{m2} may be \kbd{NULL}, in
which case it must be omitted. You may initially set \kbd{m} and \kbd{m2} to
non-\kbd{NULL} values, in which case, the above procedure yields the max of
(the initial) \kbd{m}, the square root of (the initial) \kbd{m2}, and the sup
norm of $x$.

The strange interface is due to the fact that $|z|^2$ is easier to compute
than $|z|$ for a \typ{QUAD} or \typ{COMPLEX} $z$: \kbd{m2} is the max of
those $|z|^2$, and \kbd{m} is the max of the other $|z|$.

\section{Substitution and evaluation}

\fun{GEN}{gsubst}{GEN x, long v, GEN y} substitutes the object \kbd{y}
into~\kbd{x} for the variable number~\kbd{v}.

\fun{GEN}{poleval}{GEN q, GEN x} evaluates the \typ{POL} or \typ{RFRAC}
$q$ at $x$. For convenience, a \typ{VEC} or \typ{COL} is also recognized as
the \typ{POL} \kbd{gtovecrev(q)}.

\fun{GEN}{RgX_cxeval}{GEN T, GEN x, GEN xi} evaluate the \typ{POL} $T$
at $x$ via Horner's scheme. If \var{xi} is not \kbd{NULL} it must be equal to
$1/x$ and we evaluate $x^{\deg T}T(1/x)$ instead. This is useful when
$|x| > 1$ is a \typ{REAL} or an inexact \typ{COMPLEX} and $T$ has
``balanced'' coefficients, since the evaluation becomes numerically stable.

\fun{GEN}{RgX_RgM_eval}{GEN q, GEN x} evaluates the \typ{POL} $q$ at the
square matrix $x$.

\fun{GEN}{RgX_RgMV_eval}{GEN f, GEN V} returns
the evaluation $\kbd{f}(\kbd{x})$, assuming that \kbd{V} was computed by
$\kbd{FpXQ\_powers}(\kbd{x}, n)$ for some $n>1$.

\fun{GEN}{qfeval}{GEN q, GEN x} evaluates the quadratic form
$q$ (symmetric matrix) at $x$ (column vector of compatible dimensions).

\fun{GEN}{qfevalb}{GEN q, GEN x, GEN y} evaluates the polar bilinear form
attached to the quadratic form $q$ (symmetric matrix) at $x$, $y$ (column
vectors of compatible dimensions).

\fun{GEN}{hqfeval}{GEN q, GEN x} evaluates the Hermitian form $q$
(a Hermitian complex matrix) at $x$.

\fun{GEN}{qf_apply_RgM}{GEN q, GEN M} $q$ is a symmetric $n\times n$ matrix,
$M$ an $n\times k$ matrix, return $M' q M$.

\fun{GEN}{qf_apply_ZM}{GEN q, GEN M} as above assuming that both
$q$ and $M$ have integer entries.

\newpage
\chapter{Miscellaneous mathematical functions}

\section{Fractions}

\fun{GEN}{absfrac}{GEN x} returns the absolute value of the \typ{FRAC} $x$.

\fun{GEN}{absfrac_shallow}{GEN x} $x$ being a \typ{FRAC}, returns a shallow
copy of $|x|$, in particular returns $x$ itself when $x \geq 0$, and
\kbd{gneg($x$)} otherwise.

\fun{GEN}{sqrfrac}{GEN x} returns the square of the \typ{FRAC} $x$.

\section{Real numbers}

\fun{GEN}{R_abs}{GEN x} $x$ being a \typ{INT}, a \typ{REAL} or a
\typ{FRAC}, returns $|x|$.

\fun{GEN}{R_abs_shallow}{GEN x} $x$ being a \typ{INT}, a \typ{REAL} or a
\typ{FRAC}, returns a shallow copy of $|x|$, in particular returns $x$ itself
when $x \geq 0$, and \kbd{gneg($x$)} otherwise.

\fun{GEN}{modRr_safe}{GEN x, GEN y} let $x$ be a \typ{INT}, a \typ{REAL} or
\typ{FRAC} and let $y$ be a \typ{REAL}. Return $x\% y$ unless the input
accuracy is unsufficient to compute the floor or $x/y$ in which case we
return \kbd{NULL}.

\section{Complex numbers}

\fun{GEN}{imag}{GEN x} returns a copy of the imaginary part of \kbd{x}.

\fun{GEN}{real}{GEN x} returns a copy of the real part of \kbd{x}. If \kbd{x}
is a \typ{QUAD}, returns the coefficient of $1$ in the ``canonical'' integral
basis $(1,\omega)$.

The last two functions are shallow, and not suitable for \tet{gerepileupto}:

\fun{GEN}{imag_i}{GEN x} as \kbd{gimag}, returns a pointer to the imaginary
part.
\fun{GEN}{real_i}{GEN x} as \kbd{greal}, returns a pointer to the real part.

\fun{GEN}{mulreal}{GEN x, GEN} returns the real part of $xy$;
$x,y$ have type \typ{INT}, \typ{FRAC}, \typ{REAL} or \typ{COMPLEX}. See also
\kbd{RgM\_mulreal}.

\fun{GEN}{cxnorm}{GEN x} norm of the \typ{COMPLEX} $x$ (modulus squared).

\fun{GEN}{cxexpm1}{GEN x} returns $\exp(x)-1$, for a \typ{COMPLEX} $x$.

\section{Quadratic numbers and binary quadratic forms}

\fun{GEN}{quad_disc}{GEN x} returns the discriminant of the \typ{QUAD} $x$.

\fun{GEN}{quadnorm}{GEN x} norm of the \typ{QUAD} $x$.

\fun{GEN}{qfb_disc}{GEN x} returns the discriminant of the \typ{QFI}
or \typ{QFR} \kbd{x}.

\fun{GEN}{qfb_disc3}{GEN x, GEN y, GEN z} returns $y^2 - 4xz$ assuming all
inputs are \typ{INT}s. Not stack-clean.

\fun{GEN}{qfb_apply_ZM}{GEN q, GEN g} returns $q \circ g$.

\fun{GEN}{qfbforms}{GEN D} given a discriminant $D < 0$, return the list
of reduced forms of discriminant $D$ as \typ{VECSMALL} with 3 components.
The primitive forms in the list enumerate the class group of the quadratic
order of discriminant $D$; if $D$ is fundamental, all returned forms
are automatically primitive.

\section{Polynomials}\label{se:polynomials}

\fun{GEN}{truecoeff}{GEN x, long n} returns \kbd{polcoeff0(x,n, -1)}, i.e.
the coefficient of the term of degree \kbd{n} in the main variable.

\fun{GEN}{polcoeff_i}{GEN x, long n, long v} internal shallow function. Rewrite
$x$ as a Laurent polynomial in the variable $v$ and returns its coefficient
of degree $n$ (\kbd{gen\_0} if this falls outside the coefficient array).
Allow \typ{POL}, \typ{SER}, \typ{RFRAC} and scalars.

\fun{long}{degree}{GEN x} returns \kbd{poldegree(x, -1)}, the degree of
\kbd{x} with respect to its main variable, with the usual meaning if the
leading coefficient of $x$ is non-zero. If the sign of $x$ is $0$, this
function always returns $-1$. Otherwise, we return the index of the leading
coefficient of $x$, i.e. the coefficient of largest index stored in $x$.
For instance the ``degrees'' of
\bprog
  0. E-38 * x^4 + 0.E-19 * x + 1
  Mod(0,2) * x^0    \\ sign is 0 !
@eprog\noindent are $4$ and $-1$ respectively.

\fun{long}{degpol}{GEN x} is a simple macro returning \kbd{lg(x) - 3}.
This is the degree of the \typ{POL}~\kbd{x} with respect to its main
variable, \emph{if} its leading coefficient is non-zero (a rational $0$ is
impossible, but an inexact $0$ is allowed, as well as an exact modular $0$,
e.g. \kbd{Mod(0,2)}). If $x$ has no coefficients (rational $0$ polynomial),
its length is $2$ and we return the expected $-1$.

\fun{GEN}{characteristic}{GEN x} returns the characteristic of the
base ring over which the polynomial is defined (as defined by \typ{INTMOD}
and \typ{FFELT} components). The function raises an exception if incompatible
primes arise from \typ{FFELT} and \typ{PADIC} components. Shallow function.

\fun{GEN}{residual_characteristic}{GEN x} returns a kind of ``residual
characteristic'' of the base ring over which the polynomial is defined. This
is defined as the gcd of all moduli \typ{INTMOD}s occurring in the structure,
as well as primes $p$ arising from \typ{PADIC}s or \typ{FFELT}s. The function
raises an exception if incompatible primes arise from \typ{FFELT} and
\typ{PADIC} components. Shallow function.

\fun{GEN}{resultant}{GEN x,GEN y} resultant of \kbd{x} and \kbd{y}, with respect
to the main variable of highest priority. Uses either
the subresultant algorithm (generic case), a modular algorithm (inputs in
$\Q[X]$) or Sylvester's matrix (inexact inputs).

\fun{GEN}{resultant2}{GEN x, GEN y} resultant of \kbd{x} and \kbd{y}, with
respect to the main variable of highest priority. Computes the determinant
of Sylvester's matrix.

\fun{GEN}{resultant_all}{GEN u, GEN v, GEN *sol} returns
\kbd{resultant(x,y)}. If \kbd{sol} is not \kbd{NULL}, sets it to the last
non-constant remainder in the polynomial remainder sequence if such a sequence
was computed, and to \kbd{gen\_0} otherwise (e.g. polynomials of degree 0,
$u,v$ in $\Q[X]$).

\fun{GEN}{cleanroots}{GEN x, long prec} returns the complex roots of
the complex polynomial $x$ (with coefficients \typ{INT}, \typ{FRAC},
\typ{REAL} or \typ{COMPLEX} of the above). The roots are returned
as \typ{REAL} or \typ{COMPLEX} of \typ{REAL}s of precision \kbd{prec}
(guaranteeing a non-$0$ imaginary part). See \tet{QX_complex_roots}.

\fun{double}{fujiwara_bound}{GEN x} return a quick upper bound for the
logarithm in base $2$ of the modulus of the largest complex roots of
the polynomial $x$ (complex coefficients).

\fun{double}{fujiwara_bound_real}{GEN x, long sign} return a quick upper
bound for the logarithm in base $2$ of the absolute value of the largest
real root of sign \var{sign} ($1$ or $-1$), for the polynomial $x$ (real
coefficients).

\fun{GEN}{polmod_to_embed}{GEN x, long prec} return the vector of complex
embeddings of the \typ{POLMOD} $x$ (with complex coefficients). Shallow
function, simple complex variant of \tet{conjvec}.

\section{Power series}

\fun{GEN}{sertoser}{GEN x, long prec} return the \typ{SER} $x$ truncated
or extended (with zeros) to \kbd{prec} terms. Shallow function, assume
that $\kbd{prec} \geq 0$.

\fun{GEN}{derivser}{GEN x} returns the derivative of the \typ{SER} \kbd{x}
with respect to its main variable.

\fun{GEN}{integser}{GEN x} returns the primitive of the \typ{SER} \kbd{x}
with respect to its main variable.

\fun{GEN}{truecoeff}{GEN x, long n} returns \kbd{polcoeff0(x,n, -1)}, i.e.
the coefficient of the term of degree \kbd{n} in the main variable.

\fun{GEN}{ser_unscale}{GEN P, GEN h} return $P(h x)$, not memory clean.

\fun{GEN}{ser_normalize}{GEN x} divide $x$ by its ``leading term'' so that
the series is either $0$ or equal to $t^v(1+O(t))$. Shallow function if the
``leading term'' is $1$.

\fun{int}{ser_isexactzero}{GEN x} return $1$ if $x$ is a zero series, all
of whose known coefficients are exact zeroes; this implies that
$\kbd{sign}(x) = 0$ and $\kbd{lg}(x) \leq 3$.

\fun{GEN}{ser_inv}{GEN x} return the inverse of the \typ{SER} $x$ using
Newton iteration. This is in general slower than \kbd{ginv} unless the
precision is huge (hundreds of terms, where the threshold depends strongly
on the base field).

\section{Functions to handle \typ{FFELT}}
These functions define the public interface of the \typ{FFELT} type to use in
generic functions.  However, in specific functions, it is better to use the
functions class \kbd{FpXQ} and/or \kbd{Flxq} as appropriate.

\fun{GEN}{FF_p}{GEN a} returns the characteristic of the definition field of the
\typ{FFELT} element \kbd{a}.

\fun{long}{FF_f}{GEN a} returns the dimension of the definition field over
its prime field; the cardinality of the dimension field is thus $p^f$.

\fun{GEN}{FF_p_i}{GEN a} shallow version of \kbd{FF\_p}.

\fun{GEN}{FF_q}{GEN a} returns the cardinality of the definition field of the
\typ{FFELT} element \kbd{a}.

\fun{GEN}{FF_mod}{GEN a} returns the polynomial (with reduced \typ{INT}
coefficients) defining the finite field, in the variable used to display $a$.

\fun{GEN}{FF_to_FpXQ}{GEN a} converts the \typ{FFELT} \kbd{a} to a polynomial
$P$ with reduced \typ{INT} coefficients such that $a=P(g)$ where $g$ is the
generator of the finite field returned by \kbd{ffgen}, in the variable used to
display $g$.

\fun{GEN}{FF_to_FpXQ_i}{GEN a} shallow version of \kbd{FF\_to\_FpXQ}.

\fun{GEN}{FF_to_F2xq}{GEN a} converts the \typ{FFELT} \kbd{a} to a \kbd{F2x}
$P$ such that $a=P(g)$ where $g$ is the generator of the finite field returned
by \kbd{ffgen}, in the variable used to display $g$. This only work if the
characteristic is $2$.

\fun{GEN}{FF_to_F2xq_i}{GEN a} shallow version of \kbd{FF\_to\_F2xq}.

\fun{GEN}{FF_to_Flxq}{GEN a} converts the \typ{FFELT} \kbd{a} to a \kbd{Flx}
$P$ such that $a=P(g)$ where $g$ is the generator of the finite field returned
by \kbd{ffgen}, in the variable used to display $g$. This only work if the
characteristic is small enough.

\fun{GEN}{FF_to_Flxq_i}{GEN a} shallow version of \kbd{FF\_to\_Flxq}.

\fun{GEN}{p_to_FF}{GEN p, long v} returns a \typ{FFELT} equal to $1$ in the
finite field $\Z/p\Z$. Useful for generic code that wants to handle
(inefficiently) $\Z/p\Z$ as if it were not a prime field.

\fun{GEN}{Tp_to_FF}{GEN T, GEN p} returns a \typ{FFELT} equal to $1$ in the
finite field $\F_p/(T)$, where $T$ is a \kbd{ZX}, assumed to be irreducible
modulo $p$, or \kbd{NULL} in which case the routine acts as \tet{p_to_FF(p,0)}.
No checks.

\fun{GEN}{Fq_to_FF}{GEN x, GEN ff} returns a \typ{FFELT} equal to $x$
in the finite field defined by the \typ{FFELT} \kbd{ff}, where
$x$ is an \kbd{Fq} (either a \typ{INT} or a \kbd{ZX}: a \typ{POL} with
\typ{INT} coefficients). No checks.

\fun{GEN}{FqX_to_FFX}{GEN x, GEN ff} given an \kbd{FqX} $x$,
return the polynomial with \typ{FFELT} coefficients obtained by
applying \tet{Fq_to_FF} coefficientwise. No checks, and no normalization
if the leading coefficient maps to $0$.

\fun{GEN}{FF_1}{GEN a} returns the unity in the definition field of the
\typ{FFELT} element \kbd{a}.

\fun{GEN}{FF_zero}{GEN a} returns the zero element of the definition field of
the \typ{FFELT} element \kbd{a}.

\fun{int}{FF_equal0}{GEN a} returns $1$ if the \typ{FFELT} \kbd{a} is equal
to $0$ else returns $0$.

\fun{int}{FF_equal1}{GEN a} returns $1$ if the \typ{FFELT} \kbd{a} is equal
to $1$ else returns $0$.

\fun{int}{FF_equalm1}{GEN a} returns $-1$ if the \typ{FFELT} \kbd{a} is equal
to $1$ else returns $0$.

\fun{int}{FF_equal}{GEN a, GEN b} return $1$ if the \typ{FFELT} \kbd{a} and
\kbd{b} have the same definition field and are equal, else $0$.

\fun{int}{FF_samefield}{GEN a, GEN b} return $1$ if the \typ{FFELT} \kbd{a} and
\kbd{b} have the same definition field, else $0$.

\fun{int}{Rg_is_FF}{GEN c, GEN *ff} to be called successively on many objects,
setting \kbd{*ff = NULL} (unset) initially. Returns $1$ as long as $c$ is a
\typ{FFELT} defined over the same field as \kbd{*ff} (setting \kbd{*ff = c}
if unset), and $0$ otherwise.

\fun{int}{RgC_is_FFC}{GEN x, GEN *ff} apply \tet{Rg_is_FF} successively to all
components of the \typ{VEC} or \typ{COL} $x$. Return $0$ if one call fails,
and $1$ otherwise.

\fun{int}{RgM_is_FFM}{GEN x, GEN *ff} apply \tet{Rg_is_FF} to all components
of the \typ{MAT}. Return $0$ if one call fails, and $1$ otherwise.

\fun{GEN}{FF_add}{GEN a, GEN b} returns $a+b$ where \kbd{a} and \kbd{b} are
\typ{FFELT} having the same definition field.

\fun{GEN}{FF_Z_add}{GEN a, GEN x} returns $a+x$, where \kbd{a} is a
\typ{FFELT}, and \kbd{x} is a \typ{INT}, the computation being
performed in the definition field of \kbd{a}.

\fun{GEN}{FF_Q_add}{GEN a, GEN x} returns $a+x$, where \kbd{a} is a
\typ{FFELT}, and \kbd{x} is a \typ{RFRAC}, the computation being
performed in the definition field of \kbd{a}.

\fun{GEN}{FF_sub}{GEN a, GEN b} returns $a-b$ where \kbd{a} and \kbd{b} are
\typ{FFELT} having the same definition field.

\fun{GEN}{FF_mul}{GEN a, GEN b} returns $a\*b$ where \kbd{a} and \kbd{b} are
\typ{FFELT} having the same definition field.

\fun{GEN}{FF_Z_mul}{GEN a, GEN b} returns $a\*b$, where \kbd{a} is a
\typ{FFELT}, and \kbd{b} is a \typ{INT}, the computation being
performed in the definition field of \kbd{a}.

\fun{GEN}{FF_div}{GEN a, GEN b} returns $a/b$ where \kbd{a} and \kbd{b} are
\typ{FFELT} having the same definition field.

\fun{GEN}{FF_neg}{GEN a} returns $-a$ where \kbd{a} is a \typ{FFELT}.

\fun{GEN}{FF_neg_i}{GEN a} shallow function returning $-a$ where \kbd{a} is a
\typ{FFELT}.

\fun{GEN}{FF_inv}{GEN a} returns $a^{-1}$ where \kbd{a} is a \typ{FFELT}.

\fun{GEN}{FF_sqr}{GEN a} returns $a^2$ where \kbd{a} is a \typ{FFELT}.

\fun{GEN}{FF_mul2n}{GEN a, long n} returns $a\*2^n$ where \kbd{a} is a
\typ{FFELT}.

\fun{GEN}{FF_pow}{GEN x, GEN n} returns $a^n$ where \kbd{a} is a \typ{FFELT}
and\kbd{n} is a \typ{INT}.

\fun{GEN}{FF_Z_Z_muldiv}{GEN a, GEN x, GEN y} returns $a\*y/z$, where \kbd{a}
is a \typ{FFELT}, and \kbd{x} and \kbd{y} are \typ{INT}, the computation being
performed in the definition field of \kbd{a}.

\fun{GEN}{Z_FF_div}{GEN x, GEN a} return $x/a$ where \kbd{a} is a
\typ{FFELT}, and \kbd{x} is a \typ{INT}, the computation being
performed in the definition field of \kbd{a}.

\fun{GEN}{FF_norm}{GEN a} returns the norm of the \typ{FFELT} \kbd{a} with
respect to its definition field.

\fun{GEN}{FF_trace}{GEN a} returns the trace of the \typ{FFELT} \kbd{a} with
respect to its definition field.

\fun{GEN}{FF_conjvec}{GEN a} returns the vector of conjugates
$[a,a^p,a^{p^2},\ldots,a^{p^{n-1}}]$ where the \typ{FFELT} \kbd{a} belong to a
field with $p^n$ elements.

\fun{GEN}{FF_charpoly}{GEN a} returns the characteristic polynomial) of the
\typ{FFELT} \kbd{a} with respect to its definition field.

\fun{GEN}{FF_minpoly}{GEN a} returns the minimal polynomial of
the \typ{FFELT} \kbd{a}.

\fun{GEN}{FF_sqrt}{GEN a} returns an \typ{FFELT} $b$ such that $a=b^2$ if
it exist, where \kbd{a} is a \typ{FFELT}.

\fun{long}{FF_issquareall}{GEN x, GEN *pt} returns $1$ if \kbd{x} is a
square, and $0$ otherwise. If \kbd{x} is indeed a square, set \kbd{pt} to its
square root.

\fun{long}{FF_issquare}{GEN x} returns $1$ if \kbd{x} is a square and $0$
otherwise.

\fun{long}{FF_ispower}{GEN x, GEN K, GEN *pt} Given $K$ a positive integer,
returns $1$ if \kbd{x} is a $K$-th power, and $0$ otherwise. If \kbd{x} is
indeed a $K$-th power, set \kbd{pt} to its $K$-th root.

\fun{GEN}{FF_sqrtn}{GEN a, GEN n, GEN *zn} returns an \kbd{n}-th root of
$\kbd{a}$ if it exist. If \kbd{zn} is non-\kbd{NULL} set it to a primitive
\kbd{n}-th root of the unity.

\fun{GEN}{FF_log}{GEN a, GEN g, GEN o} the \typ{FFELT} \kbd{g} being a
generator for the definition field of the \typ{FFELT} \kbd{a}, returns a
\typ{INT} $e$ such that $a^e=g$.  If $e$ does not exists, the result is
currently undefined. If \kbd{o} is not \kbd{NULL} it is assumed to be a
factorization of the multiplicative order of \kbd{g} (as set by
\tet{FF_primroot})

\fun{GEN}{FF_order}{GEN a, GEN o} returns the order of the \typ{FFELT} \kbd{a}.
If \kbd{o} is non-\kbd{NULL}, it is assumed that \kbd{o} is a multiple of the
order of \kbd{a}.

\fun{GEN}{FF_primroot}{GEN a, GEN *o} returns a generator of the
multiplicative group of the definition field of the \typ{FFELT} \kbd{a}.
If \kbd{o} is not \kbd{NULL}, set it to the factorization of the order
of the primitive root (to speed up \tet{FF_log}).

\fun{GEN}{FFX_factor}{GEN f, GEN a} returns the factorization of the univariate
polynomial \kbd{f} over the definition field of the \typ{FFELT} \kbd{a}. The
coefficients of \kbd{f} must be of type \typ{INT}, \typ{INTMOD} or \typ{FFELT}
and compatible with \kbd{a}.

\fun{GEN}{FFX_roots}{GEN f, GEN a} returns the roots (\typ{FFELT})
of the univariate polynomial \kbd{f} over the definition field of the
\typ{FFELT} \kbd{a}. The coefficients of \kbd{f} must be of type \typ{INT},
\typ{INTMOD} or \typ{FFELT} and compatible with \kbd{a}.

\fun{GEN}{FFM_FFC_mul}{GEN M, GEN C, GEN ff} returns the product of
the matrix~\kbd{M} (\typ{MAT}) and the column vector~\kbd{C}
(\typ{COL}) over the finite field given by \kbd{ff} (\typ{FFELT}).

\fun{GEN}{FFM_ker}{GEN M, GEN ff} returns the kernel of the \typ{MAT} \kbd{M}
defined over the finite field given by the \typ{FFELT} \kbd{ff} (obtained
by \tet{RgM_is_FFM(M,\&ff)}).

\fun{GEN}{FFM_det}{GEN M, GEN ff}

\fun{GEN}{FFM_image}{GEN M, GEN ff}

\fun{GEN}{FFM_inv}{GEN M, GEN ff}

\fun{GEN}{FFM_mul}{GEN M, GEN N, GEN ff} returns the product of the
matrices \kbd{M} and~\kbd{N} (\typ{MAT}) over the finite field given
by \kbd{ff} (\typ{FFELT}).

\fun{long}{FFM_rank}{GEN M, GEN ff}

\section{Transcendental functions}

The following two functions are only useful when interacting with \kbd{gp},
to manipulate its internal default precision (expressed as a number of
decimal digits, not in words as used everywhere else):

\fun{long}{getrealprecision}{void} returns \kbd{realprecision}.

\fun{long}{setrealprecision}{long n, long *prec} sets the new
\kbd{realprecision} to $n$, which is returned. As a side effect, set
\kbd{prec} to the corresponding number of words \kbd{ndec2prec(n)}.

\subsec{Transcendental functions with \typ{REAL} arguments}

In the following routines, $x$ is assumed to be a \typ{REAL} and the result
is a \typ{REAL} (sometimes a \typ{COMPLEX} with \typ{REAL} components), with
the largest accuracy which can be deduced from the input. The naming scheme
is inconsistent here, since we sometimes use the prefix \kbd{mp} even though
\typ{INT} inputs are forbidden:

\fun{GEN}{sqrtr}{GEN x} returns the square root of $x$.

\fun{GEN}{cbrtr}{GEN x} returns the real cube root of $x$.

\fun{GEN}{sqrtnr}{GEN x, long n} returns the $n$-th root of $x$, assuming
$n\geq 1$ and $x > 0$. Not stack clean.

\fun{GEN}{mpcos[z]}{GEN x[, GEN z]} returns $\cos(x)$.

\fun{GEN}{mpsin[z]}{GEN x[, GEN z]} returns $\sin(x)$.

\fun{GEN}{mplog[z]}{GEN x[, GEN z]} returns $\log(x)$. We must have $x > 0$
since the result must be a \typ{REAL}. Use \kbd{glog} for the general case,
where you want such computations as $\log(-1) = I$.

\fun{GEN}{mpexp[z]}{GEN x[, GEN z]} returns $\exp(x)$.

\fun{GEN}{mpexpm1}{GEN x} returns $\exp(x)-1$, but is more accurate than
\kbd{subrs(mpexp(x), 1)}, which suffers from catastrophic cancellation if
$|x|$ is very small.

\fun{void}{mpsincosm1}{GEN x, GEN *s, GEN *c} sets $s$ and $c$ to
$\sin(x)$ and $\cos(x)-1$ respectively, where $x$ is a \typ{REAL}; the latter
is more accurate than \kbd{subrs(mpcos(y), 1)}, which suffers from
catastrophic cancellation if $|x|$ is very small.

\fun{GEN}{mpveceint1}{GEN C, GEN eC, long n} as \kbd{veceint1}; assumes
that $C > 0$ is a \typ{REAL} and that \kbd{eC} is \kbd{NULL} or \kbd{mpexp(C)}.

\fun{GEN}{mpeint1}{GEN x, GEN expx} returns \kbd{eint1}$(x)$, for a \typ{REAL}
$x\geq 0$, assuming that \kbd{expx} is \kbd{mpexp}$(x)$.

\fun{GEN}{mplambertW}{GEN y} solution $x$ of the implicit equation
$x \exp(x) = y$, for $y > 0$ a \typ{REAL}.

\noindent Useful low-level functions which \emph{disregard} the sign of $x$:

\fun{GEN}{sqrtr_abs}{GEN x} returns $\sqrt{|x|}$ assuming $x\neq 0$.

\fun{GEN}{cbrtr_abs}{GEN x} returns $|x|^{1/3}$ assuming $x\neq 0$.

\fun{GEN}{exp1r_abs}{GEN x} returns $\exp(|x|) - 1$, assuming $x \neq 0$.

\fun{GEN}{logr_abs}{GEN x} returns $\log(|x|)$, assuming $x \neq 0$.

\subsec{Other complex transcendental functions}

\fun{GEN}{szeta}{long s, long prec} returns the value of Riemann's zeta
function at the (possibly negative) integer $s\neq 1$, in relative accuracy
\kbd{prec}.

\fun{GEN}{veczeta}{GEN a, GEN b, long N, long prec} returns in a vector
all the $\zeta(aj + b)$, where $j = 0, 1, \dots, N-1$, where $a$ and $b$ are
real numbers (of arbitrary type, although \typ{INT} is treated more
efficiently) and $b > 1$.

\fun{GEN}{ggamma1m1}{GEN x, long prec} return $\Gamma(1+x) - 1$ assuming
$|x| < 1$. Guard against cancellation when $x$ is small.

\noindent A few variants on sin and cos:

\fun{void}{mpsincos}{GEN x, GEN *s, GEN *c} sets $s$ and $c$ to
$\sin(x)$ and $\cos(x)$ respectively, where $x$ is a \typ{REAL}

\fun{GEN}{expIr}{GEN x} returns $\exp(ix)$, where $x$ is a \typ{REAL}.
The return type is \typ{COMPLEX} unless the imaginary part is equal to $0$
to the current accuracy (its sign is $0$).

\fun{GEN}{expIxy}{GEN x, GEN y, long prec} returns $\exp(ixy)$. Efficient
when $x$ is real and $y$ pure imaginary.

\fun{void}{gsincos}{GEN x, GEN *s, GEN *c, long prec} general case.

\fun{GEN}{rootsof1_cx}{GEN d, long prec} return $e(1/d)$ at precision
\kbd{prec}, $e(x) = \exp(2i\pi x)$.

\fun{GEN}{rootsof1u_cx}{ulong d, long prec} return $e(1/d)$ at
precision \kbd{prec}.

\noindent A generalization of \tet{affrr_fixlg}

\fun{GEN}{affc_fixlg}{GEN x, GEN res} assume \kbd{res} was allocated using
\tet{cgetc}, and that $x$ is either a \typ{REAL} or a \typ{COMPLEX}
with \typ{REAL} components. Assign $x$ to \kbd{res}, first shortening
the components of \kbd{res} if needed (in a \kbd{gerepile}-safe way). Further
convert \kbd{res} to a \typ{REAL} if $x$ is a \typ{REAL}.

\fun{GEN}{trans_eval}{const char *fun, GEN (*f) (GEN, long), GEN x, long prec}
evaluate the transcendental function $f$ (named \kbd{"fun"} at the argument
$x$ and precision \kbd{prec}. This is a quick way to implement a transcendental
function to be made available under GP, starting from a $C$ function
handling only \typ{REAL} and \typ{COMPLEX} arguments. This routine first
converts $x$ to a suitable type:

\item \typ{INT}/\typ{FRAC} to \typ{REAL} of precision \kbd{prec}, \typ{QUAD} to
\typ{REAL} or \typ{COMPLEX} of precision \kbd{prec}.

\item \typ{POLMOD} to a \typ{COL} of complex embeddings (as in \tet{conjvec})

Then evaluates the function at \typ{VEC}, \typ{COL}, \typ{MAT} arguments
coefficientwise.

\subsec{Transcendental functions with \typ{PADIC} arguments}

\fun{GEN}{Qp_exp}{GEN x} shortcut for \kbd{gexp(x, /*ignored*/prec)}

\fun{GEN}{Qp_gamma}{GEN x} shortcut for \kbd{ggamma(x, /*ignored*/prec)}

\fun{GEN}{Qp_log}{GEN x} shortcut for \kbd{glog(x, /*ignored*/prec)}

\fun{GEN}{Qp_sqrt}{GEN x} shortcut for \kbd{gsqrt(x, /*ignored*/prec)}
Return \kbd{NULL} if $x$ is not a square.

\fun{GEN}{Qp_sqrtn}{GEN x, GEN n, GEN *z} shortcut for \kbd{gsqrtn(x, n, z,
/*ignored*/prec)}. Return \kbd{NULL} if $x$ is not an $n$-th power.

\subsec{Cached constants}

The cached constant is returned at its current precision, which may be larger
than \kbd{prec}. One should always use the \kbd{mp\var{xxx}} variant:
\kbd{mppi}, \kbd{mpeuler}, or \kbd{mplog2}.

\fun{GEN}{consteuler}{long prec} precomputes Euler-Mascheroni's constant
at precision \kbd{prec}.

\fun{GEN}{constcatalan}{long prec} precomputes Catalan's constant at precision
\kbd{prec}.

\fun{GEN}{constpi}{long prec} precomputes $\pi$ at precision \kbd{prec}.

\fun{GEN}{constlog2}{long prec} precomputes $\log(2)$ at precision
\kbd{prec}.

\fun{void}{mpbern}{long n, long prec} precomputes the $n$ even
\idx{Bernoulli} numbers $B_2,\dots,B_{2n}$ as \typ{FRAC} or \typ{REAL}s of
precision \kbd{prec}. For any $2 \leq k \leq 2n$, if a floating point
approximation of $B_k$ to accuracy \kbd{prec} is enough to reconstruct it
exactly, a \typ{FRAC} is stored; otherwise a \typ{REAL} at the requested
accuracy. No more than $n$ Bernoulli numbers will ever be stored (by
\tet{bernfrac} or \tet{bernreal}), unless a subsequent call to \kbd{mpbern}
increases the cache. If \kbd{prec} is $0$, the $B_k$ are computed exactly.

The following functions use cached data if \kbd{prec} is smaller than the
precision of the cached value; otherwise the newly computed data replaces the
old cache.

\fun{GEN}{mppi}{long prec} returns $\pi$ at precision \kbd{prec}.

\fun{GEN}{Pi2n}{long n, long prec} returns $2^n\pi$ at precision \kbd{prec}.

\fun{GEN}{PiI2}{long n, long prec} returns the complex number $2\pi i$ at
precision \kbd{prec}.

\fun{GEN}{PiI2n}{long n, long prec} returns the complex number $2^n\pi i$ at
precision \kbd{prec}.

\fun{GEN}{mpeuler}{long prec} returns Euler-Mascheroni's constant at
precision \kbd{prec}.

\fun{GEN}{mpeuler}{long prec} returns Catalan's number at precision \kbd{prec}.

\fun{GEN}{mplog2}{long prec} returns $\log 2$ at precision \kbd{prec}.

\fun{GEN}{bernreal}{long i, long prec} returns the \idx{Bernoulli} number
$B_i$ as a \typ{REAL} at precision \kbd{prec}. If \kbd{mpbern(n,
p)} was called previously with $n \geq i$ and $p \geq \kbd{prec}$, then
the cached value is (converted to a \typ{REAL} of accuracy \kbd{prec} then)
returned. Otherwise, the missing value is computed. In the latter case,
if $n \geq i$, the cached table is updated.

\fun{GEN}{bernfrac}{long i} returns the \idx{Bernoulli} number $B_i$ as a
rational number (\typ{FRAC} or \typ{INT}). If a cached table includes $B_i$
as a rational number, the latter is returned. Otherwise, the missing value is
computed. In the latter case, the cached Bernoulli table may be updated.

\section{Permutations }

\noindent Permutation are represented in two different ways

\item (\kbd{perm}) a \typ{VECSMALL} $p$ representing the bijection $i\mapsto
p[i]$; unless mentioned otherwise, this is the form used in the functions
below for both input and output,

\item (\kbd{cyc}) a \typ{VEC} of \typ{VECSMALL}s representing a product of
disjoint cycles.

\fun{GEN}{identity_perm}{long n} return the identity permutation on $n$
symbols.

\fun{GEN}{cyclic_perm}{long n, long d} return the cyclic permutation mapping
$i$ to $i+d$ (mod $n$) in $S_n$. Assume that $d \leq n$.

\fun{GEN}{perm_mul}{GEN s, GEN t} multiply $s$ and $t$ (composition $s\circ t$)

\fun{GEN}{perm_conj}{GEN s, GEN t} return $sts^{-1}$.

\fun{int}{perm_commute}{GEN p, GEN q} return $1$ if $p$ and $q$ commute, 0
otherwise.

\fun{GEN}{perm_inv}{GEN p} returns the inverse of $p$.

\fun{GEN}{perm_pow}{GEN p, long n} returns $p^n$

\fun{GEN}{cyc_pow_perm}{GEN p, long n} the permutation $p$ is given as
a product of disjoint cycles (\kbd{cyc}); return $p^n$ (as a \kbd{perm}).

\fun{GEN}{cyc_pow}{GEN p, long n} the permutation $p$ is given as
a product of disjoint cycles (\kbd{cyc}); return $p^n$ (as a \kbd{cyc}).

\fun{GEN}{perm_cycles}{GEN p} return the cyclic decomposition of $p$.

\fun{long}{perm_order}{GEN p} returns the order of the permutation $p$
(as the lcm of its cycle lengths).

\fun{GEN}{vecperm_orbits}{GEN p, long n} the permutation $p\in S_n$ being
given as a product of disjoint cycles, return the orbits of the subgroup
generated by $p$ on $\{1,2,\ldots,n\}$.

\fun{GEN}{Z_to_perm}{long n, GEN x} as \kbd{numtoperm}, returning a
\typ{VECSMALL}.

\fun{GEN}{perm_to_Z}{GEN v} as \kbd{permtonum} for a \typ{VECSMALL} input.

\section{Small groups}

The small (finite) groups facility is meant to deal with subgroups of Galois
groups obtained by \tet{galoisinit} and thus is currently limited to weakly
super-solvable groups.

A group \var{grp} of order $n$ is represented by its regular representation
(for an arbitrary ordering of its element) in $S_n$.  A subgroup of such group
is represented by the restriction of the representation to the subgroup.
A \emph{small group} can be either a group or a subgroup. Thus it is embedded
in some $S_n$, where $n$ is the multiple of the order. Such an $n$ is called
the \emph{domain} of the small group. The domain of a trivial subgroup cannot
be derived from the subgroup data, so some functions require the subgroup
domain as argument.

The small group \var{grp} is represented by a \typ{VEC} with two
components:

$\var{grp}[1]$ is a generating subset $[s_1,\ldots,s_g]$ of \var{grp}
expressed as a vector of permutations of length~$n$.

$\var{grp}[2]$ contains the relative orders $[o_1,\ldots,o_g]$ of
the generators $\var{grp}[1]$.

See \tet{galoisinit} for the technical details.

\fun{GEN}{checkgroup}{GEN gal, GEN *elts} checks whether \var{gal} is a
small group or a Galois group. Returns the underlying small
group and set \var{elts} to the list of elements or to \kbd{NULL} if it is not
known.

\fun{GEN}{galois_group}{GEN gal} return the underlying small group of the
Galois group \var{gal}.

\fun{GEN}{cyclicgroup}{GEN g, long s} returns the cyclic group with generator
$g$ of order $s$.

\fun{GEN}{trivialgroup}{void} returns the trivial group.

\fun{GEN}{dicyclicgroup}{GEN g1, GEN g2, long s1, long s2} returns the group
with generators \var{g1}, \var{g2} with respecting relative orders \var{s1},
\var{s2}.

\fun{GEN}{abelian_group}{GEN v} let v be a \typ{VECSMALL} seen as the SNF of
a small abelian group, return its regular representation.

\fun{long}{group_domain}{GEN grp} returns the \kbd{domain} of the
\emph{non-trivial} small group \var{grp}. Return an error if \var{grp} is
trivial.

\fun{GEN}{group_elts}{GEN grp, long n} returns the list of elements of the
small group \var{grp} of domain \var{n} as permutations.

\fun{GEN}{group_set}{GEN grp, long n} returns a \var{F2v} $b$ such that
$b[i]$ is set if and only if the small group \var{grp} of domain \var{n}
contains a permutation sending $1$ to $i$.

\fun{GEN}{groupelts_set}{GEN elts, long n}, where \var{elts} is the list of
elements of a small group of domain \var{n}, returns a \var{F2v} $b$ such that
$b[i]$ is set if and only if the small group contains a permutation sending $1$
to $i$.

\fun{long}{group_order}{GEN grp} returns the order of the small group
\var{grp} (which is the product of the relative orders).

\fun{long}{group_isabelian}{GEN grp} returns $1$ if the small group
\var{grp} is Abelian, else $0$.

\fun{GEN}{group_abelianHNF}{GEN grp, GEN elts} if \var{grp} is not Abelian,
returns \kbd{NULL}, else returns the HNF matrix of \var{grp} with respect to
the generating family $\var{grp}[1]$. If \var{elts} is no \kbd{NULL}, it must
be the list of elements of \var{grp}.

\fun{GEN}{group_abelianSNF}{GEN grp, GEN elts} if \var{grp} is not Abelian,
returns \kbd{NULL}, else returns its cyclic decomposition. If \var{elts} is no
\kbd{NULL}, it must be the list of elements of \var{grp}.

\fun{long}{group_subgroup_isnormal}{GEN G, GEN H}, $H$ being a subgroup of the
small group $G$, returns $1$ if $H$ is normal in $G$, else $0$.

\fun{long}{group_isA4S4}{GEN grp} returns $1$ if the small group
\var{grp} is isomorphic to $A_4$, $2$ if it is isomorphic to $S_4$ and
$0$ else. This is mainly to deal with the idiosyncrasy of the format.

\fun{GEN}{group_leftcoset}{GEN G, GEN g} where $G$ is a small group and $g$ a
permutation of the same domain, the left coset $gG$ as a vector of
permutations.

\fun{GEN}{group_rightcoset}{GEN G, GEN g} where $G$ is a small group and $g$ a
permutation of the same domain, the right coset $Gg$  as a vector of
permutations.

\fun{long}{group_perm_normalize}{GEN G, GEN g} where $G$ is a small group and
$g$ a permutation of the same domain, return $1$ if $gGg^{-1}=G$, else $0$.

\fun{GEN}{group_quotient}{GEN G, GEN H}, where $G$ is a small group and
$H$ is a subgroup of $G$, returns the quotient map $G\rightarrow G/H$
as an abstract data structure.

\fun{GEN}{quotient_perm}{GEN C, GEN g} where $C$ is the quotient map
$G\rightarrow G/H$ for some subgroup $H$ of $G$ and $g$ an element of $G$,
return the image of $g$ by $C$ (i.e. the coset $gH$).

\fun{GEN}{quotient_group}{GEN C, GEN G} where $C$ is the quotient map
$G\rightarrow G/H$ for some \emph{normal} subgroup $H$ of $G$, return the
quotient group $G/H$ as a small group.

\fun{GEN}{quotient_subgroup_lift}{GEN C, GEN H, GEN S} where $C$ is the
quotient map $G\rightarrow G/H$ for some group $G$ normalizing $H$ and $S$ is
a subgroup of $G/H$, return the inverse image of $S$ by $C$.

\fun{GEN}{group_subgroups}{GEN grp} returns the list of subgroups of the
small group \var{grp} as a \typ{VEC}.

\fun{GEN}{subgroups_tableset}{GEN S, long n} where $S$ is a vector of subgroups
of domain $n$, returns a table which matchs the set of elements of the
subgroups against the index of the subgroups.

\fun{long}{tableset_find_index}{GEN tbl, GEN set} searchs the set \kbd{set} in
the table \kbd{tbl} and returns its attached index, or $0$ if not found.

\fun{GEN}{groupelts_abelian_group}{GEN elts} where \var{elts} is the list of
elements of an \emph{Abelian} small group, returns the corresponding
small group.

\fun{GEN}{groupelts_center}{GEN elts} where \var{elts} is the list of elements
of a small group, returns the list of elements of the center of the
group.

\fun{GEN}{group_export}{GEN grp, long format} exports a small group
to another format, see \tet{galoisexport}.

\fun{long}{group_ident}{GEN grp, GEN elts} returns the index of the small group
\var{grp} in the GAP4 Small Group library, see \tet{galoisidentify}. If
\var{elts} is not \kbd{NULL}, it must be the list of elements of \var{grp}.

\fun{long}{group_ident_trans}{GEN grp, GEN elts} returns the index of the
regular representation of the small group \var{grp} in the GAP4 Transitive
Group library, see \tet{polgalois}. If \var{elts} is no \kbd{NULL}, it must be
the list of elements of \var{grp}.

\newpage
\chapter{Standard data structures}

\section{Character strings}

\subsec{Functions returning a \kbd{char *}}

\fun{char*}{pari_strdup}{const char *s} returns a malloc'ed copy of $s$
(uses \kbd{pari\_malloc}).

\fun{char*}{pari_strndup}{const char *s, long n} returns a malloc'ed copy of
at most $n$ chars from $s$ (uses \kbd{pari\_malloc}). If $s$ is longer than
$n$, only $n$ characters are copied and a terminal null byte is added.

\fun{char*}{stack_strdup}{const char *s} returns a copy of $s$, allocated
on the PARI stack (uses \kbd{stack\_malloc}).

\fun{char*}{stack_strcat}{const char *s, const char *t} returns the
concatenation of $s$ and $t$, allocated on the PARI stack (uses
\kbd{stack\_malloc}).

\fun{char*}{stack_sprintf}{const char *fmt, ...} runs \kbd{pari\_sprintf}
on the given arguments, returning a string allocated on the PARI stack.

\fun{char*}{itostr}{GEN x} writes the \typ{INT} $x$ to a \tet{stack_malloc}'ed
string.

\fun{char*}{GENtostr}{GEN x}, using the current default output format
(\kbd{GP\_DATA->fmt}, which contains the output style and the number of
significant digits to print), converts $x$ to a malloc'ed string. Simple
variant of \tet{pari_sprintf}.

\fun{char*}{GENtostr_raw}{GEN x} as \tet{GENtostr} with the following
differences: 1) the output format is \tet{f_RAW}; 2) the result is allocated
on the stack and \emph{must not} be freed.

\fun{char*}{GENtostr_unquoted}{GEN x} as \tet{GENtostr_raw} with the following
additional difference: a \typ{STR} $x$ is printed without enclosing quotes
(to be used by \kbd{print}.

\fun{char*}{GENtoTeXstr}{GEN x}, as \kbd{GENtostr}, except that
\tet{f_TEX} overrides the output format from \kbd{GP\_DATA->fmt}.

\fun{char*}{RgV_to_str}{GEN g, long flag} $g$ being a vector of \kbd{GEN}s,
returns a malloc'ed string, the concatenation of the \kbd{GENtostr} applied
to its elements, except that \typ{STR} are printed without enclosing quotes.
\kbd{flag} determines the output format: \tet{f_RAW}, \tet{f_PRETTYMAT}
or \tet{f_TEX}.

\subsec{Functions returning a \typ{STR}}

\fun{GEN}{strtoGENstr}{const char *s} returns a \typ{STR} with content $s$.

\fun{GEN}{strntoGENstr}{const char *s, long n}
returns a \typ{STR} containing the first $n$ characters of $s$.

\fun{GEN}{chartoGENstr}{char c} returns a \typ{STR} containing the character
$c$.

\fun{GEN}{GENtoGENstr}{GEN x} returns a \typ{STR} containing the printed
form of $x$ (in \tet{raw} format). This is often easier to use that
\tet{GENtostr} (which returns a malloc-ed \kbd{char*}) since there is no need
to free the string after use.

\fun{GEN}{GENtoGENstr_nospace}{GEN x} as \kbd{GENtoGENstr}, removing all
spaces from the output.

\fun{GEN}{Str}{GEN g} as \tet{RgV_to_str} with output format \tet{f_RAW},
but returns a \typ{STR}, not a malloc'ed string.

\fun{GEN}{Strtex}{GEN g} as \tet{RgV_to_str} with output format \tet{f_TEX},
but returns a \typ{STR}, not a malloc'ed string.

\fun{GEN}{Strexpand}{GEN g} as \tet{RgV_to_str} with output format \tet{f_RAW},
performing tilde and environment expansion on the result. Returns a
\typ{STR}, not a malloc'ed string.

\fun{GEN}{gsprintf}{const char *fmt, ...} equivalent to
\kbd{pari\_sprintf(fmt,...}, followed by \tet{strtoGENstr}. Returns a \typ{STR},
not a malloc'ed string.

\fun{GEN}{gvsprintf}{const char *fmt, va_list ap} variadic version of
\tet{gsprintf}

\section{Output}

\subsec{Output contexts}

An output coutext, of type \tet{PariOUT}, is a \kbd{struct}
that models a stream and contains the following function pointers:
\bprog
void (*putch)(char);           /* fputc()-alike */
void (*puts)(const char*);     /* fputs()-alike */
void (*flush)(void);           /* fflush()-alike */
@eprog\noindent
The methods \tet{putch} and \tet{puts} are used to print a character
or a string respectively.  The method \tet{flush} is called to finalize a
messages.

The generic functions \tet{pari_putc}, \tet{pari_puts}, \tet{pari_flush} and
\tet{pari_printf} print according to a \emph{default output context}, which
should be sufficient for most purposes. Lower level functions are available,
which take an explicit output context as first argument:

\fun{void}{out_putc}{PariOUT *out, char c} essentially equivalent to
\kbd{out->putc(c)}. In addition, registers whether the last character printed
was a \kbd{\bs n}.

\fun{void}{out_puts}{PariOUT *out, const char *s} essentially equivalent to
\kbd{out->puts(s)}. In addition, registers whether the last character printed
was a \kbd{\bs n}.

\fun{void}{out_printf}{PariOUT *out, const char *fmt, ...}

\fun{void}{out_vprintf}{PariOUT *out, const char *fmt, va_list ap}

\noindent N.B. The function \kbd{out\_flush} does not exist since it would be
identical to \kbd{out->flush()}

\fun{int}{pari_last_was_newline}{void} returns a non-zero value if the last
character printed via \tet{out_putc} or \tet{out_puts} was \kbd{\bs
n}, and $0$ otherwise.

\fun{void}{pari_set_last_newline}{int last} sets the boolean value
to be returned by the function \tet{pari_last_was_newline} to \var{last}.

\subsec{Default output context} They are defined by the global variables
\tet{pariOut} and \tet{pariErr} for normal outputs and warnings/errors, and you
probably do not want to change them. If you \emph{do} change them, diverting
output in non-trivial ways, this probably means that you are rewriting
\kbd{gp}. For completeness, we document in this section what the default
output contexts do.

\misctitle{pariOut} writes output to the \kbd{FILE*} \tet{pari_outfile},
initialized to \tet{stdout}.  The low-level methods are actually the standard
\kbd{putc} / \kbd{fputs}, plus some magic to handle a log file if one is
open.

\misctitle{pariErr} prints to the \kbd{FILE*} \tet{pari_errfile}, initialized
to \tet{stderr}. The low-level methods are as above.

You can stick with the default \kbd{pariOut} output context and change PARI's
standard output, redirecting \tet{pari_outfile} to another file, using

\fun{void}{switchout}{const char *name} where \kbd{name} is a character string
giving the name of the file you want to write to; the output is
\emph{appended} at the end of the file. To close the file and revert to
outputting to \kbd{stdout}, call \kbd{switchout(NULL)}.

\subsec{PARI colors}
In this section we describe the low-level functions used to implement GP's
color scheme, attached to the \tet{colors} default. The following symbolic
names are attached to gp's output strings:

\item \tet{c_ERR} an error message

\item \tet{c_HIST} a history number (as in \kbd{\%1 = ...})

\item \tet{c_PROMPT} a prompt

\item \tet{c_INPUT} an input line (minus the prompt part)

\item \tet{c_OUTPUT} an output

\item \tet{c_HELP} a help message

\item \tet{c_TIME} a timer

\item \tet{c_NONE} everything else

\emph{If} the \tet{colors} default is set to a non-empty value, before gp
outputs a string, it first outputs an ANSI colors escape sequence ---
understood by most terminals ---, according to the \kbd{colors}
specifications. As long as this is in effect, the following strings are
rendered in color, possibly in bold or underlined.

\fun{void}{term_color}{long c} prints (as if using \tet{pari_puts}) the ANSI
color escape sequence attached to output object \kbd{c}. If \kbd{c} is
\tet{c_NONE}, revert to default printing style.

\fun{void}{out_term_color}{PariOUT *out, long c} as \tet{term_color},
using output context \kbd{out}.

\fun{char*}{term_get_color}{char *s, long c} returns as a character
string the ANSI color escape sequence attached to output object \kbd{c}.
If \kbd{c} is \tet{c_NONE}, the value used to revert to default printing
style is returned. The argument \kbd{s} is either \kbd{NULL} (string
allocated on the PARI stack), or preallocated storage (in which case, it must
be able to hold at least 16 chars, including the final \kbd{\bs 0}).

\subsec{Obsolete output functions}

These variants of \fun{void}{output}{GEN x}, which prints \kbd{x}, followed by
a newline and a buffer flush are complicated to use and less flexible
than what we saw above, or than the \tet{pari_printf} variants. They are
provided for backward compatibility and are scheduled to disappear.

\fun{void}{brute}{GEN x, char format, long dec}

\fun{void}{matbrute}{GEN x, char format, long dec}

\fun{void}{texe}{GEN x, char format, long dec}

\section{Files}

The following routines are trivial wrappers around system functions
(possibly around one of several functions depending on availability).
They are usually integrated within PARI's diagnostics system, printing
messages if \kbd{DEBUGFILES} is high enough.

\fun{int}{pari_is_dir}{const char *name} returns $1$ if \kbd{name} points to
a directory, $0$ otherwise.

\fun{int}{pari_is_file}{const char *name} returns $1$ if \kbd{name} points to
a directory, $0$ otherwise.

\fun{int}{file_is_binary}{FILE *f} returns $1$ if the file $f$ is a binary
file (in the \tet{writebin} sense), $0$ otherwise.

\fun{void}{pari_unlink}{const char *s} deletes the file named $s$. Warn
if the operation fails.

\fun{void}{pari_fread_chars}{void *b, size_t n, FILE *f} read $n$ chars from
stream $f$, storing the result in pre-allocated buffer $b$ (assumed to be
large enough).

\fun{char*}{path_expand}{const char *s} perform tilde and environment expansion
on $s$. Returns a \kbd{malloc}'ed buffer.

\fun{void}{strftime_expand}{const char *s, char *buf, long max} perform
time expansion on $s$, storing the result (at most \kbd{max} chars) in
buffer \kbd{buf}. Trivial wrapper around
\bprog
  time_t t = time(NULL);
  strftime(but, max, s, localtime(&t);
@eprog

\fun{char*}{pari_get_homedir}{const char *user} expands \kbd{\til user}
constructs, returning the home directory of user \kbd{user}, or \kbd{NULL} if
it could not be determined (in particular if the operating system has no such
concept). The return value may point to static area and may be overwritten
by subsequent system calls: use immediately or \kbd{strdup} it.

\fun{int}{pari_stdin_isatty}{void} returns $1$ if our standard input
\kbd{stdin} is attached to a terminal. Trivial wrapper around \kbd{isatty}.

\subsec{pariFILE}

PARI maintains a linked list of open files, to reclaim resources
(file descriptors) on error or interrupts. The corresponding data structure
is a \kbd{pariFILE}, which is a wrapper around a standard \kbd{FILE*},
containing further the file name, its type (regular file, pipe, input or
output file, etc.). The following functions create and manipulate this
structure; they are integrated within PARI's diagnostics system, printing
messages if \kbd{DEBUGFILES} is high enough.

\fun{pariFILE*}{pari_fopen}{const char *s, const char *mode} wrapper
around \kbd{fopen(s, mode)}, return \kbd{NULL} on failure.

\fun{pariFILE*}{pari_fopen_or_fail}{const char *s, const char *mode}
simple wrapper around \kbd{fopen(s, mode)}; error on failure.

\fun{pariFILE*}{pari_fopengz}{const char *s} opens the file whose name is
$s$,  and associates a (read-only) \kbd{pariFILE} with it. If $s$ is a
compressed file (\kbd{.gz} suffix), it is uncompressed on the fly.
If $s$ cannot be opened, also try to open \kbd{$s$.gz}. Returns \kbd{NULL}
on failure.

\fun{void}{pari_fclose}{pariFILE *f} closes
the underlying file descriptor and deletes the \kbd{pariFILE} struct.

\fun{pariFILE*}{pari_safefopen}{const char *s, const char *mode}
creates a \emph{new} file $s$ (a priori for writing) with \kbd{600}
permissions. Error if the file already exists. To avoid symlink attacks,
a symbolic link exists, regardless of where it points to.

\subsec{Temporary files}

PARI has its own idea of the system temp directory derived from an
environment variable (\kbd{\$GPTMPDIR}, else \kbd{\$TMPDIR}), or the first
writable directory among \kbd{/tmp}, \kbd{/var/tmp} and \kbd{.}.

\fun{char*}{pari_unique_dir}{const char *s} creates a ``unique directory''
and return its name built from the string $s$, the user id and process pid
(on Unix systems). This directory is itself located in the temp
directory mentioned above. The name returned is \tet{malloc}'ed.

\fun{char*}{pari_unique_filename}{const char *s} creates a \emph{new} empty
file in the temp directory, whose name contains the id-string $s$ (truncated
to its first $8$ chars), followed by a system-dependent suffix (incorporating
the ids of both the user and the running process, for instance). The function
returns the tempfile name. The name returned is \tet{malloc}'ed.

\section{Errors}\label{se:errors}

This section documents the various error classes, and the corresponding
arguments to \tet{pari_err}. The general syntax is

\fun{void}{pari_err}{numerr,...}

\noindent In the sequel, we mostly use sequences of arguments of the form
\bprog
  const char *s
  const char *fmt, ...
@eprog\noindent where \kbd{fmt} is a PARI
format, producing a string $s$ from the remaining arguments. Since
providing the correct arguments to \tet{pari_err} is quite error-prone, we
also provide specialized routines \kbd{pari\_err\_\var{ERRORCLASS}(\dots)}
instead of \kbd{pari\_err(e\_\var{ERRORCLASS}, \dots)} so that the C compiler
can check their arguments.

\noindent We now inspect the list of valid keywords (error classes) for
\kbd{numerr}, and the corresponding required arguments.

\subsec{Internal errors, ``system'' errors}

\subsubsec{e\_ARCH} A requested feature $s$ is not available on this
architecture or operating system.
\bprog
  pari_err(e_ARCH)
@eprog\noindent prints the error message: \kbd{sorry, '$s$' not available on
this system}.

\subsubsec{e\_BUG} A bug in the PARI library, in function $s$.
\bprog
  pari_err(e_BUG, const char *s)
  pari_err_BUG(const char *s)
@eprog\noindent prints the error message: \kbd{Bug in $s$, please report}.

\subsubsec{e\_FILE} Error while trying to open a file.
\bprog
  pari_err(e_FILE, const char *what, const char *name)
  pari_err_FILE(const char *what, const char *name)
@eprog\noindent prints the error message: \kbd{error opening
\emph{what}: `\emph{name}'}.

\subsubsec{e\_IMPL} A requested feature $s$ is not implemented.
\bprog
  pari_err(e_IMPL, const char *s)
  pari_err_IMPL(const char *s)
@eprog\noindent prints the error message: \kbd{sorry, $s$ is not yet
implemented}.

\subsubsec{e\_PACKAGE} Missing optional package $s$.
\bprog
  pari_err(e_PACKAGE, const char *s)
  pari_err_PACKAGE(const char *s)
@eprog\noindent prints the error message: \kbd{package $s$ is required,
please install it}

\subsec{Syntax errors, type errors}

\subsubsec{e\_DIM} arguments submitted to function $s$ have inconsistent
dimensions. E.g., when solving a linear system, or trying to compute the
determinant of a non-square matrix.
\bprog
  pari_err(e_DIM, const char *s)
  pari_err_DIM(const char *s)
@eprog\noindent prints the error message: \kbd{inconsistent dimensions in $s$}.

\subsubsec{e\_FLAG} A flag argument is out of bounds in function $s$.
\bprog
  pari_err(e_FLAG, const char *s)
  pari_err_FLAG(const char *s)
@eprog\noindent prints the error message: \kbd{invalid flag in $s$}.

\subsubsec{e\_NOTFUNC} Generated by the PARI evaluator; tried to use a
\kbd{GEN} which is not a \typ{CLOSURE} in a function call syntax (as in
\kbd{f = 1; f(2);}).
\bprog
  pari_err(e_NOTFUNC, GEN fun)
@eprog\noindent prints the error message: \kbd{not a function in a function
call}.

\subsubsec{e\_OP} Impossible operation between two objects than cannot be
typecast to a sensible common domain for deeper reasons than a type mismatch,
usually for arithmetic reasons. As in \kbd{O(2) + O(3)}: it is valid to add
two \typ{PADIC}s, provided the underlying prime is the same; so the addition
is not forbidden a priori for type reasons, it only becomes so when
inspecting the objects and trying to perform the operation.
\bprog
  pari_err(e_OP, const char *op, GEN x, GEN y)
  pari_err_OP(const char *op, GEN x, GEN y)
@eprog\noindent As \kbd{e\_TYPE2}, replacing \kbd{forbidden} by
\kbd{inconsistent}.

\subsubsec{e\_PRIORITY} object $o$ in function $s$ contains
variables whose priority is incompatible with the expected operation.
E.g.~\kbd{Pol([x,1], 'y)}: this raises an error because it's not possible to
create a polynomial whose coefficients involve variables with higher priority
than the main variable.
\bprog
  pari_err(e_PRIORITY, const char *s, GEN o, const char *op, long v)
  pari_err_PRIORITY(const char *s, GEN o, const char *op, long v)
@eprog\noindent prints the error message: \kbd{incorrect priority
in $s$, variable $v_o$ \var{op} $v$}, were $v_o$ is \kbd{gvar(o)}.

\subsubsec{e\_SYNTAX} Syntax error, generated by the PARI parser.
\bprog
  pari_err(e_SYNTAX, const char *msg, const char *e, const char *entry)
@eprog\noindent where \kbd{msg} is a complete error message, and \kbd{e} and
\kbd{entry} point into the \emph{same} character string, which is the input
that was incorrectly parsed: \kbd{e} points to the character where the parser
failed, and $\kbd{entry}\leq \kbd{e}$ points somewhat before.

\noindent Prints the error message: \kbd{msg}, followed by a colon, then
a part of the input character string (in general \kbd{entry} itself, but an
initial segment may be truncated if $\kbd{e}-\kbd{entry}$ is large); a caret
points at \kbd{e}, indicating where the error took place.

\subsubsec{e\_TYPE} An argument $x$ of function $s$ had an unexpected type.
(As in \kbd{factor("blah")}.)
\bprog
  pari_err(e_TYPE, const char *s, GEN x)
  pari_err_TYPE(const char *s, GEN x)
@eprog\noindent prints the error message: \kbd{incorrect type in $s$
(\typ{$x$})}, where \typ{$x$} is the type of $x$.

\subsubsec{e\_TYPE2} Forbidden operation between two objects than cannot be
typecast to a sensible common domain, because their types do not match up.
(As in \kbd{Mod(1,2) + Pi}.)
\bprog
  pari_err(e_TYPE2, const char *op, GEN x, GEN y)
  pari_err_TYPE2(const char *op, GEN x, GEN y)
@eprog\noindent prints the error message: \kbd{forbidden} $s$
\typ{$x$} \var{op} \typ{$y$}, where \typ{$z$} denotes the type of $z$.
Here, $s$ denotes the spelled out name of the operator
$\var{op}\in\{\kbd{+}, \kbd{*}, \kbd{/}, \kbd{\%}, \kbd{=}\}$, e.g.
\emph{addition} for \kbd{"+"} or \emph{assignment} for \kbd{"="}. If \var{op}
is not in the above operator, list, it is taken to be the already spelled out
name of a function, e.g. \kbd{"gcd"}, and the error message becomes
\kbd{forbidden} \var{op} \typ{$x$}, \typ{$y$}.

\subsubsec{e\_VAR} polynomials $x$ and $y$ submitted to function $s$ have
inconsistent variables. E.g., considering the algebraic number
\kbd{Mod(t,t\pow2+1)} in \kbd{nfinit(x\pow2+1)}.
\bprog
  pari_err(e_VAR, const char *s, GEN x, GEN y)
  pari_err_VAR(const char *s, GEN x, GEN y)
@eprog\noindent prints the error message: \kbd{inconsistent variables in $s$
$X$ != $Y$}, where $X$ and $Y$ are the names of the variables of $x$ and $y$,
respectively.

\subsec{Overflows}

\subsubsec{e\_COMPONENT} Trying to access an inexistent component in a
vector/matrix/list in a function: the index is less than $1$ or greater
than the allowed length.
\bprog
  pari_err(e_COMPONENT, const char *f, const char *op, GEN lim, GEN x)
  pari_err_COMPONENT(const char *f, const char *op, GEN lim, GEN x)
@eprog\noindent prints the error message: \kbd{non-existent component in $f$:
index \var{op} \var{lim}}. Special case: if $f$ is the empty string (no
meaningful public function name can be used), we ignore it and print the
message: \kbd{non-existent component: index \var{op} \var{lim}}.

\subsubsec{e\_DOMAIN} An argument $x$ is not in the function's domain (as in
\kbd{moebius(0)} or \kbd{zeta(1)}).
\bprog
  pari_err(e_DOMAIN, char *f, char *v, char *op, GEN lim, GEN x)
  pari_err_DOMAIN(char *f, char *v, char *op, GEN lim, GEN x)
@eprog\noindent prints the error message: \kbd{domain error in $f$: $v$
\var{op} \var{lim}}. Special case: if \var{op} is the empty string, we ignore
\var{lim} and print the error message: \kbd{domain error in $f$: $v$ out of
range}.

\subsubsec{e\_MAXPRIME} A function using the precomputed list of prime numbers
ran out of primes.
\bprog
  pari_err(e_MAXPRIME, ulong c)
  pari_err_MAXPRIME(ulong c)
@eprog\noindent prints the error message: \kbd{not enough precomputed primes,
need primelimit \til $c$} if $c$ is non-zero. And simply \kbd{not enough
precomputed primes} otherwise.

\subsubsec{e\_MEM} A call to \tet{pari_malloc} or \tet{pari_realloc} failed.
\bprog
  pari_err(e_MEM)
@eprog\noindent prints the error message: \kbd{not enough memory}.

\subsubsec{e\_OVERFLOW} An object in function $s$ becomes too large to be
represented within PARI's hardcoded limits. (As in \kbd{2\pow2\pow2\pow10}
or \kbd{exp(1e100)}, which overflow in \kbd{lg} and \kbd{expo}.)
\bprog
  pari_err(e_OVERFLOW, const char *s)
  pari_err_OVERFLOW(const char *s)
@eprog\noindent prints the error message: \kbd{overflow in $s$}.

\subsubsec{e\_PREC} Function $s$ fails because input accuracy is too low.
(As in \kbd{floor(1e100)} at default accuracy.)
\bprog
  pari_err(e_PREC, const char *s)
  pari_err_PREC(const char *s)
@eprog\noindent prints the error message: \kbd{precision too low in $s$}.

\subsubsec{e\_STACK} The PARI stack overflows.
\bprog
  pari_err(e_STACK)
@eprog\noindent prints the error message: \kbd{the PARI stack overflows !}
as well as some statistics concerning stack usage.

\subsec{Errors triggered intentionally}

\subsubsec{e\_ALARM} A timeout, generated by the \tet{alarm} function.
\bprog
  pari_err(e_ALARM, const char *fmt, ...)
@eprog\noindent prints the error message: $s$.

\subsubsec{e\_USER} A user error, as triggered by \tet{error}($g_1,\dots,g_n)$
in GP.
\bprog
  pari_err(e_USER, GEN g)
@eprog\noindent prints the error message: \kbd{user error:}, then the
entries of the vector $g$.

\subsec{Mathematical errors}

\subsubsec{e\_CONSTPOL} An argument of function $s$ is a constant polynomial,
which does not make sense. (As in \kbd{galoisinit(Pol(1))}.)
\bprog
  pari_err(e_CONSTPOL, const char *s)
  pari_err_CONSTPOL(const char *s)
@eprog\noindent prints the error message: \kbd{constant polynomial in $s$}.

\subsubsec{e\_COPRIME} Function $s$ expected two coprime arguments, and did
receive $x$, $y$ which were not.
\bprog
  pari_err(e_COPRIME, const char *s, GEN x, GEN y)
  pari_err_COPRIME(const char *s, GEN x, GEN y)
@eprog\noindent prints the error message: \kbd{elements not coprime in $s$:
$x, y$}.

\subsubsec{e\_INV} Tried to invert a non-invertible object $x$.
\bprog
  pari_err(e_INV, const char *s, GEN x)
  pari_err_INV(const char *s, GEN x)
@eprog\noindent prints the error message: \kbd{impossible inverse in $s$: $x$}.
If $x = \kbd{Mod}(a,b)$ is a \typ{INTMOD} and $a$ is not $0$ mod $b$, this
allows to factor the modulus, as \kbd{gcd}$(a,b)$ is a non-trivial divisor of
$b$.

\subsubsec{e\_IRREDPOL} Function $s$ expected an irreducible polynomial,
and did not receive one. (As in \kbd{nfinit(x\pow2-1)}.)
\bprog
  pari_err(e_IRREDPOL, const char *s, GEN x)
  pari_err_IRREDPOL(const char *s, GEN x)
@eprog\noindent prints the error message: \kbd{not an irreducible polynomial
in $s$: $x$}.

\subsubsec{e\_MISC} Generic uncategorized error.
\bprog
  pari_err(e_MISC, const char *fmt, ...)
@eprog\noindent prints the error message: $s$.

\subsubsec{e\_MODULUS} moduli $x$ and $y$ submitted to function $s$ are
inconsistent. E.g., considering the algebraic number
\kbd{Mod(t,t\pow2+1)} in \kbd{nfinit(t\pow3-2)}.
\bprog
  pari_err(e_MODULUS, const char *s, GEN x, GEN y)
  pari_err_MODULUS(const char *s, GEN x, GEN y)
@eprog\noindent prints the error message: \kbd{inconsistent moduli in $s$},
then the moduli.

\subsubsec{e\_PRIME} Function $s$ expected a prime number, and did receive $p$,
which was not. (As in \kbd{idealprimedec(nf, 4)}.)
\bprog
  pari_err(e_PRIME, const char *s, GEN x)
  pari_err_PRIME(const char *s, GEN x)
@eprog\noindent prints the error message: \kbd{not a prime in $s$: $x$}.

\subsubsec{e\_ROOTS0} An argument of function $s$ is a zero polynomial, and
we need to consider its roots. (As in \kbd{polroots(0)}.)
\bprog
  pari_err(e_ROOTS0, const char *s)
  pari_err_ROOTS0(const char *s)
@eprog\noindent prints the error message: \kbd{zero polynomial in $s$}.

\subsubsec{e\_SQRTN} Tried to compute an $n$-th root of $x$, which does not
exist, in function $s$.
(As in \kbd{sqrt(Mod(-1,3))}.)
\bprog
  pari_err(e_SQRTN, GEN x)
  pari_err_SQRTN(GEN x)
@eprog\noindent prints the error message: \kbd{not an n-th power residue in
$s$: $x$}.

\subsec{Miscellaneous functions}

\fun{long}{name_numerr}{const char *s} return the error number corresponding to
an error name. E.g. \kbd{name\_numerr("e\_DIM")} returns \kbd{e\_DIM}.

\fun{const char*}{numerr_name}{long errnum} returns the error name
corresponding to an error number. E.g. \kbd{name\_numerr(e\_DIM)} returns
\kbd{"e\_DIM"}.

\fun{char*}{pari_err2str}{GEN err} returns the error message that would be
printed on \typ{ERROR} \kbd{err}. The name is allocated on the PARI stack and
must not be freed.

\section{Hashtables}
A \tet{hashtable}, or associative array, is a set of pairs $(k,v)$ of keys
and values. PARI implements general extensible hashtables for fast data
retrieval: when creating a table, we may either choose to use the PARI stack,
or \kbd{malloc} so as to be stack-independent. A hashtable is implemented as
a table of linked lists, each list containing all entries sharing the same
hash value. The table length is a prime number, which roughly doubles as the
table overflows by gaining new entries; both the current number of entries
and the threshold before the table grows are stored in the table. Finally the
table remembers the functions used to hash the entries's keys and to test for
equality two entries hashed to the same value.

An entry, or \tet{hashentry}, contains

\item a key/value pair $(k,v)$, both of type \kbd{void*} for maximal
flexibility,

\item the hash value of the key, for the table hash function. This hash is
mapped to a table index (by reduction modulo the table length), but it
contains more information, and is used to bypass costly general equality
tests if possible,

\item a link pointer to the next entry sharing the same table cell.

\bprog
typedef struct {
  void *key, *val;
  ulong hash; /* hash(key) */
  struct hashentry *next;
} hashentry;

typedef struct {
  ulong len; /* table length */
  hashentry **table; /* the table */
  ulong nb, maxnb; /* number of entries stored and max nb before enlarging */
  ulong pindex; /* prime index */
  ulong (*hash) (void *k); /* hash function */
  int (*eq) (void *k1, void *k2); /* equality test */
  int use_stack; /* use the PARI stack, resp. malloc */
} hashtable;
@eprog\noindent

\fun{hashtable*}{hash_create}{size, hash, eq, use_stack}
\vskip -0.5em % switch to K&R style to avoid atrocious line break
\bprog
  ulong size;
  ulong (*hash)(void*);
  int (*eq)(void*,void*);
  int use_stack;
@eprog\noindent
creates a hashtable with enough room to contain
\kbd{size} entries. The functions \kbd{hash} and \kbd{eq} compute the hash
value of keys and test keys for equality, respectively. If \kbd{use\_stack}
is non zero, the resulting table will use the PARI stack; otherwise, we use
\kbd{malloc}.

\fun{hashtable*}{hash_create_ulong}{ulong size, long stack} special case
when the keys are \kbd{ulongs} with ordinary equality test.

\fun{hashtable*}{hash_create_str}{ulong size, long stack} special case
when the keys are character strings with string equality test (and
\tet{hash_str} hash function).

\fun{void}{hash_insert}{hashtable *h, void *k, void *v} inserts $(k,v)$
in hashtable $h$. No copy is made: $k$ and $v$ themselves are stored. The
implementation does not prevent one to insert two entries with equal
keys $k$, but which of the two is affected by later commands is undefined.

\fun{void}{hash_insert2}{hashtable *h, void *k, void *v, ulong hash}
as \kbd{hash\_insert}, assuming \kbd{h->hash(k)} is \kbd{hash}.

\fun{hashentry*}{hash_search}{hashtable *h, void *k} look for an entry
with key $k$ in $h$. Return it if it one exists, and \kbd{NULL} if not.

\fun{hashentry*}{hash_search2}{hashtable *h, void *k, ulong hash} as
\kbd{hash\_search} assuming \kbd{h->hash(k)} is \kbd{hash}.

\fun{hashentry *}{hash_select}{hashtable *h, void *k, void *E, int (*select)(void *, hashentry *)} variant of \tet{hash_search}, useful when entries
with identical keys are inserted: among the entries attached to
key $k$, return one satisfying the selection criterion (such that
\kbd{select(E,e)} is non-zero), or \kbd{NULL} if none exist.

\fun{hashentry*}{hash_remove}{hashtable *h, void *k} deletes an entry $(k,v)$
with key $k$ from $h$ and return it. (Return \kbd{NULL} if none was found.)
Only the linking structures are freed, memory attached to $k$ and $v$
is not reclaimed.

\fun{hashentry*}{hash_remove_select}{hashtable *h, void *k, void *E, int(*select)(void*, hashentry *)}
a variant of \tet{hash_remove}, useful when entries with identical keys are
inserted: among the entries attached to key $k$, return one satisfying the
selection criterion (such that \kbd{select(E,e)} is non-zero) and delete it,
or \kbd{NULL} if none exist. Only the linking structures are freed, memory
attached to $k$ and $v$ is not reclaimed.

\fun{GEN}{hash_keys}{hashtable *h} return in a \typ{VECSMALL} the keys
stored in hashtable $h$.

\fun{GEN}{hash_values}{hashtable *h} return in a \typ{VECSMALL}
the values stored in hashtable $h$.

\fun{void}{hash_destroy}{hashtable *h} deletes the hashtable, by removing all
entries.

\fun{void}{hash_dbg}{hashtable *h} print statistics for hashtable $h$, allows
to evaluate the attached hash function performance on actual data.

Some interesting hash functions are available:

\fun{ulong}{hash_str}{const char *s}

\fun{ulong}{hash_str2}{const char *s} is the historical PARI string hashing
function and seems to be generally inferior to \kbd{hash\_str}.

\fun{ulong}{hash_GEN}{GEN x}

\section{Dynamic arrays}

A \teb{dynamic array} is a generic way to manage stacks of data that need
to grow dynamically. It allocates memory using \kbd{pari\_malloc}, and is
independent of the PARI stack; it even works before the \kbd{pari\_init} call.

\subsec{Initialization}

To create a stack of objects of type \kbd{foo}, we proceed as follows:
\bprog
foo *t_foo;
pari_stack s_foo;
pari_stack_init(&s_foo, sizeof(*t_foo), (void**)t_foo);
@eprog\noindent Think of \kbd{s\_foo} as the controlling interface, and
\kbd{t\_foo} as the (dynamic) array tied to it. The value of \kbd{t\_foo}
may be changed as you add more elements.

\subsec{Adding elements}
The following function pushes an element on the stack.
\bprog
/* access globals t_foo and s_foo */
void push_foo(foo x)
{
  long n = pari_stack_new(&s_foo);
  t_foo[n] = x;
}
@eprog

\subsec{Accessing elements}

Elements are accessed naturally through the \kbd{t\_foo} pointer.
For example this function swaps two elements:
\bprog
void swapfoo(long a, long b)
{
  foo x;
  if (a > s_foo.n || b > s_foo.n) pari_err_BUG("swapfoo");
  x        = t_foo[a];
  t_foo[a] = t_foo[b];
  t_foo[b] = x;
}
@eprog

\subsec{Stack of stacks}
Changing the address of \kbd{t\_foo} is not supported in general.
In particular \kbd{realloc()}'ed array of stacks and stack of stacks are not
supported.

\subsec{Public interface}
Let \kbd{s} be a \kbd{pari\_stack} and \kbd{data} the data linked to it. The
following public fields are defined:

\item \kbd{s.alloc} is the number of elements allocated for \kbd{data}.

\item \kbd{s.n} is the number of elements in the stack and \kbd{data[s.n-1]} is
the topmost element of the stack.  \kbd{s.n} can be changed as long as
$0\leq\kbd{s.n}\leq\kbd{s.alloc}$ holds.

\fun{void}{pari_stack_init}{pari_stack *s, size_t size, void **data} links
\kbd{*s} to the data pointer \kbd{*data}, where \kbd{size} is the size of
data element. The pointer \kbd{*data} is set to \kbd{NULL}, \kbd{s->n} and
\kbd{s->alloc} are set to $0$: the array is empty.

\fun{void}{pari_stack_alloc}{pari_stack *s, long nb} makes room for \kbd{nb}
more elements, i.e.~makes sure that $\kbd{s.alloc}\geq\kbd{s.n} + \kbd{nb}$,
possibly reallocating \kbd{data}.

\fun{long}{pari_stack_new}{pari_stack *s} increases \kbd{s.n} by one unit,
possibly reallocating \kbd{data}, and returns $\kbd{s.n}-1$.

\misctitle{Caveat} The following construction is incorrect because
\kbd{stack\_new} can change the value of \kbd{t\_foo}:
\bprog
t_foo[ pari_stack_new(&s_foo) ] = x;
@eprog

\fun{void}{pari_stack_delete}{pari_stack *s} frees \kbd{data} and resets the
stack to the state immediately following \kbd{stack\_init} (\kbd{s->n} and
\kbd{s->alloc} are set to $0$).

\fun{void *}{pari_stack_pushp}{pari_stack *s, void *u} This function assumes
that \kbd{*data} is of pointer type. Pushes the element \kbd{u} on the stack
\kbd{s}.

\fun{void **}{pari_stack_base}{pari_stack *s} returns the address of \kbd{data},
typecast to a \kbd{void **}.

\section{Vectors and Matrices}

\subsec{Access and extract}
See~\secref{se:clean} and~\secref{se:unclean} for various useful constructors.
Coefficients are accessed and set using \tet{gel}, \tet{gcoeff},
see~\secref{se:accessors}. There are many internal functions to extract or
manipulate subvectors or submatrices but, like the accessors above, none of
them are suitable for \tet{gerepileupto}. Worse, there are no type
verification, nor bound checking, so use at your own risk.

\fun{GEN}{shallowcopy}{GEN x} returns a \kbd{GEN} whose components are the
components of $x$ (no copy is made). The result may now be used to compute in
place without destroying $x$. This is essentially equivalent to
\bprog
  GEN y = cgetg(lg(x), typ(x));
  for (i = 1; i < lg(x); i++) y[i] = x[i];
  return y;
@eprog\noindent
except that \typ{MAT} is treated specially since shallow copies of all columns
are made. The function also works for non-recursive types, but is useless
in that case since it makes a deep copy. If $x$ is known to be a \typ{MAT}, you
may call \tet{RgM_shallowcopy} directly; if $x$ is known not to be a \typ{MAT},
you may call \tet{leafcopy} directly.

\fun{GEN}{RgM_shallowcopy}{GEN x} returns \kbd{shallowcopy(x)}, where $x$
is a \typ{MAT}.

\fun{GEN}{shallowtrans}{GEN x} returns the transpose of $x$, \emph{without}
copying its components, i.~e.,~it returns a \kbd{GEN} whose components are
(physically) the components of $x$. This is the internal function underlying
\tet{gtrans}.

\fun{GEN}{shallowconcat}{GEN x, GEN y} concatenate $x$ and $y$, \emph{without}
copying components, i.~e.,~it returns a \kbd{GEN} whose components are
(physically) the components of $x$ and $y$.

\fun{GEN}{shallowconcat1}{GEN x}
$x$ must be \typ{VEC} or \typ{LIST}, concatenate
its elements from left to right. Shallow version of \kbd{gconcat1}.

\fun{GEN}{shallowmatconcat}{GEN v} shallow version of \kbd{matconcat}.

\fun{GEN}{shallowextract}{GEN x, GEN y} extract components
of the vector or matrix $x$ according to the selection parameter $y$.
This is the shallow analog of \kbd{extract0(x, y, NULL)}, see \tet{vecextract}.
\kbdsidx{extract0}

\fun{GEN}{RgM_minor}{GEN A, long i, long j} given a square \typ{MAT} A,
return the matrix with $i$-th row and $j$-th column removed.

\fun{GEN}{vconcat}{GEN A, GEN B} concatenate vertically the two \typ{MAT} $A$
and $B$ of compatible dimensions. A \kbd{NULL} pointer is accepted for an
empty matrix. See \tet{shallowconcat}.

\fun{GEN}{matslice}{GEN A, long a, long b, long c, long d}
returns the submatrix $A[a..b,c..d]$. Assume $a \leq b$ and  $c \leq d$.

\fun{GEN}{row}{GEN A, long i} return $A[i,]$, the $i$-th row of the \typ{MAT}
$A$.

\fun{GEN}{row_i}{GEN A, long i, long j1, long j2} return part of the $i$-th
row of \typ{MAT}~$A$: $A[i,j_1]$, $A[i,j_1+1]\dots,A[i,j_2]$. Assume $j_1
\leq j_2$.

\fun{GEN}{rowcopy}{GEN A, long i} return the row $A[i,]$ of
the~\typ{MAT}~$A$. This function is memory clean and suitable for
\kbd{gerepileupto}. See \kbd{row} for the shallow equivalent.

\fun{GEN}{rowslice}{GEN A, long i1, long i2} return the \typ{MAT}
formed by the $i_1$-th through $i_2$-th rows of \typ{MAT} $A$. Assume $i_1
\leq i_2$.

\fun{GEN}{rowsplice}{GEN A, long i} return the \typ{MAT} formed from the
coefficients of \typ{MAT} $A$ with $j$-th row removed.

\fun{GEN}{rowpermute}{GEN A, GEN p}, $p$ being a \typ{VECSMALL}
representing a list $[p_1,\dots,p_n]$ of rows of \typ{MAT} $A$, returns the
matrix whose rows are $A[p_1,],\dots, A[p_n,]$.

\fun{GEN}{rowslicepermute}{GEN A, GEN p, long x1, long x2}, short for
\bprog
  rowslice(rowpermute(A,p), x1, x2)
@eprog\noindent
(more efficient).

\fun{GEN}{vecslice}{GEN A, long j1, long j2}, return $A[j_1], \dots,
A[j_2]$. If $A$ is a \typ{MAT}, these correspond to \emph{columns} of $A$.
The object returned has the same type as $A$ (\typ{VEC}, \typ{COL} or
\typ{MAT}). Assume $j_1 \leq j_2$.

\fun{GEN}{vecsplice}{GEN A, long j} return $A$ with $j$-th entry removed
(\typ{VEC}, \typ{COL}) or $j$-th column removed (\typ{MAT}).

\fun{GEN}{vecreverse}{GEN A}. Returns a \kbd{GEN} which has the same
type as $A$ (\typ{VEC}, \typ{COL} or \typ{MAT}), and whose components
are the $A[n],\dots,A[1]$. If $A$ is a \typ{MAT}, these are the
\emph{columns} of $A$.

\fun{void}{vecreverse_inplace}{GEN A} as \kbd{vecreverse}, but reverse
$A$ in place.

\fun{GEN}{vecpermute}{GEN A, GEN p} $p$ is a \typ{VECSMALL} representing
a list $[p_1,\dots,p_n]$ of indices. Returns a \kbd{GEN} which has the same
type as $A$ (\typ{VEC}, \typ{COL} or \typ{MAT}), and whose components
are $A[p_1],\dots,A[p_n]$. If $A$ is a \typ{MAT}, these are the
\emph{columns} of $A$.

\fun{GEN}{vecsmallpermute}{GEN A, GEN p} as \kbd{vecpermute} when \kbd{A} is a
\typ{VECSMALL}.

\fun{GEN}{vecslicepermute}{GEN A, GEN p, long y1, long y2} short for
\bprog
  vecslice(vecpermute(A,p), y1, y2)
@eprog\noindent
(more efficient).

\subsec{Componentwise operations}

The following convenience routines automate trivial loops of the form
\bprog
  for (i = 1; i < lg(a); i++) gel(v,i) = f(gel(a,i), gel(b,i))
@eprog\noindent
for suitable $f$:

\fun{GEN}{vecinv}{GEN a}. Given a vector $a$,
returns the vector whose $i$-th component is \kbd{ginv}$(a[i])$.

\fun{GEN}{vecmul}{GEN a, GEN b}. Given $a$ and $b$ two vectors of the same
length, returns the vector whose $i$-th component is \kbd{gmul}$(a[i], b[i])$.

\fun{GEN}{vecdiv}{GEN a, GEN b}. Given $a$ and $b$ two vectors of the same
length, returns the vector whose $i$-th component is \kbd{gdiv}$(a[i], b[i])$.

\fun{GEN}{vecpow}{GEN a, GEN n}. Given $n$ a \typ{INT}, returns
the vector whose $i$-th component is $a[i]^n$.

\fun{GEN}{vecmodii}{GEN a, GEN b}. Assuming $a$ and $b$ are two \kbd{ZV}
of the same length, returns the vector whose $i$-th component
is \kbd{modii}$(a[i], b[i])$.

Note that \kbd{vecadd} or \kbd{vecsub} do not exist since \kbd{gadd}
and \kbd{gsub} have the expected behavior. On the other hand,
\kbd{ginv} does not accept vector types, hence \kbd{vecinv}.

\subsec{Low-level vectors and columns functions}

These functions handle \typ{VEC} as an abstract container type of
\kbd{GEN}s. No specific meaning is attached to the content. They accept both
\typ{VEC} and \typ{COL} as input, but \kbd{col} functions always return
\typ{COL} and \kbd{vec} functions always return \typ{VEC}.

\misctitle{Note} All the functions below are shallow.

\fun{GEN}{const_col}{long n, GEN x} returns a \typ{COL} of \kbd{n} components
equal to \kbd{x}.

\fun{GEN}{const_vec}{long n, GEN x} returns a \typ{VEC} of \kbd{n} components
equal to \kbd{x}.

\fun{int}{vec_isconst}{GEN v} Returns 1 if all the components of \kbd{v} are
equal, else returns 0.

\fun{void}{vec_setconst}{GEN v, GEN x} $v$ a pre-existing vector. Set all its
components to $x$.

\fun{int}{vec_is1to1}{GEN v}  Returns 1 if the components of \kbd{v} are
pair-wise distinct, i.e. if $i\mapsto v[i]$ is a 1-to-1 mapping, else returns
0.

\fun{GEN}{vec_append}{GEN V, GEN s} append \kbd{s} to the vector \kbd{V}.

\fun{GEN}{vec_shorten}{GEN v, long n} shortens the vector \kbd{v} to \kbd{n}
components.

\fun{GEN}{vec_lengthen}{GEN v, long n} lengthens the vector \kbd{v}
to \kbd{n} components. The extra components are not initialized.

\fun{GEN}{vec_insert}{GEN v, long n, GEN x} inserts $x$ at position $n$ in the vector
$v$.

\section{Vectors of small integers}

\subsec{\typ{VECSMALL}}

These functions handle \typ{VECSMALL} as an abstract container type
of small signed integers. No specific meaning is attached to the content.

\fun{GEN}{const_vecsmall}{long n, long c} returns a \typ{VECSMALL}
of \kbd{n} components equal to \kbd{c}.

\fun{GEN}{vec_to_vecsmall}{GEN z} identical to \kbd{ZV\_to\_zv(z)}.

\fun{GEN}{vecsmall_to_vec}{GEN z} identical to \kbd{zv\_to\_ZV(z)}.

\fun{GEN}{vecsmall_to_col}{GEN z} identical to \kbd{zv\_to\_ZC(z)}.

\fun{GEN}{vecsmall_copy}{GEN x} makes a copy of \kbd{x} on the stack.

\fun{GEN}{vecsmall_shorten}{GEN v, long n} shortens the \typ{VECSMALL} \kbd{v}
to \kbd{n} components.

\fun{GEN}{vecsmall_lengthen}{GEN v, long n} lengthens the \typ{VECSMALL}
\kbd{v} to \kbd{n} components. The extra components are not initialized.

\fun{GEN}{vecsmall_indexsort}{GEN x} performs an indirect sort of the
components of the \typ{VECSMALL} \kbd{x} and return a permutation stored in a
\typ{VECSMALL}.

\fun{void}{vecsmall_sort}{GEN v} sorts the \typ{VECSMALL} \kbd{v} in place.

\fun{void}{vecsmall_reverse}{GEN v} as \kbd{vecreverse} for a \typ{VECSMALL}
\kbd{v}.

\fun{long}{vecsmall_max}{GEN v} returns the maximum of the elements of
\typ{VECSMALL} \kbd{v}, assumed non-empty.

\fun{long}{vecsmall_indexmax}{GEN v} returns the index of the largest
element of \typ{VECSMALL} \kbd{v}, assumed non-empty.

\fun{long}{vecsmall_min}{GEN v} returns the minimum of the elements of
\typ{VECSMALL} \kbd{v}, assumed non-empty.

\fun{long}{vecsmall_indexmin}{GEN v} returns the index of the smallest
element of \typ{VECSMALL} \kbd{v}, assumed non-empty.

\fun{long}{vecsmall_isin}{GEN v, long x} returns the first index $i$
such that \kbd{v[$i$]} is equal to \kbd{x}. Naive search in linear time, does
not assume that \kbd{v} is sorted.

\fun{GEN}{vecsmall_uniq}{GEN v} given a \typ{VECSMALL} \kbd{v}, return
the vector of unique occurrences.

\fun{GEN}{vecsmall_uniq_sorted}{GEN v} same as \kbd{vecsmall\_uniq}, but assumes
 \kbd{v} sorted.

\fun{long}{vecsmall_duplicate}{GEN v} given a \typ{VECSMALL} \kbd{v}, return
$0$ if there is no duplicates, or the index of the first duplicate
(\kbd{vecsmall\_duplicate([1,1])} returns $2$).

\fun{long}{vecsmall_duplicate_sorted}{GEN v} same as
\kbd{vecsmall\_duplicate}, but assume \kbd{v} sorted.

\fun{int}{vecsmall_lexcmp}{GEN x, GEN y} compares two \typ{VECSMALL} lexically.

\fun{int}{vecsmall_prefixcmp}{GEN x, GEN y} truncate the longest \typ{VECSMALL}
to the length of the shortest and compares them lexicographically.

\fun{GEN}{vecsmall_prepend}{GEN V, long s} prepend \kbd{s} to the
\typ{VECSMALL} \kbd{V}.

\fun{GEN}{vecsmall_append}{GEN V, long s} append \kbd{s} to the
\typ{VECSMALL} \kbd{V}.

\fun{GEN}{vecsmall_concat}{GEN u, GEN v} concat the \typ{VECSMALL} \kbd{u}
and \kbd{v}.

\fun{long}{vecsmall_coincidence}{GEN u, GEN v} returns the numbers of indices
where \kbd{u} and \kbd{v} agree.

\fun{long}{vecsmall_pack}{GEN v, long base, long mod} handles the
\typ{VECSMALL} \kbd{v} as the digit of a number in base \kbd{base} and return
this number modulo \kbd{mod}. This can be used as an hash function.

\subsec{Vectors of \typ{VECSMALL}}
These functions manipulate vectors of \typ{VECSMALL} (vecvecsmall).

\fun{GEN}{vecvecsmall_sort}{GEN x} sorts lexicographically the components of
the vector \kbd{x}.

\fun{GEN}{vecvecsmall_sort_uniq}{GEN x} sorts lexicographically the components of
the vector \kbd{x}, removing duplicates entries.

\fun{GEN}{vecvecsmall_indexsort}{GEN x} performs an indirect lexicographic
sorting of the components of the vector \kbd{x} and return a permutation
stored in a \typ{VECSMALL}.

\fun{long}{vecvecsmall_search}{GEN x, GEN y, long flag} \kbd{x} being a sorted
vecvecsmall and \kbd{y} a \typ{VECSMALL}, search \kbd{y} inside \kbd{x}.
\kbd{flag} has the same meaning as for \kbd{setsearch}.

\newpage
\chapter{Functions related to the GP interpreter}

\section{Handling closures}\label{se:closure}

\subsec{Functions to evaluate \typ{CLOSURE}}

\fun{void}{closure_disassemble}{GEN C} print the \typ{CLOSURE} \kbd{C} in
GP assembly format.

\fun{GEN}{closure_callgenall}{GEN C, long n, ...} evaluate the \typ{CLOSURE}
\kbd{C} with the \kbd{n} arguments (of type \kbd{GEN}) following \kbd{n} in
the function call. Assumes \kbd{C} has arity $\geq \kbd{n}$.

\fun{GEN}{closure_callgenvec}{GEN C, GEN args} evaluate the \typ{CLOSURE}
\kbd{C} with the arguments supplied in the vector \kbd{args}. Assumes \kbd{C}
has arity $\geq \kbd{lg(args)-1}$.

\fun{GEN}{closure_callgenvecprec}{GEN C, GEN args, long prec} as
\kbd{closure\_callgenvec} but set the precision locally to \kbd{prec}.

\fun{GEN}{closure_callgen1}{GEN C, GEN x} evaluate the \typ{CLOSURE}
\kbd{C} with argument \kbd{x}. Assumes \kbd{C} has arity $\geq 1$.

\fun{GEN}{closure_callgen1prec}{GEN C, GEN x, long prec} as
\kbd{closure\_callgen1}, but set the precision locally to \kbd{prec}.

\fun{GEN}{closure_callgen2}{GEN C, GEN x, GEN y} evaluate the \typ{CLOSURE}
\kbd{C} with argument \kbd{x}, \kbd{y}. Assumes \kbd{C} has arity $\geq 2$.

\fun{void}{closure_callvoid1}{GEN C, GEN x} evaluate the \typ{CLOSURE}
\kbd{C} with argument \kbd{x} and discard the result. Assumes \kbd{C}
has arity $\geq 1$.

The following technical functions are used to evaluate \emph{inline}
closures and closures of arity 0.

The control flow statements (break, next and return) will cause the
evaluation of the closure to be interrupted; this is called below a
\emph{flow change}. When that occurs, the functions below generally
 return \kbd{NULL}. The caller can then adopt three positions:

\item raises an exception (\kbd{closure\_evalnobrk}).

\item passes through (by returning NULL itself).

\item handles the flow change.

\fun{GEN}{closure_evalgen}{GEN code} evaluates a closure and returns the result,
or \kbd{NULL} if a flow change occurred.

\fun{GEN}{closure_evalnobrk}{GEN code} as \kbd{closure\_evalgen} but raise
an exception if a flow change occurs. Meant for iterators where
interrupting the closure is meaningless, e.g.~\kbd{intnum} or \kbd{sumnum}.

\fun{void}{closure_evalvoid}{GEN code} evaluates a closure whose return
value is ignored. The caller has to deal with eventual flow changes by
calling \kbd{loop\_break}.

The remaining functions below are for exceptional situations:

\fun{GEN}{closure_evalres}{GEN code} evaluates a closure and returns the result.
The difference with \kbd{closure\_evalgen} being that, if the flow end by a
\kbd{return} statement, the result will be the returned value instead of
\kbd{NULL}. Used by the main GP loop.

\fun{GEN}{closure_evalbrk}{GEN code, long *status} as \kbd{closure\_evalres}
but set \kbd{status} to a non-zero value if a flow change occurred. This
variant is not stack clean. Used by the break loop.

\fun{GEN}{closure_trapgen}{long numerr, GEN code} evaluates closure, while
trapping error \kbd{numerr}. Return \kbd{(GEN)1L} if error trapped, and the
result otherwise, or \kbd{NULL} if a flow change occurred. Used by trap.


\subsec{Functions to handle control flow changes}

\fun{long}{loop_break}{void} processes an eventual flow changes inside an
iterator. If this function return $1$, the iterator should stop.

\subsec{Functions to deal with lexical local variables}\label{se:pushlex}

Function using the prototype code \kbd{`V'} need to manually create and delete a
lexical variable for each code \kbd{`V'}, which will be given a number $-1, -2,
\ldots$.

\fun{void}{push_lex}{GEN a, GEN code} creates a new lexical variable whose
initial value is $a$ on the top of the stack. This variable get the number
$-1$, and the number of the other variables is decreased by one unit. When
the first variable of a closure is created, the argument \kbd{code} must be the
closure that references this lexical variable. The argument \kbd{code} must be
\kbd{NULL} for all subsequent variables (if any).  (The closure contains the
debugging data for the variable).

\fun{void}{pop_lex}{long n} deletes the $n$ topmost lexical variables,
increasing the number of other variables by $n$. The argument $n$ must match
the number of variables allocated through \kbd{push\_lex}.

\fun{GEN}{get_lex}{long vn} get the value of the variable with number \kbd{vn}.

\fun{void}{set_lex}{long vn, GEN x} set the value of the variable with number
\kbd{vn}.

\subsec{Functions returning new closures}

\fun{GEN}{compile_str}{const char *s} returns the closure corresponding to the
GP expression $s$.

\fun{GEN}{closure_deriv}{GEN code} returns a closure corresponding to the
numerical derivative of the closure \kbd{code}.

\fun{GEN}{snm_closure}{entree *ep, GEN data}
Let \kbd{data} be a vector of length $m$, \kbd{ep} be an \kbd{entree}
pointing to a C function $f$ of arity $n+m$, returns a \typ{CLOSURE} object
$g$ of arity $n$ such that
$g(x_1,\ldots,x_n)=f(x_1,\ldots,x_n,gel(data,1),...,gel(data,m))$. If
\kbd{data} is \kbd{NULL}, then $m=0$ is assumed.  This function has a low
overhead since it does not copy \kbd{data}.

\fun{GEN}{strtofunction}{char *str} returns a closure corresponding to the
built-in or install'ed function named \kbd{str}.

\fun{GEN}{strtoclosure}{char *str, long n, ...} returns a closure
corresponding to the built-in or install'ed function named \kbd{str} with the
$n$ last parameters set to the $n$ \kbd{GEN}s following $n$, see
\tet{snm_closure}. This function has an higher overhead since it copies the
parameters and does more input validation.

In the example code below, \kbd{agm1} is set to the function
\kbd{x->agm(x,1)} and \kbd{res} is set to \kbd{agm(2,1)}.

\bprog
  GEN agm1 = strtoclosure("agm",1, gen_1);
  GEN res = closure_callgen1(agm1, gen_2);
@eprog

\subsec{Functions used by the gp debugger (break loop)}
\fun{long}{closure_context}{long s} restores the compilation context starting
at frame \kbd{s+1}, and returns the index of the topmost frame. This allow to
compile expressions in the topmost lexical scope.

\fun{void}{closure_err}{void} prints a backtrace of the last $20$ stack frames.

\subsec{Standard wrappers for iterators}
Two families of standard wrappers are provided to interface iterators like
\kbd{intnum} or \kbd{sumnum} with GP.

\subsubsec{Standard wrappers for inline closures}
Theses wrappers are used to implement GP functions taking inline closures as
input. The object \kbd{(GEN)E} must be an inline closure which is evaluated
with the lexical variable number $-1$ set to $x$.

\fun{GEN}{gp_eval}{void *E, GEN x} is used for the prototype code \kbd{`E'}.

\fun{GEN}{gp_evalprec}{void *E, GEN x, long prec} as \kbd{gp\_eval}, but
set the precision locally to \kbd{prec}.

\fun{long}{gp_evalvoid}{void *E, GEN x} is used for the prototype code
\kbd{`I'}. The resulting value is discarded.  Return a non-zero value if a
control-flow instruction request the iterator to terminate immediately.

\fun{long}{gp_evalbool}{void *E, GEN x} returns the boolean
\kbd{gp\_eval(E, x)} evaluates to (i.e. true iff the value is non-zero).

\fun{GEN}{gp_evalupto}{void *E, GEN x} memory-safe version of \kbd{gp\_eval},
\kbd{gcopy}-ing the result, when the evaluator returns components of
previously allocated objects (e.g. member functions).

\subsubsec{Standard wrappers for true closures}
These wrappers are used to implement GP functions taking true closures as
input.

\fun{GEN}{gp_call}{void *E, GEN x} evaluates the closure \kbd{(GEN)E} on $x$.

\fun{GEN}{gp_callprec}{void *E, GEN x, long prec} as \kbd{gp\_call},
but set the precision locally to \kbd{prec}.

\fun{GEN}{gp_call2}{void *E, GEN x, GEN y} evaluates the closure \kbd{(GEN)E}
on $(x,y)$.

\fun{long}{gp_callbool}{void *E, GEN x} evaluates the closure \kbd{(GEN)E} on
$x$, returns \kbd{1} if its result is non-zero, and \kbd{0} otherwise.

\fun{long}{gp_callvoid}{void *E, GEN x} evaluates the closure \kbd{(GEN)E} on
$x$, discarding the result. Return a non-zero value if a control-flow
instruction request the iterator to terminate immediately.

\section{Defaults}

\fun{entree*}{pari_is_default}{const char *s} return the \kbd{entree}
structure attached to $s$ if it is the name of a default, \kbd{NULL}
otherwise.

\fun{GEN}{setdefault}{const char *s, const char *v, long flag} is the
low-level function underlying \kbd{default0}. If $s$ is \kbd{NULL}, call all
default setting functions with string argument \kbd{NULL} and flag
\tet{d_ACKNOWLEDGE}. Otherwise, check whether $s$ corresponds to a default
and call the corresponding default setting function with arguments $v$ and
\fl.

We shall describe these functions below: if $v$ is \kbd{NULL}, we only look
at the default value (and possibly print or return it, depending on
\kbd{flag}); otherwise the value of the default to $v$, possibly after some
translation work. The flag is one of

\item \tet{d_INITRC} called while reading the \kbd{gprc}: print and return
\kbd{gnil}, possibly defer until \kbd{gp} actually starts.

\item \tet{d_RETURN} return the current value, as a \typ{INT} if possible, as
a \typ{STR} otherwise.

\item \tet{d_ACKNOWLEDGE} print the current value, return \kbd{gnil}.

\item \tet{d_SILENT} print nothing, return \kbd{gnil}.

\noindent Low-level functions called by \kbd{setdefault}:


\fun{GEN}{sd_TeXstyle}{const char *v, long flag}

\fun{GEN}{sd_breakloop}{const char *v, long flag}

\fun{GEN}{sd_colors}{const char *v, long flag}

\fun{GEN}{sd_compatible}{const char *v, long flag}

\fun{GEN}{sd_datadir}{const char *v, long flag}

\fun{GEN}{sd_debug}{const char *v, long flag}

\fun{GEN}{sd_debugfiles}{const char *v, long flag}

\fun{GEN}{sd_debugmem}{const char *v, long flag}

\fun{GEN}{sd_echo}{const char *v, long flag}

\fun{GEN}{sd_factor_add_primes}{const char *v, long flag}

\fun{GEN}{sd_factor_proven}{const char *v, long flag}

\fun{GEN}{sd_format}{const char *v, long flag}

\fun{GEN}{sd_graphcolormap}{const char *v, long flag}

\fun{GEN}{sd_graphcolors}{const char *v, long flag}

\fun{GEN}{sd_help}{const char *v, long flag}

\fun{GEN}{sd_histfile}{const char *v, long flag}

\fun{GEN}{sd_histsize}{const char *v, long flag}

\fun{GEN}{sd_lines}{const char *v, long flag}

\fun{GEN}{sd_linewrap}{const char *v, long flag}

\fun{GEN}{sd_log}{const char *v, long flag}

\fun{GEN}{sd_logfile}{const char *v, long flag}

\fun{GEN}{sd_nbthreads}{const char *v, long flag}

\fun{GEN}{sd_new_galois_format}{const char *v, long flag}

\fun{GEN}{sd_output}{const char *v, long flag}

\fun{GEN}{sd_parisize}{const char *v, long flag}

\fun{GEN}{sd_parisizemax}{const char *v, long flag}

\fun{GEN}{sd_path}{const char *v, long flag}

\fun{GEN}{sd_prettyprinter}{const char *v, long flag}

\fun{GEN}{sd_primelimit}{const char *v, long flag}

\fun{GEN}{sd_prompt}{const char *v, long flag}

\fun{GEN}{sd_prompt_cont}{const char *v, long flag}

\fun{GEN}{sd_psfile}{const char *v, long flag}

\fun{GEN}{sd_readline}{const char *v, long flag}

\fun{GEN}{sd_realbitprecision}{const char *v, long flag}

\fun{GEN}{sd_realprecision}{const char *v, long flag}

\fun{GEN}{sd_recover}{const char *v, long flag}

\fun{GEN}{sd_secure}{const char *v, long flag}

\fun{GEN}{sd_seriesprecision}{const char *v, long flag}

\fun{GEN}{sd_simplify}{const char *v, long flag}

\fun{GEN}{sd_sopath}{const char *v, int flag}

\fun{GEN}{sd_strictargs}{const char *v, long flag}

\fun{GEN}{sd_strictmatch}{const char *v, long flag}

\fun{GEN}{sd_timer}{const char *v, long flag}

\fun{GEN}{sd_threadsize}{const char *v, long flag}

\fun{GEN}{sd_threadsizemax}{const char *v, long flag}

\noindent Generic functions used to implement defaults: most of the above
routines are implemented in terms of the following generic ones. In all
routines below

\item \kbd{v} and \kbd{flag} are the arguments passed to \kbd{default}:
\kbd{v} is a new value (or the empty string: no change), and \kbd{flag} is one
of \tet{d_INITRC}, \tet{d_RETURN}, etc.

\item \kbd{s} is the name of the default being changed, used to display error
messages or acknowledgements.

\fun{GEN}{sd_toggle}{const char *v, long flag, const char *s, int *ptn}

\item if \kbd{v} is neither \kbd{"0"} nor \kbd{"1"}, an error is raised using
\tet{pari_err}.

\item \kbd{ptn} points to the current numerical value of the toggle (1 or 0),
and is set to the new value (when \kbd{v} is non-empty).

For instance, here is how the timer default is implemented internally:
\bprog
GEN
sd_timer(const char *v, long flag)
{ return sd_toggle(v,flag,"timer", &(GP_DATA->chrono)); }
@eprog

The exact behavior and return value depends on \kbd{flag}:

\item \tet{d_RETURN}: returns the new toggle value, as a \kbd{GEN}.

\item \tet{d_ACKNOWLEDGE}: prints a message indicating the new toggle value
and return \kbd{gnil}.

\item other cases: print nothing and return \kbd{gnil}.


\fun{GEN}{sd_ulong}{const char *v, long flag, const char *s, ulong *ptn,
ulong Min, ulong Max, const char **msg}\hbadness 10000

\item \kbd{ptn} points to the current numerical value of the toggle, and is set
to the new value (when \kbd{v} is non-empty).

\item \kbd{Min} and \kbd{Max} point to the minimum and maximum values allowed
for the default.

\item \kbd{v} must translate to an integer in the allowed ranger, a suffix
among
\kbd{k}/\kbd{K} ($\times 10^3$),
\kbd{m}/\kbd{M} ($\times 10^6$),
or
\kbd{g}/\kbd{G} ($\times 10^9$) is allowed, but no arithmetic expression.

\item \kbd{msg} is a \kbd[NULL]-terminated array of messages or \kbd{NULL}
(ignored). If \kbd{msg} is not \kbd{NULL}, \kbd{msg}$[i]$ contains
a message attached to the value $i$ of the default. The last entry in the
\kbd{msg} array is used as a message attached to all subsequent ones.

The exact behavior and return value depends on \kbd{flag}:

\item \tet{d_RETURN}: returns the new toggle value, as a \kbd{GEN}.

\item \tet{d_ACKNOWLEDGE}: prints a message indicating the new value,
possibly a message attached to it via the \kbd{msg} argument, and return
\kbd{gnil}.

\item other cases: print nothing and return \kbd{gnil}.

\fun{GEN}{sd_string}{const char *v, long flag, const char *s, char **pstr}
\item \kbd{v} is subjet to environment expansion, then time expansion.

\item \kbd{pstr} points to the current string value, and is set to the new
value (when \kbd{v} is non-empty).

\section{Records and Lazy vectors}
The functions in this section are used to implement \kbd{ell} structures and
analogous objects, which are vectors some of whose components are initialized
to dummy values, later computed on demand. We start by initializing the
structure:

\fun{GEN}{obj_init}{long d, long n} returns an \tev{obj} $S$, a \typ{VEC}
with $d$ regular components, accessed as \kbd{gel(S,1)}, \dots,
\kbd{gel(S,d)}; together with a record of $n$ members, all initialized to
$0$. The arguments $d$ and $n$ must be non-negative.

After \kbd{S = obj\_init(d, n)}, the prototype of our other functions are of
the form
\bprog
  GEN obj_do(GEN S, long tag, ...)
@eprog\noindent The first argument $S$ holds the structure to be managed.
The second argument \var{tag} is the index of the struct member (from $1$ to
$n$) we operate on. We recommend to define an \kbd{enum} and use descriptive
names instead of hardcoded numbers. For instance, if $n = 3$, after defining
\bprog
  enum { TAG_p = 1, TAG_list, TAG_data };
@eprog\noindent one may use \kbd{TAG\_list} or $2$ indifferently as a tag.
The former being preferred, of course.

\misctitle{Technical note}
In the current implementation, $S$ is a \typ{VEC} with $d+1$ entries.
The first $d$ components are ordinary \typ{GEN} entries, which you can
read or assign to in the customary way. But the last component $\kbd{gel(S,
d+1)}$, a \typ{VEC} of length $n$ initialized to \kbd{zerovec}$(n)$, must
be handled in a special way: you should never access or modify its components
directly, only through the API we are about to describe. Indeed, its entries
are meant to contain dynamic data, which will be stored, retrieved and
replaced (for instance by a value computed to a higher accuracy), while
interacting safely with intermediate \kbd{gerepile} calls. This mechanism
allows to simulate C \kbd{struct}s, in a simpler way than with general
hashtables, while remaining compatible with the GP language, which knows
neither structs nor hashtables. It also serialize the structure in an
ordinary \kbd{GEN}, which facilitates copies and garbage collection (use
\kbd{gcopy} or \kbd{gerepile}), rather than having to deal with individual
components of actual C \kbd{struct}s.

\fun{GEN}{obj_reinit}{GEN S} make a shallow copy of $S$, re-initializing
all dynamic components. This allows ``forking'' a lazy vector while
avoiding both a memory leak, and storing pointers to the same data
in different objects (with risks of a double free later).

\fun{GEN}{obj_check}{GEN S, long tag} if the \emph{tag}-component in $S$
is non empty, return it. Otherwise return \kbd{NULL}. The \typ{INT} $0$
(initial value) is used as a sentinel to indicated an empty component.

\fun{GEN}{obj_insert}{GEN S, long tag, GEN O} insert (a clone of) $O$
as \emph{tag}-component of $S$. Any previous value is deleted, and
data pointing to it become invalid.

\fun{GEN}{obj_insert_shallow}{GEN S, long K, GEN O} as \tet{obj_insert},
inserting $O$ as-is, not via a clone.

\fun{GEN}{obj_checkbuild}{GEN S, long tag, GEN (*build)(GEN)} if the
\emph{tag}-component of $S$ is non empty, return it. Otherwise insert
(a clone of) \kbd{build(S)} as \emph{tag}-component in $S$, and return it.

\fun{GEN}{obj_checkbuild_padicprec}{GEN S, long tag, GEN (*build)(GEN,long),
long prec}
if the \emph{tag}-component of $S$ is non empty \emph{and} has relative
$p$-adic precision $\geq \kbd{prec}$, return it. Otherwise insert (a clone
of) \kbd{build(S, prec)} as \emph{tag}-component in $S$, and return it.

\fun{GEN}{obj_checkbuild_realprec}{GEN S, long tag, GEN (*build)(GEN, long),
long prec} if the \emph{tag}-component of $S$ is non empty \emph{and}
satisfies \kbd{gprecision} $\geq \kbd{prec}$, return it. Otherwise insert (a
clone of) \kbd{build(S, prec)} as \emph{tag}-component in $S$, and return it.

\fun{GEN}{obj_checkbuild_prec}{GEN S, long tag, GEN (*build)(GEN,long), GEN
(*gpr)(GEN), long prec} if the \emph{tag}-component of $S$ is non empty
\emph{and} has precision $\kbd{gpr}(x)\geq \kbd{prec}$, return it. Otherwise
insert (a clone of) \kbd{build(S, prec)} as \emph{tag}-component in $S$,
and return it.

\fun{void}{obj_free}{GEN S} destroys all clones stored in the $n$ tagged
components, and replace them by the initial value $0$. The regular entries of
$S$ are unaffected, and $S$ remains a valid object. This is used to
avoid memory leaks.