summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl.straw/lib/Math/libPARI.dumb.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl.straw/lib/Math/libPARI.dumb.pod')
-rwxr-xr-xMaster/tlpkg/tlperl.straw/lib/Math/libPARI.dumb.pod8045
1 files changed, 8045 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl.straw/lib/Math/libPARI.dumb.pod b/Master/tlpkg/tlperl.straw/lib/Math/libPARI.dumb.pod
new file mode 100755
index 00000000000..6925a6bc243
--- /dev/null
+++ b/Master/tlpkg/tlperl.straw/lib/Math/libPARI.dumb.pod
@@ -0,0 +1,8045 @@
+=head1 NAME
+
+libPARI - Functions and Operations Available in PARI and GP
+
+=head1 DESCRIPTION
+
+X<Label se:functions>
+The functions and operators available in PARI and in the GP/PARI calculator
+are numerous and everexpanding. Here is a description of the ones available
+in version B<2.2.0>. It should be noted that many of these functions accept
+quite different types as arguments, but others are more restricted. The list
+of acceptable types will be given for each function or class of functions.
+Except when stated otherwise, it is understood that a function or operation
+which should make natural sense is legal. In this chapter, we will describe
+the functions according to a rough classification. The general entry looks
+something like:
+
+B<foo>C<(x,{>I<flag>C< = 0})>: short description.
+
+X<foo>The library syntax is B<foo>C<(x,>I<flag>C<)>.
+
+This means that the GP function C<foo> has one mandatory argument C<x>, and
+an optional one, I<flag>, whose default value is 0 (the C<{}> should never be
+typed, it is just a convenient notation we will use throughout to denote
+optional arguments). That is, you can type C<foo(x,2)>, or C<foo(x)>,
+which is then understood to mean C<foo(x,0)>. As well, a comma or closing
+parenthesis, where an optional argument should have been, signals to GP it
+should use the default. Thus, the syntax C<foo(x,)> is also accepted as a
+synonym for our last expression. When a function has more than one optional
+argument, the argument list is filled with user supplied values, in order.
+And when none are left, the defaults are used instead. Thus, assuming that
+C<foo>'s prototype had been
+
+S< >
+B<foo>C<({x = 1},{y = 2},{z = 3}),
+>
+
+typing in C<foo(6,4)> would give
+you C<foo(6,4,3)>. In the rare case when you want to set some far away
+flag, and leave the defaults in between as they stand, you can use the
+``empty arg'' trick alluded to above: C<foo(6,,1)> would yield
+C<foo(6,2,1)>. By the way, C<foo()> by itself yields
+C<foo(1,2,3)> as was to be expected. In this rather special case of a
+function having no mandatory argument, you can even omit the C<()>: a
+standalone C<foo> would be enough (though we don't really recommend it for
+your scripts, for the sake of clarity). In defining GP syntax, we strove
+to put optional arguments at the end of the argument list (of course, since
+they would not make sense otherwise), and in order of decreasing usefulness
+so that, most of the time, you will be able to ignore them.
+
+B<Binary Flags>.X<binary flag> For some of these optional
+flags, we adopted the customary binary notation as a compact way to
+represent many toggles with just one number. Letting C<(p_0,...,p_n)> be a
+list of switches (i.e.S< >of properties which can be assumed to take either
+the value C<0> orS< >C<1>), the number C<2^3 + 2^5 = 40> means that C<p_3> and C<p_5>
+have been set (that is, set to C<1>), and none of the others were (that is,
+they were set to 0). This will usually be announced as ``The binary digits
+of I<flag> mean 1: C<p_0>, 2: C<p_1>, 4: C<p_2>'', and so on, using the
+available consecutive powers ofS< >C<2>.
+
+B<Pointers>.X<pointer> If a parameter in the function
+prototype is prefixed with a & sign, as in
+
+B<foo>C<(x,&e)>
+
+it means that, besides the normal return value, the variable named
+C<e> may be set as a side effect. When passing the argument, the & sign has
+to be typed in explicitly. As of version B<2.2.0>, this X<pointer>C<pointer> argument
+is optional for all documented functions, hence the & will always appear
+between brackets as in C<issquare>C<(x,{&e})>.
+
+B<About library programming>. To finish with our generic
+simple-minded example, the I<library> function C<foo>, as defined
+above, is seen to have two mandatory arguments, C<x> and I<flag> (no PARI
+mathematical function has been implemented so as to accept a variable
+number of arguments). When not mentioned otherwise, the result and
+arguments of a function are assumed implicitly to be of type C<GEN>.
+Most other functions return an object of type C<long> integer in C (see
+ChapterS< >4). The variable or parameter names I<prec> and I<flag> always
+denote C<long> integers.
+
+The X<entree>C<entree> type is used by the library to implement iterators (loops,
+sums, integrals, etc.) when a formal variable has to successively assume a
+number of values in a given set. When programming with the library, it is
+easier and much more efficient to code loops and the like directly. Hence
+this type is not documented, although it does appear in a few library
+function prototypes below. See L<Label se:sums> for more details.
+
+=head1 Standard monadic or dyadic operators
+
+=head2 +C</>-
+
+The expressions C<+>C<x> and C<->C<x> refer
+to monadic operators (the first does nothing, the second negates C<x>).
+
+X<gneg>The library syntax is B<gneg>C<(x)> for C<->C<x>.
+
+=head2 +, C<->
+
+The expression C<x> C<+> C<y> is the X<sum>sum and
+C<x> C<-> C<y> is the X<difference>difference of C<x> and C<y>. Among the prominent
+impossibilities are addition/subtraction between a scalar type and a vector
+or a matrix, between vector/matrices of incompatible sizes and between an
+integermod and a real number.
+
+X<gadd>The library syntax is B<gadd>C<(x,y)> C<x> C<+> C<y>, X<gsub>B<gsub>C<(x,y)> for C<x> C<-> C<y>.
+
+=head2 *
+
+The expression C<x> C<*> C<y> is the X<product>product of C<x>
+and C<y>. Among the prominent impossibilities are multiplication between
+vector/matrices of incompatible sizes, between an integermod and a real
+number. Note that because of vector and matrix operations, C<*> is not
+necessarily commutative. Note also that since multiplication between two
+column or two row vectors is not allowed, to obtain the X<scalar product>scalar product
+of two vectors of the same length, you must multiply a line vector by a
+column vector, if necessary by transposing one of the vectors (using
+the operator C<~> or the function C<mattranspose>, see
+L<Label se:linear_algebra>).
+
+If C<x> and C<y> are binary quadratic forms, compose them. See also
+C<qfbnucomp> and C<qfbnupow>.
+
+X<gmul>The library syntax is B<gmul>C<(x,y)> for C<x> C<*> C<y>. Also available is
+X<gsqr>B<gsqr>C<(x)> for C<x> C<*> C<x> (faster of course!).
+
+=head2 /
+
+The expression C<x> C</> C<y> is the X<quotient>quotient of C<x>
+and C<y>. In addition to the impossibilities for multiplication, note that if
+the divisor is a matrix, it must be an invertible square matrix, and in that
+case the result is C<x*y^{-1}>. Furthermore note that the result is as exact
+as possible: in particular, division of two integers always gives a rational
+number (which may be an integer if the quotient is exact) and I<not> the
+Euclidean quotient (see C<x> C<\> C<y> for that), and similarly the
+quotient of two polynomials is a rational function in general. To obtain the
+approximate real value of the quotient of two integers, add C<0.> to the
+result; to obtain the approximate C<p>-adic value of the quotient of two
+integers, add C<O(p^k)> to the result; finally, to obtain the
+X<Taylor series>Taylor series expansion of the quotient of two polynomials, add
+C<O(X^k)> to the result or use the C<taylor> function
+(see L<Label se:taylor>). X<Label se:gdiv>
+
+X<gdiv>The library syntax is B<gdiv>C<(x,y)> for C<x> C</> C<y>.
+
+=head2 \
+
+The expression C<x> C<\> C<y> is the
+
+X<Euclidean quotient>Euclidean quotient of C<x> and C<y>. The types must be either both
+integer or both polynomials. The result is the Euclidean quotient. In the
+case of integer division, the quotient is such that the corresponding
+remainder is non-negative.
+
+X<gdivent>The library syntax is B<gdivent>C<(x,y)> for C<x> C<\> C<y>.
+
+=head2 \/
+
+The expression C<x> C<\/> C<y> is the Euclidean
+quotient of C<x> and C<y>. The types must be either both integer or both
+polynomials. The result is the rounded Euclidean quotient. In the case of
+integer division, the quotient is such that the corresponding remainder is
+smallest in absolute value and in case of a tie the quotient closest to
+C<+ oo > is chosen.
+
+X<gdivround>The library syntax is B<gdivround>C<(x,y)> for C<x> C<\/> C<y>.
+
+=head2 %
+
+The expression C<x> C<%> C<y> is the
+
+X<Euclidean remainder>Euclidean remainder of C<x> and C<y>. The modulus C<y> must be of type
+integer or polynomial. The result is the remainder, always non-negative in
+the case of integers. Allowed dividend types are scalar exact types when
+the modulus is an integer, and polynomials, polmods and rational functions
+when the modulus is a polynomial.
+
+X<gmod>The library syntax is B<gmod>C<(x,y)> for C<x> C<%> C<y>.
+
+=head2 X<divrem>divremC<(x,y)>
+
+creates a column vector with two components,
+the first being the Euclidean quotient, the second the Euclidean remainder,
+of the division of C<x> by C<y>. This avoids the need to do two divisions if
+one needs both the quotient and the remainder. The arguments must be both
+integers or both polynomials; in the case of integers, the remainder is
+non-negative.
+
+X<gdiventres>The library syntax is B<gdiventres>C<(x,y)>.
+
+=head2 ^
+
+The expression C<x^n> is X<powering>powering.
+If the exponent is an integer, then exact operations are performed using
+binary (left-shift) powering techniques. In particular, in this case C<x>
+cannot be a vector or matrix unless it is a square matrix (and moreover
+invertible if the exponent is negative). If C<x> is a C<p>-adic number, its
+precision will increase if C<v_p(n) E<gt> 0>. PARI is able to rewrite the
+multiplication C<x * x> of two I<identical> objects as C<x^2>, or
+C<sqr(x)> (here, identical means the operands are two different labels
+referencing the same chunk of memory; no equality test is performed). This
+is no longer true when more than two arguments are involved.
+
+If the exponent is not of type integer, this is treated as a transcendental
+function (see L<Label se:trans>), and in particular has the effect of
+componentwise powering on vector or matrices.
+
+As an exception, if the exponent is a rational number C<p/q> and C<x> an
+integer modulo a prime, return a solution C<y> of C<y^q = x^p> if it
+exists. Currently, C<q> must not have large prime factors.
+
+Beware that
+
+ ? Mod(7,19)^(1/2)
+ %1 = Mod(11, 19)/*is any square root*/
+ ? sqrt(Mod(7,19))
+ %2 = Mod(8, 19)/*is the smallest square root*/
+ ? Mod(7,19)^(3/5)
+ %3 = Mod(1, 19)
+ ? %3^(5/3)
+ %4 = Mod(1, 19)/*Mod(7,19) is just another cubic root*/
+
+X<gpow>The library syntax is B<gpow>C<(x,n,>I<prec>C<)> for C<x^n>.
+
+=head2 X<shift>shiftC<(x,n)> or C<x> C<E<lt>E<lt> > C<n> ( = C<x> C<E<gt>E<gt> > C<(-n)>)
+
+shifts
+C<x> componentwise left by C<n> bits if C<n E<gt>= 0> and right by C<|n|> bits if
+C<n E<lt> 0>. A left shift by C<n> corresponds to multiplication by C<2^n>. A right
+shift of an integer C<x> by C<|n|> corresponds to a Euclidean division of
+C<x> by C<2^{|n|}> with a
+remainder of the same sign as C<x>, hence is not the same (in general) as
+C<x \ 2^n>.
+
+X<gshift>The library syntax is B<gshift>C<(x,n)> where C<n> is a C<long>.
+
+=head2 X<shiftmul>shiftmulC<(x,n)>
+
+multiplies C<x> by C<2^n>. The difference with
+C<shift> is that when C<n E<lt> 0>, ordinary division takes place, hence for
+example if C<x> is an integer the result may be a fraction, while for
+C<shift> Euclidean division takes place when C<n E<lt> 0> hence if C<x> is an
+integer the result is still an integer.
+
+X<gmul2n>The library syntax is B<gmul2n>C<(x,n)> where C<n> is a C<long>.
+
+=head2 Comparison and boolean operators
+
+X<boolean operators>
+The six standard X<comparison operators>comparison operators C<E<lt>= >, C<E<lt> >, C<E<gt>= >,
+C<E<gt> >, C< == >, C<! = > are available in GP, and in library mode under
+the names X<gle>B<gle>, X<glt>B<glt>, X<gge>B<gge>, X<ggt>B<ggt>, X<geq>B<geq>, X<gne>B<gne>
+respectively. The library syntax is I<co>C<(x,y)>, where I<co> is the
+comparison operator. The result is 1 (as a C<GEN>) if the comparison is
+true, 0 (as a C<GEN>) if it is false.
+
+The standard boolean functions C<||> (X<inclusive or>inclusive or), C<&&>
+(X<and>and)X<or> and C<!> (X<not>not) are also available, and the
+library syntax is X<gor>B<gor>C<(x,y)>, X<gand>B<gand>C<(x,y)> and X<gnot>B<gnot>C<(x)>
+respectively.
+
+In library mode, it is in fact usually preferable to use the two basic
+functions which are X<gcmp>B<gcmp>C<(x,y)> which gives the sign (1, 0, or -1) of
+C<x-y>, where C<x> and C<y> must be in B<R>, and X<gegal>B<gegal>C<(x,y)> which
+can be applied to any two PARI objects C<x> and C<y> and gives 1 (i.e.S< >true) if
+they are equal (but not necessarily identical), 0 (i.e.S< >false) otherwise.
+Particular cases of X<gegal>B<gegal> which should be used are X<gcmp0>B<gcmp0>C<(x)>
+(C<x == 0> ?), X<gcmp1>B<gcmp1>C<(x)> (C<x == 1> ?), and
+X<gcmp_1>B<gcmp_1>C<(x)> (C<x == -1> ?).
+
+Note that X<gcmp0>B<gcmp0>C<(x)> tests whether C<x> is equal to zero, even if C<x> is
+not an exact object. To test whether C<x> is an exact object which is equal to
+zero, one must use X<isexactzero>B<isexactzero>.
+
+Also note that the C<gcmp> and C<gegal> functions return a C-integer,
+and I<not> a C<GEN> like C<gle> etc.
+
+GP accepts the following synonyms for some of the above functions: since we
+thought it might easily lead to confusion, we don't use the customary C
+operators for bitwise C<and> or bitwise C<or> (use X<bitand>C<bitand> or
+X<bitor>C<bitor>), hence C<|> and C<&> are accepted as
+X<bitwise and>X<bitwise or> synonyms of C<||> and C<&&> respectively.
+Also, C<E<lt> E<gt> > is accepted as a synonym for C<! = >. On the other hand,
+C< = > is definitely I<not> a synonym for C< == > since it is the
+assignment statement.
+
+=head2 X<lex>lexC<(x,y)>
+
+gives the result of a lexicographic comparison
+between C<x> and C<y>. This is to be interpreted in quite a wide sense. For
+example, the vector C<[1,3]> will be considered smaller than the longer
+vector C<[1,3,-1]> (but of course larger than C<[1,2,5]>),
+i.e.S< >C<lex([1,3], [1,3,-1])> will return C<-1>.
+
+X<lexcmp>The library syntax is B<lexcmp>C<(x,y)>.
+
+=head2 X<sign>signC<(x)>
+
+X<sign>sign (C<0>, C<1> or C<-1>) of C<x>, which must be of
+type integer, real or fraction.
+
+X<gsigne>The library syntax is B<gsigne>C<(x)>. The result is a C<long>.
+
+=head2 X<max>maxC<(x,y)> and X<min>B<min>C<(x,y)>
+
+creates the
+maximum and minimum of C<x> and C<y> when they can be compared.
+
+X<gmax>The library syntax is B<gmax>C<(x,y)> and X<gmin>B<gmin>C<(x,y)>.
+
+=head2 X<vecmax>vecmaxC<(x)>
+
+if C<x> is a vector or a matrix, returns the maximum
+of the elements of C<x>, otherwise returns a copy of C<x>. Returns C<- oo >
+in the form of C<-(2^{31}-1)> (or C<-(2^{63}-1)> for 64-bit machines) if C<x> is
+empty.
+
+X<vecmax>The library syntax is B<vecmax>C<(x)>.
+
+=head2 X<vecmin>vecminC<(x)>
+
+if C<x> is a vector or a matrix, returns the minimum
+of the elements of C<x>, otherwise returns a copy of C<x>. Returns C<+ oo >
+in the form of C<2^{31}-1> (or C<2^{63}-1> for 64-bit machines) if C<x> is empty.
+
+X<vecmin>The library syntax is B<vecmin>C<(x)>.
+
+=head1 Conversions and similar elementary functions or commands
+
+X<Label se:conversion>
+Many of the conversion functions are rounding or truncating operations. In
+this case, if the argument is a rational function, the result is the
+Euclidean quotient of the numerator by the denominator, and if the argument
+is a vector or a matrix, the operation is done componentwise. This will not
+be restated for every function.
+
+=head2 X<List>ListC<({x = []})>
+
+transforms a (row or column) vector C<x>
+into a list. The only other way to create a C<t_LIST> is to use the
+function C<listcreate>.
+
+This is useless in library mode.
+
+=head2 X<Mat>MatC<({x = []})>
+
+transforms the object C<x> into a matrix.
+If C<x> is not a vector or a matrix, this creates a C<1 x 1> matrix.
+If C<x> is a row (resp. column) vector, this creates a 1-row (resp.
+1-column) matrix. If C<x> is already a matrix, a copy of C<x> is created.
+
+This function can be useful in connection with the function C<concat>
+(see there).
+
+X<gtomat>The library syntax is B<gtomat>C<(x)>.
+
+=head2 X<Mod>ModC<(x,y,{>I<flag>C< = 0})>
+
+X<Label se:Mod> creates the PARI object
+C<(x mod y)>, i.e.S< >an integermod or a polmod. C<y> must be an integer or a
+polynomial. If C<y> is an integer, C<x> must be an integer, a rational
+number, or a C<p>-adic number compatible with the modulus C<y>. If C<y> is a
+polynomial, C<x> must be a scalar (which is not a polmod), a polynomial, a
+rational function, or a power series.
+
+This function is not the same as C<x> C<%> C<y>, the result of which is an
+integer or a polynomial.
+
+If I<flag> is equal to C<1>, the modulus of the created result is put on the
+heap and not on the stack, and hence becomes a permanent copy which cannot be
+erased later by garbage collecting (see L<Label se:garbage>). Functions
+will operate faster on such objects and memory consumption will be lower.
+On the other hand, care should be taken to avoid creating too many such
+objects.
+
+Under GP, the same effect can be obtained by assigning the object to a GP
+variable (the value of which is a permanent object for the duration of the
+relevant library function call, and is treated as such). This value is
+subject to garbage collection, since it will be deleted when the value
+changes. This is preferable and the above flag is only retained for
+compatibility reasons (it can still be useful in library mode).
+
+X<Mod0>The library syntax is B<Mod0>C<(x,y,>I<flag>C<)>. Also available are
+
+B<*> for I<flag>C< = 1>: X<gmodulo>B<gmodulo>C<(x,y)>.
+
+B<*> for I<flag>C< = 0>: X<gmodulcp>B<gmodulcp>C<(x,y)>.
+
+=head2 X<Pol>PolC<(x,{v = x})>
+
+transforms the object C<x> into a polynomial with
+main variable C<v>. If C<x> is a scalar, this gives a constant polynomial. If
+C<x> is a power series, the effect is identical to C<truncate> (see there),
+i.e.S< >it chops off the C<O(X^k)>. If C<x> is a vector, this function creates
+the polynomial whose coefficients are given in C<x>, with C<x[1]> being the
+leading coefficient (which can be zero).
+
+Warning: this is I<not> a substitution function. It is intended to be
+quick and dirty. So if you try C<Pol(a,y)> on the polynomial C<a = x+y>,
+you will get C<y+y>, which is not a valid PARI object.
+
+X<gtopoly>The library syntax is B<gtopoly>C<(x,v)>, where C<v> is a variable number.
+
+=head2 X<Polrev>PolrevC<(x,{v = x})>
+
+transform the object C<x> into a polynomial
+with main variable C<v>. If C<x> is a scalar, this gives a constant polynomial.
+If C<x> is a power series, the effect is identical to C<truncate> (see
+there), i.e.S< >it chops off the C<O(X^k)>. If C<x> is a vector, this function
+creates the polynomial whose coefficients are given in C<x>, with C<x[1]> being
+the constant term. Note that this is the reverse of C<Pol> if C<x> is a
+vector, otherwise it is identical to C<Pol>.
+
+X<gtopolyrev>The library syntax is B<gtopolyrev>C<(x,v)>, where C<v> is a variable number.
+
+=head2 X<Qfb>QfbC<(a,b,c,{D = 0.})>
+
+creates the binary quadratic form
+C<ax^2+bxy+cy^2>. If C<b^2-4ac E<gt> 0>, initialize X<Shanks>Shanks' distance
+function to C<D>.
+
+X<Qfb0>The library syntax is B<Qfb0>C<(a,b,c,D,>I<prec>C<)>. Also available are
+X<qfi>B<qfi>C<(a,b,c)> (when C<b^2-4ac E<lt> 0>), and
+X<qfr>B<qfr>C<(a,b,c,d)> (when C<b^2-4ac E<gt> 0>).X<binary quadratic form>
+
+=head2 X<Ser>SerC<(x,{v = x})>
+
+transforms the object C<x> into a power series
+with main variable C<v> (C<x> by default). If C<x> is a scalar, this gives a
+constant power series with precision given by the default C<serieslength>
+(corresponding to the C global variable C<precdl>). If C<x> is a
+polynomial, the precision is the greatest of C<precdl> and the degree of
+the polynomial. If C<x> is a vector, the precision is similarly given, and the
+coefficients of the vector are understood to be the coefficients of the power
+series starting from the constant term (i.e.S< >the reverse of the function
+C<Pol>).
+
+The warning given for C<Pol> applies here: this is not a substitution
+function.
+
+X<gtoser>The library syntax is B<gtoser>C<(x,v)>, where C<v> is a variable number (i.e.S< >a C integer).
+
+=head2 X<Set>SetC<({x = []})>
+
+converts C<x> into a set, i.e.S< >into a row vector
+with strictly increasing entries. C<x> can be of any type, but is most useful
+when C<x> is already a vector. The components of C<x> are put in canonical form
+(type C<t_STR>) so as to be easily sorted. To recover an ordinary C<GEN>
+from such an element, you can apply X<eval>C<eval> to it.
+
+X<gtoset>The library syntax is B<gtoset>C<(x)>.
+
+=head2 X<Str>StrC<({x = ""},{>I<flag>C< = 0})>
+
+converts C<x> into a
+character string (type C<t_STR>, the empty string if C<x> is omitted). To
+recover an ordinary C<GEN> from a string, apply C<eval> to it. The
+arguments of C<Str> are evaluated in string context (see
+L<Label se:strings>). If I<flag> is set, treat C<x> as a filename and perform
+X<environment expansion>environment expansion on the string. This feature can be used to read
+X<environment variable>environment variable values.
+
+ ? i = 1; Str("x" i)
+ %1 = "x1"
+ ? eval(%)
+ %2 = x1;
+ ? Str("$HOME", 1)
+ %3 = "/home/pari"
+
+X<strtoGENstr>The library syntax is B<strtoGENstr>C<(x,>I<flag>C<)>. This function is mostly useless in library mode. Use
+the pair X<strtoGEN>C<strtoGEN>/X<GENtostr>C<GENtostr> to convert between C<char*> and
+C<GEN>.
+
+=head2 X<Vec>VecC<({x = []})>
+
+transforms the object C<x> into a row vector. The
+vector will be with one component only, except when C<x> is a vector/matrix or
+a quadratic form (in which case the resulting vector is simply the initial
+object considered as a row vector), but more importantly when C<x> is a
+polynomial or a power series. In the case of a polynomial, the coefficients
+of the vector start with the leading coefficient of the polynomial, while
+for power series only the significant coefficients are taken into account,
+but this time by increasing order of degree.
+
+X<gtovec>The library syntax is B<gtovec>C<(x)>.
+
+=head2 X<binary>binaryC<(x)>
+
+outputs the vector of the binary digits of C<|x|>.
+Here C<x> can be an integer, a real number (in which case the result has two
+components, one for the integer part, one for the fractional part) or a
+vector/matrix.
+
+X<binaire>The library syntax is B<binaire>C<(x)>.
+
+=head2 X<bitand>bitandC<(x,y)>
+
+bitwise X<and>C<and>X<bitwise and> of two
+integers C<x> and C<y>, that is the integer
+
+S< >F<sum>C< (x_iS< >andS< >y_i) 2^i>
+
+Negative numbers behave as if modulo a huge power of C<2>.
+
+X<gbitand>The library syntax is B<gbitand>C<(x,y)>.
+
+=head2 X<bitneg>bitnegC<(x,{n = -1})>
+
+X<bitwise negation>bitwise negation of an integer C<x>,
+truncated to C<n> bits, that is the integer
+
+S< >F<sum>C<_{i = 0}^n not(x_i) 2^i>
+
+The special case C<n = -1> means no truncation: an infinite sequence of
+leading C<1> is then represented as a negative number.
+
+Negative numbers behave as if modulo a huge power of C<2>.
+
+X<gbitneg>The library syntax is B<gbitneg>C<(x)>.
+
+=head2 X<bitnegimply>bitnegimplyC<(x,y)>
+
+bitwise negated imply of two integers C<x>
+and C<y> (or C<not> C<(x ==E<gt> y)>), that is the integer
+
+S< >F<sum>C< (x_iS< >and not(y_i)) 2^i>
+
+Negative numbers behave as if modulo a huge power of C<2>.
+
+X<gbitnegimply>The library syntax is B<gbitnegimply>C<(x,y)>.
+
+=head2 X<bitor>bitorC<(x,y)>
+
+bitwise (inclusive) X<or>C<or>
+X<bitwise inclusive or> of two integers C<x> and C<y>, that is the integer
+
+S< >F<sum>C< (x_iS< >orS< >y_i) 2^i>
+
+Negative numbers behave as if modulo a huge power of C<2>.
+
+X<gbitor>The library syntax is B<gbitor>C<(x,y)>.
+
+=head2 X<bittest>bittestC<(x,n)>
+
+outputs the C<n^{th}> bit of C<|x|> starting
+from the right (i.e.S< >the coefficient of C<2^n> in the binary expansion of C<x>).
+The result is 0 or 1. To extract several bits at once as a vector, pass a
+vector for C<n>.
+
+X<bittest>The library syntax is B<bittest>C<(x,n)>, where C<n> and the result are C<long>s.
+
+=head2 X<bitxor>bitxorC<(x,y)>
+
+bitwise (exclusive) X<or>C<or>
+X<bitwise exclusive or> of two integers C<x> and C<y>, that is the integer
+
+S< >F<sum>C< (x_iS< >xorS< >y_i) 2^i>
+
+Negative numbers behave as if modulo a huge power of C<2>.
+
+X<gbitxor>The library syntax is B<gbitxor>C<(x,y)>.
+
+=head2 X<ceil>ceilC<(x)>
+
+ceiling of C<x>. When C<x> is in B<R>,
+the result is the smallest integer greater than or equal to C<x>. Applied to a
+rational function, C<ceil(x)> returns the euclidian quotient of the
+numerator by the denominator.
+
+X<gceil>The library syntax is B<gceil>C<(x)>.
+
+=head2 X<centerlift>centerliftC<(x,{v})>
+
+lifts an element C<x = a mod n> of B<Z>C</n>B<Z>
+to C<a> in B<Z>, and similarly lifts a polmod to a polynomial. This is the
+same as C<lift> except that in the particular case of elements of
+B<Z>C</n>B<Z>, the lift C<y> is such that C<-n/2 E<lt> y E<lt>= n/2>. If C<x> is of type
+fraction, complex, quadratic, polynomial, power series, rational function,
+vector or matrix, the lift is done for each coefficient. Real and C<p>-adics
+are forbidden.
+
+X<centerlift0>The library syntax is B<centerlift0>C<(x,v)>, where C<v> is a C<long> and an omitted C<v> is coded
+as C<-1>. Also available is X<centerlift>B<centerlift>C<(x)> = C<centerlift0(x,-1)>.
+
+=head2 X<changevar>changevarC<(x,y)>
+
+creates a copy of the object C<x> where its
+variables are modified according to the permutation specified by the vector
+C<y>. For example, assume that the variables have been introduced in the
+order C<x>, C<a>, C<b>, C<c>. Then, if C<y> is the vector
+C<[x,c,a,b]>, the variable C<a> will be replaced by C<c>, C<b> by
+C<a>, and C<c> by C<b>, C<x> being unchanged. Note that the
+permutation must be completely specified, e.g.S< >C<[c,a,b]> would not work,
+since this would replace C<x> by C<c>, and leave C<a> and C<b>
+unchanged (as well as C<c> which is the fourth variable of the initial
+list). In particular, the new variable names must be distinct.
+
+X<changevar>The library syntax is B<changevar>C<(x,y)>.
+
+=head2 components of a PARI object
+
+There are essentially three ways to extract the X<components>components from a PARI
+object.
+
+The first and most general, is the function X<component>B<component>C<(x,n)> which
+extracts the C<n^{th}>-component of C<x>. This is to be understood as
+follows: every PARI type has one or two initial X<code words>code words. The
+components are counted, starting at 1, after these code words. In particular
+if C<x> is a vector, this is indeed the C<n^{th}>-component of C<x>, if
+C<x> is a matrix, the C<n^{th}> column, if C<x> is a polynomial, the
+C<n^{th}> coefficient (i.e.S< >of degree C<n-1>), and for power series, the
+C<n^{th}> significant coefficient. The use of the function
+C<component> implies the knowledge of the structure of the different PARI
+types, which can be recalled by typing C<\t> under GP.
+
+X<compo>The library syntax is B<compo>C<(x,n)>, where C<n> is a C<long>.
+
+The two other methods are more natural but more restricted. The function
+ B<polcoeff>C<(x,n)>X<polcoeff> gives the coefficient of degree C<n> of the polynomial
+or power series C<x>, with respect to the main variable of C<x> (to check
+variable ordering, or to change it, use the function X<reorder>C<reorder>, see
+L<Label se:reorder>). In particular if C<n> is less than the valuation of
+C<x> or in the case of a polynomial, greater than the degree, the result is
+zero (contrary to C<compo> which would send an error message). If C<x> is
+a power series and C<n> is greater than the largest significant degree, then
+an error message is issued.
+
+For greater flexibility, vector or matrix types are also accepted for C<x>,
+and the meaning is then identical with that of C<compo>.
+
+Finally note that a scalar type is considered by C<polcoeff> as a
+polynomial of degree zero.
+
+X<truecoeff>The library syntax is B<truecoeff>C<(x,n)>.
+
+The third method is specific to vectors or matrices under GP. If C<x> is a
+(row or column) vector, then X<x[n]>C<x[n]> represents the C<n^{th}>
+component of C<x>, i.e.S< >C<compo(x,n)>. It is more natural and shorter to
+write. If C<x> is a matrix, X<x[m,n]>C<x[m,n]> represents the coefficient of
+row C<m> and column C<n> of the matrix, X<x[m,]>C<x[m,]> represents
+the C<m^{th}> I<row> of C<x>, and X<x[,n]>C<x[,n]> represents
+the C<n^{th}> I<column> of C<x>.
+
+Finally note that in library mode, the macros X<coeff>B<coeff> and X<mael>B<mael>
+are available to deal with the non-recursivity of the C<GEN> type from the
+compiler's point of view. See the discussion on typecasts in Chapter 4.
+
+=head2 X<conj>conjC<(x)>
+
+conjugate of C<x>. The meaning of this
+is clear, except that for real quadratic numbers, it means conjugation in the
+real quadratic field. This function has no effect on integers, reals,
+integermods, fractions or C<p>-adics. The only forbidden type is polmod
+(see C<conjvec> for this).
+
+X<gconj>The library syntax is B<gconj>C<(x)>.
+
+=head2 X<conjvec>conjvecC<(x)>
+
+conjugate vector representation of C<x>. If C<x> is a
+polmod, equal to C<Mod>C<(a,q)>, this gives a vector of length
+C<degree(q)> containing the complex embeddings of the polmod if C<q> has
+integral or rational coefficients, and the conjugates of the polmod if C<q>
+has some integermod coefficients. The order is the same as that of the
+C<polroots> functions. If C<x> is an integer or a rational number, the
+result isS< >C<x>. If C<x> is a (row or column) vector, the result is a matrix
+whose columns are the conjugate vectors of the individual elements of C<x>.
+
+X<conjvec>The library syntax is B<conjvec>C<(x,>I<prec>C<)>.
+
+=head2 X<denominator>denominatorC<(x)>
+
+lowest denominator of C<x>. The meaning of this
+is clear when C<x> is a rational number or function. When C<x> is an integer
+or a polynomial, the result is equal to C<1>. When C<x> is a vector or a matrix,
+the lowest common denominator of the components of C<x> is computed. All other
+types are forbidden.
+
+X<denom>The library syntax is B<denom>C<(x)>.
+
+=head2 X<floor>floorC<(x)>
+
+floor of C<x>. When C<x> is in B<R>, the result is the
+largest integer smaller than or equal to C<x>. Applied to a rational function,
+C<floor(x)> returns the euclidian quotient of the numerator by the
+denominator.
+
+X<gfloor>The library syntax is B<gfloor>C<(x)>.
+
+=head2 X<frac>fracC<(x)>
+
+fractional part of C<x>. Identical to
+C<x-floor(x)>. If C<x> is real, the result is in C<[0,1[>.
+
+X<gfrac>The library syntax is B<gfrac>C<(x)>.
+
+=head2 X<imag>imagC<(x)>
+
+imaginary part of C<x>. When
+C<x> is a quadratic number, this is the coefficient of F<omega> in
+the ``canonical'' integral basis C<(1,>F<omega>C<)>.
+
+X<gimag>The library syntax is B<gimag>C<(x)>.
+
+=head2 X<length>lengthC<(x)>
+
+number of non-code words in C<x> really used (i.e.S< >the
+effective length minus 2 for integers and polynomials). In particular,
+the degree of a polynomial is equal to its length minus 1. If C<x> has type
+C<t_STR>, output number of letters.
+
+X<glength>The library syntax is B<glength>C<(x)> and the result is a C long.
+
+=head2 X<lift>liftC<(x,{v})>
+
+lifts an element C<x = a mod n> of B<Z>C</n>B<Z> to
+C<a> in B<Z>, and similarly lifts a polmod to a polynomial if C<v> is omitted.
+Otherwise, lifts only polmods with main variable C<v> (if C<v> does not occur
+in C<x>, lifts only intmods). If C<x> is of type fraction, complex, quadratic,
+polynomial, power series, rational function, vector or matrix, the lift is
+done for each coefficient. Forbidden types for C<x> are reals and C<p>-adics.
+
+X<lift0>The library syntax is B<lift0>C<(x,v)>, where C<v> is a C<long> and an omitted C<v> is coded as
+C<-1>. Also available is X<lift>B<lift>C<(x)> = C<lift0(x,-1)>.
+
+=head2 X<norm>normC<(x)>
+
+algebraic norm of C<x>, i.e.S< >the product of C<x> with
+its conjugate (no square roots are taken), or conjugates for polmods. For
+vectors and matrices, the norm is taken componentwise and hence is not the
+C<L^2>-norm (see C<norml2>). Note that the norm of an element of
+B<R> is its square, so as to be compatible with the complex norm.
+
+X<gnorm>The library syntax is B<gnorm>C<(x)>.
+
+=head2 X<norml2>norml2C<(x)>
+
+square of the C<L^2>-norm of C<x>. C<x> must
+be a (row or column) vector.
+
+X<gnorml2>The library syntax is B<gnorml2>C<(x)>.
+
+=head2 X<numerator>numeratorC<(x)>
+
+numerator of C<x>. When C<x> is a rational number
+or function, the meaning is clear. When C<x> is an integer or a polynomial,
+the result is C<x> itself. When C<x> is a vector or a matrix, then
+C<numerator(x)> is defined to be C<denominator(x)*x>. All other types
+are forbidden.
+
+X<numer>The library syntax is B<numer>C<(x)>.
+
+=head2 X<numtoperm>numtopermC<(n,k)>
+
+generates the C<k>-th permutation (as a
+row vector of length C<n>) of the numbers C<1> to C<n>. The number C<k> is taken
+modulo C<n!>, i.e.S< >inverse function of X<permtonum>C<permtonum>.
+
+X<permute>The library syntax is B<permute>C<(n,k)>, where C<n> is a C<long>.
+
+=head2 X<padicprec>padicprecC<(x,p)>
+
+absolute C<p>-adic precision of the object C<x>.
+This is the minimum precision of the components of C<x>. The result is
+C<VERYBIGINT> (C<2^{31}-1> for 32-bit machines or C<2^{63}-1> for 64-bit
+machines) if C<x> is an exact object.
+
+X<padicprec>The library syntax is B<padicprec>C<(x,p)> and the result is a C<long>
+integer.
+
+=head2 X<permtonum>permtonumC<(x)>
+
+given a permutation C<x> on C<n> elements,
+gives the number C<k> such that C<x = numtoperm(n,k)>, i.e.S< >inverse
+function of X<numtoperm>C<numtoperm>.
+
+X<permuteInv>The library syntax is B<permuteInv>C<(x)>.
+
+=head2 X<precision>precisionC<(x,{n})>
+
+gives the precision in decimal digits of the
+PARI object C<x>. If C<x> is an exact object, the largest single precision
+integer is returned. If C<n> is not omitted, creates a new object equal to C<x>
+with a new precision C<n>. This is to be understood as follows:
+
+For exact types, no change. For C<x> a vector or a matrix, the operation
+is done componentwise.
+
+For real C<x>, C<n> is the number of desired significant I<decimal> digits.
+If C<n> is smaller than the precision of C<x>, C<x> is truncated, otherwise C<x>
+is extended with zeros.
+
+For C<x> a C<p>-adic or a power series, C<n> is the desired number of
+significant C<p>-adic or C<X>-adic digits, where C<X> is the main variable of
+C<x>.
+
+Note that the function C<precision> never changes the type of the result.
+In particular it is not possible to use it to obtain a polynomial from a
+power series. For that, see C<truncate>.
+
+X<precision0>The library syntax is B<precision0>C<(x,n)>, where C<n> is a C<long>. Also available are
+X<ggprecision>B<ggprecision>C<(x)> (result is a C<GEN>) and X<gprec>B<gprec>C<(x,n)>, where
+C<n> is a C<long>.
+
+=head2 X<random>randomC<({N = 2^{31}})>
+
+gives a random integer between 0 and
+C<N-1>. C<N> can be arbitrary large. This is an internal PARI function and does
+not depend on the system's random number generator. Note that the resulting
+integer is obtained by means of linear congruences and will not be well
+distributed in arithmetic progressions.
+
+X<genrand>The library syntax is B<genrand>C<(N)>.
+
+=head2 X<real>realC<(x)>
+
+real part of C<x>. In the case where C<x> is a quadratic
+number, this is the coefficient of C<1> in the ``canonical'' integral basis
+C<(1,>F<omega>C<)>.
+
+X<greal>The library syntax is B<greal>C<(x)>.
+
+=head2 X<round>roundC<(x,{&e})>
+
+If C<x> is in B<R>, rounds C<x> to the nearest
+integer and sets C<e> to the number of error bits, that is the binary exponent
+of the difference between the original and the rounded value (the
+``fractional part''). If the exponent of C<x> is too large compared to its
+precision (i.e.S< >C<e E<gt> 0>), the result is undefined and an error occurs if C<e>
+was not given.
+
+B<Important remark:> note that, contrary to the other truncation
+functions, this function operates on every coefficient at every level of a
+PARI object. For example
+
+S< >C<truncate((2.4*X^2-1.7)/(X)) = 2.4*X,>
+
+whereas
+
+S< >C<round((2.4*X^2-1.7)/(X)) = (2*X^2-2)/(X).>
+
+An important use of C<round> is to get exact results after a long
+approximate computation, when theory tells you that the coefficients
+must be integers.
+
+X<grndtoi>The library syntax is B<grndtoi>C<(x,&e)>, where C<e> is a C<long> integer. Also available is
+X<ground>B<ground>C<(x)>.
+
+=head2 X<simplify>simplifyC<(x)>
+
+this function tries to simplify the object C<x> as
+much as it can. The simplifications do not concern rational functions (which
+PARI automatically tries to simplify), but type changes. Specifically, a
+complex or quadratic number whose imaginary part is exactly equal to 0
+(i.e.S< >not a real zero) is converted to its real part, and a polynomial of
+degree zero is converted to its constant term. For all types, this of course
+occurs recursively. This function is useful in any case, but in particular
+before the use of arithmetic functions which expect integer arguments, and
+not for example a complex number of 0 imaginary part and integer real part
+(which is however printed as an integer).
+
+X<simplify>The library syntax is B<simplify>C<(x)>.
+
+=head2 X<sizebyte>sizebyteC<(x)>
+
+outputs the total number of bytes occupied by the
+tree representing the PARI object C<x>.
+
+X<taille2>The library syntax is B<taille2>C<(x)> which returns a C<long>. The
+function X<taille>B<taille> returns the number of I<words> instead.
+
+=head2 X<sizedigit>sizedigitC<(x)>
+
+outputs a quick bound for the number of decimal
+digits of (the components of) C<x>, off by at most C<1>. If you want the
+exact value, you can use C<length(Str(x))>, which is much slower.
+
+X<sizedigit>The library syntax is B<sizedigit>C<(x)> which returns a C<long>.
+
+=head2 X<truncate>truncateC<(x,{&e})>
+
+truncates C<x> and sets C<e> to the number of
+error bits. When C<x> is in B<R>, this means that the part after the decimal
+point is chopped away, C<e> is the binary exponent of the difference between
+the original and the truncated value (the ``fractional part''). If the
+exponent of C<x> is too large compared to its precision (i.e.S< >C<e E<gt> 0>), the
+result is undefined and an error occurs if C<e> was not given. The function
+applies componentwise on rational functions and vector / matrices; C<e> is
+then the maximal number of error bits.
+
+Note a very special use of C<truncate>: when applied to a power series, it
+transforms it into a polynomial or a rational function with denominator
+a power of C<X>, by chopping away the C<O(X^k)>. Similarly, when applied to
+a C<p>-adic number, it transforms it into an integer or a rational number
+by chopping away the C<O(p^k)>.
+
+X<gcvtoi>The library syntax is B<gcvtoi>C<(x,&e)>, where C<e> is a C<long> integer. Also available is
+X<gtrunc>B<gtrunc>C<(x)>.
+
+=head2 X<valuation>valuationC<(x,p)>
+
+X<Label se:valuation> computes the highest
+exponent of C<p> dividing C<x>. If C<p> is of type integer, C<x> must be an
+integer, an integermod whose modulus is divisible by C<p>, a fraction, a
+C<q>-adic number with C<q = p>, or a polynomial or power series in which case the
+valuation is the minimum of the valuation of the coefficients.
+
+If C<p> is of type polynomial, C<x> must be of type polynomial or rational
+function, and also a power series if C<x> is a monomial. Finally, the
+valuation of a vector, complex or quadratic number is the minimum of the
+component valuations.
+
+If C<x = 0>, the result is C<VERYBIGINT> (C<2^{31}-1> for 32-bit machines or
+C<2^{63}-1> for 64-bit machines) if C<x> is an exact object. If C<x> is a
+C<p>-adic numbers or power series, the result is the exponent of the zero.
+Any other type combinations gives an error.
+
+X<ggval>The library syntax is B<ggval>C<(x,p)>, and the result is a C<long>.
+
+=head2 X<variable>variableC<(x)>
+
+gives the main variable of the object C<x>, and
+C<p> if C<x> is a C<p>-adic number. Gives an error if C<x> has no variable
+associated to it. Note that this function is useful only in GP, since in
+library mode the function C<gvar> is more appropriate.
+
+X<gpolvar>The library syntax is B<gpolvar>C<(x)>. However, in library mode, this function should not be used.
+Instead, test whether C<x> is a C<p>-adic (type C<t_PADIC>), in which case C<p>
+is in C<x[2]>, or call the function B<gvar>C<(x)> which returns the variable
+I<number> of C<x> if it exists, C<BIGINT> otherwise.
+
+=head1 Transcendental functions
+
+X<Label se:trans>
+As a general rule, which of course in some cases may have exceptions,
+transcendental functions operate in the following way:
+
+B<*> If the argument is either an integer, a real, a rational, a complex
+or a quadratic number, it is, if necessary, first converted to a real (or
+complex) number using the current X<precision>precision held in the default
+C<realprecision>. Note that only exact arguments are converted, while
+inexact arguments such as reals are not.
+
+Under GP this is transparent to the user, but when programming in library
+mode, care must be taken to supply a meaningful parameter I<prec> as the
+last argument of the function if the first argument is an exact object.
+This parameter is ignored if the argument is inexact.
+
+Note that in library mode the precision argument I<prec> is a word
+count including codewords, i.e.S< >represents the length in words of a real
+number, while under GP the precision (which is changed by the metacommand
+C<\p> or using C<default(realprecision,...)>) is the number of significant
+decimal digits.
+
+Note that some accuracies attainable on 32-bit machines cannot be attained
+on 64-bit machines for parity reasons. For example the default GP accuracy
+is 28 decimal digits on 32-bit machines, corresponding to I<prec> having
+the value 5, but this cannot be attained on 64-bit machines.
+
+After possible conversion, the function is computed. Note that even if the
+argument is real, the result may be complex (e.g.S< >C<acos(2.0)> or
+C<acosh(0.0)>). Note also that the principal branch is always chosen.
+
+B<*> If the argument is an integermod or a C<p>-adic, at present only a
+few functions like C<sqrt> (square root), C<sqr> (square), C<log>,
+C<exp>, powering, C<teichmuller> (TeichmE<uuml>ller character) and
+C<agm> (arithmetic-geometric mean) are implemented.
+
+Note that in the case of a C<2>-adic number, C<sqr(x)> may not be
+identical to C<x*x>: for example if C<x = 1+O(2^5)> and C<y = 1+O(2^5)> then
+C<x*y = 1+O(2^5)> while C<sqr(x) = 1+O(2^6)>. Here, C<x * x> yields the
+same result as C<sqr(x)> since the two operands are known to be I<
+identical>. The same statement holds true for C<p>-adics raised to the power
+C<n>, where C<v_p(n) E<gt> 0>.
+
+B<Remark:> note that if we wanted to be strictly consistent with
+the PARI philosophy, we should have C<x*y = (4 mod 8)> and C<sqr(x) =
+(4 mod 32)> when both C<x> and C<y> are congruent to C<2> modulo C<4>.
+However, since integermod is an exact object, PARI assumes that the modulus
+must not change, and the result is hence C<(0 mod 4)> in both cases. On
+the other hand, C<p>-adics are not exact objects, hence are treated
+differently.
+
+B<*> If the argument is a polynomial, power series or rational function,
+it is, if necessary, first converted to a power series using the current
+precision held in the variable X<precdl>C<precdl>. Under GP this again is
+transparent to the user. When programming in library mode, however, the
+global variable C<precdl> must be set before calling the function if the
+argument has an exact type (i.e.S< >not a power series). Here C<precdl> is
+not an argument of the function, but a global variable.
+
+Then the Taylor series expansion of the function around C<X = 0> (where C<X> is
+the main variable) is computed to a number of terms depending on the number
+of terms of the argument and the function being computed.
+
+B<*> If the argument is a vector or a matrix, the result is the
+componentwise evaluation of the function. In particular, transcendental
+functions on square matrices, which are not implemented in the present
+version B<2.2.0> (see AppendixS< >B however), will have a slightly different name
+if they are implemented some day.
+
+=head2 ^
+
+If C<y> is not of type integer, C<x^y> has the same
+effect as C<exp(y*ln(x))>. It can be applied to C<p>-adic numbers as
+well as to the more usual types.X<powering>
+
+X<gpow>The library syntax is B<gpow>C<(x,y,>I<prec>C<)>.
+
+=head2 Euler
+
+Euler's constant C<0.57721...>. Note that C<Euler>
+is one of the few special reserved names which cannot be used for variables
+(the others are C<I> and C<Pi>, as well as all function names).
+X<Label se:euler>
+
+X<mpeuler>The library syntax is B<mpeuler>C<(>I<prec>C<)> where I<prec> I<must> be given. Note that
+this creates F<gamma> on the PARI stack, but a copy is also created on the
+heap for quicker computations next time the function is called.
+
+=head2 I
+
+the complex number F<sqrt> C<{-1}>.
+
+The library syntax is the global variable C<gi> (of type C<GEN>).
+
+=head2 Pi
+
+the constant F<Pi> (C<3.14159...>).X<Label se:pi>
+
+X<mppi>The library syntax is B<mppi>C<(>I<prec>C<)> where I<prec> I<must> be given. Note that this
+creates F<Pi> on the PARI stack, but a copy is also created on the heap for
+quicker computations next time the function is called.
+
+=head2 X<abs>absC<(x)>
+
+absolute value of C<x> (modulus if C<x> is complex).
+Power series and rational functions are not allowed. Contrary to most
+transcendental functions, an exact argument is I<not> converted to a real
+number before applying C<abs> and an exact result is returned if possible.
+
+ ? abs(-1)
+ %1 = 1
+ ? abs(3/7 + 4/7*I)
+ %2 = 5/7
+ ? abs(1 + I)
+ %3 = 1.414213562373095048801688724
+
+If C<x> is a polynomial, returns C<-x> if the leading coefficient is
+real and negative else returns C<x>. For a power series, the constant
+coefficient is considered instead.
+
+X<gabs>The library syntax is B<gabs>C<(x,>I<prec>C<)>.
+
+=head2 X<acos>acosC<(x)>
+
+principal branch of C<cos^{-1}(x)>,
+i.e.S< >such that C<Re(acos(x)) belongs to [0,>F<Pi>C<]>. If
+C<x belongs to >B<R> and C<|x| E<gt> 1>, then C<acos(x)> is complex.
+
+X<gacos>The library syntax is B<gacos>C<(x,>I<prec>C<)>.
+
+=head2 X<acosh>acoshC<(x)>
+
+principal branch of C<cosh^{-1}(x)>,
+i.e.S< >such that C<Im(acosh(x)) belongs to [0,>F<Pi>C<]>. If
+C<x belongs to >B<R> and C<x E<lt> 1>, then C<acosh(x)> is complex.
+
+X<gach>The library syntax is B<gach>C<(x,>I<prec>C<)>.
+
+=head2 X<agm>agmC<(x,y)>
+
+arithmetic-geometric mean of C<x> and C<y>. In the
+case of complex or negative numbers, the principal square root is always
+chosen. C<p>-adic or power series arguments are also allowed. Note that
+a C<p>-adic agm exists only if C<x/y> is congruent to 1 modulo C<p> (modulo
+16 for C<p = 2>). C<x> and C<y> cannot both be vectors or matrices.
+
+X<agm>The library syntax is B<agm>C<(x,y,>I<prec>C<)>.
+
+=head2 X<arg>argC<(x)>
+
+argument of the complex number C<x>, such that
+C<->F<Pi>C< E<lt> arg(x) E<lt>= >F<Pi>.
+
+X<garg>The library syntax is B<garg>C<(x,>I<prec>C<)>.
+
+=head2 X<asin>asinC<(x)>
+
+principal branch of C<sin^{-1}(x)>, i.e.S< >such
+that C<Re(asin(x)) belongs to [->F<Pi>C</2,>F<Pi>C</2]>. If C<x belongs to >B<R> and C<|x| E<gt> 1> then
+C<asin(x)> is complex.
+
+X<gasin>The library syntax is B<gasin>C<(x,>I<prec>C<)>.
+
+=head2 X<asinh>asinhC<(x)>
+
+principal branch of C<sinh^{-1}(x)>, i.e.S< >such
+that C<Im(asinh(x)) belongs to [->F<Pi>C</2,>F<Pi>C</2]>.
+
+X<gash>The library syntax is B<gash>C<(x,>I<prec>C<)>.
+
+=head2 X<atan>atanC<(x)>
+
+principal branch of C<tan^{-1}(x)>, i.e.S< >such
+that C<Re(atan(x)) belongs to ]->F<Pi>C</2,>F<Pi>C</2[>.
+
+X<gatan>The library syntax is B<gatan>C<(x,>I<prec>C<)>.
+
+=head2 X<atanh>atanhC<(x)>
+
+principal branch of C<tanh^{-1}(x)>, i.e.S< >such
+that C<Im(atanh(x)) belongs to ]->F<Pi>C</2,>F<Pi>C</2]>. If C<x belongs to >B<R> and C<|x| E<gt> 1> then
+C<atanh(x)> is complex.
+
+X<gath>The library syntax is B<gath>C<(x,>I<prec>C<)>.
+
+=head2 X<bernfrac>bernfracC<(x)>
+
+Bernoulli numberX<Bernoulli numbers> C<B_x>,
+where C<B_0 = 1>, C<B_1 = -1/2>, C<B_2 = 1/6>,..., expressed as a rational number.
+The argument C<x> should be of type integer.
+
+X<bernfrac>The library syntax is B<bernfrac>C<(x)>.
+
+=head2 X<bernreal>bernrealC<(x)>
+
+Bernoulli numberX<Bernoulli numbers>
+C<B_x>, as C<bernfrac>, but C<B_x> is returned as a real number
+(with the current precision).
+
+X<bernreal>The library syntax is B<bernreal>C<(x,>I<prec>C<)>.
+
+=head2 X<bernvec>bernvecC<(x)>
+
+creates a vector containing, as rational numbers,
+the X<Bernoulli numbers>Bernoulli numbers C<B_0>, C<B_2>,..., C<B_{2x}>. These Bernoulli
+numbers can then be used as follows. Assume that this vector has been put
+into a variable, say C<bernint>. Then you can define under GP:
+
+ bern(x) =
+ {
+ if (x == 1, return(-1/2));
+ if (x < 0 || x % 2, return(0));
+ bernint[x/2+1]
+ }
+
+and then C<bern(k)> gives the Bernoulli number of index C<k> as a
+rational number, exactly as C<bernreal(k)> gives it as a real number. If
+you need only a few values, calling C<bernfrac(k)> each time will be much
+more efficient than computing the huge vector above.
+
+X<bernvec>The library syntax is B<bernvec>C<(x)>.
+
+=head2 X<besseljh>besseljhC<(n,x)>
+
+C<J>-Bessel function of half integral index.
+More precisely, C<besseljh(n,x)> computes C<J_{n+1/2}(x)> where C<n>
+must be of type integer, and C<x> is any element of B<C>. In the
+present version B<2.2.0>, this function is not very accurate when C<x> is
+small.
+
+X<jbesselh>The library syntax is B<jbesselh>C<(n,x,>I<prec>C<)>.
+
+=head2 X<besselk>besselkC<(>I<nu>C<,x,{>I<flag>C< = 0})>
+
+C<K>-Bessel function of index
+I<nu> (which can be complex) and argument C<x>. Only real and positive
+arguments
+C<x> are allowed in the present version B<2.2.0>. If I<flag> is equal to 1,
+uses another implementation of this function which is often faster.
+
+X<kbessel>The library syntax is B<kbessel>C<(>I<nu>C<,x,>I<prec>C<)> and
+X<kbessel2>B<kbessel2>C<(>I<nu>C<,x,>I<prec>C<)> respectively.
+
+=head2 X<cos>cosC<(x)>
+
+cosine of C<x>.
+
+X<gcos>The library syntax is B<gcos>C<(x,>I<prec>C<)>.
+
+=head2 X<cosh>coshC<(x)>
+
+hyperbolic cosine of C<x>.
+
+X<gch>The library syntax is B<gch>C<(x,>I<prec>C<)>.
+
+=head2 X<cotan>cotanC<(x)>
+
+cotangent of C<x>.
+
+X<gcotan>The library syntax is B<gcotan>C<(x,>I<prec>C<)>.
+
+=head2 X<dilog>dilogC<(x)>
+
+principal branch of the dilogarithm of C<x>,
+i.e.S< >analytic continuation of the power series F<log> C<_2(x) = >F<sum>C<_{n E<gt>= 1}x^n/n^2>.
+
+X<dilog>The library syntax is B<dilog>C<(x,>I<prec>C<)>.
+
+=head2 X<eint1>eint1C<(x,{n})>
+
+exponential integral
+F<int>C<_x^ oo (e^{-t})/(t)dt> (C<x belongs to >B<R>)
+
+If C<n> is present, outputs the C<n>-dimensional vector
+C<[eint1(x),...,eint1(nx)]> (C<x E<gt>= 0>). This is faster than
+repeatedly calling C<eint1(i * x)>.
+
+X<veceint1>The library syntax is B<veceint1>C<(x,n,>I<prec>C<)>. Also available is
+X<eint1>B<eint1>C<(x,>I<prec>C<)>.
+
+=head2 X<erfc>erfcC<(x)>
+
+complementary error function
+C<(2/> F<sqrt> F<Pi>C<)>F<int>C<_x^ oo e^{-t^2}dt>.
+
+X<erfc>The library syntax is B<erfc>C<(x,>I<prec>C<)>.
+
+=head2 X<eta>etaC<(x,{>I<flag>C< = 0})>
+
+X<Dedekind>Dedekind's F<eta> function, without the
+C<q^{1/24}>. This means the following: if C<x> is a complex number with positive
+imaginary part, the result is F<prod>C<_{n = 1}^ oo (1-q^n)>, where
+C<q = e^{2i>F<Pi>C< x}>. If C<x> is a power series (or can be converted to a power
+series) with positive valuation, the result is F<prod>C<_{n = 1}^ oo (1-x^n)>.
+
+If I<flag>C< = 1> and C<x> can be converted to a complex number (i.e.S< >is not a power
+series), computes the true F<eta> function, including the leading C<q^{1/24}>.
+
+X<eta>The library syntax is B<eta>C<(x,>I<prec>C<)>.
+
+=head2 X<exp>expC<(x)>
+
+exponential of C<x>.
+C<p>-adic arguments with positive valuation are accepted.
+
+X<gexp>The library syntax is B<gexp>C<(x,>I<prec>C<)>.
+
+=head2 X<gammah>gammahC<(x)>
+
+gamma function evaluated at the argument
+C<x+1/2>. When C<x> is an integer, this is much faster than using
+C<gamma(x+1/2)>.
+
+X<ggamd>The library syntax is B<ggamd>C<(x,>I<prec>C<)>.
+
+=head2 X<gamma>gammaC<(x)>
+
+gamma function of C<x>. In the present version
+B<2.2.0> the C<p>-adic gamma function is not implemented.
+
+X<ggamma>The library syntax is B<ggamma>C<(x,>I<prec>C<)>.
+
+=head2 X<hyperu>hyperuC<(a,b,x)>
+
+C<U>-confluent hypergeometric function with
+parameters C<a> and C<b>. The parameters C<a> and C<b> can be complex but
+the present implementation requires C<x> to be positive.
+
+X<hyperu>The library syntax is B<hyperu>C<(a,b,x,>I<prec>C<)>.
+
+=head2 X<incgam>incgamC<(s,x,{y})>
+
+incomplete gamma function.
+
+C<x> must be positive and C<s> real. The result returned is F<int>C<_x^ oo
+e^{-t}t^{s-1}dt>. When C<y> is given, assume (of course without checking!)
+that C<y = >F<Gamma>C<(s)>. For small C<x>, this will tremendously speed up the
+computation.
+
+X<incgam>The library syntax is B<incgam>C<(s,x,>I<prec>C<)> and X<incgam4>B<incgam4>C<(s,x,y,>I<prec>C<)>,
+respectively. There exist also the functions X<incgam1>B<incgam1> and
+X<incgam2>B<incgam2> which are used for internal purposes.
+
+=head2 X<incgamc>incgamcC<(s,x)>
+
+complementary incomplete gamma function.
+
+The arguments C<s> and C<x> must be positive. The result returned is
+F<int>C<_0^x e^{-t}t^{s-1}dt>, when C<x> is not too large.
+
+X<incgam3>The library syntax is B<incgam3>C<(s,x,>I<prec>C<)>.
+
+=head2 X<log>logC<(x,{>I<flag>C< = 0})>
+
+principal branch of the natural logarithm of
+C<x>, i.e.S< >such that C<Im(ln(x)) belongs to ]->F<Pi>C<,>F<Pi>C<]>. The result is complex
+(with imaginary part equal to F<Pi>) if C<x belongs to >B<R> and C<x E<lt> 0>.
+
+C<p>-adic arguments are also accepted for C<x>, with the convention that
+ F<ln> C<(p) = 0>. Hence in particular F<exp> C<(> F<ln> C<(x))/x> will not in general be
+equal to 1 but to a C<(p-1)>-th root of unity (or C<F<+->1> if C<p = 2>)
+times a power of C<p>.
+
+If I<flag> is equal to 1, use an agm formula suggested by Mestre, when C<x> is
+real, otherwise identical to C<log>.
+
+X<glog>The library syntax is B<glog>C<(x,>I<prec>C<)> or X<glogagm>B<glogagm>C<(x,>I<prec>C<)>.
+
+=head2 X<lngamma>lngammaC<(x)>
+
+principal branch of the logarithm of the gamma
+function of C<x>. Can have much larger arguments than C<gamma> itself.
+In the present version B<2.2.0>, the C<p>-adic C<lngamma> function is not
+implemented.
+
+X<glngamma>The library syntax is B<glngamma>C<(x,>I<prec>C<)>.
+
+=head2 X<polylog>polylogC<(m,x,{>I<flag>C< = 0})>
+
+one of the different polylogarithms,
+depending on I<flag>:
+
+If I<flag>C< = 0> or is omitted: C<m^th> polylogarithm of C<x>, i.e.S< >analytic
+continuation of the power series C<Li_m(x) = >F<sum>C<_{n E<gt>= 1}x^n/n^m>. The
+program uses the power series when C<|x|^2 E<lt>= 1/2>, and the power series
+expansion in F<log> C<(x)> otherwise. It is valid in a large domain (at least
+C<|x| E<lt> 230>), but should not be used too far away from the unit circle since it
+is then better to use the functional equation linking the value at C<x> to the
+value at C<1/x>, which takes a trivial form for the variant below. Power
+series, polynomial, rational and vector/matrix arguments are allowed.
+
+For the variants to follow we need a notation: let F<Re> C<_m>
+denotes F<Re> or F<Im> depending whether C<m> is odd or even.
+
+If I<flag>C< = 1>: modified C<m^th> polylogarithm of C<x>, called
+C<~ D_m(x)> in Zagier, defined for C<|x| E<lt>= 1> by
+
+S< > F<Re> C<_m(>F<sum>C<_{k = 0}^{m-1} ((-> F<log> C<|x|)^k)/(k!)Li_{m-k}(x)
++((-> F<log> C<|x|)^{m-1})/(m!)> F<log> C<|1-x|).>
+
+If I<flag>C< = 2>: modified C<m^th> polylogarithm of C<x>,
+called C<D_m(x)> in Zagier, defined for C<|x| E<lt>= 1> by
+
+S< > F<Re> C<_m(>F<sum>C<_{k = 0}^{m-1}((-> F<log> C<|x|)^k)/(k!)Li_{m-k}(x)
+-(1)/(2)((-> F<log> C<|x|)^m)/(m!)).>
+
+If I<flag>C< = 3>: another modified C<m^th>
+polylogarithm of C<x>, called C<P_m(x)> in Zagier, defined for C<|x| E<lt>= 1> by
+
+S< > F<Re> C<_m(>F<sum>C<_{k = 0}^{m-1}(2^kB_k)/(k!)(> F<log> C<|x|)^kLi_{m-k}(x)
+-(2^{m-1}B_m)/(m!)(> F<log> C<|x|)^m).>
+
+These three functions satisfy the functional equation
+C<f_m(1/x) = (-1)^{m-1}f_m(x)>.
+
+X<polylog0>The library syntax is B<polylog0>C<(m,x,>I<flag>C<,>I<prec>C<)>.
+
+=head2 X<psi>psiC<(x)>
+
+the F<psi>-function of C<x>, i.e.S< >the
+logarithmic derivative F<Gamma>C<'(x)/>F<Gamma>C<(x)>.
+
+X<gpsi>The library syntax is B<gpsi>C<(x,>I<prec>C<)>.
+
+=head2 X<sin>sinC<(x)>
+
+sine of C<x>.
+
+X<gsin>The library syntax is B<gsin>C<(x,>I<prec>C<)>.
+
+=head2 X<sinh>sinhC<(x)>
+
+hyperbolic sine of C<x>.
+
+X<gsh>The library syntax is B<gsh>C<(x,>I<prec>C<)>.
+
+=head2 X<sqr>sqrC<(x)>
+
+square of C<x>. This operation is not completely
+straightforward, i.e.S< >identical to C<x * x>, since it can usually be
+computed more efficiently (roughly one-half of the elementary
+multiplications can be saved). Also, squaring a C<2>-adic number increases
+its precision. For example,
+
+ ? (1 + O(2^4))^2
+ %1 = 1 + O(2^5)
+ ? (1 + O(2^4)) * (1 + O(2^4))
+ %2 = 1 + O(2^4)
+
+Note that this function is also called whenever one multiplies two objects
+which are known to be I<identical>, e.g.S< >they are the value of the same
+variable, or we are computing a power.
+
+ ? x = (1 + O(2^4)); x * x
+ %3 = 1 + O(2^5)
+ ? (1 + O(2^4))^4
+ %4 = 1 + O(2^6)
+
+(note the difference between C<%2> and C<%3> above).
+
+X<gsqr>The library syntax is B<gsqr>C<(x)>.
+
+=head2 X<sqrt>sqrtC<(x)>
+
+principal branch of the square root of C<x>,
+i.e.S< >such that C<Arg(sqrt(x)) belongs to ]->F<Pi>C</2, >F<Pi>C</2]>, or in other
+words such that F<Re> C<(sqrt(x)) E<gt> 0> or F<Re> C<(sqrt(x)) = 0> and
+ F<Im> C<(sqrt(x)) E<gt>= 0>. If C<x belongs to >B<R> and C<x E<lt> 0>, then the result is
+complex with positive imaginary part.
+
+Integermod a prime and C<p>-adics are allowed as arguments. In that case,
+the square root (if it exists) which is returned is the one whose
+first C<p>-adic digit (or its unique C<p>-adic digit in the case of
+integermods) is in the interval C<[0,p/2]>. When the argument is an
+integermod a non-prime (or a non-prime-adic), the result is undefined.
+
+X<gsqrt>The library syntax is B<gsqrt>C<(x,>I<prec>C<)>.
+
+=head2 X<sqrtn>sqrtnC<(x,n,{&z})>
+
+principal branch of the C<n>th root of C<x>,
+i.e.S< >such that C<Arg(sqrt(x)) belongs to ]->F<Pi>C</n, >F<Pi>C</n]>.
+
+Integermod a prime and C<p>-adics are allowed as arguments.
+
+If C<z> is present, it is set to a suitable root of unity allowing to
+recover all the other roots. If it was not possible, z is
+set to zero.
+
+The following script computes all roots in all possible cases:
+
+ sqrtnall(x,n)=
+ {
+ local(V,r,z,r2);
+ r = sqrtn(x,n, &z);
+ if (!z, error("Impossible case in sqrtn"));
+ if (type(x) == "t_INTMOD" || type(x)=="t_PADIC" ,
+ r2 = r*z; n = 1;
+ while (r2!=r, r2*=z;n++));
+ V = vector(n); V[1] = r;
+ for(i=2, n, V[i] = V[i-1]*z);
+ V
+ }
+ addhelp(sqrtnall,"sqrtnall(x,n):compute the vector of nth-roots of x");
+
+X<gsqrtn>The library syntax is B<gsqrtn>C<(x,n,&z,>I<prec>C<)>.
+
+=head2 X<tan>tanC<(x)>
+
+tangent of C<x>.
+
+X<gtan>The library syntax is B<gtan>C<(x,>I<prec>C<)>.
+
+=head2 X<tanh>tanhC<(x)>
+
+hyperbolic tangent of C<x>.
+
+X<gth>The library syntax is B<gth>C<(x,>I<prec>C<)>.
+
+=head2 X<teichmuller>teichmullerC<(x)>
+
+TeichmE<uuml>ller character of the C<p>-adic number
+C<x>.
+
+X<teich>The library syntax is B<teich>C<(x)>.
+
+=head2 X<theta>thetaC<(q,z)>
+
+Jacobi sine theta-function.
+
+X<theta>The library syntax is B<theta>C<(q,z,>I<prec>C<)>.
+
+=head2 X<thetanullk>thetanullkC<(q,k)>
+
+C<k>-th derivative at C<z = 0> of
+C<theta(q,z)>.
+
+X<thetanullk>The library syntax is B<thetanullk>C<(q,k,>I<prec>C<)>, where C<k> is a C<long>.
+
+=head2 X<weber>weberC<(x,{>I<flag>C< = 0})>
+
+one of Weber's three C<f> functions.
+If I<flag>C< = 0>, returns
+
+S< >C<f(x) = > F<exp> C<(-i>F<Pi>C</24).>F<eta>C<((x+1)/2)/>F<eta>C<(x) such that j = (f^{24}-16)^3/f^{24},>
+
+where C<j> is the elliptic C<j>-invariant (see the function C<ellj>).
+If I<flag>C< = 1>, returns
+
+S< >C<f_1(x) = >F<eta>C<(x/2)/>F<eta>C<(x) such that j = (f_1^{24}+16)^3/f_1^{24}.>
+
+Finally, if I<flag>C< = 2>, returns
+
+S< >C<f_2(x) = > F<sqrt> C<{2}>F<eta>C<(2x)/>F<eta>C<(x) such that j = (f_2^{24}+16)^3/f_2^{24}.>
+
+Note the identities C<f^8 = f_1^8+f_2^8> and C<ff_1f_2 = > F<sqrt> C<2>.
+
+X<weber0>The library syntax is B<weber0>C<(x,>I<flag>C<,>I<prec>C<)>, or
+X<wf>B<wf>C<(x,>I<prec>C<)>, X<wf1>B<wf1>C<(x,>I<prec>C<)> or
+X<wf2>B<wf2>C<(x,>I<prec>C<)>.
+
+=head2 X<zeta>zetaC<(s)>
+
+Riemann's zeta functionX<Riemann zeta-function>
+F<zeta>C<(s) = >F<sum>C<_{n E<gt>= 1}n^{-s}>, computed using the X<Euler-Maclaurin>Euler-Maclaurin
+summation formula, except when C<s> is of type integer, in which case it
+is computed using Bernoulli numbersX<Bernoulli numbers> for
+C<s E<lt>= 0> or C<s E<gt> 0> and even, and using modular forms for C<s E<gt> 0> and odd.
+
+X<gzeta>The library syntax is B<gzeta>C<(s,>I<prec>C<)>.
+
+=head1 Arithmetic functions
+
+X<Label se:arithmetic>
+These functions are by definition functions whose natural domain of
+definition is either B<Z> (or B<Z>C<_{ E<gt> 0}>), or sometimes polynomials
+over a base ring. Functions which concern polynomials exclusively will be
+explained in the next section. The way these functions are used is
+completely different from transcendental functions: in general only the types
+integer and polynomial are accepted as arguments. If a vector or matrix type
+is given, the function will be applied on each coefficient independently.
+
+In the present version B<2.2.0>, all arithmetic functions in the narrow sense
+of the wordS< >--- Euler's totientX<Euler totient function> function, the
+X<Moebius>Moebius function, the sums over divisors or powers of divisors
+etc.--- call, after trial division by small primes, the same versatile
+factoring machinery described under C<factorint>. It includes
+X<Shanks SQUFOF>Shanks SQUFOF, X<Pollard Rho>Pollard Rho, X<ECM>ECM and X<MPQS>MPQS stages, and
+has an early exit option for the functions X<moebius>B<moebius> and (the integer
+function underlying) X<issquarefree>B<issquarefree>. Note that it relies on a (fairly
+strong) probabilistic primality test: numbers found to be strong
+pseudo-primes after 10 successful trials of the X<Rabin-Miller>Rabin-Miller test are
+declared primes.
+
+=head2 X<addprimes>addprimesC<({x = []})>
+
+adds the primes contained in the vector
+C<x> (or the single integer C<x>) to the table computed upon GP initialization
+(by C<pari_init> in library mode), and returns a row vector whose first
+entries contain all primes added by the user and whose last entries have been
+filled up with 1's. In total the returned row vector has 100 components.
+Whenever C<factor> or C<smallfact> is subsequently called, first the
+primes in the table computed by C<pari_init> will be checked, and then
+the additional primes in this table. If C<x> is empty or omitted, just returns
+the current list of extra primes.
+
+The entries in C<x> are not checked for primality. They need only be positive
+integers not divisible by any of the pre-computed primes. It's in fact a nice
+trick to add composite numbers, which for example the function
+C<factor(x,0)> was not able to factor. In case the message ``impossible
+inverse modulo C<E<lt>>I<some integermod>C<E<gt>>'' shows up afterwards,
+you have just stumbled over a non-trivial factor. Note that the arithmetic
+functions in the narrow sense, like X<eulerphi>B<eulerphi>, do I<not> use this
+extra table.
+
+The present PARI version B<2.2.0> allows up to 100 user-specified
+primes to be appended to the table. This limit may be changed
+by altering C<NUMPRTBELT> in file C<init.c>. To remove primes from the
+list use C<removeprimes>.
+
+X<addprimes>The library syntax is B<addprimes>C<(x)>.
+
+=head2 X<bestappr>bestapprC<(x,k)>
+
+if C<x belongs to >B<R>, finds the best rational
+approximation to C<x> with denominator at most equal to C<k> using continued
+fractions.
+
+X<bestappr>The library syntax is B<bestappr>C<(x,k)>.
+
+=head2 X<bezout>bezoutC<(x,y)>
+
+finds C<u> and C<v> minimal in a
+natural sense such that C<x*u+y*v = gcd(x,y)>. The arguments
+must be both integers or both polynomials, and the result is a
+row vector with three components C<u>, C<v>, and C<gcd(x,y)>.
+
+X<vecbezout>The library syntax is B<vecbezout>C<(x,y)> to get the vector, or X<gbezout>B<gbezout>C<(x,y, &u, &v)>
+which gives as result the address of the created gcd, and puts
+the addresses of the corresponding created objects into C<u> and C<v>.
+
+=head2 X<bezoutres>bezoutresC<(x,y)>
+
+as C<bezout>, with the resultant of C<x> and
+C<y> replacing the gcd.
+
+X<vecbezoutres>The library syntax is B<vecbezoutres>C<(x,y)> to get the vector, or X<subresext>B<subresext>C<(x,y, &u,
+&v)> which gives as result the address of the created gcd, and puts the
+addresses of the corresponding created objects into C<u> and C<v>.
+
+=head2 X<bigomega>bigomegaC<(x)>
+
+number of prime divisors of C<|x|> counted with
+multiplicity. C<x> must be an integer.
+
+X<bigomega>The library syntax is B<bigomega>C<(x)>, the result is a C<long>.
+
+=head2 X<binomial>binomialC<(x,y)>
+
+X<binomial coefficient>binomial coefficient C<\binom x y>.
+Here C<y> must be an integer, but C<x> can be any PARI object.
+
+X<binome>The library syntax is B<binome>C<(x,y)>, where C<y> must be a C<long>.
+
+=head2 X<chinese>chineseC<(x,y)>
+
+if C<x> and C<y> are both integermods or both
+polmods, creates (with the same type) a C<z> in the same residue class
+as C<x> and in the same residue class as C<y>, if it is possible.
+
+This function also allows vector and matrix arguments, in which case the
+operation is recursively applied to each component of the vector or matrix.
+For polynomial arguments, it is applied to each coefficient. Finally
+C<chinese(x,x) = x> regardless of the type of C<x>; this allows vector
+arguments to contain other data, so long as they are identical in both
+vectors.
+
+X<chinois>The library syntax is B<chinois>C<(x,y)>.
+
+=head2 X<content>contentC<(x)>
+
+computes the gcd of all the coefficients of C<x>,
+when this gcd makes sense. If C<x> is a scalar, this simply returns C<x>. If C<x>
+is a polynomial (and by extension a power series), it gives the usual content
+of C<x>. If C<x> is a rational function, it gives the ratio of the contents of
+the numerator and the denominator. Finally, if C<x> is a vector or a matrix,
+it gives the gcd of all the entries.
+
+X<content>The library syntax is B<content>C<(x)>.
+
+=head2 X<contfrac>contfracC<(x,{b},{lmax})>
+
+creates the row vector whose
+components are the partial quotients of the X<continued fraction>continued fraction
+expansion of C<x>, the number of partial quotients being limited to C<lmax>.
+If C<x> is a real number, the expansion stops at the last significant partial
+quotient if C<lmax> is omitted. C<x> can also be a rational function or a power
+series.
+
+If a vector C<b> is supplied, the numerators will be equal to the coefficients
+of C<b>. The length of the result is then equal to the length of C<b>, unless a
+partial remainder is encountered which is equal to zero. In which case the
+expansion stops. In the case of real numbers, the stopping criterion is thus
+different from the one mentioned above since, if C<b> is too long, some partial
+quotients may not be significant.
+
+If C<b> is an integer, the command is understood as C<contfrac(x,lmax)>.
+
+X<contfrac0>The library syntax is B<contfrac0>C<(x,b,lmax)>. Also available are
+X<gboundcf>B<gboundcf>C<(x,lmax)>, X<gcf>B<gcf>C<(x)>, or X<gcf2>B<gcf2>C<(b,x)>, where C<lmax>
+is a C integer.
+
+=head2 X<contfracpnqn>contfracpnqnC<(x)>
+
+when C<x> is a vector or a one-row matrix, C<x>
+is considered as the list of partial quotients C<[a_0,a_1,...,a_n]> of a
+rational number, and the result is the 2 by 2 matrix
+C<[p_n,p_{n-1};q_n,q_{n-1}]> in the standard notation of continued fractions,
+so C<p_n/q_n = a_0+1/(a_1+...+1/a_n)...)>. If C<x> is a matrix with two rows
+C<[b_0,b_1,...,b_n]> and C<[a_0,a_1,...,a_n]>, this is then considered as a
+generalized continued fraction and we have similarly
+C<p_n/q_n = 1/b_0(a_0+b_1/(a_1+...+b_n/a_n)...)>. Note that in this case one
+usually has C<b_0 = 1>.
+
+X<pnqn>The library syntax is B<pnqn>C<(x)>.
+
+=head2 X<core>coreC<(n,{>I<flag>C< = 0})>
+
+if C<n> is a non-zero integer written as
+C<n = df^2> with C<d> squarefree, returns C<d>. If I<flag> is non-zero,
+returns the two-element row vector C<[d,f]>.
+
+X<core0>The library syntax is B<core0>C<(n,>I<flag>C<)>.
+Also available are
+X<core>B<core>C<(n)> ( = X<core>B<core>C<(n,0)>) and
+X<core2>B<core2>C<(n)> ( = X<core>B<core>C<(n,1)>).
+
+=head2 X<coredisc>corediscC<(n,{>I<flag>C<})>
+
+if C<n> is a non-zero integer written as
+C<n = df^2> with C<d> fundamental discriminant (including 1), returns C<d>. If
+I<flag> is non-zero, returns the two-element row vector C<[d,f]>. Note that if
+C<n> is not congruent to 0 or 1 modulo 4, C<f> will be a half integer and not
+an integer.
+
+X<coredisc0>The library syntax is B<coredisc0>C<(n,>I<flag>C<)>.
+Also available are
+X<coredisc>B<coredisc>C<(n)> ( = X<coredisc>B<coredisc>C<(n,0)>) and
+X<coredisc2>B<coredisc2>C<(n)> ( = X<coredisc>B<coredisc>C<(n,1)>).
+
+=head2 X<dirdiv>dirdivC<(x,y)>
+
+C<x> and C<y> being vectors of perhaps different
+lengths but with C<y[1] ! = 0> considered as X<Dirichlet series>Dirichlet series, computes
+the quotient of C<x> by C<y>, again as a vector.
+
+X<dirdiv>The library syntax is B<dirdiv>C<(x,y)>.
+
+=head2 X<direuler>direulerC<(p = a,b,>I<expr>C<,{c})>
+
+computes the
+X<Dirichlet series>Dirichlet series to C<b> terms of the X<Euler product>Euler product of
+expression I<expr> as C<p> ranges through the primes from C<a> to C<b>.
+I<expr> must be a polynomial or rational function in another variable
+than C<p> (say C<X>) and I<expr>C<(X)> is understood as the Dirichlet
+series (or more precisely the local factor) I<expr>C<(p^{-s})>. If C<c> is
+present, output only the first C<c> coefficients in the series.
+
+X<direuler>The library syntax is B<direuler>C<(entree *ep, GEN a, GEN b, char *expr)>
+
+=head2 X<dirmul>dirmulC<(x,y)>
+
+C<x> and C<y> being vectors of perhaps different
+lengths considered as X<Dirichlet series>Dirichlet series, computes the product of
+C<x> by C<y>, again as a vector.
+
+X<dirmul>The library syntax is B<dirmul>C<(x,y)>.
+
+=head2 X<divisors>divisorsC<(x)>
+
+creates a row vector whose components are the
+positive divisors of the integer C<x> in increasing order. The factorization
+of C<x> (as output by X<factor>C<factor>) can be used instead.
+
+X<divisors>The library syntax is B<divisors>C<(x)>.
+
+=head2 X<eulerphi>eulerphiC<(x)>
+
+Euler's F<phi>
+(totient)X<Euler totient function> function of C<|x|>, in other words
+C<|(>B<Z>C</x>B<Z>C<)^*|>. C<x> must be of type integer.
+
+X<phi>The library syntax is B<phi>C<(x)>.
+
+=head2 X<factor>factorC<(x,{>I<lim>C< = -1})>
+
+general factorization function.
+If C<x> is of type integer, rational, polynomial or rational function, the
+result is a two-column matrix, the first column being the irreducibles
+dividing C<x> (prime numbers or polynomials), and the second the exponents.
+If C<x> is a vector or a matrix, the factoring is done componentwise (hence
+the result is a vector or matrix of two-column matrices). By definition,
+C<0> is factored as C<0^1>.
+
+If C<x> is of type integer or rational, an argument I<lim> can be
+added, meaning that we look only for factors up to I<lim>, or to
+C<primelimit>, whichever is lowest (except when I<lim>C< = 0> where the
+effect is identical to setting I<lim>C< = primelimit>). Hence in this
+case, the remaining part is not necessarily prime. See X<factorint>B<factorint> for
+more information about the algorithms used.
+
+The polynomials or rational functions to be factored must have scalar
+coefficients. In particular PARI does I<not> know how to factor
+multivariate polynomials.
+
+Note that PARI tries to guess in a sensible way over which ring you want
+to factor. Note also that factorization of polynomials is done up to
+multiplication by a constant. In particular, the factors of rational
+polynomials will have integer coefficients, and the content of a polynomial
+or rational function is discarded and not included in the factorization. If
+you need it, you can always ask for the content explicitly:
+
+ ? factor(t^2 + 5/2*t + 1)
+ %1 =
+ [2*t + 1 1]
+
+ [t + 2 1]
+
+ ? content(t^2 + 5/2*t + 1)
+ %2 = 1/2
+
+See also X<factornf>B<factornf>.
+
+X<factor0>The library syntax is B<factor0>C<(x,>I<lim>C<)>, where I<lim> is a C integer.
+Also available are
+X<factor>B<factor>C<(x)> ( = X<factor0>B<factor0>C<(x,-1)>),
+X<smallfact>B<smallfact>C<(x)> ( = X<factor0>B<factor0>C<(x,0)>).
+
+=head2 X<factorback>factorbackC<(f,{nf})>
+
+C<f> being any factorization, gives back
+the factored object. If a second argument I<nf> is supplied, C<f> is
+assumed to be a prime ideal factorization in the number field I<nf>.
+The resulting ideal is given in HNFX<Hermite normal form> form.
+
+X<factorback>The library syntax is B<factorback>C<(f,>I<nf>C<)>, where an omitted
+I<nf> is entered as C<NULL>.
+
+=head2 X<factorcantor>factorcantorC<(x,p)>
+
+factors the polynomial C<x> modulo the
+prime C<p>, using distinct degree plus
+X<Cantor-Zassenhaus>Cantor-ZassenhausX<Zassenhaus>. The coefficients of C<x> must be
+operation-compatible with B<Z>C</p>B<Z>. The result is a two-column matrix, the
+first column being the irreducible polynomials dividing C<x>, and the second
+the exponents. If you want only the I<degrees> of the irreducible
+polynomials (for example for computing an C<L>-function), use
+C<factormod(x,p,1)>. Note that the C<factormod> algorithm is
+usually faster than C<factorcantor>.
+
+X<factcantor>The library syntax is B<factcantor>C<(x,p)>.
+
+=head2 X<factorff>factorffC<(x,p,a)>
+
+factors the polynomial C<x> in the field
+B<F>C<_q> defined by the irreducible polynomial C<a> over B<F>C<_p>. The
+coefficients of C<x> must be operation-compatible with B<Z>C</p>B<Z>. The result
+is a two-column matrix, the first column being the irreducible polynomials
+dividing C<x>, and the second the exponents. It is recommended to use for
+the variable of C<a> (which will be used as variable of a polmod) a name
+distinct from the other variables used, so that a C<lift()> of the
+result will be legible. If all the coefficients of C<x> are in B<F>C<_p>, a much faster algorithm is applied, using the computation of isomorphisms between finite fields.
+
+X<factmod9>The library syntax is B<factmod9>C<(x,p,a)>.
+
+=head2 X<factorial>factorialC<(x)> or C<x!>
+
+factorial of C<x>. The expression C<x!>
+gives a result which is an integer, while C<factorial(x)> gives a real
+number.
+
+X<mpfact>The library syntax is B<mpfact>C<(x)> for C<x!> and
+X<mpfactr>B<mpfactr>C<(x,>I<prec>C<)> for C<factorial(x)>. C<x> must be a C<long>
+integer and not a PARI integer.
+
+=head2 X<factorint>factorintC<(n,{>I<flag>C< = 0})>
+
+factors the integer n using a
+combination of the X<Shanks SQUFOF>Shanks SQUFOF and X<Pollard Rho>Pollard Rho method (with
+modifications due to Brent), X<Lenstra>Lenstra's X<ECM>ECM (with modifications by
+Montgomery), and X<MPQS>MPQS (the latter adapted from the X<LiDIA>LiDIA code
+with the kind permission of the LiDIA maintainers), as well as a search for
+pure powers with exponentsC< E<lt>= 10>. The output is a two-column matrix as for
+C<factor>.
+
+This gives direct access to the integer factoring engine called by most
+arithmetical functions. I<flag> is optional; its binary digits mean 1: avoid
+MPQS, 2: skip first stage ECM (we may still fall back to it later), 4: avoid
+Rho and SQUFOF, 8: don't run final ECM (as a result, a huge composite may be
+declared to be prime). Note that a (strong) probabilistic primality test is
+used; thus composites might (very rarely) not be detected.
+
+The machinery underlying this function is still in a somewhat experimental
+state, but should be much faster on average than pure ECM as used by all
+PARI versions up to 2.0.8, at the expense of heavier memory use. You are
+invited to play with the flag settings and watch the internals at work by
+using GP's X<debuglevel>C<debuglevel> default parameter (level 3 shows just the
+outline, 4 turns on time keeping, 5 and above show an increasing amount
+of internal details). If you see anything funny happening, please let
+us know.
+
+X<factorint>The library syntax is B<factorint>C<(n,>I<flag>C<)>.
+
+=head2 X<factormod>factormodC<(x,p,{>I<flag>C< = 0})>
+
+factors the polynomial C<x> modulo
+the prime integer C<p>, using X<Berlekamp>Berlekamp. The coefficients of C<x> must be
+operation-compatible with B<Z>C</p>B<Z>. The result is a two-column matrix, the
+first column being the irreducible polynomials dividing C<x>, and the second
+the exponents. If I<flag> is non-zero, outputs only the I<degrees> of the
+irreducible polynomials (for example, for computing an C<L>-function). A
+different algorithm for computing the mod C<p> factorization is
+C<factorcantor> which is sometimes faster.
+
+X<factormod>The library syntax is B<factormod>C<(x,p,>I<flag>C<)>. Also available are
+X<factmod>B<factmod>C<(x,p)> (which is equivalent to X<factormod>B<factormod>C<(x,p,0)>) and
+X<simplefactmod>B<simplefactmod>C<(x,p)> ( = X<factormod>B<factormod>C<(x,p,1)>).
+
+=head2 X<fibonacci>fibonacciC<(x)>
+
+C<x^{th}> Fibonacci number.
+
+X<fibo>The library syntax is B<fibo>C<(x)>. C<x> must be a C<long>.
+
+=head2 X<ffinit>ffinitC<(p,n,{v = x})>
+
+computes a monic polynomial of degree
+C<n> which is irreducible over B<F>C<_p>. For instance if
+C<P = ffinit(3,2,y)>, you can represent elements in B<F>C<_{3^2}> as polmods
+modulo C<P>.
+
+X<ffinit>The library syntax is B<ffinit>C<(p,n,v)>, where C<v> is a variable number.
+
+=head2 X<gcd>gcdC<(x,y,{>I<flag>C< = 0})>
+
+creates the greatest common divisor of C<x>
+and C<y>. C<x> and C<y> can be of quite general types, for instance both
+rational numbers. Vector/matrix types are also accepted, in which case
+the GCD is taken recursively on each component. Note that for these
+types, C<gcd> is not commutative.
+
+If I<flag>C< = 0>, use X<Euclid>Euclid's algorithm.
+
+If I<flag>C< = 1>, use the modular gcd algorithm (C<x> and C<y> have to be
+polynomials, with integer coefficients).
+
+If I<flag>C< = 2>, use the X<subresultant algorithm>subresultant algorithm.
+
+X<gcd0>The library syntax is B<gcd0>C<(x,y,>I<flag>C<)>. Also available are
+X<ggcd>B<ggcd>C<(x,y)>, X<modulargcd>B<modulargcd>C<(x,y)>, and X<srgcd>B<srgcd>C<(x,y)>
+corresponding to I<flag>C< = 0>, C<1> and C<2> respectively.
+
+=head2 X<hilbert>hilbertC<(x,y,{p})>
+
+X<Hilbert symbol>Hilbert symbol of C<x> and C<y> modulo
+C<p>. If C<x> and C<y> are of type integer or fraction, an explicit third
+parameter C<p> must be supplied, C<p = 0> meaning the place at infinity.
+Otherwise, C<p> needs not be given, and C<x> and C<y> can be of compatible types
+integer, fraction, real, integermod a prime (result is undefined if the
+modulus is not prime), or C<p>-adic.
+
+X<hil>The library syntax is B<hil>C<(x,y,p)>.
+
+=head2 X<isfundamental>isfundamentalC<(x)>
+
+true (1) if C<x> is equal to 1 or to the
+discriminant of a quadratic field, false (0) otherwise.
+
+X<gisfundamental>The library syntax is B<gisfundamental>C<(x)>, but the
+simpler function X<isfundamental>B<isfundamental>C<(x)> which returns a C<long>
+should be used if C<x> is known to be of type integer.
+
+=head2 X<isprime>isprimeC<(x,{>I<flag>C< = 0})>
+
+if I<flag>C< = 0> (default), true (1) if C<x> is a strong pseudo-prime
+for 10 randomly chosen bases, false (0) otherwise.
+
+If I<flag>C< = 1>, use Pocklington-Lehmer ``P-1'' test. true (1) if C<x> is
+prime, false (0) otherwise.
+
+If I<flag>C< = 2>, use Pocklington-Lehmer ``P-1'' test and output a primality
+certificate as follows: return 0 if C<x> is composite, 1 if C<x> is a
+small prime (currently strictly less than C<341 550 071 728 321>), and
+a matrix if C<x> is a large prime. The matrix has three columns. The
+first contains the prime factors C<p>, the second the corresponding
+elements C<a_p> as in PropositionS< >8.3.1 in GTMS< >138, and the third the
+output of isprime(p,2).
+
+In the two last cases, the algorithm fails if one of the (strong
+pseudo-)prime factors is not prime, but it should be exceedingly rare.
+
+X<gisprime>The library syntax is B<gisprime>C<(x,>I<flag>C<)>, but the simpler function X<isprime>B<isprime>C<(x)>
+which returns a C<long> should be used if C<x> is known to be of
+type integer. Also available is X<plisprime>B<plisprime>C<(N,>I<flag>C<)>,
+corresponding to X<gisprime>B<gisprime>C<(x,>I<flag>C<+1)> if C<x> is known to be of
+type integer.
+
+=head2 X<ispseudoprime>ispseudoprimeC<(x)>
+
+true (1) if C<x> is a strong
+pseudo-prime for a randomly chosen base, false (0) otherwise.
+
+X<gispsp>The library syntax is B<gispsp>C<(x)>, but the
+simpler function X<ispsp>B<ispsp>C<(x)> which returns a C<long>
+should be used if C<x> is known to be of type integer.
+
+=head2 X<issquare>issquareC<(x,{&n})>
+
+true (1) if C<x> is square, false (0) if
+not. C<x> can be of any type. If C<n> is given and an exact square root had to
+be computed in the checking process, puts that square root in C<n>. This is in
+particular the case when C<x> is an integer or a polynomial. This is I<not>
+the case for intmods (use quadratic reciprocity) or series (only check the
+leading coefficient).
+
+X<gcarrecomplet>The library syntax is B<gcarrecomplet>C<(x,&n)>. Also available is X<gcarreparfait>B<gcarreparfait>C<(x)>.
+
+=head2 X<issquarefree>issquarefreeC<(x)>
+
+true (1) if C<x> is squarefree, false (0) if not.
+Here C<x> can be an integer or a polynomial.
+
+X<gissquarefree>The library syntax is B<gissquarefree>C<(x)>, but the simpler function X<issquarefree>B<issquarefree>C<(x)>
+which returns a C<long> should be used if C<x> is known to be of type
+integer. This X<issquarefree>B<issquarefree> is just the square of the
+X<Moebius>Moebius function, and is computed as a multiplicative
+arithmetic function much like the latter.
+
+=head2 X<kronecker>kroneckerC<(x,y)>
+
+KroneckerX<Kronecker symbol>X<Legendre symbol>
+(i.e.S< >generalized Legendre) symbol C<((x)/(y))>. C<x> and C<y>
+must be of type integer.
+
+X<kronecker>The library syntax is B<kronecker>C<(x,y)>, the result (C<0> or C<F<+-> 1>) is a C<long>.
+
+=head2 X<lcm>lcmC<(x,y)>
+
+least common multiple of C<x> and C<y>, i.e.S< >such
+that C<lcm(x,y)*gcd(x,y) = abs(x*y)>.
+
+X<glcm>The library syntax is B<glcm>C<(x,y)>.
+
+=head2 X<moebius>moebiusC<(x)>
+
+X<Moebius>Moebius F<mu>-function of C<|x|>. C<x> must
+be of type integer.
+
+X<mu>The library syntax is B<mu>C<(x)>, the result (C<0> or C<F<+-> 1>) is a C<long>.
+
+=head2 X<nextprime>nextprimeC<(x)>
+
+finds the smallest prime greater than or
+equal to C<x>. C<x> can be of any real type. Note that if C<x> is a prime,
+this function returns C<x> and not the smallest prime strictly larger than C<x>.
+
+X<nextprime>The library syntax is B<nextprime>C<(x)>.
+
+=head2 X<numdiv>numdivC<(x)>
+
+number of divisors of C<|x|>. C<x> must be of type
+integer, and the result is a C<long>.
+
+X<numbdiv>The library syntax is B<numbdiv>C<(x)>.
+
+=head2 X<omega>omegaC<(x)>
+
+number of distinct prime divisors of C<|x|>. C<x>
+must be of type integer.
+
+X<omega>The library syntax is B<omega>C<(x)>, the result is a C<long>.
+
+=head2 X<precprime>precprimeC<(x)>
+
+finds the largest prime less than or equal to
+C<x>. C<x> can be of any real type. Returns 0 if C<x E<lt>= 1>.
+Note that if C<x> is a prime, this function returns C<x> and not the largest
+prime strictly smaller than C<x>.
+
+X<precprime>The library syntax is B<precprime>C<(x)>.
+
+=head2 X<prime>primeC<(x)>
+
+the C<x^{th}> prime number, which must be among
+the precalculated primes.
+
+X<prime>The library syntax is B<prime>C<(x)>. C<x> must be a C<long>.
+
+=head2 X<primes>primesC<(x)>
+
+creates a row vector whose components
+are the first C<x> prime numbers, which must be among the precalculated primes.
+
+X<primes>The library syntax is B<primes>C<(x)>. C<x> must be a C<long>.
+
+=head2 X<qfbclassno>qfbclassnoC<(x,{>I<flag>C< = 0})>
+
+class number of the quadratic field
+of discriminant C<x>. In the present version B<2.2.0>, a simple algorithm is used
+for C<x E<gt> 0>, so C<x> should not be too large (say C<x E<lt> 10^7>) for the time to be
+reasonable. On the other hand, for C<x E<lt> 0> one can reasonably compute
+classno(C<x>) for C<|x| E<lt> 10^{25}>, since the method used is X<Shanks>Shanks' method
+which is in C<O(|x|^{1/4})>. For larger values of C<|D|>, see
+C<quadclassunit>.
+
+If I<flag>C< = 1>, compute the class number using X<Euler product>Euler products and the
+functional equation. However, it is in C<O(|x|^{1/2})>.
+
+B<Important warning.> For C<D E<lt> 0>, this function often gives
+incorrect results when the class group is non-cyclic, because the authors
+were too lazy to implement X<Shanks>Shanks' method completely. It is therefore
+strongly recommended to use either the version with I<flag>C< = 1>, the function
+C<qfbhclassno(-x)> if C<x> is known to be a fundamental discriminant, or
+the function C<quadclassunit>.
+
+X<qfbclassno0>The library syntax is B<qfbclassno0>C<(x,>I<flag>C<)>. Also available are
+X<classno>B<classno>C<(x)> ( = X<qfbclassno>B<qfbclassno>C<(x)>),
+X<classno2>B<classno2>C<(x)> ( = X<qfbclassno>B<qfbclassno>C<(x,1)>), and finally
+there exists the function X<hclassno>B<hclassno>C<(x)> which computes the class
+number of an imaginary quadratic field by counting reduced forms, an C<O(|x|)>
+algorithm. See also C<qfbhclassno>.
+
+=head2 X<qfbcompraw>qfbcomprawC<(x,y)>
+
+X<composition>composition of the binary quadratic forms
+C<x> and C<y>, without X<reduction>reduction of the result. This is useful e.g.S< >to
+compute a generating element of an ideal.
+
+X<compraw>The library syntax is B<compraw>C<(x,y)>.
+
+=head2 X<qfbhclassno>qfbhclassnoC<(x)>
+
+X<Hurwitz class number>Hurwitz class number of C<x>, where C<x> is
+non-negative and congruent to 0 or 3 modulo 4. See also C<qfbclassno>.
+
+X<hclassno>The library syntax is B<hclassno>C<(x)>.
+
+=head2 X<qfbnucomp>qfbnucompC<(x,y,l)>
+
+X<composition>composition of the primitive positive
+definite binary quadratic forms C<x> and C<y> using the NUCOMP and NUDUPL
+algorithms of X<Shanks>Shanks (E<agrave> la Atkin). C<l> is any positive constant,
+but for optimal speed, one should take C<l = |D|^{1/4}>, where C<D> is the common
+discriminant of C<x> and C<y>. When C<x> and C<y> do not have the same
+discriminant, the result is undefined.
+
+X<nucomp>The library syntax is B<nucomp>C<(x,y,l)>. The auxiliary function
+X<nudupl>B<nudupl>C<(x,l)> should be used instead for speed when C<x = y>.
+
+=head2 X<qfbnupow>qfbnupowC<(x,n)>
+
+C<n>-th power of the primitive positive definite
+binary quadratic form C<x> using the NUCOMP and NUDUPL algorithms (see
+C<qfbnucomp>).
+
+X<nupow>The library syntax is B<nupow>C<(x,n)>.
+
+=head2 X<qfbpowraw>qfbpowrawC<(x,n)>
+
+C<n>-th power of the binary quadratic form
+C<x>, computed without doing any X<reduction>reduction (i.e.S< >using C<qfbcompraw>).
+Here C<n> must be non-negative and C<n E<lt> 2^{31}>.
+
+X<powraw>The library syntax is B<powraw>C<(x,n)> where C<n> must be a C<long>
+integer.
+
+=head2 X<qfbprimeform>qfbprimeformC<(x,p)>
+
+prime binary quadratic form of discriminant
+C<x> whose first coefficient is the prime number C<p>. By abuse of notation,
+C<p = 1> is a valid special case which returns the unit form. Returns an
+error if C<x> is not a quadratic residue mod C<p>. In the case where C<x E<gt> 0>,
+the ``distance'' component of the form is set equal to zero according to
+the current precision.
+
+X<primeform>The library syntax is B<primeform>C<(x,p,>I<prec>C<)>, where the third variable I<prec> is a
+C<long>, but is only taken into account when C<x E<gt> 0>.
+
+=head2 X<qfbred>qfbredC<(x,{>I<flag>C< = 0},{D},{>I<isqrtD>C<},{>I<sqrtD>C<})>
+
+reduces the binary quadratic form C<x> (updating Shanks's distance function
+if C<x> is indefinite). The binary digits of I<flag> are toggles meaning
+
+S< >S< >1: perform a single X<reduction>reduction step
+
+S< >S< >2: don't update X<Shanks>Shanks's distance
+
+C<D>, I<isqrtD>, I<sqrtD>, if present, supply the values of the
+discriminant, C<\lfloor > F<sqrt> C<{D}\rfloor>, and F<sqrt> C<{D}> respectively
+(no checking is done of these facts). If C<D E<lt> 0> these values are useless,
+and all references to Shanks's distance are irrelevant.
+
+X<qfbred0>The library syntax is B<qfbred0>C<(x,>I<flag>C<,D,>I<isqrtD>C<,>I<sqrtD>C<)>. Use C<NULL>
+to omit any of C<D>, I<isqrtD>, I<sqrtD>.
+
+Also available are
+
+X<redimag>B<redimag>C<(x)> ( = X<qfbred>B<qfbred>C<(x)> where C<x> is definite),
+
+and for indefinite forms:
+
+X<redreal>B<redreal>C<(x)> ( = X<qfbred>B<qfbred>C<(x)>),
+
+X<rhoreal>B<rhoreal>C<(x)> ( = X<qfbred>B<qfbred>C<(x,1)>),
+
+X<redrealnod>B<redrealnod>C<(x,sq)> ( = X<qfbred>B<qfbred>C<(x,2,,isqrtD)>),
+
+X<rhorealnod>B<rhorealnod>C<(x,sq)> ( = X<qfbred>B<qfbred>C<(x,3,,isqrtD)>).
+
+=head2 X<quadclassunit>quadclassunitC<(D,{>I<flag>C< = 0},{>I<tech>C< = []})>
+
+X<Buchmann-McCurley>Buchmann-McCurley's sub-exponential algorithm for computing the class
+group of a quadratic field of discriminant C<D>. If C<D> is not fundamental,
+the function may or may not be defined, but usually is, and often gives the
+right answer (a warning is issued). The more general function X<bnrinit>C<bnrinit>
+should be used to compute the class group of an order.
+
+This function should be used instead of C<qfbclassno> or C<quadregula>
+when C<D E<lt> -10^{25}>, C<D E<gt> 10^{10}>, or when the I<structure> is wanted.
+
+If I<flag> is non-zero I<and> C<D E<gt> 0>, computes the narrow class group and
+regulator, instead of the ordinary (or wide) ones. In the current version
+B<2.2.0>, this doesn't work at allS< >: use the general function X<bnfnarrow>C<bnfnarrow>.
+
+Optional parameter I<tech> is a row vector of the form
+C<[c_1,c_2]>, where C<c_1> and C<c_2> are positive real numbers which
+control the execution time and the stack size. To get maximum speed,
+set C<c_2 = c>. To get a rigorous result (under X<GRH>GRH) you must take
+C<c_2 = 6>. Reasonable values for C<c> are between C<0.1> and C<2>.
+
+The result of this function is a vector C<v> with 4 components if C<D E<lt> 0>, and
+C<5> otherwise. The correspond respectively to
+
+B<*> C<v[1]>S< >: the class number
+
+B<*> C<v[2]>S< >: a vector giving the structure of the class group as a
+product of cyclic groups;
+
+B<*> C<v[3]>S< >: a vector giving generators of those cyclic groups (as
+binary quadratic forms).
+
+B<*> C<v[4]>S< >: (omitted if C<D E<lt> 0>) the regulator, computed to an
+accuracy which is the maximum of an internal accuracy determined by the
+program and the current default (note that once the regulator is known to a
+small accuracy it is trivial to compute it to very high accuracy, see the
+tutorial).
+
+B<*> C<v[5]>S< >: a measure of the correctness of the result. If it is
+close to 1, the result is correct (under X<GRH>GRH). If it is close to a
+larger integer, this shows that the class number is off by a factor equal
+to this integer, and you must start again with a larger value for C<c_1> or
+a different random seed. In this case, a warning message is printed.
+
+X<quadclassunit0>The library syntax is B<quadclassunit0>C<(D,>I<flag>C<,tech)>. Also available are
+X<buchimag>B<buchimag>C<(D,c_1,c_2)> and X<buchreal>B<buchreal>C<(D,>I<flag>C<,c_1,c_2)>.
+
+=head2 X<quaddisc>quaddiscC<(x)>
+
+discriminant of the quadratic field
+B<Q>C<(> F<sqrt> C<{x})>, where C<x belongs to >B<Q>.
+
+X<quaddisc>The library syntax is B<quaddisc>C<(x)>.
+
+=head2 X<quadhilbert>quadhilbertC<(D,{>I<flag>C< = 0})>
+
+relative equation defining the
+X<Hilbert class field>Hilbert class field of the quadratic field of discriminant C<D>.
+If I<flag> is non-zero
+and C<D E<lt> 0>, outputs C<[>I<form>C<,>I<root>C<(>I<form>C<)]> (to be used for
+constructing subfields). If I<flag> is non-zero and C<D E<gt> 0>, try hard to
+get the best modulus.
+Uses complex multiplication in the imaginary case and X<Stark units>Stark units
+in the real case.
+
+X<quadhilbert>The library syntax is B<quadhilbert>C<(D,>I<flag>C<,>I<prec>C<)>.
+
+=head2 X<quadgen>quadgenC<(x)>
+
+creates the quadratic numberX<omega>
+F<omega>C< = (a+> F<sqrt> C<{x})/2> where C<a = 0> if C<x = 0 mod 4>,
+C<a = 1> if C<x = 1 mod 4>, so that C<(1,>F<omega>C<)> is an integral basis for
+the quadratic order of discriminant C<x>. C<x> must be an integer congruent to
+0 or 1 modulo 4.
+
+X<quadgen>The library syntax is B<quadgen>C<(x)>.
+
+=head2 X<quadpoly>quadpolyC<(D,{v = x})>
+
+creates the ``canonical'' quadratic
+polynomial (in the variable C<v>) corresponding to the discriminant C<D>,
+i.e.S< >the minimal polynomial of C<quadgen(x)>. C<D> must be an integer
+congruent to 0 or 1 modulo 4.
+
+X<quadpoly0>The library syntax is B<quadpoly0>C<(x,v)>.
+
+=head2 X<quadray>quadrayC<(D,f,{>I<flag>C< = 0})>
+
+relative equation for the ray class
+field of conductor C<f> for the quadratic field of discriminant C<D> (which
+can also be a C<bnf>), using analytic methods.
+
+For C<D E<lt> 0>, uses the F<sigma> function. I<flag> has the following meaning: if
+it's an odd integer, outputs instead the vector of C<[>I<ideal>C<,
+>I<corresponding root>C<]>. It can also be a two-component vector
+C<[>F<lambda>C<,>I<flag>C<]>, where I<flag> is as above and F<lambda> is the technical
+element of C<bnf> necessary for Schertz's method. In that case, returns
+0 if F<lambda> is not suitable.
+
+For C<D E<gt> 0>, uses Stark's conjecture. If I<flag> is non-zero, try hard to
+get the best modulus. The function may fail with the following message
+
+ "Cannot find a suitable modulus in FindModulus"
+
+See X<bnrstark>C<bnrstark> for more details about the real case.
+
+X<quadray>The library syntax is B<quadray>C<(D,f,>I<flag>C<)>.
+
+=head2 X<quadregulator>quadregulatorC<(x)>
+
+regulator of the quadratic field of
+positive discriminant C<x>. Returns an error if C<x> is not a discriminant
+(fundamental or not) or if C<x> is a square. See also C<quadclassunit> if
+C<x> is large.
+
+X<regula>The library syntax is B<regula>C<(x,>I<prec>C<)>.
+
+=head2 X<quadunit>quadunitC<(x)>
+
+fundamental unitX<fundamental units> of the
+real quadratic field B<Q>C<(> F<sqrt> C< x)> where C<x> is the positive discriminant
+of the field. If C<x> is not a fundamental discriminant, this probably gives
+the fundamental unit of the corresponding order. C<x> must be of type
+integer, and the result is a quadratic number.
+
+X<fundunit>The library syntax is B<fundunit>C<(x)>.
+
+=head2 X<removeprimes>removeprimesC<({x = []})>
+
+removes the primes listed in C<x> from
+the prime number table. In particular C<removeprimes(addprimes)> empties
+the extra prime table. C<x> can also be a single integer. List the current
+extra primes if C<x> is omitted.
+
+X<removeprimes>The library syntax is B<removeprimes>C<(x)>.
+
+=head2 X<sigma>sigmaC<(x,{k = 1})>
+
+sum of the C<k^{th}> powers of the
+positive divisors of C<|x|>. C<x> must be of type integer.
+
+X<sumdiv>The library syntax is B<sumdiv>C<(x)> ( = X<sigma>B<sigma>C<(x)>) or X<gsumdivk>B<gsumdivk>C<(x,k)> ( =
+X<sigma>B<sigma>C<(x,k)>), where C<k> is a C long integer.
+
+=head2 X<sqrtint>sqrtintC<(x)>
+
+integer square root of C<x>, which must be of PARI
+type integer. The result is non-negative and rounded towards zero. A
+negative C<x> is allowed, and the result in that case is C<I*sqrtint(-x)>.
+
+X<racine>The library syntax is B<racine>C<(x)>.
+
+=head2 X<znlog>znlogC<(x,g)>
+
+C<g> must be a primitive root mod a prime C<p>, and
+the result is the discrete log of C<x> in the multiplicative group
+C<(>B<Z>C</p>B<Z>C<)^*>. This function using a simple-minded baby-step/giant-step
+approach and requires C<O(> F<sqrt> C<{p})> storage, hence it cannot be used for
+C<p> greater than about C<10^{13}>.
+
+X<znlog>The library syntax is B<znlog>C<(x,g)>.
+
+=head2 X<znorder>znorderC<(x)>
+
+C<x> must be an integer mod C<n>, and the result is the
+order of C<x> in the multiplicative group C<(>B<Z>C</n>B<Z>C<)^*>. Returns an error if C<x>
+is not invertible.
+
+X<order>The library syntax is B<order>C<(x)>.
+
+=head2 X<znprimroot>znprimrootC<(x)>
+
+returns a primitive root of C<x>, where C<x>
+is a prime power.
+
+X<gener>The library syntax is B<gener>C<(x)>.
+
+=head2 X<znstar>znstarC<(n)>
+
+gives the structure of the multiplicative group
+C<(>B<Z>C</n>B<Z>C<)^*> as a 3-component row vector C<v>, where C<v[1] = >F<phi>C<(n)> is the
+order of that group, C<v[2]> is a C<k>-component row-vector C<d> of integers
+C<d[i]> such that C<d[i] E<gt> 1> and C<d[i] | d[i-1]> for C<i E<gt>= 2> and
+C<(>B<Z>C</n>B<Z>C<)^* ~ >F<prod>C<_{i = 1}^k(>B<Z>C</d[i]>B<Z>C<)>, and C<v[3]> is a C<k>-component row
+vector giving generators of the image of the cyclic groups B<Z>C</d[i]>B<Z>.
+
+X<znstar>The library syntax is B<znstar>C<(n)>.
+
+=head1 Functions related to elliptic curves
+
+We have implemented a number of functions which are useful for number
+theorists working on elliptic curves. We always use X<Tate>Tate's notations.
+The functions assume that the curve is given by a general Weierstrass
+modelX<Weierstrass equation>
+
+S< >C<
+y^2+a_1xy+a_3y = x^3+a_2x^2+a_4x+a_6,
+>
+
+where a priori the C<a_i> can be of any scalar type. This curve can be
+considered as a five-component vector C<E = [a1,a2,a3,a4,a6]>. Points on
+C<E> are represented as two-component vectors C<[x,y]>, except for the
+point at infinity, i.e.S< >the identity element of the group law, represented by
+the one-component vector C<[0]>.
+
+It is useful to have at one's disposal more information. This is given by
+the function X<ellinit>C<ellinit> (see there), which usually gives a 19 component
+vector (which we will call a long vector in this section). If a specific flag
+is added, a vector with only 13 component will be output (which we will call
+a medium vector). A medium vector just gives the first 13 components of the
+long vector corresponding to the same curve, but is of course faster to
+compute. The following X<member functions>member functions are available to deal with the
+output of C<ellinit>:
+
+S< > C<a1>--C<a6>, C<b2>--C<b8>, C<c4>--C<c6> :
+coefficients of the elliptic curve.
+
+S< > X<area>C<area> : volume of the complex lattice defining C<E>.
+
+S< > X<disc>C<disc> : discriminant of the curve.
+
+S< > X<j>C<j> : C<j>-invariant of the curve.
+
+S< > X<omega>C<omega> : C<[>F<omega>C<_1,>F<omega>C<_2]>, periods forming a basis of
+the complex lattice defining C<E> (F<omega>C<_1> is the
+
+S< > real period, and F<omega>C<_2/>F<omega>C<_1> belongs to
+PoincarE<eacute>'s half-plane).
+
+S< > X<eta>C<eta> : quasi-periods C<[>F<eta>C<_1, >F<eta>C<_2]>, such that
+F<eta>C<_1>F<omega>C<_2->F<eta>C<_2>F<omega>C<_1 = i>F<Pi>.
+
+S< > X<roots>C<roots> : roots of the associated Weierstrass equation.
+
+S< > X<tate>C<tate> : C<[u^2,u,v]> in the notation of Tate.
+
+S< > X<w>C<w> : Mestre's C<w> (this is technical).
+
+Their use is best described by an example: assume that C<E> was output by
+C<ellinit>, then typing C<E.disc> will retrieve the curve's
+discriminant. The member functions C<area>, C<eta> and C<omega> are
+only available for curves over B<Q>. Conversely, C<tate> and C<w> are
+only available for curves defined over B<Q>C<_p>.
+
+Some functions, in particular those relative to height computations (see
+C<ellheight>) require also that the curve be in minimal Weierstrass
+form. This is achieved by the function C<ellglobalred>.
+
+All functions related to elliptic curves share the prefix C<ell>, and the
+precise curve we are interested in is always the first argument, in either
+one of the three formats discussed above, unless otherwise specified. For
+instance, in functions which do not use the extra information given by long
+vectors, the curve can be given either as a five-component vector, or by one
+of the longer vectors computed by C<ellinit>.
+
+=head2 X<elladd>elladdC<(E,z1,z2)>
+
+sum of the points C<z1> and C<z2> on the
+elliptic curve corresponding to the vector C<E>.
+
+X<addell>The library syntax is B<addell>C<(E,z1,z2)>.
+
+=head2 X<ellak>ellakC<(E,n)>
+
+computes the coefficient C<a_n> of the
+C<L>-function of the elliptic curve C<E>, i.e.S< >in principle coefficients of a
+newform of weight 2 assuming X<Taniyama-Weil conjecture>Taniyama-Weil conjecture (which is now
+known to hold in full generality thanks to the work of X<Breuil>Breuil,
+X<Conrad>Conrad, X<Diamond>Diamond, X<Taylor>Taylor and X<Wiles>Wiles). C<E> must be a
+medium or long vector of the type given by C<ellinit>. For this function
+to work for every C<n> and not just those prime to the conductor, C<E> must
+be a minimal Weierstrass equation. If this is not the case, use the
+function C<ellglobalred> first before using C<ellak>.
+
+X<akell>The library syntax is B<akell>C<(E,n)>.
+
+=head2 X<ellan>ellanC<(E,n)>
+
+computes the vector of the first C<n> C<a_k>
+corresponding to the elliptic curve C<E>. All comments in C<ellak>
+description remain valid.
+
+X<anell>The library syntax is B<anell>C<(E,n)>, where C<n> is a C integer.
+
+=head2 X<ellap>ellapC<(E,p,{>I<flag>C< = 0})>
+
+computes the C<a_p> corresponding to the
+elliptic curve C<E> and the prime number C<p>. These are defined by the
+equation C<#E(>B<F>C<_p) = p+1 - a_p>, where C<#E(>B<F>C<_p)> stands for the number
+of points of the curve C<E> over the finite field B<F>C<_p>. When I<flag> is C<0>,
+this uses the baby-step giant-step method and a trick due to Mestre. This
+runs in time C<O(p^{1/4})> and requires C<O(p^{1/4})> storage, hence becomes
+unreasonable when C<p> has about 30 digits.
+
+If I<flag> is C<1>, computes the C<a_p> as a sum of Legendre symbols. This is
+slower than the previous method as soon as C<p> is greater than 100, say.
+
+No checking is done that C<p> is indeed prime. C<E> must be a medium or long
+vector of the type given by C<ellinit>, defined over B<Q>, B<F>C<_p> or
+B<Q>C<_p>. C<E> must be given by a Weierstrass equation minimal at C<p>.
+
+X<ellap0>The library syntax is B<ellap0>C<(E,p,>I<flag>C<)>. Also available are X<apell>B<apell>C<(E,p)>, corresponding
+to I<flag>C< = 0>, and X<apell2>B<apell2>C<(E,p)> (I<flag>C< = 1>).
+
+=head2 X<ellbil>ellbilC<(E,z1,z2)>
+
+if C<z1> and C<z2> are points on the elliptic
+curve C<E>, this function computes the value of the canonical bilinear form on
+C<z1>, C<z2>:
+
+S< >C<
+ellheight(E,z1+z2) - ellheight(E,z1) - ellheight(E,z2)
+>
+
+where C<+> denotes of course addition on C<E>. In addition, C<z1> or C<z2>
+(but not both) can be vectors or matrices. Note that this is equal to twice
+some normalizations. C<E> is assumed to be integral, given by a minimal model.
+
+X<bilhell>The library syntax is B<bilhell>C<(E,z1,z2,>I<prec>C<)>.
+
+=head2 X<ellchangecurve>ellchangecurveC<(E,v)>
+
+changes the data for the elliptic curve C<E>
+by changing the coordinates using the vector C<v = [u,r,s,t]>, i.e.S< >if C<x'>
+and C<y'> are the new coordinates, then C<x = u^2x'+r>, C<y = u^3y'+su^2x'+t>.
+The vector C<E> must be a medium or long vector of the type given by
+C<ellinit>.
+
+X<coordch>The library syntax is B<coordch>C<(E,v)>.
+
+=head2 X<ellchangepoint>ellchangepointC<(x,v)>
+
+changes the coordinates of the point or
+vector of points C<x> using the vector C<v = [u,r,s,t]>, i.e.S< >if C<x'> and
+C<y'> are the new coordinates, then C<x = u^2x'+r>, C<y = u^3y'+su^2x'+t> (see also
+C<ellchangecurve>).
+
+X<pointch>The library syntax is B<pointch>C<(x,v)>.
+
+=head2 X<elleisnum>elleisnumC<(E,k,{>I<flag>C< = 0})>
+
+C<E> being an elliptic curve as
+output by C<ellinit> (or, alternatively, given by a 2-component vector
+C<[>F<omega>C<_1,>F<omega>C<_2]>), and C<k> being an even positive integer, computes
+the numerical value of the Eisenstein series of weight C<k> at C<E>. When
+I<flag> is non-zero and C<k = 4> or 6, returns C<g_2> or C<g_3> with the correct
+normalization.
+
+X<elleisnum>The library syntax is B<elleisnum>C<(E,k,>I<flag>C<)>.
+
+=head2 X<elleta>elletaC<(om)>
+
+returns the two-component row vector
+C<[>F<eta>C<_1,>F<eta>C<_2]> of quasi-periods associated to C<om = [>F<omega>C<_1,
+>F<omega>C<_2]>
+
+X<elleta>The library syntax is B<elleta>C<(om, >I<prec>C<)>
+
+=head2 X<ellglobalred>ellglobalredC<(E)>
+
+calculates the arithmetic conductor, the global
+minimal model of C<E> and the global X<Tamagawa number>Tamagawa number C<c>. Here C<E> is an
+elliptic curve given by a medium or long vector of the type given by
+C<ellinit>, I<and is supposed to have all its coefficients >C<a_i>I< in>
+B<Q>. The result is a 3 component vector C<[N,v,c]>. C<N> is the arithmetic
+conductor of the curve, C<v> is itself a vector C<[u,r,s,t]> with rational
+components. It gives a coordinate change for C<E> over B<Q> such that the
+resulting model has integral coefficients, is everywhere minimal, C<a_1> is 0
+or 1, C<a_2> is 0, 1 or C<-1> and C<a_3> is 0 or 1. Such a model is unique, and
+the vector C<v> is unique if we specify that C<u> is positive. To get the new
+model, simply type C<ellchangecurve(E,v)>. Finally C<c> is the product of
+the local Tamagawa numbers C<c_p>, a quantity which enters in the
+X<Birch and Swinnerton-Dyer conjecture>Birch and Swinnerton-Dyer conjecture.
+
+X<globalreduction>The library syntax is B<globalreduction>C<(E)>.
+
+=head2 X<ellheight>ellheightC<(E,z,{>I<flag>C< = 0})>
+
+global X<NE<eacute>ron-Tate height>NE<eacute>ron-Tate height of
+the point C<z> on the elliptic curve C<E>. The vector C<E> must be a long vector
+of the type given by C<ellinit>, with I<flag>C< = 1>. If I<flag>C< = 0>, this
+computation is done using sigma and theta-functions and a trick due to J.
+Silverman. If I<flag>C< = 1>, use Tate's C<4^n> algorithm, which is much slower.
+C<E> is assumed to be integral, given by a minimal model.
+
+X<ellheight0>The library syntax is B<ellheight0>C<(E,z,>I<flag>C<,>I<prec>C<)>. The Archimedean
+contribution alone is given by the library function
+X<hell>B<hell>C<(E,z,>I<prec>C<)>.
+Also available are X<ghell>B<ghell>C<(E,z,>I<prec>C<)> (I<flag>C< = 0>) and
+X<ghell2>B<ghell2>C<(E,z,>I<prec>C<)> (I<flag>C< = 1>).
+
+=head2 X<ellheightmatrix>ellheightmatrixC<(E,x)>
+
+C<x> being a vector of points, this
+function outputs the Gram matrix of C<x> with respect to the NE<eacute>ron-Tate
+height, in other words, the C<(i,j)> component of the matrix is equal to
+C<ellbil(E,x[i],x[j])>. The rank of this matrix, at least in some
+approximate sense, gives the rank of the set of points, and if C<x> is a
+basis of the X<Mordell-Weil group>Mordell-Weil group of C<E>, its determinant is equal to
+the regulator of C<E>. Note that this matrix should be divided by 2 to be in
+accordance with certain normalizations. C<E> is assumed to be integral,
+given by a minimal model.
+
+X<mathell>The library syntax is B<mathell>C<(E,x,>I<prec>C<)>.
+
+=head2 X<ellinit>ellinitC<(E,{>I<flag>C< = 0})>
+
+computes some fixed data concerning the
+elliptic curve given by the five-component vector C<E>, which will be
+essential for most further computations on the curve. The result is a
+19-component vector E (called a long vector in this section), shortened
+to 13 components (medium vector) if I<flag>C< = 1>. Both contain the
+following information in the first 13 components:
+
+S< >C< a_1,a_2,a_3,a_4,a_6,b_2,b_4,b_6,b_8,c_4,c_6,>F<Delta>C<,j.>
+
+In particular, the discriminant is C<E[12]> (or C<E.disc>), and the
+C<j>-invariant is C<E[13]> (or C<E.j>).
+
+The other six components are only present if I<flag> is C<0> (or omitted!).
+Their content depends on whether the curve is defined over B<R> or not:
+
+B<*> When C<E> is defined over B<R>, C<E[14]> (C<E.roots>) is a
+vector whose three components contain the roots of the associated Weierstrass
+equation. If the roots are all real, then they are ordered by decreasing
+value. If only one is real, it is the first component of C<E[14]>.
+
+C<E[15]> (C<E.omega[1]>) is the real period of C<E> (integral of
+C<dx/(2y+a_1x+a_3)> over the connected component of the identity element of
+the real points of the curve), and C<E[16]> (C<E.omega[2]>) is a complex
+period. In other words, F<omega>C<_1 = E[15]> and F<omega>C<_2 = E[16]> form a basis of
+the complex lattice defining C<E> (C<E.omega>), with
+F<tau>C< = (>F<omega>C<_2)/(>F<omega>C<_1)> having positive imaginary part.
+
+C<E[17]> and C<E[18]> are the corresponding values F<eta>C<_1> and F<eta>C<_2> such
+that F<eta>C<_1>F<omega>C<_2->F<eta>C<_2>F<omega>C<_1 = i>F<Pi>, and both can be retrieved by
+typing C<E.eta> (as a row vector whose components are the F<eta>C<_i>).
+
+Finally, C<E[19]> (C<E.area>) is the volume of the complex lattice defining
+C<E>.
+
+B<*> When C<E> is defined over B<Q>C<_p>, the C<p>-adic valuation of C<j>
+must be negative. Then C<E[14]> (C<E.roots>) is the vector with a single
+component equal to the C<p>-adic root of the associated Weierstrass equation
+corresponding to C<-1> under the Tate parametrization.
+
+C<E[15]> is equal to the square of the C<u>-value, in the notation of Tate.
+
+C<E[16]> is the C<u>-value itself, if it belongs to B<Q>C<_p>, otherwise zero.
+
+C<E[17]> is the value of Tate's C<q> for the curve C<E>.
+
+C<E.tate> will yield the three-component vector C<[u^2,u,q]>.
+
+C<E[18]> (C<E.w>) is the value of Mestre's C<w> (this is technical), and
+C<E[19]> is arbitrarily set equal to zero.
+
+For all other base fields or rings, the last six components are arbitrarily
+set equal to zero (see also the description of member functions related to
+elliptic curves at the beginning of this section).
+
+X<ellinit0>The library syntax is B<ellinit0>C<(E,>I<flag>C<,>I<prec>C<)>. Also available are
+X<initell>B<initell>C<(E,>I<prec>C<)> (I<flag>C< = 0>) and
+X<smallinitell>B<smallinitell>C<(E,>I<prec>C<)> (I<flag>C< = 1>).
+
+=head2 X<ellisoncurve>ellisoncurveC<(E,z)>
+
+gives 1 (i.e.S< >true) if the point C<z> is on
+the elliptic curve C<E>, 0 otherwise. If C<E> or C<z> have imprecise coefficients,
+an attempt is made to take this into account, i.e.S< >an imprecise equality is
+checked, not a precise one.
+
+X<oncurve>The library syntax is B<oncurve>C<(E,z)>, and the result is a C<long>.
+
+=head2 X<ellj>elljC<(x)>
+
+elliptic C<j>-invariant. C<x> must be a complex number
+with positive imaginary part, or convertible into a power series or a
+C<p>-adic number with positive valuation.
+
+X<jell>The library syntax is B<jell>C<(x,>I<prec>C<)>.
+
+=head2 X<elllocalred>elllocalredC<(E,p)>
+
+calculates the X<Kodaira>Kodaira type of the
+local fiber of the elliptic curve C<E> at the prime C<p>.
+C<E> must be given by a medium or
+long vector of the type given by C<ellinit>, and is assumed to have all
+its coefficients C<a_i> in B<Z>. The result is a 4-component vector
+C<[f,kod,v,c]>. Here C<f> is the exponent of C<p> in the arithmetic conductor of
+C<E>, and C<kod> is the Kodaira type which is coded as follows:
+
+1 means good reduction (type IC<_0>), 2, 3 and 4 mean types II, III and IV
+respectively, C<4+>F<nu> with F<nu>C< E<gt> 0> means type IC<_>F<nu>;
+finally the opposite values C<-1>, C<-2>, etc.S< >refer to the starred types
+IC<_0^*>, IIC<^*>, etc. The third component C<v> is itself a vector C<[u,r,s,t]>
+giving the coordinate changes done during the local reduction. Normally, this
+has no use if C<u> is 1, that is, if the given equation was already minimal.
+Finally, the last component C<c> is the local X<Tamagawa number>Tamagawa number C<c_p>.
+
+X<localreduction>The library syntax is B<localreduction>C<(E,p)>.
+
+=head2 X<elllseries>elllseriesC<(E,s,{A = 1})>
+
+C<E> being a medium or long vector
+given by C<ellinit>, this computes the value of the L-series of C<E> at
+C<s>. It is assumed that C<E> is a minimal model over B<Z> and that the curve
+is a modular elliptic curve. The optional parameter C<A> is a cutoff point for
+the integral, which must be chosen close to 1 for best speed. The result
+must be independent of C<A>, so this allows some internal checking of the
+function.
+
+Note that if the conductor of the curve is large, say greater than C<10^{12}>,
+this function will take an unreasonable amount of time since it uses an
+C<O(N^{1/2})> algorithm.
+
+X<lseriesell>The library syntax is B<lseriesell>C<(E,s,A,>I<prec>C<)> where I<prec> is a C<long> and an
+omitted C<A> is coded as C<NULL>.
+
+=head2 X<ellorder>ellorderC<(E,z)>
+
+gives the order of the point C<z> on the elliptic
+curve C<E> if it is a torsion point, zero otherwise. In the present version
+B<2.2.0>, this is implemented only for elliptic curves defined over B<Q>.
+
+X<orderell>The library syntax is B<orderell>C<(E,z)>.
+
+=head2 X<ellordinate>ellordinateC<(E,x)>
+
+gives a 0, 1 or 2-component vector containing
+the C<y>-coordinates of the points of the curve C<E> having C<x> as
+C<x>-coordinate.
+
+X<ordell>The library syntax is B<ordell>C<(E,x)>.
+
+=head2 X<ellpointtoz>ellpointtozC<(E,z)>
+
+if C<E> is an elliptic curve with coefficients
+in B<R>, this computes a complex number C<t> (modulo the lattice defining
+C<E>) corresponding to the point C<z>, i.e.S< >such that, in the standard
+Weierstrass model, F<wp> C<(t) = z[1],> F<wp> C<'(t) = z[2]>. In other words, this is the
+inverse function of C<ellztopoint>.
+
+If C<E> has coefficients in B<Q>C<_p>, then either Tate's C<u> is in B<Q>C<_p>, in
+which case the output is a C<p>-adic number C<t> corresponding to the point C<z>
+under the Tate parametrization, or only its square is, in which case the
+output is C<t+1/t>. C<E> must be a long vector output by C<ellinit>.
+
+X<zell>The library syntax is B<zell>C<(E,z,>I<prec>C<)>.
+
+=head2 X<ellpow>ellpowC<(E,z,n)>
+
+computes C<n> times the point C<z> for the
+group law on the elliptic curve C<E>. Here, C<n> can be in B<Z>, or C<n>
+can be a complex quadratic integer if the curve C<E> has complex multiplication
+by C<n> (if not, an error message is issued).
+
+X<powell>The library syntax is B<powell>C<(E,z,n)>.
+
+=head2 X<ellrootno>ellrootnoC<(E,{p = 1})>
+
+C<E> being a medium or long vector given
+by C<ellinit>, this computes the local (if C<p ! = 1>) or global (if C<p = 1>)
+root number of the L-series of the elliptic curve C<E>. Note that the global
+root number is the sign of the functional equation and conjecturally is the
+parity of the rank of the X<Mordell-Weil group>Mordell-Weil group.
+The equation for C<E> must have
+coefficients in B<Q> but need I<not> be minimal.
+
+X<ellrootno>The library syntax is B<ellrootno>C<(E,p)> and the result (equal to C<F<+->1>) is a C<long>.
+
+=head2 X<ellsigma>ellsigmaC<(E,z,{>I<flag>C< = 0})>
+
+value of the Weierstrass F<sigma>
+function of the lattice associated to C<E> as given by C<ellinit>
+(alternatively, C<E> can be given as a lattice C<[>F<omega>C<_1,>F<omega>C<_2]>).
+
+If I<flag>C< = 1>, computes an (arbitrary) determination of F<log> C<(>F<sigma>C<(z))>.
+
+If I<flag>C< = 2,3>, same using the product expansion instead of theta series.
+X<ellsigma>The library syntax is B<ellsigma>C<(E,z,>I<flag>C<)>
+
+=head2 X<ellsub>ellsubC<(E,z1,z2)>
+
+difference of the points C<z1> and C<z2> on the
+elliptic curve corresponding to the vector C<E>.
+
+X<subell>The library syntax is B<subell>C<(E,z1,z2)>.
+
+=head2 X<elltaniyama>elltaniyamaC<(E)>
+
+computes the modular parametrization of the
+elliptic curve C<E>, where C<E> is given in the (long or medium) format output
+by C<ellinit>, in the form of a two-component vector C<[u,v]> of power
+series, given to the current default series precision. This vector is
+characterized by the following two properties. First the point C<(x,y) = (u,v)>
+satisfies the equation of the elliptic curve. Second, the differential
+C<du/(2v+a_1u+a_3)> is equal to C<f(z)dz>, a differential form on
+C<H/>F<Gamma>C<_0(N)> where C<N> is the conductor of the curve. The variable used in
+the power series for C<u> and C<v> is C<x>, which is implicitly understood to be
+equal to F<exp> C<(2i>F<Pi>C< z)>. It is assumed that the curve is a I<strong>
+X<Weil curve>Weil curve, and the Manin constant is equal to 1. The equation of
+the curve C<E> must be minimal (use C<ellglobalred> to get a minimal
+equation).
+
+X<taniyama>The library syntax is B<taniyama>C<(E)>, and the precision of the result is determined by the
+global variable C<precdl>.
+
+=head2 X<elltors>elltorsC<(E,{>I<flag>C< = 0})>
+
+if C<E> is an elliptic curve I<defined
+over >B<Q>, outputs the torsion subgroup of C<E> as a 3-component vector
+C<[t,v1,v2]>, where C<t> is the order of the torsion group, C<v1>
+gives the structure of the torsion group as a product of cyclic groups
+(sorted by decreasing order), and C<v2> gives generators for these cyclic
+groups. C<E> must be a long vector as output by C<ellinit>.
+
+ ? E = ellinit([0,0,0,-1,0]);
+ ? elltors(E)
+ %1 = [4, [2, 2], [[0, 0], [1, 0]]]
+
+Here, the torsion subgroup is isomorphic to B<Z>C</2>B<Z>C< x >B<Z>C</2>B<Z>, with
+generators C<[0,0]> and C<[1,0]>.
+
+If I<flag>C< = 0>, use Doud's algorithmS< >: bound torsion by computing C<#E(>B<F>C<_p)>
+for small primes of good reduction, then look for torsion points using
+Weierstrass parametrization (and Mazur's classification).
+
+If I<flag>C< = 1>, use Lutz--Nagell (I<much> slower), C<E> is allowed to be a
+medium vector.
+
+X<elltors0>The library syntax is B<elltors0>C<(E,flag)>.
+
+=head2 X<ellwp>ellwpC<(E,{z = x},{>I<flag>C< = 0})>
+
+Computes the value at C<z> of the Weierstrass F<wp> function attached to the
+elliptic curve C<E> as given by C<ellinit> (alternatively, C<E> can be
+given as a lattice C<[>F<omega>C<_1,>F<omega>C<_2]>).
+
+If C<z> is omitted or is a simple variable, computes the I<power series>
+expansion in C<z> (starting C<z^{-2}+O(z^2)>). The number of terms to an
+I<even> power in the expansion is the default serieslength in GP, and the
+second argument (C long integer) in library mode.
+
+Optional I<flag> is (for now) only taken into account when C<z> is numeric, and
+means 0: compute only F<wp> C<(z)>, 1: compute C<[> F<wp> C<(z),> F<wp> C<'(z)]>.
+
+X<ellwp0>The library syntax is B<ellwp0>C<(E,z,>I<flag>C<,>I<prec>C<,>I<precdl>C<)>. Also available is
+X<weipell>B<weipell>C<(E,>I<precdl>C<)> for the power series (in
+C<x = polx[0]>).
+
+=head2 X<ellzeta>ellzetaC<(E,z)>
+
+value of the Weierstrass F<zeta> function of the
+lattice associated to C<E> as given by C<ellinit> (alternatively, C<E> can
+be given as a lattice C<[>F<omega>C<_1,>F<omega>C<_2]>).
+
+X<ellzeta>The library syntax is B<ellzeta>C<(E,z)>.
+
+=head2 X<ellztopoint>ellztopointC<(E,z)>
+
+C<E> being a long vector, computes the
+coordinates C<[x,y]> on the curve C<E> corresponding to the complex number C<z>.
+Hence this is the inverse function of C<ellpointtoz>. In other words, if
+the curve is put in Weierstrass form, C<[x,y]> represents the
+X<Weierstrass > F<wp> X<-function>Weierstrass F<wp> -function and its derivative.
+If C<z> is in the lattice defining C<E> over
+B<C>, the result is the point at infinity C<[0]>.
+
+X<pointell>The library syntax is B<pointell>C<(E,z,>I<prec>C<)>.
+
+=head1 Functions related to general number fields
+
+In this section can be found functions which are used almost exclusively for
+working in general number fields. Other less specific functions can be found
+in the next section on polynomials. Functions related to quadratic number
+fields can be found in the section L<Label se:arithmetic> (Arithmetic
+functions).
+
+We shall use the following conventions:
+
+B<*> X<nf>I<nf> denotes a number field, i.e.S< >a 9-component vector
+in the format output by X<nfinit>C<nfinit>. This contains the basic arithmetic data
+associated to the number field: signature, maximal order, discriminant, etc.
+
+B<*> X<bnf>I<bnf> denotes a big number field, i.e.S< >a 10-component
+vector in the format output by X<bnfinit>C<bnfinit>. This contains I<nf> and
+the deeper invariants of the field: units, class groups, as well as a lot of
+technical data necessary for some complex fonctions like C<bnfisprincipal>.
+
+B<*> X<bnr>I<bnr> denotes a big ``ray number field'', i.e.S< >some data
+structure output by C<bnrinit>, even more complicated than I<bnf>,
+corresponding to the ray class group structure of the field, for some
+modulus.
+
+B<*> X<rnf>I<rnf> denotes a relative number field (see below).
+
+B<*> X<ideal>I<ideal> can mean any of the following:
+
+S< >S< >-- a B<Z>-basis, in X<Hermite normal form>Hermite normal form
+(HNF) or not. In this case C<x> is a square matrix.
+
+S< >S< >-- an X<idele>I<idele>, i.e.S< >a 2-component vector, the first being an
+ideal given as a B<Z>--basis, the second being a C<r_1+r_2>-component row
+vector giving the complex logarithmic Archimedean information.
+
+S< >S< >-- a B<Z>C<_K>-generating system for an ideal.
+
+S< >S< >-- a I<column> vector C<x> expressing an element of the number field
+on the integral basis, in which case the ideal is treated as being the
+principal idele (or ideal) generated by C<x>.
+
+S< >S< >-- a prime ideal, i.e.S< >a 5-component vector in the format output by
+C<idealprimedec>.
+
+S< >S< >-- a polmod C<x>, i.e.S< >an algebraic integer, in which case the ideal
+is treated as being the principal idele generated by C<x>.
+
+S< >S< >-- an integer or a rational number, also treated as a principal idele.
+
+B<*> a I<{character>} on the Abelian group
+C<\bigoplus (>B<Z>C</N_i>B<Z>C<) g_i>
+is given by a row vector F<chi>C< = [a_1,...,a_n]> such that
+F<chi>C<(>F<prod>C< g_i^{n_i}) = exp(2i>F<Pi>F<sum>C< a_i n_i / N_i)>.
+
+B<Warnings:>
+
+1) An element in I<nf> can be expressed either as a polmod or as a
+vector of components on the integral basis I<nf>C<.zk>. It is absolutely
+essential that all such vectors be I<column> vectors.
+
+2) When giving an ideal by a B<Z>C<_K> generating system to a function expecting
+an ideal, it must be ensured that the function understands that it is a
+B<Z>C<_K>-generating system and not a B<Z>-generating system. When the number of
+generators is strictly less than the degree of the field, there is no
+ambiguity and the program assumes that one is giving a B<Z>C<_K>-generating set.
+When the number of generators is greater than or equal to the degree of the
+field, however, the program assumes on the contrary that you are giving a
+B<Z>-generating set. If this is not the case, you I<must> absolutely
+change it into a B<Z>-generating set, the simplest manner being to use
+C<idealhnf(>I<nf>C<,x)>.
+
+Concerning relative extensions, some additional definitions are necessary.
+
+B<*> A I<{relative matrix>} will be a matrix whose entries are
+elements of a (given) number field I<nf>, always expressed as column
+vectors on the integral basis I<nf>C<.zk>. Hence it is a matrix of
+vectors.
+
+B<*> An X<ideal list>I<ideal list> will be a row vector of (fractional)
+ideals of the number field I<nf>.
+
+B<*> A X<pseudo-matrix>I<pseudo-matrix> will be a pair C<(A,I)> where C<A> is a
+relative matrix and C<I> an ideal list whose length is the same as the number
+of columns of C<A>. This pair will be represented by a 2-component row vector.
+
+B<*> The X<module>I<module> generated by a pseudo-matrix C<(A,I)> is
+the sum F<sum>C<_i{>B<a>C<}_jA_j> where the C<{>B<a>C<}_j> are the ideals of C<I>
+and C<A_j> is the C<j>-th column of C<A>.
+
+B<*> A pseudo-matrix C<(A,I)> is a X<pseudo-basis>I<pseudo-basis> of the module
+it generates if C<A> is a square matrix with non-zero determinant and all the
+ideals of C<I> are non-zero. We say that it is in Hermite Normal
+FormX<Hermite normal form> (HNF) if it is upper triangular and all the
+elements of the diagonal are equal to 1.
+
+B<*> The I<determinant> of a pseudo-basis C<(A,I)> is the ideal
+equal to the product of the determinant of C<A> by all the ideals of C<I>. The
+determinant of a pseudo-matrix is the determinant of any pseudo-basis of the
+module it generates.
+
+Finally, when defining a relative extension, the base field should be
+defined by a variable having a lower priority (i.e.S< >a higher number)
+than the variable defining the extension. For example, under GP you can
+use the variable name C<y> (or C<t>) to define the base field, and the
+variable name C<x> to define the relative extension.
+
+Now a last set of definitions concerning the way big ray number fields
+(or I<bnr>) are input, using class field theory.
+These are defined by a triple
+C<a1>, C<a2>, C<a3>, where the defining set C<[a1,a2,a3]> can have any of the
+following forms: C<[>I<bnr>C<]>, C<[>I<bnr>C<,>I<subgroup>C<]>,
+C<[>I<bnf>C<,>I<module>C<]>, C<[>I<bnf>C<,>I<module>C<,>I<subgroup>C<]>, where:
+
+B<*> I<bnf> is as output by C<bnfclassunit> or C<bnfinit>,
+where units are mandatory unless the ideal is trivial; I<bnr> by
+C<bnrclass> (with I<flag>C< E<gt> 0>) or C<bnrinit>. This is the ground field.
+
+B<*> I<module> is either an ideal in any form (see above) or a
+two-component row vector containing an ideal and an C<r_1>-component row
+vector of flags indicating which real Archimedean embeddings to take in the
+module.
+
+B<*> I<subgroup> is the HNF matrix of a subgroup of the ray class group
+of the ground field for the modulus I<module>. This is input as a square
+matrix expressing generators of a subgroup of the ray class group
+I<bnr>C<.clgp> on the given generators.
+
+The corresponding I<bnr> is then the subfield of the ray class field of the
+ground field for the given modulus, associated to the given subgroup.
+
+All the functions which are specific to relative extensions, number fields,
+big number fields, big number rays, share the prefix C<rnf>, C<nf>,
+C<bnf>, C<bnr> respectively. They are meant to take as first argument a
+number field of that precise type, respectively output by C<rnfinit>,
+C<nfinit>, C<bnfinit>, and C<bnrinit>.
+
+However, and even though it may not be specified in the descriptions of the
+functions below, it is permissible, if the function expects a I<nf>, to
+use a I<bnf> instead (which contains much more information). The program
+will make the effort of converting to what it needs. On the other hand, if
+the program requires a big number field, the program will I<not> launch
+C<bnfinit> for you, which can be a costly operation. Instead, it will give
+you a specific error message.
+
+The data types corresponding to the structures described above are rather
+complicated. Thus, as we already have seen it with elliptic curves, GP
+provides you with some ``member functions'' to retrieve the data you need
+from these structures (once they have been initialized of course). The
+relevant types of number fields are indicated between parentheses:
+
+X<member functions>
+S< >X<bnf>C<bnf> (I<bnr>, I<bnf> ) : big number field.
+
+S< >X<clgp>C<clgp> (I<bnr>, I<bnf> ) : classgroup. This one admits the
+following three subclasses:
+
+S< > X<cyc>C<cyc> : cyclic decomposition
+(SNF)X<Smith normal form>.
+
+S< > C<gen>X<gen (member function)> :
+generators.
+
+S< > X<no>C<no> : number of elements.
+
+S< >X<diff>C<diff> (I<bnr>, I<bnf>, I<nf> ) : the different ideal.
+
+S< >X<codiff>C<codiff> (I<bnr>, I<bnf>, I<nf> ) : the codifferent
+(inverse of the different in the ideal group).
+
+S< >X<disc>C<disc> (I<bnr>, I<bnf>, I<nf> ) : discriminant.
+
+S< >X<fu>C<fu> (I<bnr>, I<bnf>, I<nf> ) :
+X<fundamental units>fundamental units.
+
+S< >X<futu>C<futu> (I<bnr>, I<bnf> ) : C<[u,w]>, C<u> is a vector of
+fundamental units, C<w> generates the torsion.
+
+S< >X<nf>C<nf> (I<bnr>, I<bnf>, I<nf> ) : number field.
+
+S< >X<reg>C<reg> (I<bnr>, I<bnf>, ) : regulator.
+
+S< >X<roots>C<roots> (I<bnr>, I<bnf>, I<nf> ) : roots of the
+polnomial generating the field.
+
+S< >X<sign>C<sign> (I<bnr>, I<bnf>, I<nf> ) : C<[r_1,r_2]> the
+signature of the field. This means that the field has C<r_1> real
+S< > embeddings, C<2r_2> complex ones.
+
+S< >X<t2>C<t2> (I<bnr>, I<bnf>, I<nf> ) : the T2 matrix (see
+C<nfinit>).
+
+S< >X<tu>C<tu> (I<bnr>, I<bnf>, ) : a generator for the torsion
+units.
+
+S< >X<tufu>C<tufu> (I<bnr>, I<bnf>, ) : as C<futu>, but outputs
+C<[w,u]>.
+
+S< >X<zk>C<zk> (I<bnr>, I<bnf>, I<nf> ) : integral basis, i.e.S< >a
+B<Z>-basis of the maximal order.
+
+S< >X<zkst>C<zkst> (I<bnr> ) : structure of C<(>B<Z>C<_K/m)^*> (can be
+extracted also from an I<idealstar>).
+
+For instance, assume that I<bnf>C< = bnfinit(>I<pol>C<)>, for some
+polynomial. Then I<bnf>C<.clgp> retrieves the class group, and
+I<bnf>C<.clgp.no> the class number. If we had set I<bnf>C< =
+nfinit(>I<pol>C<)>, both would have output an error message. All these
+functions are completely recursive, thus for instance
+I<bnr>C<.bnf.nf.zk> will yield the maximal order of I<bnr> (which
+you could get directly with a simple I<bnr>C<.zk> of course).
+
+The following functions, starting with C<buch> in library mode, and with
+C<bnf> under GP, are implementations of the sub-exponential algorithms for
+finding class and unit groups under X<GRH>GRH, due to Hafner-McCurley,
+X<Buchmann>Buchmann and Cohen-Diaz-Olivier.
+
+The general call to the functions concerning class groups of general number
+fields (i.e.S< >excluding C<quadclassunit>) involves a polynomial C<P> and a
+technical vector
+
+S< >I<tech>C< = [c,c2,>I<nrel>C<,>I<borne>C<,>I<nrpid>C<,>I<minsfb>C<],>
+
+where the parameters are to be understood as follows:
+
+C<P> is the defining polynomial for the number field, which must be in
+B<Z>C<[X]>, irreducible and, preferably, monic. In fact, if you supply a
+non-monic polynomial at this point, GP will issue a warning, then
+I<transform your polynomial> so that it becomes monic. Instead of the
+normal result, say C<res>, you then get a vector C<[res,Mod(a,Q)]>,
+where C<Mod(a,Q) = Mod(X,P)> gives the change of variables.
+
+The numbers C<c> and C<c2> are positive real numbers which control the
+execution time and the stack size. To get maximum speed, set C<c2 = c>. To get a
+rigorous result (under X<GRH>GRH) you must take C<c2 = 12> (or C<c2 = 6> in the
+quadratic case, but then you should use the much faster function
+C<quadclassunit>). Reasonable values for C<c> are between C<0.1> and
+C<2>. (The defaults are C<c = c2 = 0.3>).
+
+I<nrel> is the number of initial extra relations requested in
+computing the
+relation matrix. Reasonable values are between 5 and 20. (The default is 5).
+
+I<borne> is a multiplicative coefficient of the Minkowski bound which
+controls
+the search for small norm relations. If this parameter is set equal to 0, the
+program does not search for small norm relations. Otherwise reasonable values
+are between C<0.5> and C<2.0>. (The default is C<1.0>).
+
+I<nrpid> is the maximal number of small norm relations associated to each
+ideal in the factor base. Irrelevant when I<borne>C< = 0>. Otherwise,
+reasonable values are between 4 and 20. (The default is 4).
+
+I<minsfb> is the minimal number of elements in the ``sub-factorbase''.
+If the
+program does not seem to succeed in finding a full rank matrix (which you can
+see in GP by typing C<\g 2>), increase this number. Reasonable values
+are between 2 and 5. (The default is 3).
+
+B<Remarks.>
+
+Apart from the polynomial C<P>, you don't need to supply any of the technical
+parameters (under the library you still need to send at least an empty
+vector, C<cgetg(1,t_VEC)>). However, should you choose to set some of
+them, they I<must> be given in the requested order. For example, if you
+want to specify a given value of C<nrel>, you must give some values as well
+for C<c> and C<c2>, and provide a vector C<[c,c2,nrel]>.
+
+Note also that you can use an I<nf> instead of C<P>, which avoids
+recomputing the integral basis and analogous quantities.
+
+=head2 X<bnfcertify>bnfcertifyC<(>I<bnf>C<)>
+
+I<bnf> being a big number field
+as output by C<bnfinit> or C<bnfclassunit>, checks whether the result
+is correct, i.e.S< >whether it is possible to remove the assumption of the
+Generalized Riemann HypothesisX<GRH>. If it is correct, the answer is 1.
+If not, the program may output some error message, but more probably will loop
+indefinitely. In I<no> occasion can the program give a wrong answer
+(barring bugs of course): if the program answers 1, the answer is certified.
+
+X<certifybuchall>The library syntax is B<certifybuchall>C<(>I<bnf>C<)>, and the result is a C long.
+
+=head2 X<bnfclassunit>bnfclassunitC<(P,{>I<flag>C< = 0},{>I<tech>C< = []})>
+
+X<Buchmann>Buchmann's
+sub-exponential algorithm for computing the class group, the regulator and a
+system of X<fundamental units>fundamental units of the general algebraic number field C<K>
+defined by the irreducible polynomial C<P> with integer coefficients.
+
+The result of this function is a vector C<v> with 10 components (it is
+I<not> a I<bnf>, you need C<bnfinit> for that), which for ease of
+presentation is in fact output as a one column matrix. First we describe the
+default behaviour (I<flag>C< = 0>):
+
+C<v[1]> is equal to the polynomial C<P>. Note that for optimum performance,
+C<P> should have gone through C<polred> or C<nfinit(x,2)>.
+
+C<v[2]> is the 2-component vector C<[r1,r2]>, where C<r1> and C<r2> are as usual
+the number of real and half the number of complex embeddings of the number
+field C<K>.
+
+C<v[3]> is the 2-component vector containing the field discriminant and the
+index.
+
+C<v[4]> is an integral basis in Hermite normal form.
+
+C<v[5]> (C<v.clgp>) is a 3-component vector containing the class number
+(C<v.clgp.no>), the structure of the class group as a product of cyclic
+groups of order C<n_i> (C<v.clgp.cyc>), and the corresponding generators
+of the class group of respective orders C<n_i> (C<v.clgp.gen>).
+
+C<v[6]> (C<v.reg>) is the regulator computed to an accuracy which is the
+maximum of an internally determined accuracy and of the default.
+
+C<v[7]> is a measure of the correctness of the result. If it is close to 1,
+the results are correct (under X<GRH>GRH). If it is close to a larger integer,
+this shows that the product of the class number by the regulator is off by a
+factor equal to this integer, and you must start again with a larger value
+for C<c> or a different random seed, i.e.S< >use the function C<setrand>.
+(Since the computation involves a random process, starting again with exactly
+the same parameters may give the correct result.) In this case a warning
+message is printed.
+
+C<v[8]> (C<v.tu>) a vector with 2 components, the first being the number
+C<w> of roots of unity in C<K> and the second a primitive C<w>-th root of unity
+expressed as a polynomial.
+
+C<v[9]> (C<v.fu>) is a system of fundamental units also expressed as
+polynomials.
+
+C<v[10]> gives a measure of the correctness of the computations of the
+fundamental units (not of the regulator), expressed as a number of bits. If
+this number is greater than C<20>, say, everything is OK. If C<v[10] E<lt>= 0>,
+then we have lost all accuracy in computing the units (usually an error
+message will be printed and the units not given). In the intermediate cases,
+one must proceed with caution (for example by increasing the current
+precision).
+
+If I<flag>C< = 1>, and the precision happens to be insufficient for obtaining the
+fundamental units exactly, the internal precision is doubled and the
+computation redone, until the exact results are obtained. The user should be
+warned that this can take a very long time when the coefficients of the
+fundamental units on the integral basis are very large, for example in the
+case of large real quadratic fields. In that case, there are alternate
+methods for representing algebraic numbers which are not implemented in PARI.
+
+If I<flag>C< = 2>, the fundamental units and roots of unity are not computed.
+Hence the result has only 7 components, the first seven ones.
+
+I<tech> is a technical vector (empty by default) containing C<c>, C<c2>,
+I<nrel>, I<borne>, I<nbpid>, I<minsfb>, in this order (see
+the beginning of the section or the keyword C<bnf>).
+You can supply any number of these I<provided you give an actual value to
+each of them> (the ``empty arg'' trick won't work here). Careful use of these
+parameters may speed up your computations considerably.
+
+X<bnfclassunit0>The library syntax is B<bnfclassunit0>C<(P,>I<flag>C<,>I<tech>C<,>I<prec>C<)>.
+
+=head2 X<bnfclgp>bnfclgpC<(P,{>I<tech>C< = []})>
+
+as C<bnfclassunit>, but only
+outputs C<v[5]>, i.e.S< >the class group.
+
+X<bnfclassgrouponly>The library syntax is B<bnfclassgrouponly>C<(P,>I<tech>C<,>I<prec>C<)>, where I<tech>
+is as described under C<bnfclassunit>.
+
+=head2 X<bnfdecodemodule>bnfdecodemoduleC<(>I<nf>C<,m)>
+
+if C<m> is a module as output in the
+first component of an extension given by C<bnrdisclist>, outputs the
+true module.
+
+X<decodemodule>The library syntax is B<decodemodule>C<(>I<nf>C<,m)>.
+
+=head2 X<bnfinit>bnfinitC<(P,{>I<flag>C< = 0},{>I<tech>C< = []})>
+
+essentially identical
+to C<bnfclassunit> except that the output contains a lot of technical data,
+and should not be printed out explicitly in general. The result of
+C<bnfinit> is used in programs such as C<bnfisprincipal>,
+C<bnfisunit> or C<bnfnarrow>. The result is a 10-component vector
+I<bnf>.
+
+B<*> The first 6 and last 2 components are technical and in
+principle are not used by the casual user. However, for the sake of
+completeness, their description is as follows. We use the notations explained
+in the book by H. Cohen, I<A Course in Computational Algebraic Number
+Theory>, Graduate Texts in Maths B<138>, Springer-Verlag, 1993, Section
+6.5, and subsection 6.5.5 in particular.
+
+I<bnf>C<[1]> contains the matrix C<W>, i.e.S< >the matrix in Hermite normal
+form giving relations for the class group on prime ideal generators
+C<(>B<p>C<_i)_{1 E<lt>= i E<lt>= r}>.
+
+I<bnf>C<[2]> contains the matrix C<B>, i.e.S< >the matrix containing the
+expressions of the prime ideal factorbase in terms of the B<p>C<_i>. It is an
+C<r x c> matrix.
+
+I<bnf>C<[3]> contains the complex logarithmic embeddings of the system of
+fundamental units which has been found. It is an C<(r_1+r_2) x (r_1+r_2-1)>
+matrix.
+
+I<bnf>C<[4]> contains the matrix C<M''_C> of Archimedean components of the
+relations of the matrix C<(W|B)>.
+
+I<bnf>C<[5]> contains the prime factor base, i.e.S< >the list of prime
+ideals used in finding the relations.
+
+I<bnf>C<[6]> contains the permutation of the prime factor base which was
+necessary to reduce the relation matrix to the form explained in subsection
+6.5.5 of GTMS< >138 (i.e.S< >with a big C<c x c> identity matrix on the lower
+right). Note that in the above mentioned book, the need to permute the rows
+of the relation matrices which occur was not emphasized.
+
+I<bnf>C<[9]> is a 3-element row vector used in X<bnfisprincipal>C<bnfisprincipal> only
+and obtained as follows. Let C<D = U W V> obtained by applying the
+X<Smith normal form>Smith normal form algorithm to the matrix C<W> ( = I<bnf>C<[1]>) and
+let C<U_r> be the reduction of C<U> modulo C<D>. The first elements of the
+factorbase are given (in terms of C<bnf.gen>) by the columns of C<U_r>,
+with archimedian component C<g_a>; let also C<GD_a> be the archimedian
+components of the generators of the (principal) ideals defined by the
+C<bnf.gen[i]^bnf.cyc[i]>. Then I<bnf>C<[9] = [U_r, g_a, GD_a]>.
+
+Finally, I<bnf>C<[10]> is by default unused and set equal to 0. This
+field is used to store further information about the field as it becomes
+available (which is rarely needed, hence would be too expensive to compute
+during the initial C<bnfinit> call). For instance, the generators of the
+principal ideals C<bnf.gen[i]^bnf.cyc[i]> (during a call to
+X<bnrisprincipal>C<bnrisprincipal>), or those corresponding to the relations in C<W> and
+C<B> (when the C<bnf> internal precision needs to be increased).
+
+B<*> The less technical components are as follows:
+
+I<bnf>C<[7]> or I<bnf>C<.nf> is equal to the number field data
+I<nf> as would be given by C<nfinit>.
+
+I<bnf>C<[8]> is a vector containing the last 6 components of
+C<bnfclassunit[,1]>, i.e.S< >the classgroup I<bnf>C<.clgp>, the
+regulator I<bnf>C<.reg>, the general ``check'' number which should be
+close to 1, the number of roots of unity and a generator I<bnf>C<.tu>,
+the fundamental units I<bnf>C<.fu>, and finally the check on their
+computation. If the precision becomes insufficient, GP outputs a warning
+(C<fundamental units too large, not given>) and does not strive to
+compute the units by default (I<flag>C< = 0>).
+
+When I<flag>C< = 1>, GP insists on finding the fundamental units exactly, the
+internal precision being doubled and the computation redone, until the exact
+results are obtained. The user should be warned that this can take a very
+long time when the coefficients of the fundamental units on the integral
+basis are very large.
+
+When I<flag>C< = 2>, on the contrary, it is initially agreed that GP
+will not compute units.
+
+When I<flag>C< = 3>, computes a very small version of C<bnfinit>, a ``small big
+number field'' (or I<sbnf> for short) which contains enough information
+to recover the full I<bnf> vector very rapidly, but which is much
+smaller and hence easy to store and print. It is supposed to be used in
+conjunction with C<bnfmake>. The output is a 12 component vector C<v>, as
+follows. Let I<bnf> be the result of a full C<bnfinit>, complete with
+units. Then C<v[1]> is the polynomial C<P>, C<v[2]> is the number of real
+embeddings C<r_1>, C<v[3]> is the field discriminant, C<v[4]> is the integral
+basis, C<v[5]> is the list of roots as in the sixth component of C<nfinit>,
+C<v[6]> is the matrix C<MD> of C<nfinit> giving a B<Z>-basis of the
+different, C<v[7]> is the matrix C<W = >I<bnf>C<[1]>, C<v[8]> is the
+matrix C<matalpha = >I<bnf>C<[2]>, C<v[9]> is the prime ideal factor base
+I<bnf>C<[5]> coded in a compact way, and ordered according to the
+permutation I<bnf>C<[6]>, C<v[10]> is the 2-component vector giving the
+number of roots of unity and a generator, expressed on the integral basis,
+C<v[11]> is the list of fundamental units, expressed on the integral basis,
+C<v[12]> is a vector containing the algebraic numbers alpha corresponding to
+the columns of the matrix C<matalpha>, expressed on the integral basis.
+
+Note that all the components are exact (integral or rational), except for
+the roots in C<v[5]>. In practice, this is the only component which a user
+is allowed to modify, by recomputing the roots to a higher accuracy if
+desired. Note also that the member functions will I<not> work on
+I<sbnf>, you have to use C<bnfmake> explicitly first.
+
+X<bnfinit0>The library syntax is B<bnfinit0>C<(P,>I<flag>C<,>I<tech>C<,>I<prec>C<)>.
+
+=head2 X<bnfisintnorm>bnfisintnormC<(>I<bnf>C<,x)>
+
+computes a complete system of
+solutions (modulo units of positive norm) of the absolute norm equation
+C<Norm(a) = x>,
+where C<a> is an integer in I<bnf>. If I<bnf> has not been certified,
+the correctness of the result depends on the validity of X<GRH>GRH.
+
+X<bnfisintnorm>The library syntax is B<bnfisintnorm>C<(>I<bnf>C<,x)>.
+
+=head2 X<bnfisnorm>bnfisnormC<(>I<bnf>C<,x,{>I<flag>C< = 1})>
+
+tries to tell whether the
+rational number C<x> is the norm of some element y in I<bnf>. Returns a
+vector C<[a,b]> where C<x = Norm(a)*b>. Looks for a solution which is an C<S>-unit,
+with C<S> a certain set of prime ideals containing (among others) all primes
+dividing C<x>. If I<bnf> is known to be X<Galois>Galois, set I<flag>C< = 0> (in
+this case,
+C<x> is a norm iff C<b = 1>). If I<flag> is non zero the program adds to C<S> the
+following prime ideals, depending on the sign of I<flag>. If I<flag>C< E<gt> 0>, the
+ideals of norm less than I<flag>. And if I<flag>C< E<lt> 0> the ideals dividing I<flag>.
+
+If you are willing to assume X<GRH>GRH, the answer is guaranteed
+(i.e.S< >C<x> is a norm iff C<b = 1>), if C<S> contains all primes less than
+C<12> F<log> C<(>I<disc>C<(>I<Bnf>C<))^2>,
+where I<Bnf> is the Galois closure of I<bnf>.
+
+X<bnfisnorm>The library syntax is B<bnfisnorm>C<(>I<bnf>C<,x,>I<flag>C<,>I<prec>C<)>, where I<flag> and
+I<prec> are C<long>s.
+
+=head2 X<bnfissunit>bnfissunitC<(>I<bnf>C<,>I<sfu>C<,x)>
+
+I<bnf> being output by
+C<bnfinit>, I<sfu> by C<bnfsunit>, gives the column vector of
+exponents of C<x> on the fundamental C<S>-units and the roots of unity.
+If C<x> is not a unit, outputs an empty vector.
+
+X<bnfissunit>The library syntax is B<bnfissunit>C<(>I<bnf>C<,>I<sfu>C<,x)>.
+
+=head2 X<bnfisprincipal>bnfisprincipalC<(>I<bnf>C<,x,{>I<flag>C< = 1})>
+
+I<bnf> being the
+number field data output by C<bnfinit>, and C<x> being either a B<Z>-basis
+of an ideal in the number field (not necessarily in HNF) or a prime ideal in
+the format output by the function C<idealprimedec>, this function tests
+whether the ideal is principal or not. The result is more complete than a
+simple true/false answer: it gives a row vector C<[v_1,v_2,check]>, where
+
+C<v_1> is the vector of components C<c_i> of the class of the ideal C<x> in the
+class group, expressed on the generators C<g_i> given by C<bnfinit>
+(specifically I<bnf>C<.clgp.gen> which is the same as
+I<bnf>C<[8][1][3]>). The C<c_i> are chosen so that C<0 E<lt>= c_i E<lt> n_i>
+where C<n_i> is the order of C<g_i> (the vector of C<n_i> being
+I<bnf>C<.clgp.cyc>, that is I<bnf>C<[8][1][2]>).
+
+C<v_2> gives on the integral basis the components of F<alpha> such that
+C<x = >F<alpha>F<prod>C<_ig_i^{c_i}>. In particular, C<x> is principal if and only if
+C<v_1> is equal to the zero vector, and if this the case C<x = >F<alpha>B<Z>C<_K> where
+F<alpha> is given by C<v_2>. Note that if F<alpha> is too large to be given, a
+warning message will be printed and C<v_2> will be set equal to the empty
+vector.
+
+Finally the third component I<check> is analogous to the last component of
+C<bnfclassunit>: it gives a check on the accuracy of the result, in bits.
+I<check> should be at least C<10>, and preferably much more. In any case, the
+result is checked for correctness.
+
+If I<flag>C< = 0>, outputs only C<v_1>, which is much easier to compute.
+
+If I<flag>C< = 2>, does as if I<flag> were C<0>, but doubles the precision until a
+result is obtained.
+
+If I<flag>C< = 3>, as in the default behaviour (I<flag>C< = 1>), but doubles the precision
+until a result is obtained.
+
+The user is warned that these two last setting may induce I<very> lengthy
+computations.
+
+X<isprincipalall>The library syntax is B<isprincipalall>C<(>I<bnf>C<,x,>I<flag>C<)>.
+
+=head2 X<bnfisunit>bnfisunitC<(>I<bnf>C<,x)>
+
+I<bnf> being the number field data
+output by
+C<bnfinit> and C<x> being an algebraic number (type integer, rational or
+polmod), this outputs the decomposition of C<x> on the fundamental units and
+the roots of unity if C<x> is a unit, the empty vector otherwise. More
+precisely, if C<u_1>,...,C<u_r> are the fundamental units, and F<zeta> is
+the generator of the group of roots of unity (found by C<bnfclassunit> or
+C<bnfinit>), the output is a vector C<[x_1,...,x_r,x_{r+1}]> such that
+C<x = u_1^{x_1}...u_r^{x_r}.>F<zeta>C<^{x_{r+1}}>. The C<x_i> are integers for
+C<i E<lt>= r> and is an integer modulo the order of F<zeta> for C<i = r+1>.
+
+X<isunit>The library syntax is B<isunit>C<(>I<bnf>C<,x)>.
+
+=head2 X<bnfmake>bnfmakeC<(>I<sbnf>C<)>
+
+I<sbnf> being a ``small I<bnf>''
+as output by C<bnfinit>C<(x,3)>, computes the complete C<bnfinit>
+information. The result is I<not> identical to what C<bnfinit> would
+yield, but is functionally identical. The execution time is very small
+compared to a complete C<bnfinit>. Note that if the default precision in
+GP (or I<prec> in library mode) is greater than the precision of the
+roots I<sbnf>C<[5]>, these are recomputed so as to get a result with
+greater accuracy.
+
+Note that the member functions are I<not> available for I<sbnf>, you
+have to use C<bnfmake> explicitly first.
+
+X<makebigbnf>The library syntax is B<makebigbnf>C<(>I<sbnf>C<,>I<prec>C<)>, where I<prec> is a
+C long integer.
+
+=head2 X<bnfnarrow>bnfnarrowC<(>I<bnf>C<)>
+
+I<bnf> being a big number field as
+output by C<bnfinit>, computes the narrow class group of I<bnf>. The
+output is a 3-component row vector C<v> analogous to the corresponding
+class group component I<bnf>C<.clgp> (I<bnf>C<[8][1]>): the
+first component is the narrow class number C<v.no>, the second component
+is a vector containing the SNFX<Smith normal form> cyclic components
+C<v.cyc> of the narrow
+class group, and the third is a vector giving the generators of the
+corresponding C<v.gen> cyclic groups. Note that this function is a
+special case of C<bnrclass>.
+
+X<buchnarrow>The library syntax is B<buchnarrow>C<(>I<bnf>C<)>.
+
+=head2 X<bnfsignunit>bnfsignunitC<(>I<bnf>C<)>
+
+I<bnf> being a big number field
+output by C<bnfinit>, this computes an C<r_1 x (r_1+r_2-1)> matrix
+having C<F<+->1> components, giving the signs of the real embeddings of the
+fundamental units.
+
+X<signunits>The library syntax is B<signunits>C<(>I<bnf>C<)>.
+
+=head2 X<bnfreg>bnfregC<(>I<bnf>C<)>
+
+I<bnf> being a big number field
+output by C<bnfinit>, computes its regulator.
+
+X<regulator>The library syntax is B<regulator>C<(>I<bnf>C<,>I<tech>C<,>I<prec>C<)>, where I<tech> is as in
+C<bnfclassunit>.
+
+=head2 X<bnfsunit>bnfsunitC<(>I<bnf>C<,S)>
+
+computes the fundamental C<S>-units of the
+number field I<bnf> (output by C<bnfinit>), where C<S> is a list of
+prime ideals (output by C<idealprimedec>). The output is a vector C<v> with
+6 components.
+
+C<v[1]> gives a minimal system of (integral) generators of the C<S>-unit group
+modulo the unit group.
+
+C<v[2]> contains technical data needed by C<bnfissunit>.
+
+C<v[3]> is an empty vector (used to give the logarithmic embeddings of the
+generators in C<v[1]> in version 2.0.16).
+
+C<v[4]> is the C<S>-regulator (this is the product of the regulator, the
+determinant of C<v[2]> and the natural logarithms of the norms of the ideals
+in C<S>).
+
+C<v[5]> gives the C<S>-class group structure, in the usual format
+(a row vector whose three components give in order the C<S>-class number,
+the cyclic components and the generators).
+
+C<v[6]> is a copy of C<S>.
+
+X<bnfsunit>The library syntax is B<bnfsunit>C<(>I<bnf>C<,S,>I<prec>C<)>.
+
+=head2 X<bnfunit>bnfunitC<(>I<bnf>C<)>
+
+I<bnf> being a big number field as
+output by
+C<bnfinit>, outputs a two-component row vector giving in the first
+component the vector of fundamental units of the number field, and in the
+second component the number of bit of accuracy which remained in the
+computation (which is always correct, otherwise an error message is printed).
+This function is mainly for people who used the wrong flag in C<bnfinit>
+and would like to skip part of a lengthy C<bnfinit> computation.
+
+X<buchfu>The library syntax is B<buchfu>C<(>I<bnf>C<)>.
+
+=head2 X<bnrL1>bnrL1C<(>I<bnr>C<,>I<subgroup>C<,{>I<flag>C< = 0})>
+
+I<bnr> being the number field data which is output by
+C<bnrinit(,,1)> and I<subgroup> being a square matrix defining a
+congruence subgroup of the ray class group corresponding to I<bnr>
+(or C<0> for the trivial congruence subgroup), returns for each
+X<character>character F<chi> of the ray class group which is trivial on this
+subgroup, the value at C<s = 1> (or C<s = 0>) of the abelian
+C<L>-function associated to F<chi>. For the value at C<s = 0>, the
+function returns in fact for each character F<chi> a vector C<[r_>F<chi>C< ,
+c_>F<chi>C<]> where C<r_>F<chi> is the order of C<L(s, >F<chi>C<)> at C<s = 0> and
+C<c_>F<chi> the first non-zero term in the expansion of C<L(s,
+>F<chi>C<)> at C<s = 0>; in other words
+
+S< >C<L(s, >F<chi>C<) = c_>F<chi>C<.s^{r_>F<chi>C<} + O(s^{r_>F<chi>C< + 1})>
+
+near C<0>. I<flag> is optional, default value is 0; its binary digits
+mean 1: compute at C<s = 1> if set to 1 or C<s = 0> if set to 0, 2: compute
+the primitive C<L>-functions associated to F<chi> if set to 0 or the
+C<L>-function with Euler factors at prime ideals dividing the modulus of
+I<bnr> removed if set to 1 (this is the so-called C<L_S(s, >F<chi>C<)>
+function where C<S> is the set of infinite places of the number field
+together with the finite prime ideals dividing the modulus of I<bnr>,
+see the example below), 3: returns also the character.
+
+Example:
+
+ bnf = bnfinit(x^2 - 229);
+ bnr = bnrinit(bnf,1,1);
+ bnrL1(bnr, 0)
+
+returns the order and the first non-zero term of the abelian
+C<L>-functions C<L(s, >F<chi>C<)> at C<s = 0> where F<chi> runs through the
+characters of the class group of B<Q>C<(> F<sqrt> C<{229})>. Then
+
+ bnr2 = bnrinit(bnf,2,1);
+ bnrL1(bnr2,0,2)
+
+returns the order and the first non-zero terms of the abelian
+C<L>-functions C<L_S(s, >F<chi>C<)> at C<s = 0> where F<chi> runs through the
+characters of the class group of B<Q>C<(> F<sqrt> C<{229})> and C<S> is the set
+of infinite places of B<Q>C<(> F<sqrt> C<{229})> together with the finite prime
+C<2> (note that the ray class group modulo C<2> is in fact the class
+group, so C<bnrL1(bnr2,0)> returns exactly the same answer as
+C<bnrL1(bnr,0)>!).
+
+X<bnrL1>The library syntax is B<bnrL1>C<(>I<bnr>C<,>I<subgroup>C<,>I<flag>C<,>I<prec>C<)>
+
+=head2 X<bnrclass>bnrclassC<(>I<bnf>C<,>I<ideal>C<,{>I<flag>C< = 0})>
+
+I<bnf> being a big number field
+as output by C<bnfinit> (the units are mandatory unless the ideal is
+trivial), and I<ideal> being either an ideal in any form or a two-component
+row vector containing an ideal and an C<r_1>-component row vector of flags
+indicating which real Archimedean embeddings to take in the module, computes
+the ray class group of the number field for the module I<ideal>, as a
+3-component vector as all other finite Abelian groups (cardinality, vector of
+cyclic components, corresponding generators).
+
+If I<flag>C< = 2>, the output is different. It is a 6-component vector C<w>. C<w[1]>
+is I<bnf>. C<w[2]> is the result of applying
+C<idealstar(>I<bnf>C<,I,2)>. C<w[3]>, C<w[4]> and C<w[6]> are technical
+components used only by the function C<bnrisprincipal>. C<w[5]> is the
+structure of the ray class group as would have been output with I<flag>C< = 0>.
+
+If I<flag>C< = 1>, as above, except that the generators of the ray class group are
+not computed, which saves time.
+
+X<bnrclass0>The library syntax is B<bnrclass0>C<(>I<bnf>C<,>I<ideal>C<,>I<flag>C<,>I<prec>C<)>.
+
+=head2 X<bnrclassno>bnrclassnoC<(>I<bnf>C<,I)>
+
+I<bnf> being a big number field
+as output
+by C<bnfinit> (units are mandatory unless the ideal is trivial), and C<I>
+being either an ideal in any form or a two-component row vector containing an
+ideal and an C<r_1>-component row vector of flags indicating which real
+Archimedean embeddings to take in the modulus, computes the ray class number
+of the number field for the modulus C<I>. This is faster than C<bnrclass>
+and should be used if only the ray class number is desired.
+
+X<rayclassno>The library syntax is B<rayclassno>C<(>I<bnf>C<,I)>.
+
+=head2 X<bnrclassnolist>bnrclassnolistC<(>I<bnf>C<,>I<list>C<)>
+
+I<bnf> being a
+big number field as output by C<bnfinit> (units are mandatory unless
+the ideal is trivial), and I<list> being a list of modules as output
+by C<ideallist> of C<ideallistarch>,
+outputs the list of the class numbers of the corresponding ray class groups.
+
+X<rayclassnolist>The library syntax is B<rayclassnolist>C<(>I<bnf>C<,>I<list>C<)>.
+
+=head2 X<bnrconductor>bnrconductorC<(a_1,{a_2},{a_3}, {>I<flag>C< = 0})>
+
+conductor of the
+subfield of a ray class field as defined by C<[a_1,a_2,a_3]> (see C<bnr>
+at the beginning of this section).
+
+X<bnrconductor>The library syntax is B<bnrconductor>C<(a_1,a_2,a_3,>I<flag>C<,>I<prec>C<)>, where an omitted argument
+among the C<a_i> is input as C<gzero>, and I<flag> is a C long.
+
+=head2 X<bnrconductorofchar>bnrconductorofcharC<(>I<bnr>C<,>I<chi>C<)>
+
+I<bnr> being a
+big ray number field
+as output by C<bnrclass>, and I<chi> being a row vector representing a
+X<character>character as expressed on the generators of the ray class group, gives
+the conductor of this character as a modulus.
+
+X<bnrconductorofchar>The library syntax is B<bnrconductorofchar>C<(>I<bnr>C<,>I<chi>C<,>I<prec>C<)> where I<prec>
+is a C<long>.
+
+=head2 X<bnrdisc>bnrdiscC<(a1,{a2},{a3},{>I<flag>C< = 0})>
+
+C<a1>, C<a2>, C<a3>
+defining a big ray number field C<L> over a groud field C<K> (see C<bnr>
+at the beginning of this section for the
+meaning of C<a1>, C<a2>, C<a3>), outputs a 3-component row vector C<[N,R_1,D]>,
+where C<N> is the (absolute) degree of C<L>, C<R_1> the number of real places of
+C<L>, and C<D> the discriminant of C<L/>B<Q>, including sign (if I<flag>C< = 0>).
+
+If I<flag>C< = 1>, as above but outputs relative data. C<N> is now the degree of
+C<L/K>, C<R_1> is the number of real places of C<K> unramified in C<L> (so that
+the number of real places of C<L> is equal to C<R_1> times the relative degree
+C<N>), and C<D> is the relative discriminant ideal of C<L/K>.
+
+If I<flag>C< = 2>, does as in case 0, except that if the modulus is not the exact
+conductor corresponding to the C<L>, no data is computed and the result is C<0>
+(C<gzero>).
+
+If I<flag>C< = 3>, as case 2, outputting relative data.
+
+X<bnrdisc0>The library syntax is B<bnrdisc0>C<(a1,a2,a3,>I<flag>C<,>I<prec>C<)>.
+
+=head2 X<bnrdisclist>bnrdisclistC<(>I<bnf>C<,>I<bound>C<,{>I<arch>C<},{>I<flag>C< = 0})>
+
+I<bnf> being a big
+number field as output by C<bnfinit> (the units are mandatory), computes a
+list of discriminants of Abelian extensions of the number field by increasing
+modulus norm up to bound I<bound>, where the ramified Archimedean places are
+given by I<arch> (unramified at infinity if I<arch> is void or
+omitted). If
+I<flag> is non-zero, give I<arch> all the possible values. (See C<bnr>
+at the beginning of this section for the meaning of C<a1>, C<a2>, C<a3>.)
+
+The alternative syntax C<bnrdisclist(>I<bnf>C<,>I<list>C<)>
+is supported, where I<list> is as output by C<ideallist> or
+C<ideallistarch> (with units).
+
+The output format is as follows. The output C<v> is a row vector of row
+vectors, allowing the bound to be greater than C<2^{16}> for 32-bit machines,
+and C<v[i][j]> is understood to be in fact C<V[2^{15}(i-1)+j]> of a unique big
+vector C<V> (note that C<2^{15}> is hardwired and can be increased in the
+source code only on 64-bit machines and higher).
+
+Such a component C<V[k]> is itself a vector C<W> (maybe of length 0) whose
+components correspond to each possible ideal of norm C<k>. Each component
+C<W[i]> corresponds to an Abelian extension C<L> of I<bnf> whose modulus is
+an ideal of norm C<k> and no Archimedean components (hence the extension is
+unramified at infinity). The extension C<W[i]> is represented by a 4-component
+row vector C<[m,d,r,D]> with the following meaning. C<m> is the prime ideal
+factorization of the modulus, C<d = [L:>B<Q>C<]> is the absolute degree of C<L>,
+C<r> is the number of real places of C<L>, and C<D> is the factorization of the
+absolute discriminant. Each prime ideal C<pr = [p,>F<alpha>C<,e,f,>F<beta>C<]> in the
+prime factorization C<m> is coded as C<p.n^2+(f-1).n+(j-1)>, where
+C<n> is the degree of the base field and C<j> is such that
+
+C<pr = idealprimedec(>I<nf>C<,p)[j]>.
+
+C<m> can be decoded using C<bnfdecodemodule>.
+
+X<bnrdisclist0>The library syntax is B<bnrdisclist0>C<(a1,a2,a3,>I<bound>C<,>I<arch>C<,>I<flag>C<)>.
+
+=head2 X<bnrinit>bnrinitC<(>I<bnf>C<,>I<ideal>C<,{>I<flag>C< = 0})>
+
+I<bnf> is as
+output by C<bnfinit>, I<ideal> is a valid ideal (or a module),
+initializes data linked
+to the ray class group structure corresponding to this module. This is the
+same as C<bnrclass(>I<bnf>C<,>I<ideal>C<,>I<flag>C<+1)>.
+
+X<bnrinit0>The library syntax is B<bnrinit0>C<(>I<bnf>C<,>I<ideal>C<,>I<flag>C<,>I<prec>C<)>.
+
+=head2 X<bnrisconductor>bnrisconductorC<(a1,{a2},{a3})>
+
+C<a1>, C<a2>, C<a3> represent
+an extension of the base field, given by class field theory for some modulus
+encoded in the parameters. Outputs 1 if this modulus is the conductor, and 0
+otherwise. This is slightly faster than C<bnrconductor>.
+
+X<bnrisconductor>The library syntax is B<bnrisconductor>C<(a1,a2,a3)> and the result is a C<long>.
+
+=head2 X<bnrisprincipal>bnrisprincipalC<(>I<bnr>C<,x,{>I<flag>C< = 1})>
+
+I<bnr> being the
+number field data which is output by C<bnrinit>C<(,,1)> and C<x> being an
+ideal in any form, outputs the components of C<x> on the ray class group
+generators in a way similar to C<bnfisprincipal>. That is a 3-component
+vector C<v> where C<v[1]> is the vector of components of C<x> on the ray class
+group generators, C<v[2]> gives on the integral basis an element F<alpha> such
+that C<x = >F<alpha>F<prod>C<_ig_i^{x_i}>. Finally C<v[3]> indicates the number of bits
+of accuracy left in the result. In any case the result is checked for
+correctness, but C<v[3]> is included to see if it is necessary to increase the
+accuracy in other computations.
+
+If I<flag>C< = 0>, outputs only C<v_1>. In that case, I<bnr> need not contain the
+ray class group generators, i.e.S< >it may be created with C<bnrinit>C<(,,0)>
+
+X<isprincipalrayall>The library syntax is B<isprincipalrayall>C<(>I<bnr>C<,x,>I<flag>C<)>.
+
+=head2 X<bnrrootnumber>bnrrootnumberC<(>I<bnr>C<,>I<chi>C<,{>I<flag>C< = 0})>
+
+if F<chi>C< = >I<chi> is a (not necessarily primitive)
+X<character>character over I<bnr>, let
+C<L(s,>F<chi>C<) = >F<sum>C<_{id} >F<chi>C<(id) N(id)^{-s}> be the associated
+X<Artin L-function>Artin L-function. Returns the so-called X<Artin root number>Artin root number, i.e.S< >the
+complex number C<W(>F<chi>C<)> of modulus 1 such that
+
+S< >F<Lambda>C<(1-s,>F<chi>C<) = W(>F<chi>C<) >F<Lambda>C<(s,\overline{>F<chi>C<})>
+
+where F<Lambda>C<(s,>F<chi>C<) = A(>F<chi>C<)^{s/2}>F<gamma>C<_>F<chi>C<(s) L(s,>F<chi>C<)> is
+the enlarged L-function associated to C<L>.
+
+The generators of the ray class group are needed, and you can set I<flag>C< = 1> if
+the character is known to be primitive. Example:
+
+ bnf = bnfinit(x^2 - 145);
+ bnr = bnrinit(bnf,7,1);
+ bnrrootnumber(bnr, [5])
+
+returns the root number of the character F<chi> of C<Cl_7(>B<Q>C<(> F<sqrt> C<{145}))>
+such that F<chi>C<(g) = >F<zeta>C<^5>, where C<g> is the generator of the ray-class
+field and F<zeta>C< = e^{2i>F<Pi>C</N}> where C<N> is the order of C<g> (C<N = 12> as
+C<bnr.cyc> readily tells us).
+
+X<bnrrootnumber>The library syntax is B<bnrrootnumber>C<(>I<bnf>C<,>I<chi>C<,>I<flag>C<)>
+
+=head2 bnrstarkC<{(>I<bnr>C<,>I<subgroup>C<,{>I<flag>C< = 0})}>
+
+I<bnr>
+being as output by C<bnrinit(,,1)>, finds a relative equation for the
+class field corresponding to the modulus in I<bnr> and the given
+congruence subgroup using X<Stark units>Stark units (set I<subgroup>C< = 0> if you
+want the whole ray class group). The main variable of I<bnr> must not be
+C<x>, and the ground field and the class field must be totally real and not
+isomorphic to B<Q> (over the rationnals, use X<polsubcyclo>C<polsubcyclo> or
+X<galoissubcyclo>C<galoissubcyclo>). I<flag> is optional and may be set to 0 to obtain a
+reduced relative polynomial, 1 to be satisfied with any relative
+polynomial, 2 to obtain an absolute polynomial and 3 to obtain the
+irreducible relative polynomial of the Stark unit, 0 being default.
+Example:
+
+ bnf = bnfinit(y^2 - 3);
+ bnr = bnrinit(bnf, 5, 1);
+ bnrstark(bnr, 0)
+
+returns the ray class field of B<Q>C<(> F<sqrt> C<{3})> modulo C<5>.
+
+B<Remark.> The result of the computation depends on the choice of
+a modulus verifying special conditions. By default the function will try
+few moduli, choosing the one giving the smallest result. In some cases
+where the result is however very large, you can tell the function to
+try more moduli by adding C<4> to the value of flag. Whether this flag is
+set or not, the function may fail in some extreme cases, returning the
+error message
+
+C<"Cannot find a suitable modulus in FindModule">.
+
+In this case, the corresponding congruence group is a product of cyclic
+groups and, for the time being, the class field has to be obtained by
+splitting this group into its cyclic components.
+
+X<bnrstark>The library syntax is B<bnrstark>C<(>I<bnr>C<,>I<subgroup>C<,>I<flag>C<)>.
+
+=head2 X<dirzetak>dirzetakC<(>I<nf>C<,b)>
+
+gives as a vector the first C<b>
+coefficients of the X<Dedekind>Dedekind zeta function of the number field I<nf>
+considered as a X<Dirichlet series>Dirichlet series.
+
+X<dirzetak>The library syntax is B<dirzetak>C<(>I<nf>C<,b)>.
+
+=head2 X<factornf>factornfC<(x,t)>
+
+factorization of the univariate polynomial C<x>
+over the number field defined by the (univariate) polynomial C<t>. C<x> may
+have coefficients in B<Q> or in the number field. The main variable of
+C<t> must be of I<lower> priority than that of C<x> (in other words the
+variable number of C<t> must be I<greater> than that of C<x>). However if
+the coefficients of the number field occur explicitly (as polmods) as
+coefficients of C<x>, the variable of these polmods I<must> be the same as
+the main variable of C<t>. For example
+
+ ? factornf(x^2 + Mod(y, y^2+1), y^2+1);
+ ? factornf(x^2 + 1, y^2+1); \\ these two are OK
+ ? factornf(x^2 + Mod(z,z^2+1), y^2+1)
+ *** incorrect type in gmulsg
+
+X<polfnf>The library syntax is B<polfnf>C<(x,t)>.
+
+=head2 X<galoisfixedfield>galoisfixedfieldC<(>I<gal>C<,>I<perm>C<,{fl = 0},{v = y}))>
+
+I<gal> being be a Galois field as output by X<galoisinit>C<galoisinit> and
+I<perm> an element of I<gal>C<.group> or a vector of such elements,
+computes the fixed field of I<gal> by the automorphism defined by the
+permutations I<perm> of the roots I<gal>C<.roots>. C<P> is guaranteed to
+be squarefree modulo I<gal>C<.p>.
+
+If no flags or I<flag>C< = 0>, output format is the same as for X<nfsubfield>C<nfsubfield>,
+returning C<[P,x]> such that C<P> is a polynomial defining the fixed field, and
+C<x> is a root of C<P> expressed as a polmod in I<gal>C<.pol>.
+
+If I<flag>C< = 1> return only the polynomial C<P>.
+
+If I<flag>C< = 2> return C<[P,x,F]> where C<P> and C<x> are as above and C<F> is the
+factorization of I<gal>C<.pol> over the field defined by C<P>, where
+variable C<v> (C<y> by default) stands for a root of C<P>. The priority of C<v>
+must be less than the priority of the variable of I<gal>C<.pol>.
+
+Example:
+
+ G = galoisinit(x^4+1);
+ galoisfixedfield(G,G.group[2],2)
+ [x^2 + 2, Mod(x^3 + x, x^4 + 1), [x^2 - y*x - 1, x^2 + y*x - 1]]
+
+computes the factorization C<x^4+1 = (x^2-> F<sqrt> C<{-2}x-1)(x^2+> F<sqrt> C<{-2}x-1)>
+
+X<galoisfixedfield>The library syntax is B<galoisfixedfield>C<(>I<gal>C<,>I<perm>C<,p)>.
+
+=head2 X<galoisinit>galoisinitC<(>I<pol>C<,{den})>
+
+computes the Galois group
+and all neccessary information for computing the fixed fields of the
+Galois extension C<K/>B<Q> where C<K> is the number field defined by
+I<pol> (monic irreducible polynomial in B<Z>C<[X]> or
+a number field as output by X<nfinit>C<nfinit>). The extension C<K/>B<Q> must be
+Galois with Galois group ``weakly'' super-solvable (see X<nfgaloisconj>C<nfgaloisconj>)
+
+B<Warning:> The interface of this function is experimental,
+so the described output can be subject to important changes in the
+near future. However the function itself should work as described. For any
+remarks about this interface, please mail C<allomber@math.u-bordeaux.fr>.
+
+The output is an 8-component vector I<gal>.
+
+I<gal>C<[1]> contains the polynomial I<pol>
+(I<gal>C<.pol>).
+
+I<gal>C<[2]> is a three--components vector C<[p,e,q]> where C<p> is a
+prime number (I<gal>C<.p>) such that I<pol> totally split
+modulo C<p> , C<e> is an integer and C<q = p^e> (I<gal>C<.mod>) is the
+modulus of the roots in I<gal>C<.roots>.
+
+I<gal>C<[3]> is a vector C<L> containing the C<p>-adic roots of
+I<pol> as integers implicitly modulo I<gal>C<.mod>.
+(I<gal>C<.roots>).
+
+I<gal>C<[4]> is the inverse of the Van der Monde matrix of the
+C<p>-adic roots of I<pol>, multiplied by I<gal>C<[5]>.
+
+I<gal>C<[5]> is a multiple of the least common denominator of the
+automorphisms expressed as polynomial in a root of I<pol>.
+
+I<gal>C<[6]> is the Galois group C<G> expressed as a vector of
+permutations of C<L> (I<gal>C<.group>).
+
+I<gal>C<[7]> is a generating subset C<S = [s_1,...,s_g]> of C<G>
+expressed as a vector of permutations of C<L> (I<gal>C<.gen>).
+
+I<gal>C<[8]> contains the relative orders C<[o_1,...,o_g]> of
+the generators of C<S> (I<gal>C<.orders>).
+
+Let C<H> be the maximal normal supersolvable subgroup of C<G>, we have the
+following properties:
+
+S< >S< >B<*> if C<G/H ~ A_4> then C<[o_1,...,o_g]> ends by
+C<[2,2,3]>.
+
+S< >S< >B<*> if C<G/H ~ S_4> then C<[o_1,...,o_g]> ends by
+C<[2,2,3,2]>.
+
+S< >S< >B<*> else C<G> is super-solvable.
+
+S< >S< >B<*> for C<1 E<lt>= i E<lt>= g> the subgroup of C<G> generated by
+C<[s_1,...,s_g]> is normal, with the exception of C<i = g-2> in the
+second case and of C<i = g-3> in the third.
+
+S< >S< >B<*> the relative order C<o_i> of C<s_i> is its order in the
+quotient group C<G/E<lt>s_1,...,s_{i-1}E<gt>>, with the same
+exceptions.
+
+S< >S< >B<*> for any C<x belongs to G> there exists a unique family
+C<[e_1,...,e_g]> such that (no exceptions):
+
+-- for C<1 E<lt>= i E<lt>= g> we have C<0 E<lt>= e_i E<lt> o_i>
+
+-- C<x = g_1^{e_1}g_2^{e_2}...g_n^{e_n}>
+
+If present C<den> must be a suitable value for I<gal>C<[5]>.
+
+X<galoisinit>The library syntax is B<galoisinit>C<(>I<gal>C<,>I<den>C<)>.
+
+=head2 X<galoispermtopol>galoispermtopolC<(>I<gal>C<,>I<perm>C<)>
+
+I<gal> being a
+galois field as output by C<galoisinit> and I<perm> a element of
+I<gal>C<.group>, return the polynomial defining the Galois
+automorphism, as output by C<nfgaloisconj>, associated with the
+permutation I<perm> of the roots I<gal>C<.roots>. I<perm> can
+also be a vector or matrix, in this case, C<galoispermtopol> is
+applied to all components recursively.
+
+Note that
+
+ G = galoisinit(pol);
+ galoispermtopol(G, G[6])~
+
+is equivalent to C<nfgaloisconj(pol)>, if degree of I<pol>
+is greater or equal to C<2>.
+
+X<galoispermtopol>The library syntax is B<galoispermtopol>C<(>I<gal>C<,>I<perm>C<)>.
+
+=head2 X<galoissubcyclo>galoissubcycloC<(n,H,{Z},{v})>
+
+compute a polynomial
+defining the subfield of B<Q>C<(>F<zeta>C<_n)> fixed by the subgroup I<H> of
+B<Z>C</n>B<Z>. The subgroup I<H> can be given by a generator, a set of
+generators given by a vector or a HNF matrix. If present C<Z> must be
+C<znstar(n)>, and is currently only used when I<H> is a HNF matrix. If
+I<v> is given, the polynomial is given in the variable I<v>.
+
+The following function can be used to compute all subfields of
+B<Q>C<(>F<zeta>C<_n)> (of order less than C<d>, if C<d> is set):
+
+ subcyclo(n, d = -1)=
+ {
+ local(Z,G,S);
+ if (d < 0, d = n);
+ Z = znstar(n);
+ G = matdiagonal(Z[2]);
+ S = [];
+ forsubgroup(H = G, d,
+ S = concat(S, galoissubcyclo(n, mathnf(concat(G,H)),Z));
+ );
+ S
+ }
+
+X<galoissubcyclo>The library syntax is B<galoissubcyclo>C<(n,H,Z,v)> where n is a C long integer.
+
+=head2 X<idealadd>idealaddC<(>I<nf>C<,x,y)>
+
+sum of the two ideals C<x> and C<y> in the
+number field I<nf>. When C<x> and C<y> are given by B<Z>-bases, this does
+not depend on I<nf> and can be used to compute the sum of any two
+B<Z>-modules. The result is given in HNF.
+
+X<idealadd>The library syntax is B<idealadd>C<(>I<nf>C<,x,y)>.
+
+=head2 X<idealaddtoone>idealaddtooneC<(>I<nf>C<,x,{y})>
+
+C<x> and C<y> being two co-prime
+integral ideals (given in any form), this gives a two-component row vector
+C<[a,b]> such that C<a belongs to x>, C<b belongs to y> and C<a+b = 1>.
+
+The alternative syntax C<idealaddtoone(>I<nf>C<,v)>, is supported, where
+C<v> is a C<k>-component vector of ideals (given in any form) which sum to
+B<Z>C<_K>. This outputs a C<k>-component vector C<e> such that C<e[i] belongs to x[i]> for
+C<1 E<lt>= i E<lt>= k> and F<sum>C<_{1 E<lt>= i E<lt>= k}e[i] = 1>.
+
+X<idealaddtoone0>The library syntax is B<idealaddtoone0>C<(>I<nf>C<,x,y)>, where an omitted C<y> is coded as
+C<NULL>.
+
+=head2 X<idealappr>idealapprC<(>I<nf>C<,x,{>I<flag>C< = 0})>
+
+if C<x> is a fractional ideal
+(given in any form), gives an element F<alpha> in I<nf> such that for
+all prime ideals B<p> such that the valuation of C<x> at B<p> is non-zero, we
+have C<v_{>B<p>C<}(>F<alpha>C<) = v_{>B<p>C<}(x)>, and. C<v_{>B<p>C<}(>F<alpha>C<) E<gt>= 0> for all other
+C<{>B<p>C<}>.
+
+If I<flag> is non-zero, C<x> must be given as a prime ideal factorization, as
+output by C<idealfactor>, but possibly with zero or negative exponents.
+This yields an element F<alpha> such that for all prime ideals B<p> occurring
+in C<x>, C<v_{>B<p>C<}(>F<alpha>C<)> is equal to the exponent of B<p> in C<x>, and for all
+other prime ideals, C<v_{>B<p>C<}(>F<alpha>C<) E<gt>= 0>. This generalizes
+C<idealappr(>I<nf>C<,x,0)> since zero exponents are allowed. Note that
+the algorithm used is slightly different, so that
+C<idealapp(>I<nf>C<,idealfactor(>I<nf>C<,x))> may not be the same as
+C<idealappr(>I<nf>C<,x,1)>.
+
+X<idealappr0>The library syntax is B<idealappr0>C<(>I<nf>C<,x,>I<flag>C<)>.
+
+=head2 X<idealchinese>idealchineseC<(>I<nf>C<,x,y)>
+
+C<x> being a prime ideal factorization
+(i.e.S< >a 2 by 2 matrix whose first column contain prime ideals, and the second
+column integral exponents), C<y> a vector of elements in I<nf> indexed by
+the ideals in C<x>, computes an element C<b> such that
+
+C<v_>B<p>C<(b - y_>B<p>C<) E<gt>= v_>B<p>C<(x)> for all prime ideals in C<x> and C<v_>B<p>C<(b) E<gt>= 0>
+for all other B<p>.
+
+X<idealchinese>The library syntax is B<idealchinese>C<(>I<nf>C<,x,y)>.
+
+=head2 X<idealcoprime>idealcoprimeC<(>I<nf>C<,x,y)>
+
+given two integral ideals C<x> and C<y>
+in the number field I<nf>, finds a F<beta> in the field, expressed on the
+integral basis I<nf>C<[7]>, such that F<beta>C<.y> is an integral ideal
+coprime to C<x>.
+
+X<idealcoprime>The library syntax is B<idealcoprime>C<(>I<nf>C<,x)>.
+
+=head2 X<idealdiv>idealdivC<(>I<nf>C<,x,y,{>I<flag>C< = 0})>
+
+quotient C<x.y^{-1}> of the
+two ideals C<x> and C<y> in the number field I<nf>. The result is given in
+HNF.
+
+If I<flag> is non-zero, the quotient C<x.y^{-1}> is assumed to be an
+integral ideal. This can be much faster when the norm of the quotient is
+small even though the norms of C<x> and C<y> are large.
+
+X<idealdiv0>The library syntax is B<idealdiv0>C<(>I<nf>C<,x,y,>I<flag>C<)>. Also available
+are X<idealdiv>B<idealdiv>C<(>I<nf>C<,x,y)> (I<flag>C< = 0>) and
+X<idealdivexact>B<idealdivexact>C<(>I<nf>C<,x,y)> (I<flag>C< = 1>).
+
+=head2 X<idealfactor>idealfactorC<(>I<nf>C<,x)>
+
+factors into prime ideal powers the
+ideal C<x> in the number field I<nf>. The output format is similar to the
+C<factor> function, and the prime ideals are represented in the form
+output by the C<idealprimedec> function, i.e.S< >as 5-element vectors.
+
+X<idealfactor>The library syntax is B<idealfactor>C<(>I<nf>C<,x)>.
+
+=head2 X<idealhnf>idealhnfC<(>I<nf>C<,a,{b})>
+
+gives the X<Hermite normal form>Hermite normal form
+matrix of the ideal C<a>. The ideal can be given in any form whatsoever
+(typically by an algebraic number if it is principal, by a B<Z>C<_K>-system of
+generators, as a prime ideal as given by C<idealprimedec>, or by a
+B<Z>-basis).
+
+If C<b> is not omitted, assume the ideal given was C<a>B<Z>C<_K+b>B<Z>C<_K>, where C<a>
+and C<b> are elements of C<K> given either as vectors on the integral basis
+I<nf>C<[7]> or as algebraic numbers.
+
+X<idealhnf0>The library syntax is B<idealhnf0>C<(>I<nf>C<,a,b)> where an omitted C<b> is coded as C<NULL>.
+Also available is X<idealhermite>B<idealhermite>C<(>I<nf>C<,a)> (C<b> omitted).
+
+=head2 X<idealintersect>idealintersectC<(>I<nf>C<,x,y)>
+
+intersection of the two ideals
+C<x> and C<y> in the number field I<nf>. When C<x> and C<y> are given by
+B<Z>-bases, this does not depend on I<nf> and can be used to compute the
+intersection of any two B<Z>-modules. The result is given in HNF.
+
+X<idealintersect>The library syntax is B<idealintersect>C<(>I<nf>C<,x,y)>.
+
+=head2 X<idealinv>idealinvC<(>I<nf>C<,x)>
+
+inverse of the ideal C<x> in the
+number field I<nf>. The result is the Hermite normal form of the inverse
+of the ideal, together with the opposite of the Archimedean information if it
+is given.
+
+X<idealinv>The library syntax is B<idealinv>C<(>I<nf>C<,x)>.
+
+=head2 X<ideallist>ideallistC<(>I<nf>C<,>I<bound>C<,{>I<flag>C< = 4})>
+
+computes the list
+of all ideals of norm less or equal to I<bound> in the number field
+I<nf>. The result is a row vector with exactly I<bound> components.
+Each component is itself a row vector containing the information about
+ideals of a given norm, in no specific order. This information can be
+either the HNF of the ideal or the C<idealstar> with possibly some
+additional information.
+
+If I<flag> is present, its binary digits are toggles meaning
+
+S< >S< >1: give also the generators in the C<idealstar>.
+
+S< >S< >2: output C<[L,U]>, where C<L> is as before and C<U> is a vector of
+C<zinternallog>s of the units.
+
+S< >S< >4: give only the ideals and not the C<idealstar> or the C<ideallog>
+of the units.
+
+X<ideallist0>The library syntax is B<ideallist0>C<(>I<nf>C<,>I<bound>C<,>I<flag>C<)>, where I<bound> must
+be a C long integer. Also available is X<ideallist>B<ideallist>C<(>I<nf>C<,>I<bound>C<)>,
+corresponding to the case I<flag>C< = 0>.
+
+=head2 X<ideallistarch>ideallistarchC<(>I<nf>C<,>I<list>C<,{>I<arch>C< = []},{>I<flag>C< = 0})>
+
+vector of vectors of all C<idealstarinit> (see C<idealstar>) of all
+modules in I<list>, with Archimedean part I<arch> added (void if
+omitted). I<list> is a vector of big ideals, as output by
+C<ideallist>C<(..., >I<flag>C<)> for instance. I<flag> is optional; its binary
+digits are toggles meaning: 1: give generators as well, 2: list format is
+C<[L,U]> (see C<ideallist>).
+
+X<ideallistarch0>The library syntax is B<ideallistarch0>C<(>I<nf>C<,>I<list>C<,>I<arch>C<,>I<flag>C<)>, where an omitted
+I<arch> is coded as C<NULL>.
+
+=head2 X<ideallog>ideallogC<(>I<nf>C<,x,>I<bid>C<)>
+
+I<nf> being a number field,
+I<bid> being a ``big ideal'' as output by C<idealstar> and C<x> being a
+non-necessarily integral element of I<nf> which must have valuation
+equal to 0 at all prime ideals dividing C<I = >I<bid>C<[1]>, computes the
+``discrete logarithm'' of C<x> on the generators given in I<bid>C<[2]>.
+In other words, if C<g_i> are these generators, of orders C<d_i> respectively,
+the result is a column vector of integers C<(x_i)> such that C<0 E<lt>= x_i E<lt> d_i> and
+
+S< >C<x = >F<prod>C<_ig_i^{x_i} (mod ^*I) .>
+
+Note that when C<I> is a module, this implies also sign conditions on the
+embeddings.
+
+X<zideallog>The library syntax is B<zideallog>C<(>I<nf>C<,x,>I<bid>C<)>.
+
+=head2 X<idealmin>idealminC<(>I<nf>C<,x,{>I<vdir>C<})>
+
+computes a minimum of
+the ideal C<x> in the direction I<vdir> in the number field I<nf>.
+
+X<minideal>The library syntax is B<minideal>C<(>I<nf>C<,x,>I<vdir>C<,>I<prec>C<)>, where an omitted
+I<vdir> is coded as C<NULL>.
+
+=head2 X<idealmul>idealmulC<(>I<nf>C<,x,y,{>I<flag>C< = 0})>
+
+ideal multiplication of the
+ideals C<x> and C<y> in the number field I<nf>. The result is a generating
+set for the ideal product with at most C<n> elements, and is in Hermite normal
+form if either C<x> or C<y> is in HNF or is a prime ideal as output by
+C<idealprimedec>, and this is given together with the sum of the
+Archimedean information in C<x> and C<y> if both are given.
+
+If I<flag> is non-zero, reduce the result using C<idealred>.
+
+X<idealmul>The library syntax is B<idealmul>C<(>I<nf>C<,x,y)> (I<flag>C< = 0>) or
+X<idealmulred>B<idealmulred>C<(>I<nf>C<,x,y,>I<prec>C<)> (I<flag>C< ! = 0>), where as usual,
+I<prec> is a C long integer representing the precision.
+
+=head2 X<idealnorm>idealnormC<(>I<nf>C<,x)>
+
+computes the norm of the idealS< >C<x>
+in the number fieldS< >I<nf>.
+
+X<idealnorm>The library syntax is B<idealnorm>C<(>I<nf>C<, x)>.
+
+=head2 X<idealpow>idealpowC<(>I<nf>C<,x,k,{>I<flag>C< = 0})>
+
+computes the C<k>-th power of
+the ideal C<x> in the number field I<nf>. C<k> can be positive, negative
+or zero. The result is NOT reduced, it is really the C<k>-th ideal power, and
+is given in HNF.
+
+If I<flag> is non-zero, reduce the result using C<idealred>. Note however
+that this is NOT the same as as C<idealpow(>I<nf>C<,x,k)> followed by
+reduction, since the reduction is performed throughout the powering process.
+
+The library syntax corresponding to I<flag>C< = 0> is
+X<idealpow>B<idealpow>C<(>I<nf>C<,x,k)>. If C<k> is a C<long>, you can use
+X<idealpows>B<idealpows>C<(>I<nf>C<,x,k)>. Corresponding to I<flag>C< = 1> is
+X<idealpowred>B<idealpowred>C<(>I<nf>C<,vp,k,>I<prec>C<)>, where I<prec> is a
+C<long>.
+
+=head2 X<idealprimedec>idealprimedecC<(>I<nf>C<,p)>
+
+computes the prime ideal
+decomposition of the prime number C<p> in the number field I<nf>. C<p>
+must be a (positive) prime number. Note that the fact that C<p> is prime is
+not checked, so if a non-prime number C<p> is given it may lead to
+unpredictable results.
+
+The result is a vector of 5-component vectors, each representing one of the
+prime ideals above C<p> in the number field I<nf>. The representation
+C<vp = [p,a,e,f,b]> of a prime ideal means the following. The prime ideal is
+equal to C<p>B<Z>C<_K+>F<alpha>B<Z>C<_K> where B<Z>C<_K> is the ring of integers of the field
+and F<alpha>C< = >F<sum>C<_i a_i>F<omega>C<_i> where the F<omega>C<_i> form the integral basis
+I<nf>C<.zk>, C<e> is the ramification index, C<f> is the residual index,
+and C<b> is an C<n>-component column vector representing a F<beta>C< belongs to >B<Z>C<_K> such
+that C<vp^{-1} = >B<Z>C<_K+>F<beta>C</p>B<Z>C<_K> which will be useful for computing
+valuations, but which the user can ignore. The number F<alpha> is guaranteed
+to have a valuation equal to 1 at the prime ideal (this is automatic if
+C<e E<gt> 1>).
+
+X<idealprimedec>The library syntax is B<idealprimedec>C<(>I<nf>C<,p)>.
+
+=head2 X<idealprincipal>idealprincipalC<(>I<nf>C<,x)>
+
+creates the principal ideal
+generated by the algebraic number C<x> (which must be of type integer,
+rational or polmod) in the number field I<nf>. The result is a
+one-column matrix.
+
+X<principalideal>The library syntax is B<principalideal>C<(>I<nf>C<,x)>.
+
+=head2 X<idealred>idealredC<(>I<nf>C<,I,{>I<vdir>C< = 0})>
+
+X<LLL>LLL reduction of
+the ideal C<I> in the number field I<nf>, along the direction I<vdir>.
+If I<vdir> is present, it must be an C<r1+r2>-component vector (C<r1> and
+C<r2> number of real and complex places of I<nf> as usual).
+
+This function finds a ``small'' C<a> in C<I> (it is an LLL pseudo-minimum
+along direction I<vdir>). The result is the X<Hermite normal form>Hermite normal form of
+the LLL-reduced ideal C<r I/a>, where C<r> is a rational number such that the
+resulting ideal is integral and primitive. This is often, but not always, a
+reduced ideal in the sense of X<Buchmann>Buchmann. If C<I> is an idele, the
+logarithmic embeddings of C<a> are subtracted to the Archimedean part.
+
+More often than not, a X<principal ideal>principal ideal will yield the identity
+matrix. This is a quick and dirty way to check if ideals are principal
+without computing a full C<bnf> structure, but it's not a necessary
+condition; hence, a non-trivial result doesn't prove the ideal is
+non-trivial in the class group.
+
+Note that this is I<not> the same as the LLL reduction of the lattice
+C<I> since ideal operations are involved.
+
+X<ideallllred>The library syntax is B<ideallllred>C<(>I<nf>C<,x,>I<vdir>C<,>I<prec>C<)>, where an omitted
+I<vdir> is coded as C<NULL>.
+
+=head2 X<idealstar>idealstarC<(>I<nf>C<,I,{>I<flag>C< = 1})>
+
+I<nf> being a number
+field, and C<I>
+either and ideal in any form, or a row vector whose first component is an
+ideal and whose second component is a row vector of C<r_1> 0 or 1, outputs
+necessary data for computing in the group C<(>B<Z>C<_K/I)^*>.
+
+If I<flag>C< = 2>, the result is a 5-component vector C<w>. C<w[1]> is the ideal
+or module C<I> itself. C<w[2]> is the structure of the group. The other
+components are difficult to describe and are used only in conjunction with
+the function C<ideallog>.
+
+If I<flag>C< = 1> (default), as I<flag>C< = 2>, but do not compute explicit generators
+for the cyclic components, which saves time.
+
+If I<flag>C< = 0>, computes the structure of C<(>B<Z>C<_K/I)^*> as a 3-component vector
+C<v>. C<v[1]> is the order, C<v[2]> is the vector of SNFX<Smith normal form>
+cyclic components and
+C<v[3]> the corresponding generators. When the row vector is explicitly
+included, the
+non-zero elements of this vector are considered as real embeddings of
+I<nf> in the order given by C<polroots>, i.e.S< >in I<nf>[6]
+(I<nf>C<.roots>), and then C<I> is a module with components at infinity.
+
+To solve discrete logarithms (using C<ideallog>), you have to choose
+I<flag>C< = 2>.
+
+X<idealstar0>The library syntax is B<idealstar0>C<(>I<nf>C<,I,>I<flag>C<)>.
+
+=head2 X<idealtwoelt>idealtwoeltC<(>I<nf>C<,x,{a})>
+
+computes a two-element
+representation of the ideal C<x> in the number field I<nf>, using a
+straightforward (exponential time) search. C<x> can be an ideal in any form,
+(including perhaps an Archimedean part, which is ignored) and the result is a
+row vector C<[a,>F<alpha>C<]> with two components such that C<x = a>B<Z>C<_K+>F<alpha>B<Z>C<_K>
+and C<a belongs to >B<Z>, where C<a> is the one passed as argument if any. If C<x> is given
+by at least two generators, C<a> is chosen to be the positive generator of
+C<x> F<cap> B<Z>.
+
+Note that when an explicit C<a> is given, we use an asymptotically faster
+method, however in practice it is usually slower.
+
+X<ideal_two_elt0>The library syntax is B<ideal_two_elt0>C<(>I<nf>C<,x,a)>, where an omitted C<a> is entered as
+C<NULL>.
+
+=head2 X<idealval>idealvalC<(>I<nf>C<,x,>I<vp>C<)>
+
+gives the valuation of the
+ideal C<x> at the prime ideal I<vp> in the number field I<nf>,
+where I<vp> must be a
+5-component vector as given by C<idealprimedec>.
+
+X<idealval>The library syntax is B<idealval>C<(>I<nf>C<,x,>I<vp>C<)>, and the result is a C<long>
+integer.
+
+=head2 X<ideleprincipal>ideleprincipalC<(>I<nf>C<,x)>
+
+creates the principal idele
+generated by the algebraic number C<x> (which must be of type integer,
+rational or polmod) in the number field I<nf>. The result is a
+two-component vector, the first being a one-column matrix representing the
+corresponding principal ideal, and the second being the vector with C<r_1+r_2>
+components giving the complex logarithmic embedding of C<x>.
+
+X<principalidele>The library syntax is B<principalidele>C<(>I<nf>C<,x)>.
+
+=head2 X<matalgtobasis>matalgtobasisC<(>I<nf>C<,x)>
+
+I<nf> being a number field in
+C<nfinit> format, and C<x> a matrix whose coefficients are expressed as
+polmods in I<nf>, transforms this matrix into a matrix whose
+coefficients are expressed on the integral basis of I<nf>. This is the
+same as applying C<nfalgtobasis> to each entry, but it would be dangerous
+to use the same name.
+
+X<matalgtobasis>The library syntax is B<matalgtobasis>C<(>I<nf>C<,x)>.
+
+=head2 X<matbasistoalg>matbasistoalgC<(>I<nf>C<,x)>
+
+I<nf> being a number field in
+C<nfinit> format, and C<x> a matrix whose coefficients are expressed as
+column vectors on the integral basis of I<nf>, transforms this matrix
+into a matrix whose coefficients are algebraic numbers expressed as
+polmods. This is the same as applying C<nfbasistoalg> to each entry, but
+it would be dangerous to use the same name.
+
+X<matbasistoalg>The library syntax is B<matbasistoalg>C<(>I<nf>C<,x)>.
+
+=head2 X<modreverse>modreverseC<(a)>
+
+C<a> being a polmod C<A(X)> modulo C<T(X)>, finds
+the ``reverse polmod'' C<B(X)> modulo C<Q(X)>, where C<Q> is the minimal
+polynomial of C<a>, which must be equal to the degree of C<T>, and such that if
+F<theta> is a root of C<T> then F<theta>C< = B(>F<alpha>C<)> for a certain root F<alpha>
+of C<Q>.
+
+This is very useful when one changes the generating element in algebraic
+extensions.
+
+X<polmodrecip>The library syntax is B<polmodrecip>C<(x)>.
+
+=head2 X<newtonpoly>newtonpolyC<(x,p)>
+
+gives the vector of the slopes of the Newton
+polygon of the polynomial C<x> with respect to the prime number C<p>. The C<n>
+components of the vector are in decreasing order, where C<n> is equal to the
+degree of C<x>. Vertical slopes occur iff the constant coefficient of C<x> is
+zero and are denoted by C<VERYBIGINT>, the biggest single precision
+integer representable on the machine (C<2^{31}-1> (resp.S< >C<2^{63}-1>) on 32-bit
+(resp.S< >64-bit) machines), see L<Label se:valuation>.
+
+X<newtonpoly>The library syntax is B<newtonpoly>C<(x,p)>.
+
+=head2 X<nfalgtobasis>nfalgtobasisC<(>I<nf>C<,x)>
+
+this is the inverse function of
+C<nfbasistoalg>. Given an object C<x> whose entries are expressed as
+algebraic numbers in the number field I<nf>, transforms it so that the
+entries are expressed as a column vector on the integral basis
+I<nf>C<.zk>.
+
+X<algtobasis>The library syntax is B<algtobasis>C<(>I<nf>C<,x)>.
+
+=head2 X<nfbasis>nfbasisC<(x,{>I<flag>C< = 0},{p})>
+
+X<integral basis>integral basis of the number
+field defined by the irreducible, preferably monic, polynomial C<x>,
+using a modified version of the X<round 4>round 4 algorithm by
+default. The binary digits of I<flag> have the following meaning:
+
+1: assume that no square of a prime greater than the default C<primelimit>
+divides the discriminant of C<x>, i.e.S< >that the index of C<x> has only small
+prime divisors.
+
+2: use X<round 2>round 2 algorithm. For small degrees and coefficient size, this is
+sometimes a little faster. (This program is the translation into C of a program
+written by David X<Ford>Ford in Algeb.)
+
+Thus for instance, if I<flag>C< = 3>, this uses the round 2 algorithm and outputs
+an order which will be maximal at all the small primes.
+
+If C<p> is present, we assume (without checking!) that it is the two-column
+matrix of the factorization of the discriminant of the polynomial C<x>. Note
+that it does I<not> have to be a complete factorization. This is
+especially useful if only a local integral basis for some small set of places
+is desired: only factors with exponents greater or equal to 2 will be
+considered.
+
+X<nfbasis0>The library syntax is B<nfbasis0>C<(x,>I<flag>C<,p)>. An extended version
+is X<nfbasis>B<nfbasis>C<(x,&d,>I<flag>C<,p)>, where C<d> will receive the discriminant of
+the number field (I<not> of the polynomial C<x>), and an omitted C<p> should
+be input as C<gzero>. Also available are X<base>B<base>C<(x,&d)> (I<flag>C< = 0>),
+X<base2>B<base2>C<(x,&d)> (I<flag>C< = 2>) and X<factoredbase>B<factoredbase>C<(x,p,&d)>.
+
+=head2 X<nfbasistoalg>nfbasistoalgC<(>I<nf>C<,x)>
+
+this is the inverse function of
+C<nfalgtobasis>. Given an object C<x> whose entries are expressed on the
+integral basis I<nf>C<.zk>, transforms it into an object whose entries
+are algebraic numbers (i.e.S< >polmods).
+
+X<basistoalg>The library syntax is B<basistoalg>C<(>I<nf>C<,x)>.
+
+=head2 X<nfdetint>nfdetintC<(>I<nf>C<,x)>
+
+given a pseudo-matrix C<x>, computes a
+non-zero ideal contained in (i.e.S< >multiple of) the determinant of C<x>. This
+is particularly useful in conjunction with C<nfhnfmod>.
+
+X<nfdetint>The library syntax is B<nfdetint>C<(>I<nf>C<,x)>.
+
+=head2 X<nfdisc>nfdiscC<(x,{>I<flag>C< = 0},{p})>
+
+X<field discriminant>field discriminant of the
+number field defined by the integral, preferably monic, irreducible
+polynomial C<x>. I<flag> and C<p> are exactly as in C<nfbasis>. That is, C<p>
+provides the matrix of a partial factorization of the discriminant of C<x>,
+and binary digits of I<flag> are as follows:
+
+1: assume that no square of a prime greater than C<primelimit>
+divides the discriminant.
+
+2: use the round 2 algorithm, instead of the default X<round 4>round 4.
+This should be
+slower except maybe for polynomials of small degree and coefficients.
+
+X<nfdiscf0>The library syntax is B<nfdiscf0>C<(x,>I<flag>C<,p)> where, to omit C<p>, you should input C<gzero>. You
+can also use X<discf>B<discf>C<(x)> (I<flag>C< = 0>).
+
+=head2 X<nfeltdiv>nfeltdivC<(>I<nf>C<,x,y)>
+
+given two elements C<x> and C<y> in
+I<nf>, computes their quotient C<x/y> in the number field I<nf>.
+
+X<element_div>The library syntax is B<element_div>C<(>I<nf>C<,x,y)>.
+
+=head2 X<nfeltdiveuc>nfeltdiveucC<(>I<nf>C<,x,y)>
+
+given two elements C<x> and C<y> in
+I<nf>, computes an algebraic integer C<q> in the number field I<nf>
+such that the components of C<x-qy> are reasonably small. In fact, this is
+functionally identical to C<round(nfeltdiv(>I<nf>C<,x,y))>.
+
+X<nfdiveuc>The library syntax is B<nfdiveuc>C<(>I<nf>C<,x,y)>.
+
+=head2 X<nfeltdivmodpr>nfeltdivmodprC<(>I<nf>C<,x,y,>I<pr>C<)>
+
+given two elements C<x>
+and C<y> in I<nf> and I<pr> a prime ideal in C<modpr> format (see
+X<nfmodprinit>C<nfmodprinit>), computes their quotient C<x / y> modulo the prime ideal
+I<pr>.
+
+X<element_divmodpr>The library syntax is B<element_divmodpr>C<(>I<nf>C<,x,y,>I<pr>C<)>.
+
+=head2 X<nfeltdivrem>nfeltdivremC<(>I<nf>C<,x,y)>
+
+given two elements C<x> and C<y> in
+I<nf>, gives a two-element row vector C<[q,r]> such that C<x = qy+r>, C<q> is
+an algebraic integer in I<nf>, and the components of C<r> are
+reasonably small.
+
+X<nfdivres>The library syntax is B<nfdivres>C<(>I<nf>C<,x,y)>.
+
+=head2 X<nfeltmod>nfeltmodC<(>I<nf>C<,x,y)>
+
+given two elements C<x> and C<y> in
+I<nf>, computes an element C<r> of I<nf> of the form C<r = x-qy> with
+C<q> and algebraic integer, and such that C<r> is small. This is functionally
+identical to
+
+S< >C<x - nfeltmul(>I<nf>C<,round(nfeltdiv(>I<nf>C<,x,y)),y).>
+
+X<nfmod>The library syntax is B<nfmod>C<(>I<nf>C<,x,y)>.
+
+=head2 X<nfeltmul>nfeltmulC<(>I<nf>C<,x,y)>
+
+given two elements C<x> and C<y> in
+I<nf>, computes their product C<x*y> in the number field I<nf>.
+
+X<element_mul>The library syntax is B<element_mul>C<(>I<nf>C<,x,y)>.
+
+=head2 X<nfeltmulmodpr>nfeltmulmodprC<(>I<nf>C<,x,y,>I<pr>C<)>
+
+given two elements C<x> and
+C<y> in I<nf> and I<pr> a prime ideal in C<modpr> format (see
+X<nfmodprinit>C<nfmodprinit>), computes their product C<x*y> modulo the prime ideal
+I<pr>.
+
+X<element_mulmodpr>The library syntax is B<element_mulmodpr>C<(>I<nf>C<,x,y,>I<pr>C<)>.
+
+=head2 X<nfeltpow>nfeltpowC<(>I<nf>C<,x,k)>
+
+given an element C<x> in I<nf>,
+and a positive or negative integer C<k>, computes C<x^k> in the number field
+I<nf>.
+
+X<element_pow>The library syntax is B<element_pow>C<(>I<nf>C<,x,k)>.
+
+=head2 X<nfeltpowmodpr>nfeltpowmodprC<(>I<nf>C<,x,k,>I<pr>C<)>
+
+given an element C<x> in
+I<nf>, an integer C<k> and a prime ideal I<pr> in C<modpr> format
+(see X<nfmodprinit>C<nfmodprinit>), computes C<x^k> modulo the prime ideal I<pr>.
+
+X<element_powmodpr>The library syntax is B<element_powmodpr>C<(>I<nf>C<,x,k,>I<pr>C<)>.
+
+=head2 X<nfeltreduce>nfeltreduceC<(>I<nf>C<,x,>I<ideal>C<)>
+
+given an ideal in
+Hermite normal form and an element C<x> of the number field I<nf>,
+finds an element C<r> in I<nf> such that C<x-r> belongs to the ideal
+and C<r> is small.
+
+X<element_reduce>The library syntax is B<element_reduce>C<(>I<nf>C<,x,>I<ideal>C<)>.
+
+=head2 X<nfeltreducemodpr>nfeltreducemodprC<(>I<nf>C<,x,>I<pr>C<)>
+
+given
+an element C<x> of the number field I<nf> and a prime ideal I<pr> in
+C<modpr> format compute a canonical representative for the class of C<x>
+modulo I<pr>.
+
+X<nfreducemodpr2>The library syntax is B<nfreducemodpr2>C<(>I<nf>C<,x,>I<pr>C<)>.
+
+=head2 X<nfeltval>nfeltvalC<(>I<nf>C<,x,>I<pr>C<)>
+
+given an element C<x> in
+I<nf> and a prime ideal I<pr> in the format output by
+C<idealprimedec>, computes their the valuation at I<pr> of the
+element C<x>. The same result could be obtained using
+C<idealval(>I<nf>C<,x,>I<pr>C<)> (since C<x> would then be converted to a
+principal ideal), but it would be less efficient.
+
+X<element_val>The library syntax is B<element_val>C<(>I<nf>C<,x,>I<pr>C<)>, and the result is a C<long>.
+
+=head2 X<nffactor>nffactorC<(>I<nf>C<,x)>
+
+factorization of the univariate
+polynomial C<x> over the number field I<nf> given by C<nfinit>. C<x>
+has coefficients in I<nf> (i.e.S< >either scalar, polmod, polynomial or
+column vector). The main variable of I<nf> must be of I<lower>
+priority than that of C<x> (in other words, the variable number of I<nf>
+must be I<greater> than that of C<x>). However if the polynomial defining
+the number field occurs explicitly in the coefficients of C<x> (as modulus of
+a C<t_POLMOD>), its main variable must be I<the same> as the main
+variable of C<x>. For example,
+
+ ? nf = nfinit(y^2 + 1);
+ ? nffactor(nf, x^2 + y); \\ OK
+ ? nffactor(nf, x^2 + Mod(y, y^2+1)); \\ OK
+ ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ WRONG
+
+X<nffactor>The library syntax is B<nffactor>C<(>I<nf>C<,x)>.
+
+=head2 X<nffactormod>nffactormodC<(>I<nf>C<,x,>I<pr>C<)>
+
+factorization of the
+univariate polynomial C<x> modulo the prime ideal I<pr> in the number
+field I<nf>. C<x> can have coefficients in the number field (scalar,
+polmod, polynomial, column vector) or modulo the prime ideal (integermod
+modulo the rational prime under I<pr>, polmod or polynomial with
+integermod coefficients, column vector of integermod). The prime ideal
+I<pr> I<must> be in the format output by C<idealprimedec>. The
+main variable of I<nf> must be of lower priority than that of C<x> (in
+other words the variable number of I<nf> must be greater than that of
+C<x>). However if the coefficients of the number field occur explicitly (as
+polmods) as coefficients of C<x>, the variable of these polmods I<must>
+be the same as the main variable of C<t> (see C<nffactor>).
+
+X<nffactormod>The library syntax is B<nffactormod>C<(>I<nf>C<,x,>I<pr>C<)>.
+
+=head2 X<nfgaloisapply>nfgaloisapplyC<(>I<nf>C<,>I<aut>C<,x)>
+
+I<nf> being a
+number field as output by C<nfinit>, and I<aut> being a X<Galois>Galois
+automorphism of I<nf> expressed either as a polynomial or a polmod
+(such automorphisms being found using for example one of the variants of
+C<nfgaloisconj>), computes the action of the automorphism I<aut> on
+the object C<x> in the number field. C<x> can be an element (scalar, polmod,
+polynomial or column vector) of the number field, an ideal (either given by
+B<Z>C<_K>-generators or by a B<Z>-basis), a prime ideal (given as a 5-element
+row vector) or an idele (given as a 2-element row vector). Because of
+possible confusion with elements and ideals, other vector or matrix
+arguments are forbidden.
+
+X<galoisapply>The library syntax is B<galoisapply>C<(>I<nf>C<,>I<aut>C<,x)>.
+
+=head2 X<nfgaloisconj>nfgaloisconjC<(>I<nf>C<,{>I<flag>C< = 0},{d})>
+
+I<nf> being a
+number field as output by C<nfinit>, computes the conjugates of a root
+C<r> of the non-constant polynomial C<x = >I<nf>C<[1]> expressed as
+polynomials in C<r>. This can be used even if the number field I<nf> is
+not X<Galois>Galois since some conjugates may lie in the field. As a note to
+old-timers of PARI, starting with version 2.0.17 this function works much
+better than in earlier versions.
+
+I<nf> can simply be a polynomial if I<flag>C< ! = 1>.
+
+If no flags or I<flag>C< = 0>, if I<nf> is a number field use a
+combination of flag C<4> and C<1> and the result is always complete,
+else use a combination of flag C<4> and C<2> and the result is subject
+to the restriction of I<flag>C< = 2>, but a warning is issued when it is not
+proven complete.
+
+If I<flag>C< = 1>, use C<nfroots> (require a number field).
+
+If I<flag>C< = 2>, use complex approximations to the roots and an integral
+X<LLL>LLL. The result is not guaranteed to be complete: some
+conjugates may be missing (no warning issued), especially so if the
+corresponding polynomial has a huge index. In that case, increasing
+the default precision may help.
+
+If I<flag>C< = 4>, use Allombert's algorithm and permutation testing. If the
+field is Galois with ``weakly'' super solvable Galois group, return
+the complete list of automorphisms, else only the identity element. If
+present, C<d> is assumed to be a multiple of the least common
+denominator of the conjugates expressed as polynomial in a root of
+I<pol>.
+
+A group G is ``weakly'' super solvable if it contains a super solvable
+normal subgroup C<H> such that C<G = H> , or C<G/H ~ A_4> , or C<G/H ~
+S_4>. Abelian and nilpotent groups are ``weakly'' super solvable. In
+practice, almost all groups of small order are ``weakly'' super solvable, the
+exceptions having order 36(1 exception), 48(2), 56(1), 60(1), 72(5), 75(1),
+80(1), 96(10) and C< E<gt>= 108>.
+
+Hence I<flag>C< = 4> permits to quickly check whether a polynomial of order
+strictly less than C<36> is Galois or not. This method is much faster than
+C<nfroots> and can be applied to polynomials of degree larger than C<50>.
+
+X<galoisconj0>The library syntax is B<galoisconj0>C<(>I<nf>C<,>I<flag>C<,d,>I<prec>C<)>. Also available are
+X<galoisconj>B<galoisconj>C<(>I<nf>C<)> for I<flag>C< = 0>,
+X<galoisconj2>B<galoisconj2>C<(>I<nf>C<,n,>I<prec>C<)> for I<flag>C< = 2> where C<n> is a bound
+on the number of conjugates, and X<galoisconj4>B<galoisconj4>C<(>I<nf>C<,d)>
+corresponding to I<flag>C< = 4>.
+
+=head2 X<nfhilbert>nfhilbertC<(>I<nf>C<,a,b,{>I<pr>C<})>
+
+if I<pr> is omitted,
+compute the global X<Hilbert symbol>Hilbert symbol C<(a,b)> in I<nf>, that is C<1>
+if C<x^2 - a y^2 - b z^2> has a non trivial solution C<(x,y,z)> in I<nf>,
+and C<-1> otherwise. Otherwise compute the local symbol modulo the prime ideal
+I<pr> (as output by C<idealprimedec>).
+
+X<nfhilbert>The library syntax is B<nfhilbert>C<(>I<nf>C<,a,b,>I<pr>C<)>, where an omitted I<pr> is coded
+as C<NULL>.
+
+=head2 X<nfhnf>nfhnfC<(>I<nf>C<,x)>
+
+given a pseudo-matrix C<(A,I)>, finds a
+pseudo-basis in X<Hermite normal form>Hermite normal form of the module it generates.
+
+X<nfhermite>The library syntax is B<nfhermite>C<(>I<nf>C<,x)>.
+
+=head2 X<nfhnfmod>nfhnfmodC<(>I<nf>C<,x,>I<detx>C<)>
+
+given a pseudo-matrix C<(A,I)>
+and an ideal I<detx> which is contained in (read integral multiple of) the
+determinant of C<(A,I)>, finds a pseudo-basis in X<Hermite normal form>Hermite normal form
+of the module generated by C<(A,I)>. This avoids coefficient explosion.
+I<detx> can be computed using the function C<nfdetint>.
+
+X<nfhermitemod>The library syntax is B<nfhermitemod>C<(>I<nf>C<,x,>I<detx>C<)>.
+
+=head2 X<nfinit>nfinitC<(>I<pol>C<,{>I<flag>C< = 0})>
+
+I<pol> being a non-constant,
+preferably monic, irreducible polynomial in B<Z>C<[X]>, initializes a
+I<number field> structure (C<nf>) associated to the field C<K> defined
+by I<pol>. As such, it's a technical object passed as the first argument
+to most C<nf>I<xxx> functions, but it contains some information which
+may be directly useful. Access to this information via I<member
+functions> is prefered since the specific data organization specified below
+may change in the future. Currently, C<nf> is a row vector with 9
+components:
+
+I<nf>C<[1]> contains the polynomial I<pol> (I<nf>C<.pol>).
+
+I<nf>C<[2]> contains C<[r1,r2]> (I<nf>C<.sign>), the number of real
+and complex places of C<K>.
+
+I<nf>C<[3]> contains the discriminant C<d(K)> (I<nf>C<.disc>) of C<K>.
+
+I<nf>C<[4]> contains the index of I<nf>C<[1]>,
+i.e.S< >C<[>B<Z>C<_K : >B<Z>C<[>F<theta>C<]]>, where F<theta> is any root of I<nf>C<[1]>.
+
+I<nf>C<[5]> is a vector containing 7 matrices C<M>, C<MC>, C<T2>, C<T>,
+C<MD>, C<TI>, C<MDI> useful for certain computations in the number field C<K>.
+
+S< >S< >B<*> C<M> is the C<(r1+r2) x n> matrix whose columns represent
+the numerical values of the conjugates of the elements of the integral
+basis.
+
+S< >S< >B<*> C<MC> is essentially the conjugate of the transpose of C<M>,
+except that the last C<r2> columns are also multiplied by 2.
+
+S< >S< >B<*> C<T2> is an C<n x n> matrix equal to the real part of the
+product C<MC.M> (which is a real positive definite symmetric matrix), the
+so-called C<T_2>-matrix (I<nf>C<.t2>).
+
+S< >S< >B<*> C<T> is the C<n x n> matrix whose coefficients are
+C<Tr(>F<omega>C<_i>F<omega>C<_j)> where the F<omega>C<_i> are the elements of the
+integral basis. Note that C<T = \overline{MC}.M> and in particular that
+C<T = T_2> if the field is totally real (in practice C<T_2> will have real
+approximate entries and C<T> will have integer entries). Note also that
+ F<det> C<(T)> is equal to the discriminant of the field C<K>.
+
+S< >S< >B<*> The columns of C<MD> (I<nf>C<.diff>) express a B<Z>-basis
+of the different of C<K> on the integral basis.
+
+S< >S< >B<*> C<TI> is equal to C<d(K)T^{-1}>, which has integral
+coefficients. Note that, understood as as ideal, the matrix C<T^{-1}>
+generates the codifferent ideal.
+
+S< >S< >B<*> Finally, C<MDI> is a two-element representation (for faster
+ideal product) of C<d(K)> times the codifferent ideal
+(I<nf>C<.disc*>I<nf>C<.codiff>, which is an integral ideal). C<MDI>
+is only used in X<idealinv>C<idealinv>.
+
+I<nf>C<[6]> is the vector containing the C<r1+r2> roots
+(I<nf>C<.roots>) of I<nf>C<[1]> corresponding to the C<r1+r2>
+embeddings of the number field into B<C> (the first C<r1> components are real,
+the next C<r2> have positive imaginary part).
+
+I<nf>C<[7]> is an integral basis in Hermite normal form for B<Z>C<_K>
+(I<nf>C<.zk>) expressed on the powers ofS< >F<theta>.
+
+I<nf>C<[8]> is the C<n x n> integral matrix expressing the power
+basis in terms of the integral basis, and finally
+
+I<nf>C<[9]> is the C<n x n^2> matrix giving the multiplication table
+of the integral basis.
+
+If a non monic polynomial is input, C<nfinit> will transform it into a
+monic one, then reduce it (see I<flag>C< = 3>). It is allowed, though not very
+useful given the existence of X<nfnewprec>B<nfnewprec>, to input a C<nf> or a
+C<bnf> instead of a polynomial.
+
+The special input format C<[x,B]> is also accepted where C<x> is a polynomial
+as above and C<B> is the integer basis, as computed by X<nfbasis>C<nfbasis>. This can
+be useful since C<nfinit> uses the round 4 algorithm by default, which can
+be very slow in pathological cases where round 2 (C<nfbasis(x,2)>) would
+succeed very quickly.
+
+If I<flag>C< = 2>: I<pol> is changed into another polynomial C<P> defining the same
+number field, which is as simple as can easily be found using the
+C<polred> algorithm, and all the subsequent computations are done using
+this new polynomial. In particular, the first component of the result is the
+modified polynomial.
+
+If I<flag>C< = 3>, does a C<polred> as in case 2, but outputs
+C<[>I<nf>C<,Mod(a,P)]>, where I<nf> is as before and
+C<Mod(a,P) = Mod(x,>I<pol>C<)> gives the change of
+variables. This is implicit when I<pol> is not monic: first a linear change
+of variables is performed, to get a monic polynomial, then a C<polred>
+reduction.
+
+If I<flag>C< = 4>, as C<2> but uses a partial C<polred>.
+
+If I<flag>C< = 5>, as C<3> using a partial C<polred>.
+
+X<nfinit0>The library syntax is B<nfinit0>C<(x,>I<flag>C<,>I<prec>C<)>.
+
+=head2 X<nfisideal>nfisidealC<(>I<nf>C<,x)>
+
+returns 1 if C<x> is an ideal in
+the number field I<nf>, 0 otherwise.
+
+X<isideal>The library syntax is B<isideal>C<(x)>.
+
+=head2 X<nfisincl>nfisinclC<(x,y)>
+
+tests whether the number field C<K> defined
+by the polynomial C<x> is conjugate to a subfield of the field C<L> defined
+by C<y> (where C<x> and C<y> must be in B<Q>C<[X]>). If they are not, the output
+is the number 0. If they are, the output is a vector of polynomials, each
+polynomial C<a> representing an embedding of C<K> into C<L>, i.e.S< >being such
+that C<y | x o a>.
+
+If C<y> is a number field (I<nf>), a much faster algorithm is used
+(factoring C<x> over C<y> using X<nffactor>C<nffactor>). Before version 2.0.14, this
+wasn't guaranteed to return all the embeddings, hence was triggered by a
+special flag. This is no more the case.
+
+X<nfisincl>The library syntax is B<nfisincl>C<(x,y,>I<flag>C<)>.
+
+=head2 X<nfisisom>nfisisomC<(x,y)>
+
+as X<nfisincl>C<nfisincl>, but tests
+for isomorphism. If either C<x> or C<y> is a number field, a much faster
+algorithm will be used.
+
+X<nfisisom>The library syntax is B<nfisisom>C<(x,y,>I<flag>C<)>.
+
+=head2 X<nfnewprec>nfnewprecC<(>I<nf>C<)>
+
+transforms the number field I<nf>
+into the corresponding data using current (usually larger) precision. This
+function works as expected if I<nf> is in fact a I<bnf> (update
+I<bnf> to current precision) but may be quite slow (many generators of
+principal ideals have to be computed).
+
+X<nfnewprec>The library syntax is B<nfnewprec>C<(>I<nf>C<,>I<prec>C<)>.
+
+=head2 X<nfkermodpr>nfkermodprC<(>I<nf>C<,a,>I<pr>C<)>
+
+kernel of the matrix C<a> in
+B<Z>C<_K/>I<pr>, where I<pr> is in B<modpr> format
+(see C<nfmodprinit>).
+
+X<nfkermodpr>The library syntax is B<nfkermodpr>C<(>I<nf>C<,a,>I<pr>C<)>.
+
+=head2 X<nfmodprinit>nfmodprinitC<(>I<nf>C<,>I<pr>C<)>
+
+transforms the prime ideal
+I<pr> into X<modpr>C<modpr> format necessary for all operations modulo
+I<pr> in the number field I<nf>. Returns a two-component vector
+C<[P,a]>, where C<P> is the X<Hermite normal form>Hermite normal form of I<pr>, and C<a> is
+an integral element congruent to C<1> modulo I<pr>, and congruent to C<0>
+modulo C<p / pr^e>. Here C<p = >B<Z> F<cap> I<pr> and C<e>
+is the absolute ramification index.X<Label se:nfmodprinit>
+
+X<nfmodprinit>The library syntax is B<nfmodprinit>C<(>I<nf>C<,>I<pr>C<)>.
+
+=head2 X<nfsubfields>nfsubfieldsC<(>I<nf>C<,{d = 0})>
+
+finds all subfields of degree C<d>
+of the number field I<nf> (all subfields if C<d> is null or omitted).
+The result is a vector of subfields, each being given by C<[g,h]>, where C<g> is an
+absolute equation and C<h> expresses one of the roots of C<g> in terms of the
+root C<x> of the polynomial defining I<nf>. This is a crude
+implementation by M.S< >Olivier of an algorithm due to J.S< >KlE<uuml>ners.
+
+X<subfields>The library syntax is B<subfields>C<(>I<nf>C<,d)>.
+
+=head2 X<nfroots>nfrootsC<(>I<nf>C<,x)>
+
+roots of the polynomial C<x> in the number
+field I<nf> given by C<nfinit> without multiplicity. C<x> has
+coefficients in the number field (scalar, polmod, polynomial, column
+vector). The main variable of I<nf> must be of lower priority than that
+of C<x> (in other words the variable number of I<nf> must be greater than
+that of C<x>). However if the coefficients of the number field occur
+explicitly (as polmods) as coefficients of C<x>, the variable of these
+polmods I<must> be the same as the main variable of C<t> (see
+C<nffactor>).
+
+X<nfroots>The library syntax is B<nfroots>C<(>I<nf>C<,x)>.
+
+=head2 X<nfrootsof1>nfrootsof1C<(>I<nf>C<)>
+
+computes the number of roots of unity
+C<w> and a primitive C<w>-th root of unity (expressed on the integral basis)
+belonging to the number field I<nf>. The result is a two-component
+vector C<[w,z]> where C<z> is a column vector expressing a primitive C<w>-th
+root of unity on the integral basis I<nf>C<.zk>.
+
+X<rootsof1>The library syntax is B<rootsof1>C<(>I<nf>C<)>.
+
+=head2 X<nfsnf>nfsnfC<(>I<nf>C<,x)>
+
+given a torsion module C<x> as a 3-component
+row
+vector C<[A,I,J]> where C<A> is a square invertible C<n x n> matrix, C<I> and
+C<J> are two ideal lists, outputs an ideal list C<d_1,...,d_n> which is the
+X<Smith normal form>Smith normal form of C<x>. In other words, C<x> is isomorphic to
+B<Z>C<_K/d_1> F<oplus> C<...> F<oplus> B<Z>C<_K/d_n> and C<d_i> divides C<d_{i-1}> for C<i E<gt>= 2>.
+The link between C<x> and C<[A,I,J]> is as follows: if C<e_i> is the canonical
+basis of C<K^n>, C<I = [b_1,...,b_n]> and C<J = [a_1,...,a_n]>, then C<x> is
+isomorphic to
+
+S< >C< (b_1e_1> F<oplus> C<...> F<oplus> C< b_ne_n) / (a_1A_1> F<oplus> C<...> F<oplus> C< a_nA_n)
+ , >
+
+where the C<A_j> are the columns of the matrix C<A>. Note that every finitely
+generated torsion module can be given in this way, and even with C<b_i = Z_K>
+for all C<i>.
+
+X<nfsmith>The library syntax is B<nfsmith>C<(>I<nf>C<,x)>.
+
+=head2 X<nfsolvemodpr>nfsolvemodprC<(>I<nf>C<,a,b,>I<pr>C<)>
+
+solution of C<a.x = b>
+in B<Z>C<_K/>I<pr>, where C<a> is a matrix and C<b> a column vector, and where
+I<pr> is in B<modpr> format (see C<nfmodprinit>).
+
+X<nfsolvemodpr>The library syntax is B<nfsolvemodpr>C<(>I<nf>C<,a,b,>I<pr>C<)>.
+
+=head2 X<polcompositum>polcompositumC<(x,y,{>I<flag>C< = 0})>
+
+C<x> and C<y> being polynomials
+in B<Z>C<[X]> in the same variable, outputs a vector giving the list of all
+possible composita of the number fields defined by C<x> and C<y>, if C<x> and
+C<y> are irreducible, or of the corresponding E<eacute>tale algebras, if they are
+only squarefree. Returns an error if one of the polynomials is not
+squarefree. When one of the polynomials is irreducible (say C<x>), it is
+often I<much> faster to use C<nffactor(nfinit(x), y)> then
+X<rnfequation>C<rnfequation>.
+
+If I<flag>C< = 1>, outputs a vector of 4-component vectors C<[z,a,b,k]>, where C<z>
+ranges through the list of all possible compositums as above, and C<a>
+(resp. C<b>) expresses the root of C<x> (resp. C<y>) as a polmod in a root of
+C<z>, and C<k> is a small integer k such that C<a+kb> is the chosen root of
+C<z>.
+
+The compositum will quite often be defined by a complicated polynomial,
+which it is advisable to reduce before further work. Here is a simple
+example involving the field B<Q>C<(>F<zeta>C<_5, 5^{1/5})>:
+
+ ? z = polcompositum(x^5 - 5, polcyclo(5), 1)[1];
+ ? pol = z[1] \\ pol defines the compositum
+ %2 = x^20 + 5*x^19 + 15*x^18 + 35*x^17 + 70*x^16 + 141*x^15 + 260*x^14 \
+ + 355*x^13 + 95*x^12 - 1460*x^11 - 3279*x^10 - 3660*x^9 - 2005*x^8 \
+ + 705*x^7 + 9210*x^6 + 13506*x^5 + 7145*x^4 - 2740*x^3 + 1040*x^2 \
+ - 320*x + 256
+ ? a = z[2]; a^5 - 5 \\ a is a fifth root of 5
+ %3 = 0
+ ? z = polredabs(pol, 1); \\ look for a simpler polynomial
+ ? pol = z[1]
+ %5 = x^20 + 25*x^10 + 5
+ ? a = subst(a.pol, x, z[2]) \\ a in the new coordinates
+ %6 = Mod(-5/22*x^19 + 1/22*x^14 - 123/22*x^9 + 9/11*x^4, x^20 + 25*x^10 + 5)
+
+X<polcompositum0>The library syntax is B<polcompositum0>C<(x,y,>I<flag>C<)>.
+
+=head2 X<polgalois>polgaloisC<(x)>
+
+X<Galois>Galois group of the non-constant polynomial
+C<x belongs to >B<Q>C<[X]>. In the present version B<2.2.0>, C<x> must be irreducible and
+the degree of C<x> must be less than or equal to 7. On certain versions for
+which the data file of Galois resolvents has been installed (available
+in the Unix distribution as a separate package), degrees 8, 9, 10 and 11
+are also implemented.
+
+The output is a 3-component vector C<[n,s,k]> with the following meaning: C<n>
+is the cardinality of the group, C<s> is its signature (C<s = 1> if the group is
+a subgroup of the alternating group C<A_n>, C<s = -1> otherwise), and C<k> is the
+number of the group corresponding to a given pair C<(n,s)> (C<k = 1> except in 2
+cases). Specifically, the groups are coded as follows, using standard
+notations (see GTM 138, quoted at the beginning of this section; see also
+``The transitive groups of degree up to eleven'', by G.S< >Butler and J.S< >McKay
+in Communications in Algebra, vol.S< >11, 1983, pp.S< >863--911):
+
+In degree 1: C<S_1 = [1,-1,1]>.
+
+In degree 2: C<S_2 = [2,-1,1]>.
+
+In degree 3: C<A_3 = C_3 = [3,1,1]>, C<S_3 = [6,-1,1]>.
+
+In degree 4: C<C_4 = [4,-1,1]>, C<V_4 = [4,1,1]>, C<D_4 = [8,-1,1]>, C<A_4 = [12,1,1]>,
+C<S_4 = [24,-1,1]>.
+
+In degree 5: C<C_5 = [5,1,1]>, C<D_5 = [10,1,1]>, C<M_{20} = [20,-1,1]>,
+C<A_5 = [60,1,1]>, C<S_5 = [120,-1,1]>.
+
+In degree 6: C<C_6 = [6,-1,1]>, C<S_3 = [6,-1,2]>, C<D_6 = [12,-1,1]>, C<A_4 = [12,1,1]>,
+C<G_{18} = [18,-1,1]>, C<S_4^ -= [24,-1,1]>, C<A_4 x C_2 = [24,-1,2]>,
+C<S_4^ += [24,1,1]>, C<G_{36}^ -= [36,-1,1]>, C<G_{36}^ += [36,1,1]>,
+C<S_4 x C_2 = [48,-1,1]>, C<A_5 = PSL_2(5) = [60,1,1]>, C<G_{72} = [72,-1,1]>,
+C<S_5 = PGL_2(5) = [120,-1,1]>, C<A_6 = [360,1,1]>, C<S_6 = [720,-1,1]>.
+
+In degree 7: C<C_7 = [7,1,1]>, C<D_7 = [14,-1,1]>, C<M_{21} = [21,1,1]>,
+C<M_{42} = [42,-1,1]>, C<PSL_2(7) = PSL_3(2) = [168,1,1]>, C<A_7 = [2520,1,1]>,
+C<S_7 = [5040,-1,1]>.
+
+The method used is that of resolvent polynomials and is sensitive to the
+current precision. The precision is updated internally but, in very rare
+cases, a wrong result may be returned if the initial precision was not
+sufficient.
+
+X<galois>The library syntax is B<galois>C<(x,>I<prec>C<)>.
+
+=head2 X<polred>polredC<(x,{>I<flag>C< = 0},{p})>
+
+finds polynomials with reasonably
+small coefficients defining subfields of the number field defined by C<x>.
+One of the polynomials always defines B<Q> (hence is equal to C<x-1>),
+and another always defines the same number field as C<x> if C<x> is irreducible.
+All C<x> accepted by X<nfinit>C<nfinit> are also allowed here (e.g. non-monic
+polynomials, C<nf>, C<bnf>, C<[x,Z_K_basis]>).
+
+The following binary digits of I<flag> are significant:
+
+1: does a partial reduction only. This means that only a suborder of the
+maximal order may be used.
+
+2: gives also elements. The result is a two-column matrix, the first column
+giving the elements defining these subfields, the second giving the
+corresponding minimal polynomials.
+
+If C<p> is given, it is assumed that it is the two-column matrix of the
+factorization of the discriminant of the polynomial C<x>.
+
+X<polred0>The library syntax is B<polred0>C<(x,>I<flag>C<,p,>I<prec>C<)>, where an omitted C<p> is
+coded by C<gzero>. Also available are X<polred>B<polred>C<(x,>I<prec>C<)> and
+X<factoredpolred>B<factoredpolred>C<(x,p,>I<prec>C<)>, both corresponding to I<flag>C< = 0>.
+
+=head2 X<polredabs>polredabsC<(x,{>I<flag>C< = 0})>
+
+finds one of the polynomial defining
+the same number field as the one defined by C<x>, and such that the sum of the
+squares of the modulus of the roots (i.e.S< >the C<T_2>-norm) is minimal.
+All C<x> accepted by X<nfinit>C<nfinit> are also allowed here (e.g. non-monic
+polynomials, C<nf>, C<bnf>, C<[x,Z_K_basis]>).
+
+The binary digits of I<flag> mean
+
+1: outputs a two-component row vector C<[P,a]>, where C<P> is the default
+output and C<a> is an element expressed on a root of the polynomial C<P>,
+whose minimal polynomial is equal to C<x>.
+
+4: gives I<all> polynomials of minimal C<T_2> norm (of the two polynomials
+C<P(x)> and C<P(-x)>, only one is given).
+
+X<polredabs0>The library syntax is B<polredabs0>C<(x,>I<flag>C<,>I<prec>C<)>.
+
+=head2 X<polredord>polredordC<(x)>
+
+finds polynomials with reasonably small
+coefficients and of the same degree as that of C<x> defining suborders of the
+order defined by C<x>. One of the polynomials always defines B<Q> (hence
+is equal to C<(x-1)^n>, where C<n> is the degree), and another always defines
+the same order as C<x> if C<x> is irreducible.
+
+X<ordred>The library syntax is B<ordred>C<(x)>.
+
+=head2 X<poltschirnhaus>poltschirnhausC<(x)>
+
+applies a random Tschirnhausen
+transformation to the polynomial C<x>, which is assumed to be non-constant
+and separable, so as to obtain a new equation for the E<eacute>tale algebra
+defined by C<x>. This is for instance useful when computing resolvents,
+hence is used by the C<polgalois> function.
+
+X<tschirnhaus>The library syntax is B<tschirnhaus>C<(x)>.
+
+=head2 X<rnfalgtobasis>rnfalgtobasisC<(>I<rnf>C<,x)>
+
+I<rnf> being a relative number
+field extension C<L/K> as output by C<rnfinit> and C<x> being an element of
+C<L> expressed as a polynomial or polmod with polmod coefficients, expresses
+C<x> on the relative integral basis.
+
+X<rnfalgtobasis>The library syntax is B<rnfalgtobasis>C<(>I<rnf>C<,x)>.
+
+=head2 X<rnfbasis>rnfbasisC<(>I<bnf>C<,x)>
+
+given a big number field I<bnf> as
+output by C<bnfinit>, and either a polynomial C<x> with coefficients in
+I<bnf> defining a relative extension C<L> of I<bnf>, or a
+pseudo-basis C<x> of such an extension, gives either a true I<bnf>-basis
+of C<L> if it exists, or an C<n+1>-element generating set of C<L> if not, where
+C<n> is the rank of C<L> over I<bnf>.
+
+X<rnfbasis>The library syntax is B<rnfbasis>C<(>I<bnf>C<,x)>.
+
+=head2 X<rnfbasistoalg>rnfbasistoalgC<(>I<rnf>C<,x)>
+
+I<rnf> being a relative number
+field extension C<L/K> as output by C<rnfinit> and C<x> being an element of
+C<L> expressed on the relative integral basis, computes the representation of
+C<x> as a polmod with polmods coefficients.
+
+X<rnfbasistoalg>The library syntax is B<rnfbasistoalg>C<(>I<rnf>C<,x)>.
+
+=head2 X<rnfcharpoly>rnfcharpolyC<(>I<nf>C<,T,a,{v = x})>
+
+characteristic polynomial of
+C<a> over I<nf>, where C<a> belongs to the algebra defined by C<T> over
+I<nf>, i.e.S< >I<nf>C<[X]/(T)>. Returns a polynomial in variable C<v>
+(C<x> by default).
+
+X<rnfcharpoly>The library syntax is B<rnfcharpoly>C<(>I<nf>C<,T,a,v)>, where C<v> is a variable number.
+
+=head2 X<rnfconductor>rnfconductorC<(>I<bnf>C<,>I<pol>C<)>
+
+I<bnf> being a big number
+field as output by C<bnfinit>, and I<pol> a relative polynomial defining
+an X<Abelian extension>Abelian extension, computes the class field theory conductor of this
+Abelian extension. The result is a 3-component vector
+C<[>I<conductor>C<,>I<rayclgp>C<,>I<subgroup>C<]>, where I<conductor> is
+the conductor of the extension given as a 2-component row vector
+C<[f_0,f_ oo ]>, I<rayclgp> is the full ray class group corresponding to
+the conductor given as a 3-component vector [h,cyc,gen] as usual for a group,
+and I<subgroup> is a matrix in HNF defining the subgroup of the ray class
+group on the given generators gen.
+
+X<rnfconductor>The library syntax is B<rnfconductor>C<(>I<rnf>C<,>I<pol>C<,>I<prec>C<)>.
+
+=head2 X<rnfdedekind>rnfdedekindC<(>I<nf>C<,>I<pol>C<,>I<pr>C<)>
+
+given a number field
+I<nf> as output by C<nfinit> and a polynomial I<pol> with
+coefficients in I<nf> defining a relative extension C<L> of I<nf>,
+evaluates the relative X<Dedekind>Dedekind criterion over the order defined by a
+root of I<pol> for the prime ideal I<pr> and outputs a 3-component
+vector as the result. The first component is a flag equal to 1 if the
+enlarged order could be proven to be I<pr>-maximal and to 0 otherwise (it
+may be maximal in the latter case if I<pr> is ramified in C<L>), the second
+component is a pseudo-basis of the enlarged order and the third component is
+the valuation at I<pr> of the order discriminant.
+
+X<rnfdedekind>The library syntax is B<rnfdedekind>C<(>I<nf>C<,>I<pol>C<,>I<pr>C<)>.
+
+=head2 X<rnfdet>rnfdetC<(>I<nf>C<,M)>
+
+given a pseudomatrix C<M> over the maximal
+order of I<nf>, computes its pseudodeterminant.
+
+X<rnfdet>The library syntax is B<rnfdet>C<(>I<nf>C<,M)>.
+
+=head2 X<rnfdisc>rnfdiscC<(>I<nf>C<,>I<pol>C<)>
+
+given a number field I<nf> as
+output by C<nfinit> and a polynomial I<pol> with coefficients in
+I<nf> defining a relative extension C<L> of I<nf>, computes
+the relative
+discriminant of C<L>. This is a two-element row vector C<[D,d]>, where C<D> is
+the relative ideal discriminant and C<d> is the relative discriminant
+considered as an element of I<nf>C<^*/{>I<nf>C<^*}^2>. The main variable of
+I<nf> I<must> be of lower priority than that of I<pol>.
+
+Note: As usual, I<nf> can be a I<bnf> as output by C<nfinit>.
+
+X<rnfdiscf>The library syntax is B<rnfdiscf>C<(>I<bnf>C<,>I<pol>C<)>.
+
+=head2 X<rnfeltabstorel>rnfeltabstorelC<(>I<rnf>C<,x)>
+
+I<rnf> being a relative
+number field
+extension C<L/K> as output by C<rnfinit> and C<x> being an element of C<L>
+expressed as a polynomial modulo the absolute equation I<rnf>C<[11][1]>,
+computes C<x> as an element of the relative extension C<L/K> as a polmod with
+polmod coefficients.
+
+X<rnfelementabstorel>The library syntax is B<rnfelementabstorel>C<(>I<rnf>C<,x)>.
+
+=head2 X<rnfeltdown>rnfeltdownC<(>I<rnf>C<,x)>
+
+I<rnf> being a relative number
+field extension C<L/K> as output by C<rnfinit> and C<x> being an element of
+C<L> expressed as a polynomial or polmod with polmod coefficients, computes
+C<x> as an element of C<K> as a polmod, assuming C<x> is in C<K> (otherwise an
+error will occur). If C<x> is given on the relative integral basis, apply
+C<rnfbasistoalg> first, otherwise PARI will believe you are dealing with a
+vector.
+
+X<rnfelementdown>The library syntax is B<rnfelementdown>C<(>I<rnf>C<,x)>.
+
+=head2 X<rnfeltreltoabs>rnfeltreltoabsC<(>I<rnf>C<,x)>
+
+I<rnf> being a relative
+number field extension C<L/K> as output by C<rnfinit> and C<x> being an
+element of C<L> expressed as a polynomial or polmod with polmod
+coefficients, computes C<x> as an element of the absolute extension C<L/>B<Q> as
+a polynomial modulo the absolute equation I<rnf>C<[11][1]>. If C<x> is
+given on the relative integral basis, apply C<rnfbasistoalg> first,
+otherwise PARI will believe you are dealing with a vector.
+
+X<rnfelementreltoabs>The library syntax is B<rnfelementreltoabs>C<(>I<rnf>C<,x)>.
+
+=head2 X<rnfeltup>rnfeltupC<(>I<rnf>C<,x)>
+
+I<rnf> being a relative number
+field extension C<L/K> as output by C<rnfinit> and C<x> being an element of
+C<K> expressed as a polynomial or polmod, computes C<x> as an element of the
+absolute extension C<L/>B<Q> as a polynomial modulo the absolute equation
+I<rnf>C<[11][1]>. Note that it is unnecessary to compute C<x> as an
+element of the relative extension C<L/K> (its expression would be identical to
+itself). If C<x> is given on the integral basis of C<K>, apply
+C<nfbasistoalg> first, otherwise PARI will believe you are dealing with a
+vector.
+
+X<rnfelementup>The library syntax is B<rnfelementup>C<(>I<rnf>C<,x)>.
+
+=head2 X<rnfequation>rnfequationC<(>I<nf>C<,>I<pol>C<,{>I<flag>C< = 0})>
+
+given a number field
+I<nf> as output by C<nfinit> (or simply a polynomial) and a
+polynomial I<pol> with coefficients in I<nf> defining a relative
+extension C<L> of I<nf>, computes the absolute equation of C<L> over
+B<Q>.
+
+If I<flag> is non-zero, outputs a 3-component row vector C<[z,a,k]>, where
+C<z> is the absolute equation of C<L> over B<Q>, as in the default behaviour,
+C<a> expresses as an element of C<L> a root F<alpha> of the polynomial
+defining the base field I<nf>, and C<k> is a small integer such that
+F<theta>C< = >F<beta>C<+k>F<alpha> where F<theta> is a root of C<z> and F<beta> a root
+of I<pol>.
+
+The main variable of I<nf> I<must> be of lower priority than that
+of I<pol>. Note that for efficiency, this does not check whether the
+relative equation is irreducible over I<nf>, but only if it is
+squarefree. If it is reducible but squarefree, the result will be the
+absolute equation of the E<eacute>tale algebra defined by I<pol>. If I<pol>
+is not squarefree, an error message will be issued.
+
+X<rnfequation0>The library syntax is B<rnfequation0>C<(>I<nf>C<,>I<pol>C<,>I<flag>C<)>.
+
+=head2 X<rnfhnfbasis>rnfhnfbasisC<(>I<bnf>C<,x)>
+
+given a big number field I<bnf>
+as output by C<bnfinit>, and either a polynomial C<x> with coefficients in
+I<bnf> defining a relative extension C<L> of I<bnf>, or a
+pseudo-basis C<x> of such an extension, gives either a true I<bnf>-basis
+of C<L> in upper triangular Hermite normal form, if it exists,
+zero otherwise.
+
+X<rnfhermitebasis>The library syntax is B<rnfhermitebasis>C<(>I<nf>C<,x)>.
+
+=head2 X<rnfidealabstorel>rnfidealabstorelC<(>I<rnf>C<,x)>
+
+I<rnf> being a relative
+number field extension C<L/K> as output by C<rnfinit> and C<x> being an
+ideal of the absolute extension C<L/>B<Q> given in HNFX<Hermite normal form>
+(if it is not, apply C<idealhnf> first), computes the relative pseudomatrix
+in HNF giving the ideal C<x> considered as an ideal of the relative extension
+C<L/K>.
+
+X<rnfidealabstorel>The library syntax is B<rnfidealabstorel>C<(>I<rnf>C<,x)>.
+
+=head2 X<rnfidealdown>rnfidealdownC<(>I<rnf>C<,x)>
+
+I<rnf> being a relative number
+field extension C<L/K> as output by C<rnfinit> and C<x> being an ideal of
+the absolute extension C<L/>B<Q> given in HNF (if it is not, apply
+C<idealhnf> first), gives the ideal of C<K> below C<x>, i.e.S< >the
+intersection of C<x> with C<K>. Note that, if C<x> is given as a relative ideal
+(i.e.S< >a pseudomatrix in HNF), then it is not necessary to use this function
+since the result is simply the first ideal of the ideal list of the
+pseudomatrix.
+
+X<rnfidealdown>The library syntax is B<rnfidealdown>C<(>I<rnf>C<,x)>.
+
+=head2 X<rnfidealhnf>rnfidealhnfC<(>I<rnf>C<,x)>
+
+I<rnf> being a relative number
+field extension C<L/K> as output by C<rnfinit> and C<x> being a relative
+ideal (which can be, as in the absolute case, of many different types,
+including of course elements), computes as a 2-component row vector the
+relative Hermite normal form of C<x>, the first component being the HNF matrix
+(with entries on the integral basis), and the second component the ideals.
+
+X<rnfidealhermite>The library syntax is B<rnfidealhermite>C<(>I<rnf>C<,x)>.
+
+=head2 X<rnfidealmul>rnfidealmulC<(>I<rnf>C<,x,y)>
+
+I<rnf> being a relative number
+field extension C<L/K> as output by C<rnfinit> and C<x> and C<y> being ideals
+of the relative extension C<L/K> given by pseudo-matrices, outputs the ideal
+product, again as a relative ideal.
+
+X<rnfidealmul>The library syntax is B<rnfidealmul>C<(>I<rnf>C<,x,y)>.
+
+=head2 X<rnfidealnormabs>rnfidealnormabsC<(>I<rnf>C<,x)>
+
+I<rnf> being a relative
+number field extension C<L/K> as output by C<rnfinit> and C<x> being a
+relative ideal (which can be, as in the absolute case, of many different
+types, including of course elements), computes the norm of the ideal C<x>
+considered as an ideal of the absolute extension C<L/>B<Q>. This is identical to
+C<idealnorm(rnfidealnormrel(>I<rnf>C<,x))>, only faster.
+
+X<rnfidealnormabs>The library syntax is B<rnfidealnormabs>C<(>I<rnf>C<,x)>.
+
+=head2 X<rnfidealnormrel>rnfidealnormrelC<(>I<rnf>C<,x)>
+
+I<rnf> being a relative
+number field
+extension C<L/K> as output by C<rnfinit> and C<x> being a relative ideal
+(which can be, as in the absolute case, of many different types, including
+of course elements), computes the relative norm of C<x> as a ideal of C<K>
+in HNF.
+
+X<rnfidealnormrel>The library syntax is B<rnfidealnormrel>C<(>I<rnf>C<,x)>.
+
+=head2 X<rnfidealreltoabs>rnfidealreltoabsC<(>I<rnf>C<,x)>
+
+I<rnf> being a relative
+number field
+extension C<L/K> as output by C<rnfinit> and C<x> being a relative ideal
+(which can be, as in the absolute case, of many different types, including
+of course elements), computes the HNF matrix of the ideal C<x> considered
+as an ideal of the absolute extension C<L/>B<Q>.
+
+X<rnfidealreltoabs>The library syntax is B<rnfidealreltoabs>C<(>I<rnf>C<,x)>.
+
+=head2 X<rnfidealtwoelt>rnfidealtwoeltC<(>I<rnf>C<,x)>
+
+I<rnf> being a relative
+number field
+extension C<L/K> as output by C<rnfinit> and C<x> being an ideal of the
+relative extension C<L/K> given by a pseudo-matrix, gives a vector of
+two generators of C<x> over B<Z>C<_L> expressed as polmods with polmod
+coefficients.
+
+X<rnfidealtwoelement>The library syntax is B<rnfidealtwoelement>C<(>I<rnf>C<,x)>.
+
+=head2 X<rnfidealup>rnfidealupC<(>I<rnf>C<,x)>
+
+I<rnf> being a relative number
+field
+extension C<L/K> as output by C<rnfinit> and C<x> being an ideal of
+C<K>, gives the ideal C<x>B<Z>C<_L> as an absolute ideal of C<L/>B<Q> (the relative
+ideal representation is trivial: the matrix is the identity matrix, and
+the ideal list starts with C<x>, all the other ideals being B<Z>C<_K>).
+
+X<rnfidealup>The library syntax is B<rnfidealup>C<(>I<rnf>C<,x)>.
+
+=head2 X<rnfinit>rnfinitC<(>I<nf>C<,>I<pol>C<)>
+
+I<nf> being a number field in
+C<nfinit>
+format considered as base field, and I<pol> a polynomial defining a relative
+extension over I<nf>, this computes all the necessary data to work in the
+relative extension. The main variable of I<pol> must be of higher priority
+(i.e.S< >lower number) than that of I<nf>, and the coefficients of I<pol>
+must be in I<nf>.
+
+The result is an 11-component row vector as follows (most of the components
+are technical), the numbering being very close to that of C<nfinit>. In
+the following description, we let C<K> be the base field defined by
+I<nf>, C<m> the degree of the base field, C<n> the relative degree, C<L>
+the large field (of relative degree C<n> or absolute degree C<nm>), C<r_1> and
+C<r_2> the number of real and complex places of C<K>.
+
+I<rnf>C<[1]> contains the relative polynomial I<pol>.
+
+I<rnf>C<[2]> is a row vector with C<r_1+r_2> entries, entry C<j> being
+a 2-component row vector C<[r_{j,1},r_{j,2}]> where C<r_{j,1}> and C<r_{j,2}>
+are the number of real and complex places of C<L> above the C<j>-th place of
+C<K> so that C<r_{j,1} = 0> and C<r_{j,2} = n> if C<j> is a complex place, while if
+C<j> is a real place we have C<r_{j,1}+2r_{j,2} = n>.
+
+I<rnf>C<[3]> is a two-component row vector C<[>B<d>C<(L/K),s]> where B<d>C<(L/K)>
+is the relative ideal discriminant of C<L/K> and C<s> is the discriminant of
+C<L/K> viewed as an element of C<K^*/(K^*)^2>, in other words it is the output
+of C<rnfdisc>.
+
+I<rnf>C<[4]> is the ideal index B<f>, i.e.S< >such that
+C<d(pol)>B<Z>C<_K = >B<f>C<^2>B<d>C<(L/K)>.
+
+I<rnf>C<[5]> is a vector I<vm> with 7 entries useful for certain
+computations in the relative extension C<L/K>. I<vm>C<[1]> is a vector of
+C<r_1+r_2> matrices, the C<j>-th matrix being an C<(r_{1,j}+r_{2,j}) x n>
+matrix C<M_j> representing the numerical values of the conjugates of the
+C<j>-th embedding of the elements of the integral basis, where C<r_{i,j}> is as
+in I<rnf>C<[2]>. I<vm>C<[2]> is a vector of C<r_1+r_2> matrices, the
+C<j>-th matrix C<MC_j> being essentially the conjugate of the matrix C<M_j>
+except that the last C<r_{2,j}> columns are also multiplied by 2.
+I<vm>C<[3]> is a vector of C<r_1+r_2> matrices C<T2_j>, where C<T2_j> is
+an C<n x n> matrix equal to the real part of the product C<MC_j.M_j>
+(which is a real positive definite matrix). I<vm>C<[4]> is the C<n x n>
+matrix C<T> whose entries are the relative traces of F<omega>C<_i>F<omega>C<_j>
+expressed as polmods in I<nf>, where the F<omega>C<_i> are the elements
+of the relative integral basis. Note that the C<j>-th embedding of C<T> is
+equal to C<\overline{MC_j}.M_j>, and in particular will be equal to
+C<T2_j> if C<r_{2,j} = 0>. Note also that the relative ideal discriminant of
+C<L/K> is equal to F<det> C<(T)> times the square of the product of the ideals
+in the relative pseudo-basis (in I<rnf>C<[7][2]>). The last 3 entries
+I<vm>C<[5]>, I<vm>C<[6]> and I<vm>C<[7]> are linked to the different
+as in C<nfinit>, but have not yet been implemented.
+
+I<rnf>C<[6]> is a row vector with C<r_1+r_2> entries, the C<j>-th entry
+being the
+row vector with C<r_{1,j}+r_{2,j}> entries of the roots of the C<j>-th embedding
+of the relative polynomial I<pol>.
+
+I<rnf>C<[7]> is a two-component row vector, where the first component is
+the relative integral pseudo basis expressed as polynomials (in the variable of
+C<pol>) with polmod coefficients in I<nf>, and the second component is the
+ideal list of the pseudobasis in HNF.
+
+I<rnf>C<[8]> is the inverse matrix of the integral basis matrix, with
+coefficients polmods in I<nf>.
+
+I<rnf>C<[9]> may be the multiplication table of the integral basis, but
+is not implemented at present.
+
+I<rnf>C<[10]> is I<nf>.
+
+I<rnf>C<[11]> is a vector I<vabs> with 5 entries describing the
+I<absolute> extension C<L/>B<Q>. I<vabs>C<[1]> is an absolute equation.
+I<vabs>C<[2]> expresses the generator F<alpha> of the number field
+I<nf> as a polynomial modulo the absolute equation I<vabs>C<[1]>.
+I<vabs>C<[3]> is a small integer C<k> such that, if F<beta> is an abstract
+root of I<pol> and F<alpha> the generator of I<nf>, the generator
+whose root is I<vabs> will be F<beta>C< + k >F<alpha>. Note that one must
+be very careful if C<k ! = 0> when dealing simultaneously with absolute and
+relative quantities since the generator chosen for the absolute extension
+is not the same as for the relative one. If this happens, one can of course
+go on working, but we strongly advise to change the relative polynomial so
+that its root will be F<beta>C< + k >F<alpha>. Typically, the GP instruction would
+be
+
+C<pol = subst(pol, x, x - k*Mod(y,>I<nf>C<.pol))>
+
+Finally, I<vabs>C<[4]> is the absolute integral basis of C<L> expressed in HNF
+(hence as would be output by C<nfinit(vabs[1])>), and I<vabs>C<[5]> the
+inverse matrix of the integral basis, allowing to go from polmod to integral
+basis representation.
+
+X<rnfinitalg>The library syntax is B<rnfinitalg>C<(>I<nf>C<,>I<pol>C<,>I<prec>C<)>.
+
+=head2 X<rnfisfree>rnfisfreeC<(>I<bnf>C<,x)>
+
+given a big number field I<bnf> as
+output by C<bnfinit>, and either a polynomial C<x> with coefficients in
+I<bnf> defining a relative extension C<L> of I<bnf>, or a
+pseudo-basis C<x> of such an extension, returns true (1) if C<L/>I<bnf> is
+free, false (0) if not.
+
+X<rnfisfree>The library syntax is B<rnfisfree>C<(>I<bnf>C<,x)>, and the result is a C<long>.
+
+=head2 X<rnfisnorm>rnfisnormC<(>I<bnf>C<,>I<ext>C<,>I<el>C<,{>I<flag>C< = 1})>
+
+similar to
+C<bnfisnorm> but in the relative case. This tries to decide whether the
+element I<el> in I<bnf> is the norm of some C<y> in I<ext>.
+I<bnf> is as output by C<bnfinit>.
+
+I<ext> is a relative extension which has to be a row vector whose
+components are:
+
+I<ext>C<[1]>: a relative equation of the number field I<ext> over
+I<bnf>. As usual, the priority of the variable of the polynomial
+defining the ground field I<bnf> (say C<y>) must be lower than the
+main variable of I<ext>C<[1]>, say C<x>.
+
+I<ext>C<[2]>: the generator C<y> of the base field as a polynomial in C<x> (as
+given by C<rnfequation> with I<flag>C< = 1>).
+
+I<ext>C<[3]>: is the C<bnfinit> of the absolute extension I<ext>C</>B<Q>.
+
+This returns a vector C<[a,b]>, where I<el>C< = >I<Norm>C<(a)*b>. It looks for a
+solution which is an C<S>-integer, with C<S> a list of places (of I<bnf>)
+containing the ramified primes, the generators of the class group of
+I<ext>, as well as those primes dividing I<el>. If I<ext>C</>I<bnf>
+is known to be X<Galois>Galois, set I<flag>C< = 0> (here I<el> is a norm iff C<b = 1>).
+If I<flag> is non zero add to C<S> all the places above the primes which: divide
+I<flag> if I<flag>C< E<lt> 0>, or are less than I<flag> if I<flag>C< E<gt> 0>. The answer is guaranteed
+(i.e.S< >I<el> is a norm iff C<b = 1>) under X<GRH>GRH, if C<S> contains all
+primes less than C<12> F<log> C<^2|disc(>I<Ext>C<)|>, where
+I<Ext> is the normal closure of I<ext>C< / >I<bnf>. Example:
+
+ bnf = bnfinit(y^3 + y^2 - 2*y - 1);
+ p = x^2 + Mod(y^2 + 2*y + 1, bnf.pol);
+ rnf = rnfequation(bnf,p,1);
+ ext = [p, rnf[2], bnfinit(rnf[1])];
+ rnfisnorm(bnf,ext,17, 1)
+
+checks whether C<17> is a norm in the Galois extension B<Q>C<(>F<beta>C<) /
+>B<Q>C<(>F<alpha>C<)>, where F<alpha>C<^3 + >F<alpha>C<^2 - 2>F<alpha>C< - 1 = 0> and F<beta>C<^2 +
+>F<alpha>C<^2 + 2*>F<alpha>C< + 1 = 0> (it is).
+
+X<rnfisnorm>The library syntax is B<rnfisnorm>C<(>I<bnf>C<,ext,x,>I<flag>C<,>I<prec>C<)>.
+
+=head2 X<rnfkummer>rnfkummerC<(>I<bnr>C<,>I<subgroup>C<,{deg = 0})>
+
+I<bnr>
+being as output by C<bnrinit>, finds a relative equation for the
+class field corresponding to the module in I<bnr> and the given
+congruence subgroup. If I<deg> is positive, outputs the list of all
+relative equations of degree I<deg> contained in the ray class field
+defined by I<bnr>.
+
+(THIS PROGRAM IS STILL IN DEVELOPMENT STAGE)
+
+X<rnfkummer>The library syntax is B<rnfkummer>C<(>I<bnr>C<,>I<subgroup>C<,>I<deg>C<,>I<prec>C<)>,
+where I<deg> is a C<long>.
+
+=head2 X<rnflllgram>rnflllgramC<(>I<nf>C<,>I<pol>C<,>I<order>C<)>
+
+given a polynomial
+I<pol> with coefficients in I<nf> and an order I<order> as output
+by C<rnfpseudobasis> or similar, gives C<[[>I<neworder>C<],U]>, where
+I<neworder> is a reduced order and C<U> is the unimodular transformation
+matrix.
+
+X<rnflllgram>The library syntax is B<rnflllgram>C<(>I<nf>C<,>I<pol>C<,>I<order>C<,>I<prec>C<)>.
+
+=head2 X<rnfnormgroup>rnfnormgroupC<(>I<bnr>C<,>I<pol>C<)>
+
+I<bnr> being a big ray
+class field as output by C<bnrinit> and I<pol> a relative polynomial
+defining an X<Abelian extension>Abelian extension, computes the norm group (alias Artin
+or Takagi group) corresponding to the Abelian extension of I<bnf>C< = bnr[1]>
+defined by I<pol>, where the module corresponding to I<bnr> is assumed
+to be a multiple of the conductor (i.e.S< >polrel defines a subextension of
+bnr). The result is the HNF defining the norm group on the given generators
+of I<bnr>C<[5][3]>. Note that neither the fact that I<pol> defines an
+Abelian extension nor the fact that the module is a multiple of the conductor
+is checked. The result is undefined if the assumption is not correct.
+
+X<rnfnormgroup>The library syntax is B<rnfnormgroup>C<(>I<bnr>C<,>I<pol>C<)>.
+
+=head2 X<rnfpolred>rnfpolredC<(>I<nf>C<,>I<pol>C<)>
+
+relative version of C<polred>.
+Given a monic polynomial I<pol> with coefficients in I<nf>, finds a
+list of relative polynomials defining some subfields, hopefully simpler and
+containing the original field. In the present version B<2.2.0>, this is slower
+than C<rnfpolredabs>.
+
+X<rnfpolred>The library syntax is B<rnfpolred>C<(>I<nf>C<,>I<pol>C<,>I<prec>C<)>.
+
+=head2 X<rnfpolredabs>rnfpolredabsC<(>I<nf>C<,>I<pol>C<,{>I<flag>C< = 0})>
+
+relative version of
+C<polredabs>. Given a monic polynomial I<pol> with coefficients in
+I<nf>, finds a simpler relative polynomial defining the same field. If
+I<flag>C< = 1>, returns C<[P,a]> where C<P> is the default output and C<a> is an
+element expressed on a root of C<P> whose characteristic polynomial is
+I<pol>, if I<flag>C< = 2>, returns an absolute polynomial (same as
+
+C<rnfequation(>I<nf>C<,rnfpolredabs(>I<nf>C<,>I<pol>C<))>
+
+but faster).
+
+B<Remark.> In the present implementation, this is both faster and
+much more efficient than C<rnfpolred>, the difference being more
+dramatic than in the absolute case. This is because the implementation of
+C<rnfpolred> is based on (a partial implementation of) an incomplete
+reduction theory of lattices over number fields (i.e.S< >the function
+C<rnflllgram>) which deserves to be improved.
+
+X<rnfpolredabs>The library syntax is B<rnfpolredabs>C<(>I<nf>C<,>I<pol>C<,>I<flag>C<,>I<prec>C<)>.
+
+=head2 X<rnfpseudobasis>rnfpseudobasisC<(>I<nf>C<,>I<pol>C<)>
+
+given a number field
+I<nf> as output by C<nfinit> and a polynomial I<pol> with
+coefficients in I<nf> defining a relative extension C<L> of I<nf>,
+computes a pseudo-basis C<(A,I)> and the relative discriminant of C<L>.
+This is output as
+a four-element row vector C<[A,I,D,d]>, where C<D> is the relative ideal
+discriminant and C<d> is the relative discriminant considered as an element of
+I<nf>C<^*/{>I<nf>C<^*}^2>.
+
+Note: As usual, I<nf> can be a I<bnf> as output by C<bnfinit>.
+
+X<rnfpseudobasis>The library syntax is B<rnfpseudobasis>C<(>I<nf>C<,>I<pol>C<)>.
+
+=head2 X<rnfsteinitz>rnfsteinitzC<(>I<nf>C<,x)>
+
+given a number field I<nf> as
+output by C<nfinit> and either a polynomial C<x> with coefficients in
+I<nf> defining a relative extension C<L> of I<nf>, or a pseudo-basis
+C<x> of such an extension as output for example by C<rnfpseudobasis>,
+computes another pseudo-basis C<(A,I)> (not in HNF in general) such that all
+the ideals of C<I> except perhaps the last one are equal to the ring of
+integers of I<nf>, and outputs the four-component row vector C<[A,I,D,d]>
+as in C<rnfpseudobasis>. The name of this function comes from the fact
+that the ideal class of the last ideal of C<I> (which is well defined) is
+called the X<Steinitz class>I<Steinitz class> of the module B<Z>C<_L>.
+
+Note: I<nf> can be a I<bnf> as output by C<bnfinit>.
+
+X<rnfsteinitz>The library syntax is B<rnfsteinitz>C<(>I<nf>C<,x)>.
+
+=head2 X<subgrouplist>subgrouplistC<(>I<bnr>C<,{>I<bound>C<},{>I<flag>C< = 0})>
+
+I<bnr> being as output by C<bnrinit> or a list of cyclic components
+of a finite Abelian group C<G>, outputs the list of subgroups of C<G>
+(of index bounded by I<bound>, if not omitted). Subgroups are given
+as HNFX<Hermite normal form> left divisors of the
+SNFX<Smith normal form> matrix corresponding to C<G>. If I<flag>C< = 0>
+(default) and I<bnr> is as output by
+C<bnrinit>, gives only the subgroups whose modulus is the conductor.
+
+X<subgrouplist0>The library syntax is B<subgrouplist0>C<(>I<bnr>C<,>I<bound>C<,>I<flag>C<,>I<prec>C<)>, where
+I<bound>, I<flag> and I<prec> are long integers.
+
+=head2 X<zetak>zetakC<(>I<znf>C<,x,{>I<flag>C< = 0})>
+
+I<znf> being a number
+field initialized by C<zetakinit> (I<not> by C<nfinit>),
+computes the value of the X<Dedekind>Dedekind zeta function of the number
+field at the complex number C<x>. If I<flag>C< = 1> computes Dedekind F<Lambda>
+function instead (i.e.S< >the product of the
+Dedekind zeta function by its gamma and exponential factors).
+
+The accuracy of the result depends in an essential way on the accuracy of
+both the C<zetakinit> program and the current accuracy, but even so the
+result may be off by up to 5 or 10 decimal digits.
+
+X<glambdak>The library syntax is B<glambdak>C<(>I<znf>C<,x,>I<prec>C<)> or
+X<gzetak>B<gzetak>C<(>I<znf>C<,x,>I<prec>C<)>.
+
+=head2 X<zetakinit>zetakinitC<(x)>
+
+computes a number of initialization data
+concerning the number field defined by the polynomial C<x> so as to be able
+to compute the X<Dedekind>Dedekind zeta and lambda functions (respectively
+C<zetak(x)> and C<zetak(x,1)>). This function calls in particular
+the C<bnfinit> program. The result is a 9-component vector C<v> whose
+components are very technical and cannot really be used by the user except
+through the C<zetak> function. The only component which can be used if
+it has not been computed already is C<v[1][4]> which is the result of the
+C<bnfinit> call.
+
+This function is very inefficient and should be rewritten. It needs to
+computes millions of coefficients of the corresponding Dirichlet series if
+the precision is big. Unless the discriminant is small it will not be able
+to handle more than 9 digits of relative precision
+(e.gS< >C<zetakinit(x^8 - 2)> needs 440MB of memory at default
+precision).
+
+X<initzeta>The library syntax is B<initzeta>C<(x)>.
+
+=head1 Polynomials and power series
+
+We group here all functions which are specific to polynomials or power
+series. Many other functions which can be applied on these objects are
+described in the other sections. Also, some of the functions described here
+can be applied to other types.
+
+=head2 X<O>OC<(a>C<^>C<b)>
+
+C<p>-adic (if C<a> is an integer greater or
+equal to 2) or power series zero (in all other cases), with precision given
+by C<b>.
+
+X<ggrandocp>The library syntax is B<ggrandocp>C<(a,b)>, where C<b> is a C<long>.
+
+=head2 X<deriv>derivC<(x,{v})>
+
+derivative of C<x> with respect to the main
+variable if C<v> is omitted, and with respect to C<v> otherwise. C<x> can be any
+type except polmod. The derivative of a scalar type is zero, and the
+derivative of a vector or matrix is done componentwise. One can use C<x'> as a
+shortcut if the derivative is with respect to the main variable of C<x>.
+
+X<deriv>The library syntax is B<deriv>C<(x,v)>, where C<v> is a C<long>, and an omitted C<v> is coded as
+C<-1>.
+
+=head2 X<eval>evalC<(x)>
+
+replaces in C<x> the formal variables by the values that
+have been assigned to them after the creation of C<x>. This is mainly useful
+in GP, and not in library mode. Do not confuse this with substitution (see
+C<subst>). Applying this function to a character string yields the
+output from the corresponding GP command, as if directly input from the
+keyboard (see L<Label se:strings>).X<Label se:eval>
+
+X<geval>The library syntax is B<geval>C<(x)>. The more basic functions X<poleval>B<poleval>C<(q,x)>,
+X<qfeval>B<qfeval>C<(q,x)>, and X<hqfeval>B<hqfeval>C<(q,x)> evaluate C<q> at C<x>, where C<q>
+is respectively assumed to be a polynomial, a quadratic form (a symmetric
+matrix), or an Hermitian form (an Hermitian complex matrix).
+
+=head2 X<factorpadic>factorpadicC<(>I<pol>C<,p,r,{>I<flag>C< = 0})>
+
+C<p>-adic factorization
+of the polynomial I<pol> to precision C<r>, the result being a
+two-column matrix as in C<factor>. The factors are normalized so that
+their leading coefficient is a power of C<p>. C<r> must be strictly larger than
+the C<p>-adic valuation of the discriminant of I<pol> for the result to
+make any sense. The method used is a modified version of the X<round 4>round 4
+algorithm of X<Zassenhaus>Zassenhaus.
+
+If I<flag>C< = 1>, use an algorithm due to X<Buchmann>Buchmann and X<Lenstra>Lenstra, which is
+usually less efficient.
+
+X<factorpadic4>The library syntax is B<factorpadic4>C<(>I<pol>C<,p,r)>, where C<r> is a C<long> integer.
+
+=head2 X<intformal>intformalC<(x,{v})>
+
+X<formal integration>formal integration of C<x> with
+respect to the main variable if C<v> is omitted, with respect to the variable
+C<v> otherwise. Since PARI does not know about ``abstract'' logarithms (they
+are immediately evaluated, if only to a power series), logarithmic terms in
+the result will yield an error. C<x> can be of any type. When C<x> is a
+rational function, it is assumed that the base ring is an integral domain of
+characteristic zero.
+
+X<integ>The library syntax is B<integ>C<(x,v)>, where C<v> is a C<long> and an omitted C<v> is coded
+as C<-1>.
+
+=head2 X<padicappr>padicapprC<(>I<pol>C<,a)>
+
+vector of C<p>-adic roots of the
+polynomial
+C<pol> congruent to the C<p>-adic number C<a> modulo C<p> (or modulo 4 if C<p = 2>),
+and with the same C<p>-adic precision as C<a>. The number C<a> can be an
+ordinary C<p>-adic number (type C<t_PADIC>, i.e.S< >an element of B<Q>C<_p>) or
+can be an element of a finite extension of B<Q>C<_p>, in which case it is of
+type C<t_POLMOD>, where at least one of the coefficients of the polmod is a
+C<p>-adic number. In this case, the result is the vector of roots belonging to
+the same extension of B<Q>C<_p> as C<a>.
+
+X<apprgen9>The library syntax is B<apprgen9>C<(>I<pol>C<,a)>, but if C<a> is known to be simply a C<p>-adic number
+(type C<t_PADIC>), the syntax X<apprgen>B<apprgen>C<(>I<pol>C<,a)> can be used.
+
+=head2 X<polcoeff>polcoeffC<(x,s,{v})>
+
+coefficient of degree C<s> of the
+polynomial C<x>, with respect to the main variable if C<v> is omitted, with
+respect to C<v> otherwise.
+
+X<polcoeff0>The library syntax is B<polcoeff0>C<(x,s,v)>, where C<v> is a C<long> and an omitted C<v> is coded
+as C<-1>. Also available is X<truecoeff>B<truecoeff>C<(x,v)>.
+
+=head2 X<poldegree>poldegreeC<(x,{v})>
+
+degree of the polynomial C<x> in the main
+variable if C<v> is omitted, in the variable C<v> otherwise. This is to be
+understood as follows. When C<x> is a polynomial or a rational function, it
+gives the degree of C<x>, the degree of C<0> being C<-1> by convention. When C<x>
+is a non-zero scalar, it gives 0, and when C<x> is a zero scalar, it gives
+C<-1>. Return an error otherwise.
+
+X<poldegree>The library syntax is B<poldegree>C<(x,v)>, where C<v> and the result are C<long>s (and an
+omitted C<v> is coded as C<-1>). Also available is X<degree>B<degree>C<(x)>, which is
+equivalent to C<poldegree(x,-1)>.
+
+=head2 X<polcyclo>polcycloC<(n,{v = x})>
+
+C<n>-th cyclotomic polynomial, in variable
+C<v> (C<x> by default). The integer C<n> must be positive.
+
+X<cyclo>The library syntax is B<cyclo>C<(n,v)>, where C<n> and C<v> are C<long>
+integers (C<v> is a variable number, usually obtained through C<varn>).
+
+=head2 X<poldisc>poldiscC<(>I<pol>C<,{v})>
+
+discriminant of the polynomial
+I<pol> in the main variable is C<v> is omitted, in C<v> otherwise. The
+algorithm used is the X<subresultant algorithm>subresultant algorithm.
+
+X<poldisc0>The library syntax is B<poldisc0>C<(x,v)>. Also available is X<discsr>B<discsr>C<(x)>, equivalent
+to C<poldisc0(x,-1)>.
+
+=head2 X<poldiscreduced>poldiscreducedC<(f)>
+
+reduced discriminant vector of the
+(integral, monic) polynomial C<f>. This is the vector of elementary divisors
+of B<Z>C<[>F<alpha>C<]/f'(>F<alpha>C<)>B<Z>C<[>F<alpha>C<]>, where F<alpha> is a root of the
+polynomial C<f>. The components of the result are all positive, and their
+product is equal to the absolute value of the discriminant ofS< >C<f>.
+
+X<reduceddiscsmith>The library syntax is B<reduceddiscsmith>C<(x)>.
+
+=head2 X<polhensellift>polhenselliftC<(x, y, p, e)>
+
+given a vector C<y> of
+polynomials that are pairwise relatively prime modulo the prime C<p>,
+and whose product is congruent to C<x> modulo C<p>, lift the elements of
+C<y> to polynomials whose product is congruent to C<x> modulo C<p^e>.
+
+X<polhensellift>The library syntax is B<polhensellift>C<(x,y,p,e)> where C<e> must be a C<long>.
+
+=head2 X<polinterpolate>polinterpolateC<(xa,{ya},{v = x},{&e})>
+
+given the data vectors
+C<xa> and C<ya> of the same length C<n> (C<xa> containing the C<x>-coordinates,
+and C<ya> the corresponding C<y>-coordinates), this function finds the
+X<interpolating polynomial>interpolating polynomial passing through these points and evaluates it
+atS< >C<v>. If C<ya> is omitted, return the polynomial interpolating the
+C<(i,xa[i])>. If present, C<e> will contain an error estimate on the returned
+value.
+
+X<polint>The library syntax is B<polint>C<(xa,ya,v,&e)>, where C<e> will contain an error estimate on the
+returned value.
+
+=head2 X<polisirreducible>polisirreducibleC<(>I<pol>C<)>
+
+I<pol> being a polynomial
+(univariate in the present version B<2.2.0>), returns 1 if I<pol> is
+non-constant and irreducible, 0 otherwise. Irreducibility is checked over
+the smallest base field over which I<pol> seems to be defined.
+
+X<gisirreducible>The library syntax is B<gisirreducible>C<(>I<pol>C<)>.
+
+=head2 X<pollead>polleadC<(x,{v})>
+
+leading coefficient of the polynomial or
+power series C<x>. This is computed with respect to the main variable of C<x>
+if C<v> is omitted, with respect to the variable C<v> otherwise.
+
+X<pollead>The library syntax is B<pollead>C<(x,v)>, where C<v> is a C<long> and an omitted C<v> is coded as
+C<-1>. Also available is X<leadingcoeff>B<leadingcoeff>C<(x)>.
+
+=head2 X<pollegendre>pollegendreC<(n,{v = x})>
+
+creates the C<n^{th}>
+X<Legendre polynomial>Legendre polynomial, in variable C<v>.
+
+X<legendre>The library syntax is B<legendre>C<(n)>, where C<x> is a C<long>.
+
+=head2 X<polrecip>polrecipC<(>I<pol>C<)>
+
+reciprocal polynomial of I<pol>,
+i.e.S< >the coefficients are in reverse order. I<pol> must be a polynomial.
+
+X<polrecip>The library syntax is B<polrecip>C<(x)>.
+
+=head2 X<polresultant>polresultantC<(x,y,{v},{>I<flag>C< = 0})>
+
+resultant of the two
+polynomials C<x> and C<y> with exact entries, with respect to the main
+variables of C<x> and C<y> if C<v> is omitted, with respect to the variable C<v>
+otherwise. The algorithm used is the X<subresultant algorithm>subresultant algorithm by default.
+
+If I<flag>C< = 1>, uses the determinant of Sylvester's matrix instead (here C<x> and
+C<y> may have non-exact coefficients).
+
+If I<flag>C< = 2>, uses Ducos's modified subresultant algorithm. It should be much
+faster than the default if the coefficient ring is complicated (e.g
+multivariate polynomials or huge coefficients), and slightly slower
+otherwise.
+
+X<polresultant0>The library syntax is B<polresultant0>C<(x,y,v,>I<flag>C<)>, where C<v> is a C<long> and an omitted C<v>
+is coded as C<-1>. Also available are X<subres>B<subres>C<(x,y)> (I<flag>C< = 0>) and
+X<resultant2>B<resultant2>C<(x,y)> (I<flag>C< = 1>).
+
+=head2 X<polroots>polrootsC<(>I<pol>C<,{>I<flag>C< = 0})>
+
+complex roots of the polynomial
+I<pol>, given as a column vector where each root is repeated according to
+its multiplicity. The precision is given as for transcendental functions: under
+GP it is kept in the variable C<realprecision> and is transparent to the
+user, but it must be explicitly given as a second argument in library mode.
+
+The algorithm used is a modification of A.S< >X<SchE<ouml>nhage>SchE<ouml>nhage's remarkable
+root-finding algorithm, due to and implemented by X.S< >Gourdon. Barring bugs,
+it is guaranteed to converge and to give the roots to the required accuracy.
+
+If I<flag>C< = 1>, use a variant of the Newton-Raphson method, which is I<not>
+guaranteed to converge, but is rather fast. If you get the messages ``too
+many iterations in roots'' or ``INTERNAL ERROR: incorrect result in roots'',
+use the default function (i.e.S< >no flag or I<flag>C< = 0>). This used to be the
+default root-finding function in PARI until version 1.39.06.
+
+X<roots>The library syntax is B<roots>C<(>I<pol>C<,>I<prec>C<)> or X<rootsold>B<rootsold>C<(>I<pol>C<,>I<prec>C<)>.
+
+=head2 X<polrootsmod>polrootsmodC<(>I<pol>C<,p,{>I<flag>C< = 0})>
+
+row vector of roots modulo
+C<p> of the polynomial I<pol>. The particular non-prime value C<p = 4> is
+accepted, mainly for C<2>-adic computations. Multiple roots are I<not>
+repeated.
+
+If C<p E<lt> 100>, you may try setting I<flag>C< = 1>, which uses a naive search. In this
+case, multiple roots I<are> repeated with their order of multiplicity.
+
+X<rootmod>The library syntax is B<rootmod>C<(>I<pol>C<,p)> (I<flag>C< = 0>) or
+X<rootmod2>B<rootmod2>C<(>I<pol>C<,p)> (I<flag>C< = 1>).
+
+=head2 X<polrootspadic>polrootspadicC<(>I<pol>C<,p,r)>
+
+row vector of C<p>-adic roots of the
+polynomial I<pol> with C<p>-adic precision equal to C<r>. Multiple roots are
+I<not> repeated. C<p> is assumed to be a prime.
+
+X<rootpadic>The library syntax is B<rootpadic>C<(>I<pol>C<,p,r)>, where C<r> is a C<long>.
+
+=head2 X<polsturm>polsturmC<(>I<pol>C<,{a},{b})>
+
+number of real roots of the real
+polynomial I<pol> in the interval C<]a,b]>, using Sturm's algorithm. C<a>
+(resp.S< >C<b>) is taken to be C<- oo > (resp.S< >C<+ oo >) if omitted.
+
+X<sturmpart>The library syntax is B<sturmpart>C<(>I<pol>C<,a,b)>. Use C<NULL> to omit an argument.
+X<sturm>B<sturm>C<(>I<pol>C<)> is equivalent to
+B<sturmpart>C<(>I<pol>C<,NULL,NULL)>. The result is a C<long>.
+
+=head2 X<polsubcyclo>polsubcycloC<(n,d,{v = x})>
+
+gives a polynomial (in variable
+C<v>) defining the sub-Abelian extension of degree C<d> of the cyclotomic
+field B<Q>C<(>F<zeta>C<_n)>, where C<d | >F<phi>C<(n)>. C<(>B<Z>C</n>B<Z>C<)^*> has to be cyclic
+(i.e.S< >C<n = 2>, C<4>, C<p^k> or C<2p^k> for an odd prime C<p>). The function
+X<galoissubcyclo>C<galoissubcyclo> covers the general case.
+
+X<subcyclo>The library syntax is B<subcyclo>C<(n,d,v)>, where C<v> is a variable number.
+
+=head2 X<polsylvestermatrix>polsylvestermatrixC<(x,y)>
+
+forms the Sylvester matrix
+corresponding to the two polynomials C<x> and C<y>, where the coefficients of
+the polynomials are put in the columns of the matrix (which is the natural
+direction for solving equations afterwards). The use of this matrix can be
+essential when dealing with polynomials with inexact entries, since
+polynomial Euclidean division doesn't make much sense in this case.
+
+X<sylvestermatrix>The library syntax is B<sylvestermatrix>C<(x,y)>.
+
+=head2 X<polsym>polsymC<(x,n)>
+
+creates the vector of the X<symmetric powers>symmetric powers
+of the roots of the polynomial C<x> up to power C<n>, using Newton's
+formula.
+
+X<polsym>The library syntax is B<polsym>C<(x)>.
+
+=head2 X<poltchebi>poltchebiC<(n,{v = x})>
+
+creates the C<n^{th}>
+X<Chebyshev>Chebyshev polynomial, in variable C<v>.
+
+X<tchebi>The library syntax is B<tchebi>C<(n,v)>, where C<n> and C<v> are C<long>
+integers (C<v> is a variable number).
+
+=head2 X<polzagier>polzagierC<(n,m)>
+
+creates Zagier's polynomial C<P_{n,m}> used in
+the functions C<sumalt> and C<sumpos> (with I<flag>C< = 1>). The exact
+definition can be found in a forthcoming paper. One must have C<m E<lt>= n>.
+
+X<polzagreel>The library syntax is B<polzagreel>C<(n,m,>I<prec>C<)> if the result is only wanted as a polynomial
+with real coefficients to the precision I<prec>, or X<polzag>B<polzag>C<(n,m)>
+if the result is wanted exactly, where C<n> and C<m> are C<long>s.
+
+=head2 X<serconvol>serconvolC<(x,y)>
+
+convolution (or X<Hadamard product>Hadamard product) of the
+two power series C<x> and C<y>; in other words if C<x = >F<sum>C< a_k*X^k> and C<y = >F<sum>C<
+b_k*X^k> then C<serconvol(x,y) = >F<sum>C< a_k*b_k*X^k>.
+
+X<convol>The library syntax is B<convol>C<(x,y)>.
+
+=head2 X<serlaplace>serlaplaceC<(x)>
+
+C<x> must be a power series with only
+non-negative exponents. If C<x = >F<sum>C< (a_k/k!)*X^k> then the result is F<sum>C<
+a_k*X^k>.
+
+X<laplace>The library syntax is B<laplace>C<(x)>.
+
+=head2 X<serreverse>serreverseC<(x)>
+
+reverse power series (i.e.S< >C<x^{-1}>, not C<1/x>)
+of C<x>. C<x> must be a power series whose valuation is exactly equal to one.
+
+X<recip>The library syntax is B<recip>C<(x)>.
+
+=head2 X<subst>substC<(x,y,z)>
+
+replace the simple variable C<y> by the argument C<z> in the ``polynomial''
+expression C<x>. Every type is allowed for C<x>, but if it is not a genuine
+polynomial (or power series, or rational function), the substitution will be
+done as if the scalar components were polynomials of degree one. In
+particular, beware that:
+
+ ? subst(1, x, [1,2; 3,4])
+ %1 =
+ [1 0]
+
+ [0 1]
+
+ ? subst(1, x, Mat([0,1]))
+ *** forbidden substitution by a non square matrix
+
+If C<x> is a power series, C<z> must be either a polynomial, a power series, or
+a rational function. C<y> must be a simple variable name.
+
+X<gsubst>The library syntax is B<gsubst>C<(x,v,z)>, where C<v> is the number of
+the variable C<y>.
+
+=head2 X<taylor>taylorC<(x,y)>
+
+Taylor expansion around C<0> of C<x> with respect
+toX<Label se:taylor>
+the simple variable C<y>. C<x> can be of any reasonable type, for example a
+rational function. The number of terms of the expansion is transparent to the
+user under GP, but must be given as a second argument in library mode.
+
+X<tayl>The library syntax is B<tayl>C<(x,y,n)>, where the C<long> integer C<n> is the desired number of
+terms in the expansion.
+
+=head2 X<thue>thueC<(>I<tnf>C<,a,{>I<sol>C<})>
+
+solves the equation
+C<P(x,y) = a> in integers C<x> and C<y>, where I<tnf> was created with
+C<thueinit(P)>. I<sol>, if present, contains the solutions of
+C<Norm(x) = a> modulo units of positive norm in the number field
+defined by C<P> (as computed by C<bnfisintnorm>). If I<tnf> was
+computed without assuming X<GRH>GRH (I<flag>C< = 1> in C<thueinit>), the
+result is unconditional. For instance, here's how to solve the Thue
+equation C<x^{13} - 5y^{13} = - 4>:
+
+ ? tnf = thueinit(x^13 - 5);
+ ? thue(tnf, -4)
+ %1 = [[1, 1]]
+
+Hence, assuming GRH, the only solution is C<x = 1>, C<y = 1>.
+
+X<thue>The library syntax is B<thue>C<(>I<tnf>C<,a,>I<sol>C<)>, where an omitted I<sol> is coded
+as C<NULL>.
+
+=head2 X<thueinit>thueinitC<(P,{>I<flag>C< = 0})>
+
+initializes the I<tnf>
+corresponding to C<P>. It is meant to be used in conjunction with X<thue>C<thue>
+to solve Thue equations C<P(x,y) = a>, where C<a> is an integer. If I<flag> is
+non-zero, certify the result unconditionnaly, Otherwise, assume X<GRH>GRH,
+this being much faster of course.
+
+X<thueinit>The library syntax is B<thueinit>C<(P,>I<flag>C<,>I<prec>C<)>.
+
+=head1 Vectors, matrices, linear algebra and sets
+
+X<Label se:linear_algebra>
+Note that most linear algebra functions operating on subspaces defined by
+generating sets (such as X<mathnf>C<mathnf>, X<qflll>C<qflll>, etc.) take matrices as
+arguments. As usual, the generating vectors are taken to be the
+I<columns> of the given matrix.
+
+=head2 X<algdep>algdepC<(x,k,{>I<flag>C< = 0})>
+
+X<algebraic dependence>C<x> being
+real, complex, or C<p>-adic, finds a polynomial of degree at most C<k> with
+integer coefficients having C<x> as approximate root. Note that the polynomial
+which is obtained is not necessarily the ``correct'' one (it's not even
+guaranteed to be irreducible!). One can check the closeness either by a
+polynomial evaluation or substitution, or by computing the roots of the
+polynomial given by algdep.
+
+If C<x> is padic, I<flag> is meaningless and the algorithm LLL-reduces the
+``dual lattice'' corresponding to the powers of C<x>.
+
+Otherwise, if I<flag> is zero, the algorithm used is a variant of the X<LLL>LLL
+algorithm due to Hastad, Lagarias and Schnorr (STACS 1986). If the precision
+is too low, the routine may enter an infinite loop.
+
+If I<flag> is non-zero, use a standard LLL. I<flag> then indicates a precision,
+which should be between C<0.5> and C<1.0> times the number of decimal digits
+to which C<x> was computed.
+
+X<algdep0>The library syntax is B<algdep0>C<(x,k,>I<flag>C<,>I<prec>C<)>, where C<k> and I<flag> are C<long>s.
+Also available is X<algdep>B<algdep>C<(x,k,>I<prec>C<)> (I<flag>C< = 0>).
+
+=head2 X<charpoly>charpolyC<(A,{v = x},{>I<flag>C< = 0})>
+
+X<characteristic polynomial>characteristic polynomial
+of C<A> with respect to the variable C<v>, i.e.S< >determinant of C<v*I-A> if C<A>
+is a square matrix, determinant of the map ``multiplication by C<A>'' if C<A>
+is a scalar, in particular a polmod (e.g.S< >C<charpoly(I,x) = x^2+1>).
+Note that in the latter case, the X<minimal polynomial>minimal polynomial can be obtained
+as
+
+ minpoly(A)=
+ {
+ local(y);
+ y = charpoly(A);
+ y / gcd(y,y')
+ }
+
+The value of I<flag> is only significant for matrices.
+
+If I<flag>C< = 0>, the method used is essentially the same as for computing the
+adjoint matrix, i.e.S< >computing the traces of the powers of C<A>.
+
+If I<flag>C< = 1>, uses Lagrange interpolation which is almost always slower.
+
+If I<flag>C< = 2>, uses the Hessenberg form. This is faster than the default when
+the coefficients are integermod a prime or real numbers, but is usually
+slower in other base rings.
+
+X<charpoly0>The library syntax is B<charpoly0>C<(A,v,>I<flag>C<)>, where C<v> is the variable number. Also available
+are the functions X<caract>B<caract>C<(A,v)> (I<flag>C< = 1>), X<carhess>B<carhess>C<(A,v)>
+(I<flag>C< = 2>), and X<caradj>B<caradj>C<(A,v,>I<pt>C<)> where, in this last case,
+I<pt> is a C<GEN*> which, if not equal to C<NULL>, will receive
+the address of the adjoint matrix of C<A> (see C<matadjoint>), so both
+can be obtained at once.
+
+=head2 X<concat>concatC<(x,{y})>
+
+concatenation of C<x> and C<y>. If C<x> or C<y> is
+not a vector or matrix, it is considered as a one-dimensional vector. All
+types are allowed for C<x> and C<y>, but the sizes must be compatible. Note
+that matrices are concatenated horizontally, i.e.S< >the number of rows stays
+the same. Using transpositions, it is easy to concatenate them vertically.
+
+To concatenate vectors sideways (i.e.S< >to obtain a two-row or two-column
+matrix), first transform the vector into a one-row or one-column matrix using
+the function X<Mat>C<Mat>. Concatenating a row vector to a matrix having the
+same number of columns will add the row to the matrix (top row if the vector
+is C<x>, i.e.S< >comes first, and bottom row otherwise).
+
+The empty matrix C<[;]> is considered to have a number of rows compatible
+with any operation, in particular concatenation. (Note that this is
+definitely I<not> the case for empty vectors C<[S< >]> or C<[S< >]~>.)
+
+If C<y> is omitted, C<x> has to be a row vector or a list, in which case its
+elements are concatenated, from left to right, using the above rules.
+
+ ? concat([1,2], [3,4])
+ %1 = [1, 2, 3, 4]
+ ? a = [[1,2]~, [3,4]~]; concat(a)
+ %2 = [1, 2, 3, 4]~
+ ? a[1] = Mat(a[1]); concat(a)
+ %3 =
+ [1 3]
+
+ [2 4]
+
+ ? concat([1,2; 3,4], [5,6]~)
+ %4 =
+ [1 2 5]
+
+ [3 4 6]
+ ? concat([%, [7,8]~, [1,2,3,4]])
+ %5 =
+ [1 2 5 7]
+
+ [3 4 6 8]
+
+ [1 2 3 4]
+
+X<concat>The library syntax is B<concat>C<(x,y)>.
+
+=head2 X<lindep>lindepC<(x,{>I<flag>C< = 0})>
+
+X<linear dependence>C<x> being a
+vector with real or complex coefficients, finds a small integral linear
+combination among these coefficients.
+
+If I<flag>C< = 0>, uses a variant of the X<LLL>LLL algorithm due to Hastad, Lagarias
+and Schnorr (STACS 1986).
+
+If I<flag>C< E<gt> 0>, uses the LLL algorithm. I<flag> is a parameter which should be
+between one half the number of decimal digits of precision and that number
+(see C<algdep>).
+
+If I<flag>C< E<lt> 0>, returns as soon as one relation has been found.
+
+X<lindep0>The library syntax is B<lindep0>C<(x,>I<flag>C<,>I<prec>C<)>. Also available is
+X<lindep>B<lindep>C<(x,>I<prec>C<)> (I<flag>C< = 0>).
+
+=head2 X<listcreate>listcreateC<(n)>
+
+creates an empty list of maximal length C<n>.
+
+This function is useless in library mode.
+
+=head2 X<listinsert>listinsertC<(>I<list>C<,x,n)>
+
+inserts the object C<x> at
+position C<n> in I<list> (which must be of type C<t_LIST>). All the
+remaining elements of I<list> (from position C<n+1> onwards) are shifted
+to the right. This and C<listput> are the only commands which enable
+you to increase a list's effective length (as long as it remains under
+the maximal length specified at the time of the C<listcreate>).
+
+This function is useless in library mode.
+
+=head2 X<listkill>listkillC<(>I<list>C<)>
+
+kill I<list>. This deletes all
+elements from I<list> and sets its effective length to C<0>. The maximal
+length is not affected.
+
+This function is useless in library mode.
+
+=head2 X<listput>listputC<(>I<list>C<,x,{n})>
+
+sets the C<n>-th element of the list
+I<list> (which must be of type C<t_LIST>) equal to C<x>. If C<n> is omitted,
+or greater than the list current effective length, just appends C<x>. This and
+C<listinsert> are the only commands which enable you to increase a list's
+effective length (as long as it remains under the maximal length specified at
+the time of the C<listcreate>).
+
+If you want to put an element into an occupied cell, i.e.S< >if you don't want to
+change the effective length, you can consider the list as a vector and use
+the usual C<list[n] = x> construct.
+
+This function is useless in library mode.
+
+=head2 X<listsort>listsortC<(>I<list>C<,{>I<flag>C< = 0})>
+
+sorts I<list> (which must
+be of type C<t_LIST>) in place. If I<flag> is non-zero, suppresses all repeated
+coefficients. This is much faster than the C<vecsort> command since no
+copy has to be made.
+
+This function is useless in library mode.
+
+=head2 X<matadjoint>matadjointC<(x)>
+
+X<adjoint matrix>adjoint matrix of C<x>, i.e.S< >the matrix C<y>
+of cofactors of C<x>, satisfying C<x*y = > F<det> C<(x)*Id>. C<x> must be a
+(non-necessarily invertible) square matrix.
+
+X<adj>The library syntax is B<adj>C<(x)>.
+
+=head2 X<matcompanion>matcompanionC<(x)>
+
+the left companion matrix to the polynomial C<x>.
+
+X<assmat>The library syntax is B<assmat>C<(x)>.
+
+=head2 X<matdet>matdetC<(x,{>I<flag>C< = 0})>
+
+determinant of C<x>. C<x> must be a
+square matrix.
+
+If I<flag>C< = 0>, uses Gauss-Bareiss.
+
+If I<flag>C< = 1>, uses classical Gaussian elimination, which is better when the
+entries of the matrix are reals or integers for example, but usually much
+worse for more complicated entries like multivariate polynomials.
+
+X<det>The library syntax is B<det>C<(x)> (I<flag>C< = 0>) and X<det2>B<det2>C<(x)>
+(I<flag>C< = 1>).
+
+=head2 X<matdetint>matdetintC<(x)>
+
+C<x> being an C<m x n> matrix with integer
+coefficients, this function computes a multiple of the determinant of the
+lattice generated by the columns of C<x> if it is of rank C<m>, and returns
+zero otherwise. This function can be useful in conjunction with the function
+C<mathnfmod> which needs to know such a multiple. Other ways to obtain
+this determinant (assuming the rank is maximal) is
+C<matdet(qflll(x,4)[2]*x)> or more simply C<matdet(mathnf(x))>.
+Experiment to see which is faster for your applications.
+
+X<detint>The library syntax is B<detint>C<(x)>.
+
+=head2 X<matdiagonal>matdiagonalC<(x)>
+
+C<x> being a vector, creates the diagonal matrix
+whose diagonal entries are those of C<x>.
+
+X<diagonal>The library syntax is B<diagonal>C<(x)>.
+
+=head2 X<mateigen>mateigenC<(x)>
+
+gives the eigenvectors of C<x> as columns of a
+matrix.
+
+X<eigen>The library syntax is B<eigen>C<(x)>.
+
+=head2 X<mathess>mathessC<(x)>
+
+Hessenberg form of the square matrix C<x>.
+
+X<hess>The library syntax is B<hess>C<(x)>.
+
+=head2 X<mathilbert>mathilbertC<(x)>
+
+C<x> being a C<long>, creates the
+X<Hilbert matrix>Hilbert
+matrix of order C<x>, i.e.S< >the matrix whose coefficient (C<i>,C<j>) is C<1/
+(i+j-1)>.
+
+X<mathilbert>The library syntax is B<mathilbert>C<(x)>.
+
+=head2 X<mathnf>mathnfC<(x,{>I<flag>C< = 0})>
+
+if C<x> is a (not necessarily square)
+matrix of maximal rank, finds the I<upper triangular>
+X<Hermite normal form>Hermite normal form of C<x>. If the rank of C<x> is equal to its number
+of rows, the result is a square matrix. In general, the columns of the
+result form a basis of the lattice spanned by the columns of C<x>.
+
+If I<flag>C< = 0>, uses the naive algorithm. If the B<Z>-module generated by the
+columns is a lattice, it is recommanded to use
+C<mathnfmod(x, matdetint(x))> instead (much faster).
+
+If I<flag>C< = 1>, uses Batut's algorithm. Outputs a two-component row vector
+C<[H,U]>, where C<H> is the I<upper triangular> Hermite normal form
+of C<x> (i.e.S< >the default result) and C<U> is the unimodular transformation
+matrix such that C<xU = [0|H]>. If the rank of C<x> is equal to its number of
+rows, C<H> is a square matrix. In general, the columns of C<H> form a basis
+of the lattice spanned by the columns of C<x>.
+
+If I<flag>C< = 2>, uses Havas's algorithm. Outputs C<[H,U,P]>, such that
+C<H> and C<U> are as before and C<P> is a permutation of the rows such that C<P>
+applied to C<xU> gives C<H>. This does not work very well in present version
+B<2.2.0>.
+
+If I<flag>C< = 3>, uses Batut's algorithm, and outputs C<[H,U,P]> as in the previous
+case.
+
+If I<flag>C< = 4>, as in case 1 above, but uses X<LLL>LLL reduction along the way.
+
+X<mathnf0>The library syntax is B<mathnf0>C<(x,>I<flag>C<)>. Also available are X<hnf>B<hnf>C<(x)> (I<flag>C< = 0>) and
+X<hnfall>B<hnfall>C<(x)> (I<flag>C< = 1>). To reduce I<huge> (say C<400 x 400> and
+more) relation matrices (sparse with small entries), you can use the pair
+C<hnfspec> / C<hnfadd>. Since this is rather technical and the
+calling interface may change, they are not documented yet. Look at the code
+in C<basemath/alglin1.c>.
+
+=head2 X<mathnfmod>mathnfmodC<(x,d)>
+
+if C<x> is a (not necessarily square) matrix of
+maximal rank with integer entries, and C<d> is a multiple of the (non-zero)
+determinant of the lattice spanned by the columns of C<x>, finds the
+I<upper triangular> X<Hermite normal form>Hermite normal form of C<x>.
+
+If the rank of C<x> is equal to its number of rows, the result is a square
+matrix. In general, the columns of the result form a basis of the lattice
+spanned by the columns of C<x>. This is much faster than C<mathnf> when C<d>
+is known.
+
+X<hnfmod>The library syntax is B<hnfmod>C<(x,d)>.
+
+=head2 X<mathnfmodid>mathnfmodidC<(x,d)>
+
+outputs the (upper triangular)
+X<Hermite normal form>Hermite normal form of C<x> concatenated with C<d> times
+the identity matrix.
+
+X<hnfmodid>The library syntax is B<hnfmodid>C<(x,d)>.
+
+=head2 X<matid>matidC<(n)>
+
+creates the C<n x n> identity matrix.
+
+X<idmat>The library syntax is B<idmat>C<(n)> where C<n> is a C<long>.
+
+Related functions are X<gscalmat>B<gscalmat>C<(x,n)>, which creates C<x> times the
+identity matrix (C<x> being a C<GEN> and C<n> a C<long>), and
+X<gscalsmat>B<gscalsmat>C<(x,n)> which is the same when C<x> is a C<long>.
+
+=head2 X<matimage>matimageC<(x,{>I<flag>C< = 0})>
+
+gives a basis for the image of the
+matrix C<x> as columns of a matrix. A priori the matrix can have entries of
+any type. If I<flag>C< = 0>, use standard Gauss pivot. If I<flag>C< = 1>, use
+C<matsupplement>.
+
+X<matimage0>The library syntax is B<matimage0>C<(x,>I<flag>C<)>. Also available is X<image>B<image>C<(x)> (I<flag>C< = 0>).
+
+=head2 X<matimagecompl>matimagecomplC<(x)>
+
+gives the vector of the column indices which
+are not extracted by the function C<matimage>. Hence the number of
+components of C<matimagecompl(x)> plus the number of columns of
+C<matimage(x)> is equal to the number of columns of the matrix C<x>.
+
+X<imagecompl>The library syntax is B<imagecompl>C<(x)>.
+
+=head2 X<matindexrank>matindexrankC<(x)>
+
+C<x> being a matrix of rank C<r>, gives two
+vectors C<y> and C<z> of length C<r> giving a list of rows and columns
+respectively (starting from 1) such that the extracted matrix obtained from
+these two vectors using X<vecextract>C<vecextract(x,y,z)> is invertible.
+
+X<indexrank>The library syntax is B<indexrank>C<(x)>.
+
+=head2 X<matintersect>matintersectC<(x,y)>
+
+C<x> and C<y> being two matrices with the same
+number of rows each of whose columns are independent, finds a basis of the
+B<Q>-vector space equal to the intersection of the spaces spanned by the
+columns of C<x> and C<y> respectively. See also the function
+X<idealintersect>C<idealintersect>, which does the same for free B<Z>-modules.
+
+X<intersect>The library syntax is B<intersect>C<(x,y)>.
+
+=head2 X<matinverseimage>matinverseimageC<(x,y)>
+
+gives a column vector belonging to the
+inverse image of the column vector C<y> by the matrix C<x> if one exists, the
+empty vector otherwise. To get the complete inverse image, it suffices to add
+to the result any element of the kernel of C<x> obtained for example by
+C<matker>.
+
+X<inverseimage>The library syntax is B<inverseimage>C<(x,y)>.
+
+=head2 X<matisdiagonal>matisdiagonalC<(x)>
+
+returns true (1) if C<x> is a diagonal matrix,
+false (0) if not.
+
+X<isdiagonal>The library syntax is B<isdiagonal>C<(x)>, and this returns a C<long>
+integer.
+
+=head2 X<matker>matkerC<(x,{>I<flag>C< = 0})>
+
+gives a basis for the kernel of the
+matrix C<x> as columns of a matrix. A priori the matrix can have entries of
+any type.
+
+If C<x> is known to have integral entries, set I<flag>C< = 1>.
+
+Note: The library function X<ker_mod_p>C<ker_mod_p(x, p)>, where C<x> has
+integer entries and C<p> is prime, which is equivalent to but many orders of
+magnitude faster than C<matker(x*Mod(1,p))> and needs much less stack
+space. To use it under GP, type C<install(ker_mod_p, GG)> first.
+
+X<matker0>The library syntax is B<matker0>C<(x,>I<flag>C<)>. Also available are X<ker>B<ker>C<(x)> (I<flag>C< = 0>),
+X<keri>B<keri>C<(x)> (I<flag>C< = 1>) and C<ker_mod_p(x,p)>.
+
+=head2 X<matkerint>matkerintC<(x,{>I<flag>C< = 0})>
+
+gives an X<LLL>LLL-reduced B<Z>-basis
+for the lattice equal to the kernel of the matrix C<x> as columns of the
+matrix C<x> with integer entries (rational entries are not permitted).
+
+If I<flag>C< = 0>, uses a modified integer LLL algorithm.
+
+If I<flag>C< = 1>, uses C<matrixqz(x,-2)>. If LLL reduction of the final result
+is not desired, you can save time using C<matrixqz(matker(x),-2)> instead.
+
+If I<flag>C< = 2>, uses another modified LLL. In the present version B<2.2.0>, only
+independent rows are allowed in this case.
+
+X<matkerint0>The library syntax is B<matkerint0>C<(x,>I<flag>C<)>. Also available is
+X<kerint>B<kerint>C<(x)> (I<flag>C< = 0>).
+
+=head2 X<matmuldiagonal>matmuldiagonalC<(x,d)>
+
+product of the matrix C<x> by the diagonal
+matrix whose diagonal entries are those of the vector C<d>. Equivalent to,
+but much faster than C<x*matdiagonal(d)>.
+
+X<matmuldiagonal>The library syntax is B<matmuldiagonal>C<(x,d)>.
+
+=head2 X<matmultodiagonal>matmultodiagonalC<(x,y)>
+
+product of the matrices C<x> and C<y>
+knowing that the result is a diagonal matrix. Much faster than C<x*y> in
+that case.
+
+X<matmultodiagonal>The library syntax is B<matmultodiagonal>C<(x,y)>.
+
+=head2 X<matpascal>matpascalC<(x,{q})>
+
+creates as a matrix the lower triangular
+X<Pascal triangle>Pascal triangle of order C<x+1> (i.e.S< >with binomial coefficients
+up to C<x>). If C<q> is given, compute the C<q>-Pascal triangle (i.e.S< >using
+C<q>-binomial coefficients).
+
+X<matqpascal>The library syntax is B<matqpascal>C<(x,q)>, where C<x> is a C<long> and C<q = NULL> is used
+to omit C<q>. Also available is X<matpascal>B<matpascal>{x}.
+
+=head2 X<matrank>matrankC<(x)>
+
+rank of the matrix C<x>.
+
+X<rank>The library syntax is B<rank>C<(x)>, and the result is a C<long>.
+
+=head2 X<matrix>matrixC<(m,n,{X},{Y},{>I<expr>C< = 0})>
+
+creation of the
+C<m x n> matrix whose coefficients are given by the expression
+I<expr>. There are two formal parameters in I<expr>, the first one
+(C<X>) corresponding to the rows, the second (C<Y>) to the columns, and C<X>
+goes from 1 to C<m>, C<Y> goes from 1 to C<n>. If one of the last 3 parameters
+is omitted, fill the matrix with zeroes.
+
+X<matrice>The library syntax is B<matrice>C<(GEN nlig,GEN ncol,entree *e1,entree *e2,char *expr)>.
+
+=head2 X<matrixqz>matrixqzC<(x,p)>
+
+C<x> being an C<m x n> matrix with C<m E<gt>= n>
+with rational or integer entries, this function has varying behaviour
+depending on the sign of C<p>:
+
+If C<p E<gt>= 0>, C<x> is assumed to be of maximal rank. This function returns a
+matrix having only integral entries, having the same image as C<x>, such that
+the GCD of all its C<n x n> subdeterminants is equal to 1 when C<p> is
+equal to 0, or not divisible by C<p> otherwise. Here C<p> must be a prime
+number (when it is non-zero). However, if the function is used when C<p> has
+no small prime factors, it will either work or give the message ``impossible
+inverse modulo'' and a non-trivial divisor of C<p>.
+
+If C<p = -1>, this function returns a matrix whose columns form a basis of the
+lattice equal to B<Z>C<^n> intersected with the lattice generated by the
+columns of C<x>.
+
+If C<p = -2>, returns a matrix whose columns form a basis of the lattice equal
+to B<Z>C<^n> intersected with the B<Q>-vector space generated by the
+columns of C<x>.
+
+X<matrixqz0>The library syntax is B<matrixqz0>C<(x,p)>.
+
+=head2 X<matsize>matsizeC<(x)>
+
+C<x> being a vector or matrix, returns a row vector
+with two components, the first being the number of rows (1 for a row vector),
+the second the number of columns (1 for a column vector).
+
+X<matsize>The library syntax is B<matsize>C<(x)>.
+
+=head2 X<matsnf>matsnfC<(X,{>I<flag>C< = 0})>
+
+if C<X> is a (singular or non-singular)
+square matrix outputs the vector of elementary divisors of C<X> (i.e.S< >the
+diagonal of the X<Smith normal form>Smith normal form of C<X>).
+
+The binary digits of I<flag> mean:
+
+1 (complete output): if set, outputs C<[U,V,D]>, where C<U> and C<V> are two
+unimodular matrices such that C<UXV> is the diagonal matrix C<D>. Otherwise
+output only the diagonal of C<D>.
+
+2 (generic input): if set, allows polynomial entries. Otherwise, assume
+that C<X> has integer coefficients.
+
+4 (cleanup): if set, cleans up the output. This means that elementary
+divisors equal to C<1> will be deleted, i.e.S< >outputs a shortened vector C<D'>
+instead of C<D>. If complete output was required, returns C<[U',V',D']> so
+that C<U'XV' = D'> holds. If this flag is set, C<X> is allowed to be of the
+form C<D> or C<[U,V,D]> as would normally be output with the cleanup flag
+unset.
+
+X<matsnf0>The library syntax is B<matsnf0>C<(X,>I<flag>C<)>. Also available is X<smith>B<smith>C<(X)> (I<flag>C< = 0>).
+
+=head2 X<matsolve>matsolveC<(x,y)>
+
+C<x> being an invertible matrix and C<y> a column
+vector, finds the solution C<u> of C<x*u = y>, using Gaussian elimination. This
+has the same effect as, but is a bit faster, than C<x^{-1}*y>.
+
+X<gauss>The library syntax is B<gauss>C<(x,y)>.
+
+=head2 X<matsolvemod>matsolvemodC<(m,d,y,{>I<flag>C< = 0})>
+
+C<m> being any integral matrix,
+C<d> a vector of positive integer moduli, and C<y> an integral
+column vector, gives a small integer solution to the system of congruences
+F<sum>C<_i m_{i,j}x_j = y_i (mod d_i)> if one exists, otherwise returns
+zero. Shorthand notation: C<y> (resp.S< >C<d>) can be given as a single integer,
+in which case all the C<y_i> (resp.S< >C<d_i>) above are taken to be equal to C<y>
+(resp.S< >C<d>).
+
+If I<flag>C< = 1>, all solutions are returned in the form of a two-component row
+vector C<[x,u]>, where C<x> is a small integer solution to the system of
+congruences and C<u> is a matrix whose columns give a basis of the homogeneous
+system (so that all solutions can be obtained by adding C<x> to any linear
+combination of columns of C<u>). If no solution exists, returns zero.
+
+X<matsolvemod0>The library syntax is B<matsolvemod0>C<(m,d,y,>I<flag>C<)>. Also available
+are X<gaussmodulo>B<gaussmodulo>C<(m,d,y)> (I<flag>C< = 0>)
+and X<gaussmodulo2>B<gaussmodulo2>C<(m,d,y)> (I<flag>C< = 1>).
+
+=head2 X<matsupplement>matsupplementC<(x)>
+
+assuming that the columns of the matrix C<x>
+are linearly independent (if they are not, an error message is issued), finds
+a square invertible matrix whose first columns are the columns of C<x>,
+i.e.S< >supplement the columns of C<x> to a basis of the whole space.
+
+X<suppl>The library syntax is B<suppl>C<(x)>.
+
+=head2 X<mattranspose>mattransposeC<(x)> or C<x~>
+
+transpose of C<x>.
+This has an effect only on vectors and matrices.
+
+X<gtrans>The library syntax is B<gtrans>C<(x)>.
+
+=head2 X<qfgaussred>qfgaussredC<(q)>
+
+X<decomposition into squares>decomposition into squares of the
+quadratic form represented by the symmetric matrix C<q>. The result is a
+matrix whose diagonal entries are the coefficients of the squares, and the
+non-diagonal entries represent the bilinear forms. More precisely, if
+C<(a_{ij})> denotes the output, one has
+
+S< >C< q(x) = >F<sum>C<_i a_{ii} (x_i + >F<sum>C<_{j E<gt> i} a_{ij} x_j)^2 >
+
+X<sqred>The library syntax is B<sqred>C<(x)>.
+
+=head2 X<qfjacobi>qfjacobiC<(x)>
+
+C<x> being a real symmetric matrix, this gives a
+vector having two components: the first one is the vector of eigenvalues of
+C<x>, the second is the corresponding orthogonal matrix of eigenvectors of
+C<x>. The method used is Jacobi's method for symmetric matrices.
+
+X<jacobi>The library syntax is B<jacobi>C<(x)>.
+
+=head2 X<qflll>qflllC<(x,{>I<flag>C< = 0})>
+
+X<LLL>LLL algorithm applied to the
+I<columns> of the (not necessarily square) matrix C<x>. The columns of C<x>
+must however be linearly independent, unless specified otherwise below. The
+result is a transformation matrix C<T> such that C<x.T> is an LLL-reduced
+basis of the lattice generated by the column vectors of C<x>.
+
+If I<flag>C< = 0> (default), the computations are done with real numbers (i.e.S< >not
+with rational numbers) hence are fast but as presently programmed (version
+B<2.2.0>) are numerically unstable.
+
+If I<flag>C< = 1>, it is assumed that the corresponding Gram matrix is integral.
+The computation is done entirely with integers and the algorithm is both
+accurate and quite fast. In this case, C<x> needs not be of maximal rank, but
+if it is not, C<T> will not be square.
+
+If I<flag>C< = 2>, similar to case 1, except C<x> should be an integer matrix whose
+columns are linearly independent. The lattice generated by the columns of
+C<x> is first partially reduced before applying the LLL algorithm. [A basis
+is said to be I<partially reduced> if C<|v_i F<+-> v_j| E<gt>= |v_i|> for any
+two distinct basis vectors C<v_i, v_j>.]
+
+This can be significantly faster than I<flag>C< = 1> when one row is huge compared
+to the other rows.
+
+If I<flag>C< = 3>, all computations are done in rational numbers. This does not
+incur numerical instability, but is extremely slow. This function is
+essentially superseded by case 1, so will soon disappear.
+
+If I<flag>C< = 4>, C<x> is assumed to have integral entries, but needs not be of
+maximal rank. The result is a two-component vector of matricesS< >: the
+columns of the first matrix represent a basis of the integer kernel of C<x>
+(not necessarily LLL-reduced) and the second matrix is the transformation
+matrix C<T> such that C<x.T> is an LLL-reduced B<Z>-basis of the image
+of the matrix C<x>.
+
+If I<flag>C< = 5>, case as case C<4>, but C<x> may have polynomial coefficients.
+
+If I<flag>C< = 7>, uses an older version of case C<0> above.
+
+If I<flag>C< = 8>, same as case C<0>, where C<x> may have polynomial coefficients.
+
+If I<flag>C< = 9>, variation on case C<1>, using content.
+
+X<qflll0>The library syntax is B<qflll0>C<(x,>I<flag>C<,>I<prec>C<)>. Also available are
+X<lll>B<lll>C<(x,>I<prec>C<)> (I<flag>C< = 0>), X<lllint>B<lllint>C<(x)> (I<flag>C< = 1>), and
+X<lllkerim>B<lllkerim>C<(x)> (I<flag>C< = 4>).
+
+=head2 X<qflllgram>qflllgramC<(x,{>I<flag>C< = 0})>
+
+same as C<qflll> except that the
+matrix C<x> which must now be a square symmetric real matrix is the Gram
+matrix of the lattice vectors, and not the coordinates of the vectors
+themselves. The result is again the transformation matrix C<T> which gives (as
+columns) the coefficients with respect to the initial basis vectors. The
+flags have more or less the same meaning, but some are missing. In brief:
+
+I<flag>C< = 0>: numerically unstable in the present version B<2.2.0>.
+
+I<flag>C< = 1>: C<x> has integer entries, the computations are all done in integers.
+
+I<flag>C< = 4>: C<x> has integer entries, gives the kernel and reduced image.
+
+I<flag>C< = 5>: same as C<4> for generic C<x>.
+
+I<flag>C< = 7>: an older version of case C<0>.
+
+X<qflllgram0>The library syntax is B<qflllgram0>C<(x,>I<flag>C<,>I<prec>C<)>. Also available are
+X<lllgram>B<lllgram>C<(x,>I<prec>C<)> (I<flag>C< = 0>), X<lllgramint>B<lllgramint>C<(x)> (I<flag>C< = 1>), and
+X<lllgramkerim>B<lllgramkerim>C<(x)> (I<flag>C< = 4>).
+
+=head2 X<qfminim>qfminimC<(x,b,m,{>I<flag>C< = 0})>
+
+C<x> being a square and symmetric
+matrix representing a positive definite quadratic form, this function
+deals with the minimal vectors of C<x>, depending on I<flag>.
+
+If I<flag>C< = 0> (default), seeks vectors of square norm less than or equal to C<b>
+(for the norm defined by C<x>), and at most C<2m> of these vectors. The result
+is a three-component vector, the first component being the number of vectors,
+the second being the maximum norm found, and the last vector is a matrix
+whose columns are the vectors found, only one being given for each
+pair C<F<+-> v> (at most C<m> such pairs).
+
+If I<flag>C< = 1>, ignores C<m> and returns the first vector whose norm is less than
+C<b>.
+
+In both these cases, C<x> I<is assumed to have integral entries>, and the
+function searches for the minimal non-zero vectors whenever C<b = 0>.
+
+If I<flag>C< = 2>, C<x> can have non integral real entries, but C<b = 0> is now
+meaningless (uses Fincke-Pohst algorithm).
+
+X<qfminim0>The library syntax is B<qfminim0>C<(x,b,m,>I<flag>C<,>I<prec>C<)>, also available are B<minim>C<(x,b,m)>X<minim>
+(I<flag>C< = 0>), B<minim2>C<(x,b,m)>X<minim2> (I<flag>C< = 1>), and finally
+ B<fincke_pohst>C<(x,b,m,>I<prec>C<)>X<fincke_pohst> (I<flag>C< = 2>).
+
+=head2 X<qfperfection>qfperfectionC<(x)>
+
+C<x> being a square and symmetric matrix with
+integer entries representing a positive definite quadratic form, outputs the
+perfection rank of the form. That is, gives the rank of the family of the C<s>
+symmetric matrices C<v_iv_i^t>, where C<s> is half the number of minimal
+vectors and the C<v_i> (C<1 E<lt>= i E<lt>= s>) are the minimal vectors.
+
+As a side note to old-timers, this used to fail bluntly when C<x> had more
+than C<5000> minimal vectors. Beware that the computations can now be very
+lengthy when C<x> has many minimal vectors.
+
+X<perf>The library syntax is B<perf>C<(x)>.
+
+=head2 X<qfsign>qfsignC<(x)>
+
+signature of the quadratic form represented by the
+symmetric matrix C<x>. The result is a two-component vector.
+
+X<signat>The library syntax is B<signat>C<(x)>.
+
+=head2 X<setintersect>setintersectC<(x,y)>
+
+intersection of the two sets C<x> and C<y>.
+
+X<setintersect>The library syntax is B<setintersect>C<(x,y)>.
+
+=head2 X<setisset>setissetC<(x)>
+
+returns true (1) if C<x> is a set, false (0) if
+not. In PARI, a set is simply a row vector whose entries are strictly
+increasing. To convert any vector (and other objects) into a set, use the
+function C<Set>.
+
+X<setisset>The library syntax is B<setisset>C<(x)>, and this returns a C<long>.
+
+=head2 X<setminus>setminusC<(x,y)>
+
+difference of the two sets C<x> and C<y>,
+i.e.S< >set of elements of C<x> which do not belong to C<y>.
+
+X<setminus>The library syntax is B<setminus>C<(x,y)>.
+
+=head2 X<setsearch>setsearchC<(x,y,{>I<flag>C< = 0})>
+
+searches if C<y> belongs to the set
+C<x>. If it does and I<flag> is zero or omitted, returns the index C<j> such that
+C<x[j] = y>, otherwise returns 0. If I<flag> is non-zero returns the index C<j>
+where C<y> should be inserted, and C<0> if it already belongs to C<x> (this is
+meant to be used in conjunction with C<listinsert>).
+
+This function works also if C<x> is a I<sorted> list (see C<listsort>).
+
+X<setsearch>The library syntax is B<setsearch>C<(x,y,>I<flag>C<)> which returns a C<long>
+integer.
+
+=head2 X<setunion>setunionC<(x,y)>
+
+union of the two sets C<x> and C<y>.
+
+X<setunion>The library syntax is B<setunion>C<(x,y)>.
+
+=head2 X<trace>traceC<(x)>
+
+this applies to quite general C<x>. If C<x> is not a
+matrix, it is equal to the sum of C<x> and its conjugate, except for polmods
+where it is the trace as an algebraic number.
+
+For C<x> a square matrix, it is the ordinary trace. If C<x> is a
+non-square matrix (but not a vector), an error occurs.
+
+X<gtrace>The library syntax is B<gtrace>C<(x)>.
+
+=head2 X<vecextract>vecextractC<(x,y,{z})>
+
+extraction of components of the
+vector or matrix C<x> according to C<y>. In case C<x> is a matrix, its
+components are as usual the I<columns> of C<x>. The parameter C<y> is a
+component specifier, which is either an integer, a string describing a
+range, or a vector.
+
+If C<y> is an integer, it is considered as a mask: the binary bits of C<y> are
+read from right to left, but correspond to taking the components from left to
+right. For example, if C<y = 13 = (1101)_2> then the components 1,3 and 4 are
+extracted.
+
+If C<y> is a vector, which must have integer entries, these entries correspond
+to the component numbers to be extracted, in the order specified.
+
+If C<y> is a string, it can be
+
+B<*> a single (non-zero) index giving a component number (a negative
+index means we start counting from the end).
+
+B<*> a range of the form C<"a..b">, where C<a> and C<b> are
+indexes as above. Any of C<a> and C<b> can be omitted; in this case, we take
+as default values C<a = 1> and C<b = -1>, i.e.S< >the first and last components
+respectively. We then extract all components in the interval C<[a,b]>, in
+reverse order if C<b E<lt> a>.
+
+In addition, if the first character in the string is C<^>, the
+complement of the given set of indices is taken.
+
+If C<z> is not omitted, C<x> must be a matrix. C<y> is then the I<line>
+specifier, and C<z> the I<column> specifier, where the component specifier
+is as explained above.
+
+ ? v = [a, b, c, d, e];
+ ? vecextract(v, 5) \\ mask
+ %1 = [a, c]
+ ? vecextract(v, [4, 2, 1]) \\ component list
+ %2 = [d, b, a]
+ ? vecextract(v, "2..4") \\ interval
+ %3 = [b, c, d]
+ ? vecextract(v, "-1..-3") \\ interval + reverse order
+ %4 = [e, d, c]
+ ? vecextract([1,2,3], "^2") \\ complement
+ %5 = [1, 3]
+ ? vecextract(matid(3), "2..", "..")
+ %6 =
+ [0 1 0]
+
+ [0 0 1]
+
+X<extract>The library syntax is B<extract>C<(x,y)> or X<matextract>B<matextract>C<(x,y,z)>.
+
+=head2 X<vecsort>vecsortC<(x,{k},{>I<flag>C< = 0})>
+
+sorts the vector C<x> in ascending
+order, using the heapsort method. C<x> must be a vector, and its components
+integers, reals, or fractions.
+
+If C<k> is present and is an integer, sorts according to the value of the
+C<k>-th subcomponents of the components ofS< >C<x>. C<k> can also be a vector,
+in which case the
+sorting is done lexicographically according to the components listed in the
+vector C<k>. For example, if C<k = [2,1,3]>, sorting will be done with respect
+to the second component, and when these are equal, with respect to the
+first, and when these are equal, with respect to the third.
+
+The binary digits of I<flag> mean:
+
+B<*> 1: indirect sorting of the vector C<x>, i.e.S< >if C<x> is an
+C<n>-component vector, returns a permutation of C<[1,2,...,n]> which
+applied to the components of C<x> sorts C<x> in increasing order.
+For example, C<vecextract(x, vecsort(x,,1))> is equivalent to
+C<vecsort(x)>.
+
+B<*> 2: sorts C<x> by ascending lexicographic order (as per the
+C<lex> comparison function).
+
+B<*> 4: use decreasing instead of ascending order.
+
+X<vecsort0>The library syntax is B<vecsort0>C<(x,k,flag)>. To omit C<k>, use C<NULL> instead. You can also
+use the simpler functions
+
+X<sort>B<sort>C<(x)> ( = C<vecsort0(x,NULL,0)>).
+
+X<indexsort>B<indexsort>C<(x)> ( = C<vecsort0(x,NULL,1)>).
+
+X<lexsort>B<lexsort>C<(x)> ( = C<vecsort0(x,NULL,2)>).
+
+Also available are X<sindexsort>B<sindexsort> and X<sindexlexsort>B<sindexlexsort> which return a
+vector of C-long integers (private type C<t_VECSMALL>) C<v>, where
+C<v[1]...v[n]> contain the indices. Note that the resulting C<v> is
+I<not> a generic PARI object, but is in general easier to use in C
+programs!
+
+=head2 X<vector>vectorC<(n,{X},{>I<expr>C< = 0})>
+
+creates a row vector (type
+C<t_VEC>) with C<n> components whose components are the expression
+I<expr> evaluated at the integer points between 1 and C<n>. If one of the
+last two arguments is omitted, fill the vector with zeroes.
+
+X<vecteur>The library syntax is B<vecteur>C<(GEN nmax, entree *ep, char *expr)>.
+
+=head2 X<vectorv>vectorvC<(n,X,>I<expr>C<)>
+
+as X<vector>B<vector>, but returns a
+column vector (type C<t_COL>).
+
+X<vvecteur>The library syntax is B<vvecteur>C<(GEN nmax, entree *ep, char *expr)>.
+
+=head1 Sums, products, integrals and similar functions
+
+X<Label se:sums>
+Although the GP calculator is programmable, it is useful to have
+preprogrammed a number of loops, including sums, products, and a certain
+number of recursions. Also, a number of functions from numerical analysis
+like numerical integration and summation of series will be described here.
+
+One of the parameters in these loops must be the control variable, hence a
+simple variable name. The last parameter can be any legal PARI expression,
+including of course expressions using loops. Since it is much easier to
+program directly the loops in library mode, these functions are mainly
+useful for GP programming. The use of these functions in library mode is a
+little tricky and its explanation will be mostly omitted, although the
+reader can try and figure it out by himself by checking the example given
+for the X<sum>C<sum> function. In this section we only give the library
+syntax, with no semantic explanation.
+
+The letter C<X> will always denote any simple variable name, and represents
+the formal parameter used in the function.
+
+B<(numerical) integration>:X<numerical integration> A number
+of Romberg-like integration methods are implemented (see C<intnum> as
+opposed to C<intformal> which we already described). The user should not
+require too much accuracy: 18 or 28 decimal digits is OK, but not much more.
+In addition, analytical cleanup of the integral must have been done: there
+must be no singularities in the interval or at the boundaries. In practice
+this can be accomplished with a simple change of variable. Furthermore, for
+improper integrals, where one or both of the limits of integration are plus
+or minus infinity, the function must decrease sufficiently rapidly at
+infinity. This can often be accomplished through integration by parts.
+Finally, the function to be integrated should not be very small
+(compared to the current precision) on the entire interval. This can
+of course be accomplished by just multiplying by an appropriate
+constant.
+
+Note that X<infinity>infinity can be represented with essentially no loss of
+accuracy by 1e4000. However beware of real underflow when dealing with
+rapidly decreasing functions. For example, if one wants to compute the
+F<int>C<_0^ oo e^{-x^2}dx> to 28 decimal digits, then one should set
+infinity equal to 10 for example, and certainly not to 1e4000.
+
+The integrand may have values belonging to a vector space over the real
+numbers; in particular, it can be complex-valued or vector-valued.
+
+See also the discrete summation methods below (sharing the prefix C<sum>).
+
+=head2 X<intnum>intnumC<(X = a,b,>I<expr>C<,{>I<flag>C< = 0})>
+
+numerical integration of
+I<expr> (smooth in C<]a,b[>), with respect to C<X>.
+
+Set I<flag>C< = 0> (or omit it altogether) when C<a> and C<b> are not too large, the
+function is smooth, and can be evaluated exactly everywhere on the interval
+C<[a,b]>.
+
+If I<flag>C< = 1>, uses a general driver routine for doing numerical integration,
+making no particular assumption (slow).
+
+I<flag>C< = 2> is tailored for being used when C<a> or C<b> are infinite. One
+I<must> have C<ab E<gt> 0>, and in fact if for example C<b = + oo >, then it is
+preferable to have C<a> as large as possible, at least C<a E<gt>= 1>.
+
+If I<flag>C< = 3>, the function is allowed to be undefined (but continuous) at C<a>
+or C<b>, for example the function F<sin> C<(x)/x> at C<x = 0>.
+
+X<intnum0>The library syntax is B<intnum0>C<(entree*e,GEN a,GEN b,char*expr,long >I<flag>C<,long prec)>.
+
+=head2 X<prod>prodC<(X = a,b,>I<expr>C<,{x = 1})>
+
+product of expression I<expr>,
+initialized at C<x>, the formal parameter C<X> going from C<a> to C<b>. As for
+C<sum>, the main purpose of the initialization parameter C<x> is to force
+the type of the operations being performed. For example if it is set equal to
+the integer 1, operations will start being done exactly. If it is set equal
+to the real C<1.>, they will be done using real numbers having the default
+precision. If it is set equal to the power series C<1+O(X^k)> for a certain
+C<k>, they will be done using power series of precision at most C<k>. These
+are the three most common initializations.
+
+As an extreme example, compare
+
+ ? prod(i=1, 100, 1 - X^i); \\ this has degree 5050 !!
+ time = 3,335 ms.
+ ? prod(i=1, 100, 1 - X^i, 1 + O(X^101))
+ time = 43 ms.
+ %2 = 1 - X - X^2 + X^5 + X^7 - X^12 - X^15 + X^22 + X^26 - X^35 - X^40 + \
+ X^51 + X^57 - X^70 - X^77 + X^92 + X^100 + O(X^101)
+
+X<produit>The library syntax is B<produit>C<(entree *ep, GEN a, GEN b, char *expr, GEN x)>.
+
+=head2 X<prodeuler>prodeulerC<(X = a,b,>I<expr>C<)>
+
+product of expression I<expr>,
+initialized at 1. (i.e.S< >to a I<real> number equal to 1 to the current
+C<realprecision>), the formal parameter C<X> ranging over the prime numbers
+between C<a> and C<b>.X<Euler product>
+
+X<prodeuler>The library syntax is B<prodeuler>C<(entree *ep, GEN a, GEN b, char *expr, long prec)>.
+
+=head2 X<prodinf>prodinfC<(X = a,>I<expr>C<,{>I<flag>C< = 0})>
+
+X<infinite product>infinite product of
+expression I<expr>, the formal parameter C<X> starting at C<a>. The evaluation
+stops when the relative error of the expression minus 1 is less than the
+default precision. The expressions must always evaluate to an element of
+B<C>.
+
+If I<flag>C< = 1>, do the product of the (C<1+>I<expr>) instead.
+
+X<prodinf>The library syntax is B<prodinf>C<(entree *ep, GEN a, char *expr, long prec)> (I<flag>C< = 0>), or
+X<prodinf1>B<prodinf1> with the same arguments (I<flag>C< = 1>).
+
+=head2 X<solve>solveC<(X = a,b,>I<expr>C<)>
+
+find a real root of expression
+I<expr> between C<a> and C<b>, under the condition
+I<expr>C<(X = a) * >I<expr>C<(X = b) E<lt>= 0>.
+This routine uses Brent's method and can fail miserably if I<expr> is
+not defined in the whole of C<[a,b]> (try C<solve(x = 1, 2, tan(x)>).
+
+X<zbrent>The library syntax is B<zbrent>C<(entree *ep, GEN a, GEN b, char *expr, long prec)>.
+
+=head2 X<sum>sumC<(X = a,b,>I<expr>C<,{x = 0})>
+
+sum of expression I<expr>,
+initialized at C<x>, the formal parameter going from C<a> to C<b>. As for
+C<prod>, the initialization parameter C<x> may be given to force the type
+of the operations being performed.
+
+As an extreme example, compare
+
+ ? sum(i=1, 5000, 1/i); \\ rational number: denominator has 2166 digits.
+ time = 1,241 ms.
+ ? sum(i=1, 5000, 1/i, 0.)
+ time = 158 ms.
+ %2 = 9.094508852984436967261245533
+
+X<somme>The library syntax is B<somme>C<(entree *ep, GEN a, GEN b, char *expr, GEN x)>. This is to be
+used as follows: C<ep> represents the dummy variable used in the
+expression C<expr>
+
+ /* compute a^2 + ... + b^2 */
+ {
+ /* define the dummy variable "i" */
+ entree *ep = is_entry("i");
+ /* sum for a <= i <= b */
+ return somme(ep, a, b, "i^2", gzero);
+ }
+
+=head2 X<sumalt>sumaltC<(X = a,>I<expr>C<,{>I<flag>C< = 0})>
+
+numerical summation of the
+series I<expr>, which should be an X<alternating series>alternating series, the formal
+variable C<X> starting at C<a>.
+
+If I<flag>C< = 0>, use an algorithm of F.S< >Villegas as modified by D.S< >Zagier. This
+is much better than X<Euler>Euler-Van Wijngaarden's method which was used
+formerly.
+Beware that the stopping criterion is that the term gets small enough, hence
+terms which are equal to 0 will create problems and should be removed.
+
+If I<flag>C< = 1>, use a variant with slightly different polynomials. Sometimes
+faster.
+
+Divergent alternating series can sometimes be summed by this method, as well
+as series which are not exactly alternating (see for example
+L<Label se:user_defined>).
+
+B<Important hint:> a significant speed gain can be obtained by
+writing the C<(-1)^X> which may occur in the expression as
+C<(1.S< >- X%2*2)>.
+
+X<sumalt>The library syntax is B<sumalt>C<(entree *ep, GEN a, char *expr, long >I<flag>C<, long prec)>.
+
+=head2 X<sumdiv>sumdivC<(n,X,>I<expr>C<)>
+
+sum of expression I<expr> over
+the positive divisors of C<n>.
+
+Arithmetic functions like X<sigma>B<sigma> use the multiplicativity of the
+underlying expression to speed up the computation. In the present version
+B<2.2.0>, there is no way to indicate that I<expr> is multiplicative in
+C<n>, hence specialized functions should be prefered whenever possible.
+
+X<divsum>The library syntax is B<divsum>C<(entree *ep, GEN num, char *expr)>.
+
+=head2 X<suminf>suminfC<(X = a,>I<expr>C<)>
+
+X<infinite sum>infinite sum of expression
+I<expr>, the formal parameter C<X> starting at C<a>. The evaluation stops
+when the relative error of the expression is less than the default precision.
+The expressions must always evaluate to a complex number.
+
+X<suminf>The library syntax is B<suminf>C<(entree *ep, GEN a, char *expr, long prec)>.
+
+=head2 X<sumpos>sumposC<(X = a,>I<expr>C<,{>I<flag>C< = 0})>
+
+numerical summation of the
+series I<expr>, which must be a series of terms having the same sign,
+the formal
+variable C<X> starting at C<a>. The algorithm used is Van Wijngaarden's trick
+for converting such a series into an alternating one, and is quite slow.
+Beware that the stopping criterion is that the term gets small enough, hence
+terms which are equal to 0 will create problems and should be removed.
+
+If I<flag>C< = 1>, use slightly different polynomials. Sometimes faster.
+
+X<sumpos>The library syntax is B<sumpos>C<(entree *ep, GEN a, char *expr, long >I<flag>C<, long prec)>.
+
+=head1 Plotting functions
+
+Although plotting is not even a side purpose of PARI, a number of plotting
+functions are provided. Moreover, a lot of people felt like suggesting
+ideas or submitting huge patches for this section of the code. Among these,
+special thanks go to Klaus-Peter Nischke who suggested the recursive plotting
+and the forking/resizing stuff under X11, and Ilya Zakharevich who
+undertook a complete rewrite of the graphic code, so that most of it is now
+platform-independent and should be relatively easy to port or expand.
+
+These graphic functions are either
+
+B<*> high-level plotting functions (all the functions starting with
+C<ploth>) in which the user has little to do but explain what type of plot
+he wants, and whose syntax is similar to the one used in the preceding
+section (with somewhat more complicated flags).
+
+B<*> low-level plotting functions, where every drawing primitive (point,
+line, box, etc.) must be specified by the user. These low-level functions
+(called I<rectplot> functions, sharing the prefix C<plot>) work as
+follows. You have at your disposal 16 virtual windows which are filled
+independently, and can then be physically ORed on a single window at
+user-defined positions. These windows are numbered from 0 to 15, and must be
+initialized before being used by the function C<plotinit>, which specifies
+the height and width of the virtual window (called a I<rectwindow> in the
+sequel). At all times, a virtual cursor (initialized at C<[0,0]>) is
+associated to the window, and its current value can be obtained using the
+function C<plotcursor>.
+
+A number of primitive graphic objects (called I<rect> objects) can then
+be drawn in these windows, using a default color associated to that window
+(which can be changed under X11, using the C<plotcolor> function, black
+otherwise) and only the part of the object which is inside the window will be
+drawn, with the exception of polygons and strings which are drawn entirely
+(but the virtual cursor can move outside of the window). The ones sharing the
+prefix C<plotr> draw relatively to the current position of the virtual
+cursor, the others use absolute coordinates. Those having the prefix
+C<plotrecth> put in the rectwindow a large batch of rect objects
+corresponding to the output of the related C<ploth> function.
+
+Finally, the actual physical drawing is done using the function
+C<plotdraw>. Note that the windows are preserved so that further drawings
+using the same windows at different positions or different windows can be
+done without extra work. If you want to erase a window (and free the
+corresponding memory), use the function C<plotkill>. It is not possible to
+partially erase a window. Erase it completely, initialize it again and then
+fill it with the graphic objects that you want to keep.
+
+In addition to initializing the window, you may want to have a scaled
+window to avoid unnecessary conversions. For this, use the function
+C<plotscale> below. As long as this function is not called, the scaling is
+simply the number of pixels, the origin being at the upper left and the
+C<y>-coordinates going downwards.
+
+Note that in the present version B<2.2.0> all these plotting functions
+(both low and high level) have been written for the X11-window system
+(hence also for GUI's based on X11 such as Openwindows and Motif) only,
+though very little code remains which is actually platform-dependent. A
+Suntools/Sunview, Macintosh, and an Atari/Gem port were provided for
+previous versions. These I<may> be adapted in future releases.
+
+Under X11/Suntools, the physical window (opened by C<plotdraw> or any
+of the C<ploth*> functions) is completely separated from GP (technically,
+a C<fork> is done, and the non-graphical memory is immediately freed in
+the child process), which means you can go on working in the current GP
+session, without having to kill the window first. Under X11, this window can
+be closed, enlarged or reduced using the standard window manager functions.
+No zooming procedure is implemented though (yet).
+
+B<*> Finally, note that in the same way that C<printtex> allows you
+to have a TeX output corresponding to printed results, the functions
+starting with C<ps> allow you to have X<PostScript>C<PostScript> output of the
+plots. This will not be absolutely identical with the screen output, but will
+be sufficiently close. Note that you can use PostScript output even if you do
+not have the plotting routines enabled. The PostScript output is written in a
+file whose name is derived from the X<psfile>C<psfile> default (C<./pari.ps> if
+you did not tamper with it). Each time a new PostScript output is asked for,
+the PostScript output is appended to that file. Hence the user must remove
+this file, or change the value of C<psfile>, first if he does not want
+unnecessary drawings from preceding sessions to appear. On the other hand, in
+this manner as many plots as desired can be kept in a single file.
+
+I<None of the graphic functions are available within the PARI library, you
+must be under GP to use them>. The reason for that is that you really should
+not use PARI for heavy-duty graphical work, there are much better specialized
+alternatives around. This whole set of routines was only meant as a
+convenient, but simple-minded, visual aid. If you really insist on using
+these in your program (we warned you), the source (C<plot*.c>) should be
+readable enough for you to achieve something.
+
+=head2 X<plot>plotC<(X = a,b,>I<expr>C<,{>I<Ymin>C<},{>I<Ymax>C<})>
+
+crude
+(ASCII) plot of the function represented by expression I<expr> from
+C<a> to C<b>, with I<Y> ranging from I<Ymin> to I<Ymax>. If
+I<Ymin> (resp. I<Ymax>) is not given, the minima (resp. the
+maxima) of the computed values of the expression is used instead.
+
+=head2 X<plotbox>plotboxC<(w,x2,y2)>
+
+let C<(x1,y1)> be the current position of the
+virtual cursor. Draw in the rectwindow C<w> the outline of the rectangle which
+is such that the points C<(x1,y1)> and C<(x2,y2)> are opposite corners. Only
+the part of the rectangle which is in C<w> is drawn. The virtual cursor does
+I<not> move.
+
+=head2 X<plotclip>plotclipC<(w)>
+
+`clips' the content of rectwindow C<w>, i.e
+remove all parts of the drawing that would not be visible on the screen.
+Together with X<plotcopy>C<plotcopy> this function enables you to draw on a
+scratchpad before commiting the part you're interested in to the final
+picture.
+
+=head2 X<plotcolor>plotcolorC<(w,c)>
+
+set default color to C<c> in rectwindow C<w>.
+In present version B<2.2.0>, this is only implemented for X11 window system,
+and you only have the following palette to choose from:
+
+1 = black, 2 = blue, 3 = sienna, 4 = red, 5 = cornsilk, 6 = grey, 7 = gainsborough.
+
+Note that it should be fairly easy for you to hardwire some more colors by
+tweaking the files C<rect.h> and C<plotX.c>. User-defined
+colormaps would be nice, and I<may> be available in future versions.
+
+=head2 X<plotcopy>plotcopyC<(w1,w2,dx,dy)>
+
+copy the contents of rectwindow
+C<w1> to rectwindow C<w2>, with offset C<(dx,dy)>.
+
+=head2 X<plotcursor>plotcursorC<(w)>
+
+give as a 2-component vector the current
+(scaled) position of the virtual cursor corresponding to the rectwindow C<w>.
+
+=head2 X<plotdraw>plotdrawC<(list)>
+
+physically draw the rectwindows given in C<list>
+which must be a vector whose number of components is divisible by 3. If
+C<list = [w1,x1,y1,w2,x2,y2,...]>, the windows C<w1>, C<w2>, etc.S< >are
+physically placed with their upper left corner at physical position
+C<(x1,y1)>, C<(x2,y2)>,...respectively, and are then drawn together.
+Overlapping regions will thus be drawn twice, and the windows are considered
+transparent. Then display the whole drawing in a special window on your
+screen.
+
+=head2 X<plotfile>plotfileC<(s)>
+
+set the output file for plotting output. Special
+filename C<-> redirects to the same place as PARI output.
+
+=head2 X<ploth>plothC<(X = a,b,>I<expr>C<,{>I<flag>C< = 0},{n = 0})>
+
+high precision
+plot of the function C<y = f(x)> represented by the expression I<expr>, C<x>
+going from C<a> to C<b>. This opens a specific window (which is killed
+whenever you click on it), and returns a four-component vector giving the
+coordinates of the bounding box in the form
+C<[>I<xmin>C<,>I<xmax>C<,>I<ymin>C<,>I<ymax>C<]>.
+
+B<Important note>: Since this may involve a lot of function calls,
+it is advised to keep the current precision to a minimum (e.g.S< >9) before
+calling this function.
+
+C<n> specifies the number of reference point on the graph (0 means use the
+hardwired default values, that is: 1000 for general plot, 1500 for
+parametric plot, and 15 for recursive plot).
+
+If no I<flag> is given, I<expr> is either a scalar expression C<f(X)>, in which
+case the plane curve C<y = f(X)> will be drawn, or a vector
+C<[f_1(X),...,f_k(X)]>, and then all the curves C<y = f_i(X)> will be drawn in
+the same window.
+
+The binary digits of I<flag> mean:
+
+B<*> 1: X<parametric plot>I<parametric plot>. Here I<expr> must be a vector with
+an even number of components. Successive pairs are then understood as the
+parametric coordinates of a plane curve. Each of these are then drawn.
+
+For instance:
+
+C<ploth(X = 0,2*Pi,[sin(X),cos(X)],1)> will draw a circle.
+
+C<ploth(X = 0,2*Pi,[sin(X),cos(X)])> will draw two entwined sinusoidal
+curves.
+
+C<ploth(X = 0,2*Pi,[X,X,sin(X),cos(X)],1)> will draw a circle and the line
+C<y = x>.
+
+B<*> 2: X<recursive plot>I<recursive plot>. If this flag is set, only I<one>
+curve can be drawn at time, i.e.S< >I<expr> must be either a two-component
+vector (for a single parametric curve, and the parametric flag I<has> to
+be set), or a scalar function. The idea is to choose pairs of successive
+reference points, and if their middle point is not too far away from the
+segment joining them, draw this as a local approximation to the curve.
+Otherwise, add the middle point to the reference points. This is very fast,
+and usually more precise than usual plot. Compare the results of
+
+S< >C<ploth(X = -1,1,sin(1/X),2) and ploth(X = -1,1,sin(1/X))>
+
+for instance. But beware that if you are extremely unlucky, or choose too few
+reference points, you may draw some nice polygon bearing little resemblance
+to the original curve. For instance you should I<never> plot recursively
+an odd function in a symmetric interval around 0. Try
+
+ ploth(x = -20, 20, sin(x), 2)
+
+to see why. Hence, it's usually a good idea to try and plot the same
+curve with slightly different parameters.
+
+The other values toggle various display options:
+
+B<*> 4: do not rescale plot according to the computed extrema. This is
+meant to be used when graphing multiple functions on a rectwindow (as a
+X<plotrecth>C<plotrecth> call), in conjuction with X<plotscale>C<plotscale>.
+
+B<*> 8: do not print the C<x>-axis.
+
+B<*> 16: do not print the C<y>-axis.
+
+B<*> 32: do not print frame.
+
+B<*> 64: only plot reference points, do not join them.
+
+B<*> 256: use splines to interpolate the points.
+
+B<*> 512: plot no C<x>-ticks.
+
+B<*> 1024: plot no C<y>-ticks.
+
+B<*> 2048: plot all ticks with the same length.
+
+=head2 X<plothraw>plothrawC<(>I<listx>C<,>I<listy>C<,{>I<flag>C< = 0})>
+
+given
+I<listx> and I<listy> two vectors of equal length, plots (in high
+precision) the points whose C<(x,y)>-coordinates are given in I<listx>
+and I<listy>. Automatic positioning and scaling is done, but with the
+same scaling factor on C<x> and C<y>. If I<flag> is 1, join points, other non-0
+flags toggle display options and should be combinations of bits C<2^k>, C<k
+ E<gt>= 3> as in C<ploth>.
+
+=head2 X<plothsizes>plothsizesC<()>
+
+return data corresponding to the output window
+in the form of a 6-component vector: window width and height, sizes for ticks
+in horizontal and vertical directions (this is intended for the C<gnuplot>
+interface and is currently not significant), width and height of characters.
+
+=head2 X<plotinit>plotinitC<(w,x,y)>
+
+initialize the rectwindow C<w> to width C<x> and
+height C<y>, and position the virtual cursor at C<(0,0)>. This destroys any rect
+objects you may have already drawn in C<w>.
+
+The plotting device imposes an upper bound for C<x> and C<y>, for instance the
+number of pixels for screen output. These bounds are available through the
+X<plothsizes>C<plothsizes> function. The following sequence initializes in a portable way
+(i.e independant of the output device) a window of maximal size, accessed through
+coordinates in the C<[0,1000] x [0,1000]> rangeS< >:
+
+ s = plothsizes();
+ plotinit(0, s[1]-1, s[2]-1);
+ plotscale(0, 0,1000, 0,1000);
+
+=head2 X<plotkill>plotkillC<(w)>
+
+erase rectwindow C<w> and free the corresponding
+memory. Note that if you want to use the rectwindow C<w> again, you have to
+use C<initrect> first to specify the new size. So it's better in this case
+to use C<initrect> directly as this throws away any previous work in the
+given rectwindow.
+
+=head2 X<plotlines>plotlinesC<(w,X,Y,{>I<flag>C< = 0})>
+
+draw on the rectwindow C<w>
+the polygon such that the (x,y)-coordinates of the vertices are in the
+vectors of equal length C<X> and C<Y>. For simplicity, the whole
+polygon is drawn, not only the part of the polygon which is inside the
+rectwindow. If I<flag> is non-zero, close the polygon. In any case, the
+virtual cursor does not move.
+
+C<X> and C<Y> are allowed to be scalars (in this case, both have to).
+There, a single segment will be drawn, between the virtual cursor current
+position and the point C<(X,Y)>. And only the part thereof which
+actually lies within the boundary of C<w>. Then I<move> the virtual cursor
+to C<(X,Y)>, even if it is outside the window. If you want to draw a
+line from C<(x1,y1)> to C<(x2,y2)> where C<(x1,y1)> is not necessarily the
+position of the virtual cursor, use C<plotmove(w,x1,y1)> before using this
+function.
+
+=head2 X<plotlinetype>plotlinetypeC<(w,>I<type>C<)>
+
+change the type of lines
+subsequently plotted in rectwindow C<w>. I<type> C<-2> corresponds to
+frames, C<-1> to axes, larger values may correspond to something else. C<w =
+-1> changes highlevel plotting. This is only taken into account by the
+C<gnuplot> interface.
+
+=head2 X<plotmove>plotmoveC<(w,x,y)>
+
+move the virtual cursor of the rectwindow C<w>
+to position C<(x,y)>.
+
+=head2 X<plotpoints>plotpointsC<(w,X,Y)>
+
+draw on the rectwindow C<w> the
+points whose C<(x,y)>-coordinates are in the vectors of equal length C<X> and
+C<Y> and which are inside C<w>. The virtual cursor does I<not> move. This
+is basically the same function as C<plothraw>, but either with no scaling
+factor or with a scale chosen using the function C<plotscale>.
+
+As was the case with the C<plotlines> function, C<X> and C<Y> are allowed to
+be (simultaneously) scalar. In this case, draw the single point C<(X,Y)> on
+the rectwindow C<w> (if it is actually inside C<w>), and in any case
+I<move> the virtual cursor to position C<(x,y)>.
+
+=head2 X<plotpointsize>plotpointsizeC<(w,size)>
+
+changes the ``size'' of following
+points in rectwindow C<w>. If C<w = -1>, change it in all rectwindows.
+This only works in the C<gnuplot> interface.
+
+=head2 X<plotpointtype>plotpointtypeC<(w,>I<type>C<)>
+
+change the type of
+points subsequently plotted in rectwindow C<w>. I<type>C< = -1>
+corresponds to a dot, larger values may correspond to something else. C<w = -1>
+changes highlevel plotting. This is only taken into account by the
+C<gnuplot> interface.
+
+=head2 X<plotrbox>plotrboxC<(w,dx,dy)>
+
+draw in the rectwindow C<w> the outline of
+the rectangle which is such that the points C<(x1,y1)> and C<(x1+dx,y1+dy)> are
+opposite corners, where C<(x1,y1)> is the current position of the cursor.
+Only the part of the rectangle which is in C<w> is drawn. The virtual cursor
+does I<not> move.
+
+=head2 X<plotrecth>plotrecthC<(w,X = a,b,>I<expr>C<,{>I<flag>C< = 0},{n = 0})>
+
+writes to
+rectwindow C<w> the curve output of C<ploth>C<(w,X = a,b,>I<expr>C<,>I<flag>C<,n)>.
+
+=head2 X<plotrecthraw>plotrecthrawC<(w,>I<data>C<,{>I<flag>C< = 0})>
+
+plot graph(s) for
+I<data> in rectwindow C<w>. I<flag> has the same significance here as in
+C<ploth>, though recursive plot is no more significant.
+
+I<data> is a vector of vectors, each corresponding to a list a coordinates.
+If parametric plot is set, there must be an even number of vectors, each
+successive pair corresponding to a curve. Otherwise, the first one containe
+the C<x> coordinates, and the other ones contain the C<y>-coordinates
+of curves to plot.
+
+=head2 X<plotrline>plotrlineC<(w,dx,dy)>
+
+draw in the rectwindow C<w> the part of the
+segment C<(x1,y1)-(x1+dx,y1+dy)> which is inside C<w>, where C<(x1,y1)> is the
+current position of the virtual cursor, and move the virtual cursor to
+C<(x1+dx,y1+dy)> (even if it is outside the window).
+
+=head2 X<plotrmove>plotrmoveC<(w,dx,dy)>
+
+move the virtual cursor of the rectwindow
+C<w> to position C<(x1+dx,y1+dy)>, where C<(x1,y1)> is the initial position of
+the cursor (i.e.S< >to position C<(dx,dy)> relative to the initial cursor).
+
+=head2 X<plotrpoint>plotrpointC<(w,dx,dy)>
+
+draw the point C<(x1+dx,y1+dy)> on the
+rectwindow C<w> (if it is inside C<w>), where C<(x1,y1)> is the current position
+of the cursor, and in any case move the virtual cursor to position
+C<(x1+dx,y1+dy)>.
+
+=head2 X<plotscale>plotscaleC<(w,x1,x2,y1,y2)>
+
+scale the local coordinates of the
+rectwindow C<w> so that C<x> goes from C<x1> to C<x2> and C<y> goes from C<y1> to
+C<y2> (C<x2 E<lt> x1> and C<y2 E<lt> y1> being allowed). Initially, after the initialization
+of the rectwindow C<w> using the function C<plotinit>, the default scaling
+is the graphic pixel count, and in particular the C<y> axis is oriented
+downwards since the origin is at the upper left. The function C<plotscale>
+allows to change all these defaults and should be used whenever functions are
+graphed.
+
+=head2 X<plotstring>plotstringC<(w,x,{>I<flag>C< = 0})>
+
+draw on the rectwindow C<w> the
+String C<x> (see L<Label se:strings>), at the current position of the cursor.
+
+I<flag> is used for justification: bits 1 and 2 regulate horizontal alignment:
+left if 0, right if 2, center if 1. Bits 4 and 8 regulate vertical
+alignment: bottom if 0, top if 8, v-center if 4. Can insert additional
+small gap between point and string: horizontal if bit 16 is set, vertical
+if bit 32 is set (see the tutorial for an example).
+
+=head2 X<plotterm>plottermC<(>I<term>C<)>
+
+sets terminal where high resolution
+plots go (this is currently only taken into account by the C<gnuplot>
+graphical driver). Using the C<gnuplot> driver, possible terminals are
+the same as in gnuplot. If I<term> is "?", lists possible values.
+
+Terminal options can be appended to the terminal name and space; terminal
+size can be put immediately after the name, as in C<"gif = 300,200">.
+Positive return value means success.
+
+=head2 X<psdraw>psdrawC<(>I<list>C<)>
+
+same as C<plotdraw>, except that the
+output is a PostScript program appended to the C<psfile>.
+
+=head2 X<psploth>psplothC<(X = a,b,>I<expr>C<)>
+
+same as C<ploth>, except that the
+output is a PostScript program appended to the C<psfile>.
+
+=head2 X<psplothraw>psplothrawC<(>I<listx>C<,>I<listy>C<)>
+
+same as C<plothraw>,
+except that the output is a PostScript program appended to the C<psfile>.
+
+=head1 Programming under GP
+
+X<programming>X<Label se:programming>
+=head2 Control statements.
+
+A number of control statements are available under GP. They are simpler and
+have a syntax slightly different from their C counterparts, but are quite
+powerful enough to write any kind of program. Some of them are specific to
+GP, since they are made for number theorists. As usual, C<X> will denote any
+simple variable name, and I<seq> will always denote a sequence of
+expressions, including the empty sequence.
+
+=item X<break>breakC<({n = 1})>
+
+interrupts execution of current I<seq>, and
+immediately exits from the C<n> innermost enclosing loops, within the
+current function call (or the top level loop). C<n> must be bigger than 1.
+If C<n> is greater than the number of enclosing loops, all enclosing loops
+are exited.
+
+=item X<for>forC<(X = a,b,>I<seq>C<)>
+
+the formal variable C<X> going from
+C<a> to C<b>, the I<seq> is evaluated. Nothing is done if C<a E<gt> b>.
+C<a> and C<b> must be in B<R>.
+
+=item X<fordiv>fordivC<(n,X,>I<seq>C<)>
+
+the formal variable C<X> ranging
+through the positive divisors of C<n>, the sequence I<seq> is evaluated.
+C<n> must be of type integer.
+
+=item X<forprime>forprimeC<(X = a,b,>I<seq>C<)>
+
+the formal variable C<X>
+ranging over the prime numbers between C<a> to C<b> (including C<a> and C<b>
+if they are prime), the I<seq> is evaluated. More precisely, the value
+of C<X> is incremented to the smallest prime strictly larger than C<X> at the
+end of each iteration. Nothing is done if C<a E<gt> b>. Note that C<a> and C<b> must
+be in B<R>.
+
+ ? { forprime(p = 2, 12,
+ print(p);
+ if (p == 3, p = 6);
+ )
+ }
+ 2
+ 3
+ 7
+ 11
+
+=item X<forstep>forstepC<(X = a,b,s,>I<seq>C<)>
+
+the formal variable C<X>
+going from C<a> to C<b>, in increments of C<s>, the I<seq> is evaluated.
+Nothing is done if C<s E<gt> 0> and C<a E<gt> b> or if C<s E<lt> 0> and C<a E<lt> b>. C<s> must be in
+B<R>C<^*> or a vector of steps C<[s_1,...,s_n]>. In the latter case, the
+successive steps are used in the order they appear in C<s>.
+
+ ? forstep(x=5, 20, [2,4], print(x))
+ 5
+ 7
+ 11
+ 13
+ 17
+ 19
+
+=item X<forsubgroup>forsubgroupC<(H = G,{B},>I<seq>C<)>
+
+executes I<seq> for
+each subgroup C<H> of the I<abelian> group C<G> (given in
+SNFX<Smith normal form> form or as a vector of elementary divisors),
+whose index is bounded by bound. The subgroups are not ordered in any
+obvious way, unless C<G> is a C<p>-group in which case Birkhoff's algorithm
+produces them by decreasing index. A X<subgroup>subgroup is given as a matrix
+whose columns give its generators on the implicit generators of C<G>. For
+example, the following prints all subgroups of index less than 2 in C<G =
+>B<Z>C</2>B<Z>C< g_1 x >B<Z>C</2>B<Z>C< g_2>S< >:
+
+ ? G = [2,2]; forsubgroup(H=G, 2, print(H))
+ [1; 1]
+ [1; 2]
+ [2; 1]
+ [1, 0; 1, 1]
+
+The last one, for instance is generated by C<(g_1, g_1 + g_2)>. This
+routine is intended to treat huge groups, when X<subgrouplist>B<subgrouplist> is not an
+option due to the sheer size of the output.
+
+For maximal speed the subgroups have been left as produced by the algorithm.
+To print them in canonical form (as left divisors of C<G> in
+HNFX<Hermite normal form> form), one can for instance use
+
+ ? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H))))
+ [2, 1; 0, 1]
+ [1, 0; 0, 2]
+ [2, 0; 0, 1]
+ [1, 0; 0, 1]
+
+Note that in this last representation, the index C<[G:H]> is given by the
+determinant.
+
+=item X<forvec>forvecC<(X = v,>I<seq>C<,{>I<flag>C< = 0})>
+
+C<v> being an C<n>-component
+vector (where C<n> is arbitrary) of two-component vectors C<[a_i,b_i]>
+for C<1 E<lt>= i E<lt>= n>, the I<seq> is evaluated with the formal variable
+C<X[1]> going from C<a_1> to C<b_1>,...,C<X[n]> going from C<a_n> to C<b_n>.
+The formal variable with the highest index moves the fastest. If I<flag>C< = 1>,
+generate only nondecreasing vectors C<X>, and if I<flag>C< = 2>, generate only
+strictly increasing vectors C<X>.
+
+=item X<if>ifC<(a,{>I<seq1>C<},{>I<seq2>C<})>
+
+if C<a> is non-zero,
+the expression sequence I<seq1> is evaluated, otherwise the expression
+I<seq2> is evaluated. Of course, I<seq1> or I<seq2> may be empty,
+so C<if (a,>I<seq>C<)> evaluates I<seq> if C<a> is not equal to zero
+(you don't have to write the second comma), and does nothing otherwise,
+whereas C<if (a,,>I<seq>C<)> evaluates I<seq> if C<a> is equal to
+zero, and does nothing otherwise. You could get the same result using
+the C<!> (C<not>) operator: C<if (!a,>I<seq>C<)>.
+
+Note that the boolean operators C<&&> and C<||> are evaluated
+according to operator precedence as explained in L<Label se:operators>, but
+that, contrary to other operators, the evaluation of the arguments is
+stopped as soon as the final truth value has been determined. For instance
+
+ if (reallydoit && longcomplicatedfunction(), ...)%
+
+is a perfectly safe statement.
+
+Recall that functions such as C<break> and C<next> operate on
+I<loops> (such as C<forxxx>, C<while>, C<until>). The C<if>
+statement is I<not> a loop (obviously!).
+
+=item X<next>nextC<({n = 1})>
+
+interrupts execution of current C<seq>,
+resume the next iteration of the innermost enclosing loop, within the
+current fonction call (or top level loop). If C<n> is specified, resume at
+the C<n>-th enclosing loop. If C<n> is bigger than the number of enclosing
+loops, all enclosing loops are exited.
+
+=item X<return>returnC<({x = 0})>
+
+returns from current subroutine, with
+result C<x>.
+
+=item X<until>untilC<(a,>I<seq>C<)>
+
+evaluates expression sequence I<seq>
+until C<a> is not equal to 0 (i.e.S< >until C<a> is true). If C<a> is initially
+not equal to 0, I<seq> is evaluated once (more generally, the condition
+on C<a> is tested I<after> execution of the I<seq>, not before as in
+C<while>).
+
+=item X<while>whileC<(a,>I<seq>C<)>
+
+while C<a> is non-zero evaluate the
+expression sequence I<seq>. The test is made I<before> evaluating
+the C<seq>, hence in particular if C<a> is initially equal to zero the
+I<seq> will not be evaluated at all.
+
+=head2 Specific functions used in GP programming
+
+X<Label se:gp_program>
+In addition to the general PARI functions, it is necessary to have some
+functions which will be of use specifically for GP, though a few of these can
+be accessed under library mode. Before we start describing these, we recall
+the difference between I<strings> and I<keywords> (see
+L<Label se:strings>): the latter don't get expanded at all, and you can type
+them without any enclosing quotes. The former are dynamic objects, where
+everything outside quotes gets immediately expanded.
+
+We need an additional notation for this chapter. An argument between braces,
+followed by a star, like C<{>I<str>C<}*>, means that any number of such
+arguments (possibly none) can be given.
+
+=item X<addhelp>addhelpC<(S,>I<str>C<)>
+
+X<Label se:addhelp> changes the help
+message for the symbol C<S>. The string I<str> is expanded on the spot
+and stored as the online help for C<S>. If C<S> is a function I<you> have
+defined, its definition will still be printed before the message I<str>.
+It is recommended that you document global variables and user functions in
+this way. Of course GP won't protest if you don't do it.
+
+There's nothing to prevent you from modifying the help of built-in PARI
+functions (but if you do, we'd like to hear why you needed to do it!).
+
+=item X<alias>aliasC<(>I<newkey>C<,>I<key>C<)>
+
+defines the keyword
+I<newkey> as an alias for keyword I<key>. I<key> must correspond
+to an existing I<function> name. This is different from the general user
+macros in that alias expansion takes place immediately upon execution,
+without having to look up any function code, and is thus much faster. A
+sample alias file C<misc/gpalias> is provided with the standard
+distribution. Alias commands are meant to be read upon startup from the
+C<.gprc> file, to cope with function names you are dissatisfied with, and
+should be useless in interactive usage.
+
+=item X<allocatemem>allocatememC<({x = 0})>
+
+this is a very special operation which
+allows the user to change the stack size I<after> initialization. C<x>
+must be a non-negative integer. If C<x! = 0>, a new stack of size C<16*\lceil
+x/16\rceil> bytes will be allocated, all the PARI data on the old stack will
+be moved to the new one, and the old stack will be discarded. If C<x = 0>, the
+size of the new stack will be twice the size of the old one.
+
+Although it is a function, this must be the I<last> instruction in any GP
+sequence. The technical reason is that this routine usually moves the stack,
+so objects from the current sequence might not be correct anymore. Hence, to
+prevent such problems, this routine terminates by a C<longjmp> (just as an
+error would) and not by a return.
+
+X<allocatemoremem>The library syntax is B<allocatemoremem>C<(x)>, where C<x> is an unsigned long, and the return type
+is void. GP uses a variant which ends by a C<longjmp>.
+
+=item X<default>defaultC<({>I<key>C<},{>I<val>C<},{>I<flag>C<})>
+
+sets the default
+corresponding to keyword I<key> to value I<val>. I<val> is a string
+(which of course accepts numeric arguments without adverse effects, due to the
+expansion mechanism). See L<Label se:defaults> for a list of available
+defaults, and L<Label se:meta> for some shortcut alternatives. Typing
+C<default()> (or C<\d>) yields the complete default list as well as
+their current values.X<Label se:default>
+
+If I<val> is omitted, prints the current value of default I<key>.
+If I<flag> is set, returns the result instead of printing it.
+
+=item X<error>errorC<({>I<str>C<}*)>
+
+outputs its argument list (each of
+them interpreted as a string), then interrupts the running GP program,
+returning to the input prompt.
+
+Example: C<error("n = ", n, " is not squarefree !")>.
+
+Note that, due to the automatic concatenation of strings, you could in fact
+use only one argument, just by suppressing the commas.
+
+=item X<extern>externC<(>I<str>C<)>
+
+the string I<str> is the name
+of an external command (i.e.S< >one you would type from your UNIX shell prompt).
+This command is immediately run and its input fed into GP, just as if read
+from a file.
+
+=item X<getheap>getheapC<()>
+
+returns a two-component row vector giving the
+number of objects on the heap and the amount of memory they occupy in long
+words. Useful mainly for debugging purposes.
+
+X<getheap>The library syntax is B<getheap>C<()>.
+
+=item X<getrand>getrandC<()>
+
+returns the current value of the random number
+seed. Useful mainly for debugging purposes.
+
+X<getrand>The library syntax is B<getrand>C<()>, returns a C long.
+
+=item X<getstack>getstackC<()>
+
+returns the current value of
+C<top-avma>,
+i.e.S< >the number of bytes used up to now on the stack. Should be equal to 0
+in between commands. Useful mainly for debugging purposes.
+
+X<getstack>The library syntax is B<getstack>C<()>, returns a C long.
+
+=item X<gettime>gettimeC<()>
+
+returns the time (in milliseconds) elapsed since
+either the last call to C<gettime>, or to the beginning of the containing
+GP instruction (if inside GP), whichever came last.
+
+X<gettime>The library syntax is B<gettime>C<()>, returns a C long.
+
+=item X<global>globalC<({>I<list of variables>C<})>
+
+X<Label se:global>
+declares the corresponding variables to be global. From now on, you will be
+forbidden to use them as formal parameters for function definitions or as
+loop indexes. This is especially useful when patching together various
+scripts, possibly written with different naming conventions. For instance the
+following situation is dangerous:
+
+ p = 3 \\ fix characteristic
+ ...
+ forprime(p = 2, N, ...)
+ f(p) = ...
+
+since within the loop or within the function's body (even worse: in the
+subroutines called in that scope), the true global value of C<p> will be
+hidden. If the statement C<global(p = 3)> appears at the beginning of
+the script, then both expressions will trigger syntax errors.
+
+Calling C<global> without arguments prints the list of global variables in
+use. In particular, C<eval(global)> will output the values of all local
+variables.
+
+=item X<input>inputC<()>
+
+reads a string, interpreted as a GP expression,
+from the input file, usually standard input (i.e.S< >the keyboard). If a
+sequence of expressions is given, the result is the result of the last
+expression of the sequence. When using this instruction, it is useful to
+prompt for the string by using the C<print1> function. Note that in the
+present version 2.19 of C<pari.el>, when using GP under GNU Emacs (see
+L<Label se:emacs>) one I<must> prompt for the string, with a string
+which ends with the same prompt as any of the previous ones (a C<"? ">
+will do for instance).
+
+=item X<install>installC<(>I<name>C<,>I<code>C<,{>I<gpname>C<},{>I<lib>C<})>
+
+loads from dynamic library I<lib> the function I<name>. Assigns to it
+the name I<gpname> in this GP session, with argument code I<code> (see
+L<Label se:gp.interface> for an explanation of those). If I<lib> is
+omitted, uses C<libpari.so>. If I<gpname> is omitted, uses
+I<name>.X<Label se:install>
+
+This function is useful for adding custom functions to the GP interpreter,
+or picking useful functions from unrelated libraries. For instance, it
+makes the function X<system>C<system> obsolete:
+
+ ? install(system, vs, sys, "libc.so")
+ ? sys("ls gp*")
+ gp.c gp.h gp_rl.c
+
+But it also gives you access to all (non static) functions defined in the
+PARI library. For instance, the function C<GEN addii(GEN x, GEN y)> adds
+two PARI integers, and is not directly accessible under GP (it's eventually
+called by the C<+> operator of course):
+
+ ? install("addii", "GG")
+ ? addii(1, 2)
+ %1 = 3
+
+B<Caution:> This function may not work on all systems, especially
+when GP has been compiled statically. In that case, the first use of an
+installed function will provoke a Segmentation Fault, i.e.S< >a major internal
+blunder (this should never happen with a dynamically linked executable).
+Hence, if you intend to use this function, please check first on some
+harmless example such as the ones above that it works properly on your
+machine.
+
+=item X<kill>killC<(s)>
+
+X<Label se:kill> kills the present value of the
+variable, alias or user-defined function C<s>. The corresponding identifier
+can now be used to name any GP object (variable or function). This is the
+only way to replace a variable by a function having the same name (or the
+other way round), as in the following example:
+
+ ? f = 1
+ %1 = 1
+ ? f(x) = 0
+ *** unused characters: f(x)=0
+ ^----
+ ? kill(f)
+ ? f(x) = 0
+ ? f()
+ %2 = 0
+
+When you kill a variable, all objects that used it become invalid. You
+can still display them, even though the killed variable will be printed in a
+funny way (following the same convention as used by the library function
+C<fetch_var>, seeS< >L<Label se:vars>). For example:
+
+ ? a^2 + 1
+ %1 = a^2 + 1
+ ? kill(a)
+ ? %1
+ %2 = #<1>^2 + 1
+
+If you simply want to restore a variable to its ``undefined'' value
+(monomial of degree one), use the X<quote>quote operator: C<a = 'a>.
+Predefined symbols (C<x> and GP function names) cannot be killed.
+
+=item X<print>printC<({>I<str>C<}*)>
+
+outputs its (string) arguments in raw
+format, ending with a newline.
+
+=item X<print1>print1C<({>I<str>C<}*)>
+
+outputs its (string) arguments in raw
+format, without ending with a newline (note that you can still embed newlines
+within your strings, using the C<\n> notationS< >!).
+
+=item X<printp>printpC<({>I<str>C<}*)>
+
+outputs its (string) arguments in
+prettyprint (beautified) format, ending with a newline.
+
+=item X<printp1>printp1C<({>I<str>C<}*)>
+
+outputs its (string) arguments in
+prettyprint (beautified) format, without ending with a newline.
+
+=item X<printtex>printtexC<({>I<str>C<}*)>
+
+outputs its (string) arguments in
+TeX format. This output can then be used in a TeX manuscript.
+The printing is done on the standard output. If you want to print it to a
+file you should use C<writetex> (see there).
+
+Another possibility is to enable the X<log>C<log> default
+(seeS< >L<Label se:defaults>).
+You could for instance do:X<logfile>
+
+ default(logfile, "new.tex");
+ default(log, 1);
+ printtex(result);
+
+(You can use the automatic string expansion/concatenation process to have
+dynamic file names if you wish).
+
+=item X<quit>quitC<()>
+
+exits GP.X<Label se:quit>
+
+=item X<read>readC<({>I<str>C<})>
+
+reads in the file whose name results
+from the expansion of the string I<str>. If I<str> is omitted,
+re-reads the last file that was fed into GP. The return value is the result of
+the last expression evaluated.X<Label se:read>
+
+=item X<reorder>reorderC<({x = []})>
+
+C<x> must be a vector. If C<x> is the
+empty vector, this gives the vector whose components are the existing
+variables in increasing order (i.e.S< >in decreasing importance). Killed
+variables (see C<kill>) will be shown as C<0>. If C<x> is
+non-empty, it must be a permutation of variable names, and this permutation
+gives a new order of importance of the variables, I<for output only>. For
+example, if the existing order is C<[x,y,z]>, then after
+C<reorder([z,x])> the order of importance of the variables, with respect
+to output, will be C<[z,y,x]>. The internal representation is unaffected.
+X<Label se:reorder>
+
+=item X<setrand>setrandC<(n)>
+
+reseeds the random number generator to the value
+C<n>. The initial seed is C<n = 1>.
+
+X<setrand>The library syntax is B<setrand>C<(n)>, where C<n> is a C<long>. Returns C<n>.
+
+=item X<system>systemC<(>I<str>C<)>
+
+I<str> is a string representing
+a system command. This command is executed, its output written to the
+standard output (this won't get into your logfile), and control returns
+to the PARI system. This simply calls the C C<system> command.
+
+=item X<trap>trapC<({e}, {>I<rec>C<}, {>I<seq>C<})>
+
+tries to
+execute I<seq>, trapping error C<e>, that is effectively preventing it
+from aborting computations in the usual way; the recovery sequence
+I<rec> is executed if the error occurs and the evaluation of I<rec>
+becomes the result of the command. If C<e> is omitted, all exceptions are
+trapped. Note in particular that hitting C<^C> (Control-C) raises an
+exception.
+
+ ? \\ trap division by 0
+ ? inv(x) = trap (gdiver2, INFINITY, 1/x)
+ ? inv(2)
+ %1 = 1/2
+ ? inv(0)
+ %2 = INFINITY
+
+If I<seq> is omitted, defines I<rec> as a default action when
+encountering exception C<e>. The error message is printed, as well as the
+result of the evaluation of I<rec>, and the control is given back to the
+GP prompt. In particular, current computation is then lost.
+
+The following error handler prints the list of all user variables, then
+stores in a file their name and their values:
+
+ ? { trap( ,
+ print(reorder);
+ write("crash", reorder);
+ write("crash", eval(reorder))) }
+
+If no recovery code is given (I<rec> is omitted) a so-called
+X<break loop>I<break loop> will be started. During a break loop, all commands are
+read and evaluated as during the main GP loop (except that no history of
+results is kept).
+
+To get out of the break loop, you can use X<next>C<next>, X<break>C<break> or
+X<return>C<return>; reading in a file by C<\r> will also terminate the loop once
+the file has been read (C<read> will remain in the break loop). If the
+error is not fatal (C<^C> is the only non-fatal error), C<next>
+will continue the computation as if nothing had happened (except of course,
+you may have changed GP state during the break loop); otherwise control
+will come back to the GP prompt. After a user interrupt (C<^C>),
+entering an empty input line (i.e hitting the return key) has the same
+effect as C<next>.
+
+Break loops are useful as a debugging tool to inspect the values of GP
+variables to understand why a problem occurred, or to change GP behaviour
+(increase debugging level, start storing results in a logfile, modify
+parameters...) in the middle of a long computation (hit C<^C>, type
+in your modifications, then type C<next>).
+
+If I<rec> is the empty string C<""> the last default handler is popped
+out, and replaced by the previous one for that error.
+
+B<Note:> The interface is currently not adequate for trapping
+individual exceptions. In the current version B<2.2.0>, the following keywords
+are recognized, but the name list will be expanded and changed in the
+future (all library mode errors can be trapped: it's a matter of defining
+the keywords to GP, and there are currently far too many useless ones):
+
+C<accurer>: accuracy problem
+
+C<gdiver2>: division by 0
+
+C<archer>: not available on this architecture or operating system
+
+C<typeer>: wrong type
+
+C<errpile>: the PARI stack overflows
+
+=item X<type>typeC<(x,{t})>
+
+this is useful only under GP. If C<t> is
+not present, returns the internal type number of the PARI object C<x>.
+Otherwise, makes a copy of C<x> and sets its type equal to type C<t>, which
+can be either a number or, preferably since internal codes may eventually
+change, a symbolic name such as C<t_FRACN> (you can skip the C<t_>
+part here, so that C<FRACN> by itself would also be all right). Check out
+existing type names with the metacommand C<\t>.X<Label se:gptype>
+
+GP won't let you create meaningless objects in this way where the internal
+structure doesn't match the type. This function can be useful to create
+reducible rationals (type C<t_FRACN>) or rational functions (type
+C<t_RFRACN>). In fact it's the only way to do so in GP. In this case, the
+created object, as well as the objects created from it, will not be reduced
+automatically, making some operations a bit faster.
+
+There is no equivalent library syntax, since the internal functions C<typ>
+and C<settyp> are available. Note that C<settyp> does I<not>
+create a copy of C<x>, contrary to most PARI functions. It also doesn't
+check for consistency. C<settyp> just changes the type in place and
+returns nothing. C<typ> returns a C long integer. Note also the different
+spellings of the internal functions (C<set>)C<typ> and of the GP
+function C<type>, which is due to the fact that C<type> is a reserved
+identifier for some C compilers.
+
+=item X<whatnow>whatnowC<(>I<key>C<)>
+
+if keyword I<key> is the name
+of a function that was present in GP version 1.39.15 or lower, outputs
+the new function name and syntax, if it changed at all (C<387> out of C<560>
+did).X<Label se:whatnow>
+
+=item X<write>writeC<(>I<filename>C<,{>I<str>C<*})>
+
+writes (appends)
+to I<filename> the remaining arguments, and appends a newline (same output
+as C<print>).X<Label se:write>
+
+=item X<write1>write1C<(>I<filename>C<,{>I<str>C<*})>
+
+writes (appends) to
+I<filename> the remaining arguments without a trailing newline
+(same output as C<print1>).
+
+=item X<writetex>writetexC<(>I<filename>C<,{>I<str>C<*})>
+
+as C<write>,
+in TeX format.X<Label se:writetex>
+