1libPARI(3)            User Contributed Perl Documentation           libPARI(3)
2
3
4

NAME

6       Math::libPARI - Functions and Operations Available in PARI and GP
7

DESCRIPTION

9       The functions and operators available in PARI and in the GP/PARI
10       calculator are numerous and everexpanding. Here is a description of the
11       ones available in version /usr/share/libpari23. It should be noted that
12       many of these functions accept quite different types as arguments, but
13       others are more restricted. The list of acceptable types will be given
14       for each function or class of functions.  Except when stated otherwise,
15       it is understood that a function or operation which should make natural
16       sense is legal. In this chapter, we will describe the functions
17       according to a rough classification. The general entry looks something
18       like:
19
20       foo"(x,{flag = 0})": short description.
21
22       The library syntax is foo"(x,flag)".
23
24       This means that the GP function "foo" has one mandatory argument "x",
25       and an optional one, "flag", whose default value is 0. (The "{}" should
26       not be typed, it is just a convenient notation we will use throughout
27       to denote optional arguments.) That is, you can type "foo(x,2)", or
28       foo(x), which is then understood to mean "foo(x,0)". As well, a comma
29       or closing parenthesis, where an optional argument should have been,
30       signals to GP it should use the default. Thus, the syntax "foo(x,)" is
31       also accepted as a synonym for our last expression. When a function has
32       more than one optional argument, the argument list is filled with user
33       supplied values, in order.  When none are left, the defaults are used
34       instead. Thus, assuming that "foo"'s prototype had been
35
36         " foo({x = 1},{y = 2},{z = 3}), "
37
38       typing in "foo(6,4)" would give you "foo(6,4,3)". In the rare case when
39       you want to set some far away argument, and leave the defaults in
40       between as they stand, you can use the ``empty arg'' trick alluded to
41       above: "foo(6,,1)" would yield "foo(6,2,1)". By the way, "foo()" by
42       itself yields "foo(1,2,3)" as was to be expected.
43
44       In this rather special case of a function having no mandatory argument,
45       you can even omit the "()": a standalone "foo" would be enough (though
46       we do not recommend it for your scripts, for the sake of clarity). In
47       defining GP syntax, we strove to put optional arguments at the end of
48       the argument list (of course, since they would not make sense
49       otherwise), and in order of decreasing usefulness so that, most of the
50       time, you will be able to ignore them.
51
52       Finally, an optional argument (between braces) followed by a star, like
53       "{x}*", means that any number of such arguments (possibly none) can be
54       given. This is in particular used by the various "print" routines.
55
56       Flags. A flag is an argument which, rather than conveying actual
57       information to the routine, intructs it to change its default
58       behaviour, e.g. return more or less information. All such flags are
59       optional, and will be called flag in the function descriptions to
60       follow. There are two different kind of flags
61
62       \item generic: all valid values for the flag are individually described
63       (``If flag is equal to 1, then...'').
64
65       \item binary: use customary binary notation as a compact way to
66       represent many toggles with just one integer. Let "(p_0,...,p_n)" be a
67       list of switches (i.e. of properties which take either the value 0
68       or 1), the number "2^3 + 2^5 = 40" means that "p_3" and "p_5" are set
69       (that is, set to 1), and none of the others are (that is, they are set
70       to 0). This is announced as ``The binary digits of "flag" mean 1:
71       "p_0", 2: "p_1", 4: "p_2"'', and so on, using the available consecutive
72       powers of 2.
73
74       Mnemonics for flags. Numeric flags as mentionned above are obscure,
75       error-prone, and quite rigid: should the authors want to adopt a new
76       flag numbering scheme (for instance when noticing flags with the same
77       meaning but different numeric values across a set of routines), it
78       would break backward compatibility. The only advantage of explicit
79       numeric values is that they are fast to type, so their use is only
80       advised when using the calculator "gp".
81
82       As an alternative, one can replace a numeric flag by a character string
83       containing symbolic identifiers. For a generic flag, the mnemonic
84       corresponding to the numeric identifier is given after it as in
85
86         fun(x, {flag = 0} ):
87
88           If flag is equal to 1 = AGM, use an agm formula\dots
89
90       which means that one can use indifferently "fun(x, 1)" or "fun(x,
91       AGM)".
92
93       For a binary flag, mnemonics corresponding to the various toggles are
94       given after each of them. They can be negated by prepending "no_" to
95       the mnemonic, or by removing such a prefix. These toggles are grouped
96       together using any punctuation character (such as ',' or ';'). For
97       instance (taken from description of "ploth(X = a,b,expr,{flag = 0},{n =
98       0})")
99
100           Binary digits of flags mean: C<1 = Parametric>,
101           C<2 = Recursive>,...
102
103       so that, instead of 1, one could use the mnemonic "Parametric;
104       no_Recursive", or simply "Parametric" since "Recursive" is unset by
105       default (default value of "flag" is 0, i.e. everything unset).
106
107       Pointers.\varsidx{pointer} If a parameter in the function prototype is
108       prefixed with a & sign, as in
109
110       foo"(x,&e)"
111
112       it means that, besides the normal return value, the function may assign
113       a value to "e" as a side effect. When passing the argument, the & sign
114       has to be typed in explicitly. As of version /usr/share/libpari23, this
115       pointer argument is optional for all documented functions, hence the &
116       will always appear between brackets as in "Z_issquare""(x,{&e})".
117
118       About library programming.  the library function "foo", as defined at
119       the beginning of this section, is seen to have two mandatory arguments,
120       "x" and flag: no PARI mathematical function has been implemented so as
121       to accept a variable number of arguments, so all arguments are
122       mandatory when programming with the library (often, variants are
123       provided corresponding to the various flag values). When not mentioned
124       otherwise, the result and arguments of a function are assumed
125       implicitly to be of type "GEN". Most other functions return an object
126       of type "long" integer in C (see Chapter 4). The variable or parameter
127       names prec and flag always denote "long" integers.
128
129       The "entree" type is used by the library to implement iterators (loops,
130       sums, integrals, etc.) when a formal variable has to successively
131       assume a number of values in a given set. When programming with the
132       library, it is easier and much more efficient to code loops and the
133       like directly. Hence this type is not documented, although it does
134       appear in a few library function prototypes below. See "Label se:sums"
135       for more details.
136

Standard monadic or dyadic operators

138   +"/"-
139       The expressions "+""x" and "-""x" refer to monadic operators (the first
140       does nothing, the second negates "x").
141
142       The library syntax is gneg"(x)" for "-""x".
143
144   +, "-"
145       The expression "x" "+" "y" is the sum and "x" "-" "y" is the difference
146       of "x" and "y". Among the prominent impossibilities are
147       addition/subtraction between a scalar type and a vector or a matrix,
148       between vector/matrices of incompatible sizes and between an intmod and
149       a real number.
150
151       The library syntax is gadd"(x,y)" "x" "+" "y", " gsub(x,y)" for "x" "-"
152       "y".
153
154   *
155       The expression "x" "*" "y" is the product of "x" and "y". Among the
156       prominent impossibilities are multiplication between vector/matrices of
157       incompatible sizes, between an intmod and a real number. Note that
158       because of vector and matrix operations, "*" is not necessarily
159       commutative. Note also that since multiplication between two column or
160       two row vectors is not allowed, to obtain the scalar product of two
161       vectors of the same length, you must multiply a line vector by a column
162       vector, if necessary by transposing one of the vectors (using the
163       operator "~" or the function "mattranspose", see "Label
164       se:linear_algebra").
165
166       If "x" and "y" are binary quadratic forms, compose them. See also
167       "qfbnucomp" and "qfbnupow".
168
169       The library syntax is gmul"(x,y)" for "x" "*" "y". Also available is "
170       gsqr(x)" for "x" "*" "x" (faster of course!).
171
172   /
173       The expression "x" "/" "y" is the quotient of "x" and "y". In addition
174       to the impossibilities for multiplication, note that if the divisor is
175       a matrix, it must be an invertible square matrix, and in that case the
176       result is "x*y^{-1}". Furthermore note that the result is as exact as
177       possible: in particular, division of two integers always gives a
178       rational number (which may be an integer if the quotient is exact) and
179       \emph{not} the Euclidean quotient (see "x" "\" "y" for that), and
180       similarly the quotient of two polynomials is a rational function in
181       general. To obtain the approximate real value of the quotient of two
182       integers, add 0. to the result; to obtain the approximate "p"-adic
183       value of the quotient of two integers, add "O(p^k)" to the result;
184       finally, to obtain the Taylor series expansion of the quotient of two
185       polynomials, add "O(X^k)" to the result or use the "taylor" function
186       (see "Label se:taylor").
187
188       The library syntax is gdiv"(x,y)" for "x" "/" "y".
189
190   \
191       The expression "x \y" is the Euclidean quotient of "x" and "y". If "y"
192       is a real scalar, this is defined as "floor(x/y)" if "y > 0", and
193       "ceil(x/y)" if "y < 0" and the division is not exact. Hence the
194       remainder "x - (x\y)*y" is in "[0, |y|[".
195
196       Note that when "y" is an integer and "x" a polynomial, "y" is first
197       promoted to a polynomial of degree 0. When "x" is a vector or matrix,
198       the operator is applied componentwise.
199
200       The library syntax is gdivent"(x,y)" for "x" "\" "y".
201
202   \/
203       The expression "x" "\/" "y" evaluates to the rounded Euclidean quotient
204       of "x" and "y". This is the same as "x \y" except for scalar division:
205       the quotient is such that the corresponding remainder is smallest in
206       absolute value and in case of a tie the quotient closest to "+ oo " is
207       chosen (hence the remainder would belong to "]-|y|/2, |y|/2]").
208
209       When "x" is a vector or matrix, the operator is applied componentwise.
210
211       The library syntax is gdivround"(x,y)" for "x" "\/" "y".
212
213   %
214       The expression "x % y" evaluates to the modular Euclidean remainder of
215       "x" and "y", which we now define. If "y" is an integer, this is the
216       smallest non-negative integer congruent to "x" modulo "y". If "y" is a
217       polynomial, this is the polynomial of smallest degree congruent to "x"
218       modulo "y". When "y" is a non-integral real number, "x%y" is defined as
219       "x - (x\y)*y". This coincides with the definition for "y" integer if
220       and only if "x" is an integer, but still belongs to "[0, |y|[". For
221       instance:
222
223         ? (1/2) % 3
224         %1 = 2
225         ? 0.5 % 3
226           ***   forbidden division t_REAL % t_INT.
227         ? (1/2) % 3.0
228         %2 = 1/2
229
230       Note that when "y" is an integer and "x" a polynomial, "y" is first
231       promoted to a polynomial of degree 0. When "x" is a vector or matrix,
232       the operator is applied componentwise.
233
234       The library syntax is gmod"(x,y)" for "x" "%" "y".
235
236   divrem"(x,y,{v})"
237       creates a column vector with two components, the first being the
238       Euclidean quotient ("x \y"), the second the Euclidean remainder ("x -
239       (x\y)*y"), of the division of "x" by "y". This avoids the need to do
240       two divisions if one needs both the quotient and the remainder. If "v"
241       is present, and "x", "y" are multivariate polynomials, divide with
242       respect to the variable "v".
243
244       Beware that "divrem(x,y)[2]" is in general not the same as "x % y";
245       there is no operator to obtain it in GP:
246
247         ? divrem(1/2, 3)[2]
248         %1 = 1/2
249         ? (1/2) % 3
250         %2 = 2
251         ? divrem(Mod(2,9), 3)[2]
252           ***   forbidden division t_INTMOD \ t_INT.
253         ? Mod(2,9) % 6
254         %3 = Mod(2,3)
255
256       The library syntax is divrem"(x,y,v)",where "v" is a "long". Also
257       available as " gdiventres(x,y)" when "v" is not needed.
258
259   ^
260       The expression "x^n" is powering.  If the exponent is an integer, then
261       exact operations are performed using binary (left-shift) powering
262       techniques. In particular, in this case "x" cannot be a vector or
263       matrix unless it is a square matrix (invertible if the exponent is
264       negative). If "x" is a "p"-adic number, its precision will increase if
265       "v_p(n) > 0". Powering a binary quadratic form (types "t_QFI" and
266       "t_QFR") returns a reduced representative of the class, provided the
267       input is reduced. In particular, "x^1" is identical to "x".
268
269       PARI is able to rewrite the multiplication "x * x" of two
270       \emph{identical} objects as "x^2", or sqr(x). Here, identical means the
271       operands are two different labels referencing the same chunk of memory;
272       no equality test is performed. This is no longer true when more than
273       two arguments are involved.
274
275       If the exponent is not of type integer, this is treated as a
276       transcendental function (see "Label se:trans"), and in particular has
277       the effect of componentwise powering on vector or matrices.
278
279       As an exception, if the exponent is a rational number "p/q" and "x" an
280       integer modulo a prime or a "p"-adic number, return a solution "y" of
281       "y^q = x^p" if it exists. Currently, "q" must not have large prime
282       factors.  Beware that
283
284             ? Mod(7,19)^(1/2)
285             %1 = Mod(11, 19) /* is any square root */
286             ? sqrt(Mod(7,19))
287             %2 = Mod(8, 19)  /* is the smallest square root */
288             ? Mod(7,19)^(3/5)
289             %3 = Mod(1, 19)
290             ? %3^(5/3)
291             %4 = Mod(1, 19)  /* Mod(7,19) is just another cubic root */
292
293       If the exponent is a negative integer, an inverse must be computed.
294       For non-invertible "t_INTMOD", this will fail and implicitly exhibit a
295       non trivial factor of the modulus:
296
297             ? Mod(4,6)^(-1)
298               ***   impossible inverse modulo: Mod(2, 6).
299
300       (Here, a factor 2 is obtained directly. In general, take the gcd of the
301       representative and the modulus.) This is most useful when performing
302       complicated operations modulo an integer "N" whose factorization is
303       unknown. Either the computation succeeds and all is well, or a factor
304       "d" is discovered and the computation may be restarted modulo "d" or
305       "N/d".
306
307       For non-invertible "t_POLMOD", this will fail without exhibiting a
308       factor.
309
310             ? Mod(x^2, x^3-x)^(-1)
311               ***   non-invertible polynomial in RgXQ_inv.
312
313             ? a = Mod(3,4)*y^3 + Mod(1,4); b = y^6+y^5+y^4+y^3+y^2+y+1;
314             ? Mod(a, b)^(-1);
315               ***   non-invertible polynomial in RgXQ_inv.
316
317       In fact the latter polynomial is invertible, but the algorithm used
318       (subresultant) assumes the base ring is a domain. If it is not the
319       case, as here for "Z/4Z", a result will be correct but chances are an
320       error will occur first. In this specific case, one should work with
321       2-adics.  In general, one can try the following approach
322
323             ? inversemod(a, b) =
324             { local(m);
325               m = polsylvestermatrix(polrecip(a), polrecip(b));
326               m = matinverseimage(m, matid(#m)[,1]);
327               Polrev( vecextract(m, Str("..", poldegree(b))), variable(b) )
328             }
329             ? inversemod(a,b)
330             %2 = Mod(2,4)*y^5 + Mod(3,4)*y^3 + Mod(1,4)*y^2 + Mod(3,4)*y + Mod(2,4)
331
332       This is not guaranteed to work either since it must invert pivots. See
333       "Label se:linear_algebra".
334
335       The library syntax is gpow"(x,n,prec)" for "x^n".
336
337   bittest"(x,n)"
338       outputs the "n^{th}" bit of "x" starting from the right (i.e. the
339       coefficient of "2^n" in the binary expansion of "x").  The result is 0
340       or 1. To extract several bits at once as a vector, pass a vector for
341       "n".
342
343       See "Label se:bitand" for the behaviour at negative arguments.
344
345       The library syntax is bittest"(x,n)", where "n" and the result are
346       "long"s.
347
348   shift"(x,n)" or "x" "<< " "n" ( = "x" ">> " "(-n)")
349       shifts "x" componentwise left by "n" bits if "n >= 0" and right by
350       "|n|" bits if "n < 0".  A left shift by "n" corresponds to
351       multiplication by "2^n". A right shift of an integer "x" by "|n|"
352       corresponds to a Euclidean division of "x" by "2^{|n|}" with a
353       remainder of the same sign as "x", hence is not the same (in general)
354       as "x \ 2^n".
355
356       The library syntax is gshift"(x,n)" where "n" is a "long".
357
358   shiftmul"(x,n)"
359       multiplies "x" by "2^n". The difference with "shift" is that when "n <
360       0", ordinary division takes place, hence for example if "x" is an
361       integer the result may be a fraction, while for shifts Euclidean
362       division takes place when "n < 0" hence if "x" is an integer the result
363       is still an integer.
364
365       The library syntax is gmul2n"(x,n)" where "n" is a "long".
366
367   Comparison and boolean operators
368       The six standard comparison operators "<= ", "< ", ">= ", "> ", " == ",
369       "! = " are available in GP, and in library mode under the names "gle",
370       "glt", "gge", "ggt", "geq", "gne" respectively.  The library syntax is
371       "co(x,y)", where co is the comparison operator. The result is 1 (as a
372       "GEN") if the comparison is true, 0 (as a "GEN") if it is false. For
373       the purpose of comparison, "t_STR" objects are strictly larger than any
374       other non-string type; two "t_STR" objects are compared using the
375       standard lexicographic order.
376
377       The standard boolean functions  "||" (inclusive or), "&&" (and) and "!"
378       (not) are also available, and the library syntax is " gor(x,y)", "
379       gand(x,y)" and " gnot(x)" respectively.
380
381       In library mode, it is in fact usually preferable to use the two basic
382       functions which are " gcmp(x,y)" which gives the sign (1, 0, or -1) of
383       "x-y", where "x" and "y" must be in R, and " gequal(x,y)" which can be
384       applied to any two PARI objects "x" and "y" and gives 1 (i.e. true) if
385       they are equal (but not necessarily identical), 0 (i.e. false)
386       otherwise. Comparisons to special constants are implemented and should
387       be used instead of "gequal": " gcmp0(x)" ("x == 0" ?), " gcmp1(x)" ("x
388       == 1" ?), and " gcmp_1(x)" ("x == -1" ?).
389
390       Note that gcmp0(x) tests whether "x" is equal to zero, even if "x" is
391       not an exact object. To test whether "x" is an exact object which is
392       equal to zero, one must use " isexactzero(x)".
393
394       Also note that the "gcmp" and "gequal" functions return a C-integer,
395       and \emph{not} a "GEN" like "gle" etc.
396
397       GP accepts the following synonyms for some of the above functions:
398       since we thought it might easily lead to confusion, we don't use the
399       customary C operators for bitwise "and" or bitwise "or" (use "bitand"
400       or "bitor"), hence "|" and "&" are accepted as synonyms of "||" and
401       "&&" respectively.  Also, "<  > " is accepted as a synonym for "! = ".
402       On the other hand, " = " is definitely \emph{not} a synonym for " == "
403       since it is the assignment statement.
404
405   lex"(x,y)"
406       gives the result of a lexicographic comparison between "x" and "y" (as
407       "-1", 0 or 1). This is to be interpreted in quite a wide sense: It is
408       admissible to compare objects of different types (scalars, vectors,
409       matrices), provided the scalars can be compared, as well as
410       vectors/matrices of different lengths. The comparison is recursive.
411
412       In case all components are equal up to the smallest length of the
413       operands, the more complex is considered to be larger. More precisely,
414       the longest is the largest; when lengths are equal, we have matrix " >
415       " vector " > " scalar.  For example:
416
417         ? lex([1,3], [1,2,5])
418         %1 = 1
419         ? lex([1,3], [1,3,-1])
420         %2 = -1
421         ? lex([1], [[1]])
422         %3 = -1
423         ? lex([1], [1]~)
424         %4 = 0
425
426       The library syntax is lexcmp"(x,y)".
427
428   sign"(x)"
429       sign (0, 1 or "-1") of "x", which must be of type integer, real or
430       fraction.
431
432       The library syntax is gsigne"(x)". The result is a "long".
433
434   max"(x,y)" and " min(x,y)"
435       creates the maximum and minimum of "x" and "y" when they can be
436       compared.
437
438       The library syntax is gmax"(x,y)" and " gmin(x,y)".
439
440   vecmax"(x)"
441       if "x" is a vector or a matrix, returns the maximum of the elements of
442       "x", otherwise returns a copy of "x". Error if "x" is empty.
443
444       The library syntax is vecmax"(x)".
445
446   vecmin"(x)"
447       if "x" is a vector or a matrix, returns the minimum of the elements of
448       "x", otherwise returns a copy of "x". Error if "x" is empty.
449
450       The library syntax is vecmin"(x)".
451

Conversions and similar elementary functions or commands

453       Many of the conversion functions are rounding or truncating operations.
454       In this case, if the argument is a rational function, the result is the
455       Euclidean quotient of the numerator by the denominator, and if the
456       argument is a vector or a matrix, the operation is done componentwise.
457       This will not be restated for every function.
458
459   Col"({x = []})"
460       transforms the object "x" into a column vector.  The vector will be
461       with one component only, except when "x" is a vector or a quadratic
462       form (in which case the resulting vector is simply the initial object
463       considered as a column vector), a matrix (the column of row vectors
464       comprising the matrix is returned), a character string (a column of
465       individual characters is returned), but more importantly when "x" is a
466       polynomial or a power series. In the case of a polynomial, the
467       coefficients of the vector start with the leading coefficient of the
468       polynomial, while for power series only the significant coefficients
469       are taken into account, but this time by increasing order of degree.
470
471       The library syntax is gtocol"(x)".
472
473   List"({x = []})"
474       transforms a (row or column) vector "x" into a list. The only other way
475       to create a "t_LIST" is to use the function "listcreate".
476
477       This is useless in library mode.
478
479   Mat"({x = []})"
480       transforms the object "x" into a matrix.  If "x" is already a matrix, a
481       copy of "x" is created.  If "x" is not a vector or a matrix, this
482       creates a "1 x 1" matrix.  If "x" is a row (resp. column) vector, this
483       creates a 1-row (resp.  1-column) matrix, \emph{unless} all elements
484       are column (resp. row) vectors of the same length, in which case the
485       vectors are concatenated sideways and the associated big matrix is
486       returned.
487
488           ? Mat(x + 1)
489           %1 =
490           [x + 1]
491           ? Vec( matid(3) )
492           %2 = [[1, 0, 0]~, [0, 1, 0]~, [0, 0, 1]~]
493           ? Mat(%)
494           %3 =
495           [1 0 0]
496
497           [0 1 0]
498
499           [0 0 1]
500           ? Col( [1,2; 3,4] )
501           %4 = [[1, 2], [3, 4]]~
502           ? Mat(%)
503           %5 =
504           [1 2]
505
506           [3 4]
507
508       The library syntax is gtomat"(x)".
509
510   Mod"(x,y,{flag = 0})"
511        creates the PARI object "(x mod y)", i.e. an intmod or a polmod. "y"
512       must be an integer or a polynomial. If "y" is an integer, "x" must be
513       an integer, a rational number, or a "p"-adic number compatible with the
514       modulus "y". If "y" is a polynomial, "x" must be a scalar (which is not
515       a polmod), a polynomial, a rational function, or a power series.
516
517       This function is not the same as "x" "%" "y", the result of which is an
518       integer or a polynomial.
519
520       "flag" is obsolete and should not be used.
521
522       The library syntax is gmodulo"(x,y)".
523
524   Pol"(x,{v = x})"
525       transforms the object "x" into a polynomial with main variable "v". If
526       "x" is a scalar, this gives a constant polynomial. If "x" is a power
527       series, the effect is identical to "truncate" (see there), i.e. it
528       chops off the "O(X^k)". If "x" is a vector, this function creates the
529       polynomial whose coefficients are given in "x", with "x[1]" being the
530       leading coefficient (which can be zero).
531
532       Warning: this is \emph{not} a substitution function. It will not
533       transform an object containing variables of higher priority than "v".
534
535         ? Pol(x + y, y)
536           *** Pol: variable must have higher priority in gtopoly.
537
538       The library syntax is gtopoly"(x,v)", where "v" is a variable number.
539
540   Polrev"(x,{v = x})"
541       transform the object "x" into a polynomial with main variable "v". If
542       "x" is a scalar, this gives a constant polynomial.  If "x" is a power
543       series, the effect is identical to "truncate" (see there), i.e. it
544       chops off the "O(X^k)". If "x" is a vector, this function creates the
545       polynomial whose coefficients are given in "x", with "x[1]" being the
546       constant term. Note that this is the reverse of "Pol" if "x" is a
547       vector, otherwise it is identical to "Pol".
548
549       The library syntax is gtopolyrev"(x,v)", where "v" is a variable
550       number.
551
552   Qfb"(a,b,c,{D = 0.})"
553       creates the binary quadratic form "ax^2+bxy+cy^2". If "b^2-4ac > 0",
554       initialize Shanks' distance function to "D". Negative definite forms
555       are not implemented, use their positive definite counterpart instead.
556
557       The library syntax is Qfb0"(a,b,c,D,prec)". Also available are "
558       qfi(a,b,c)" (when "b^2-4ac < 0"), and " qfr(a,b,c,d)" (when "b^2-4ac >
559       0").
560
561   Ser"(x,{v = x})"
562       transforms the object "x" into a power series with main variable "v"
563       ("x" by default). If "x" is a scalar, this gives a constant power
564       series with precision given by the default "serieslength"
565       (corresponding to the C global variable "precdl"). If "x" is a
566       polynomial, the precision is the greatest of "precdl" and the degree of
567       the polynomial. If "x" is a vector, the precision is similarly given,
568       and the coefficients of the vector are understood to be the
569       coefficients of the power series starting from the constant term
570       (i.e. the reverse of the function "Pol").
571
572       The warning given for "Pol" also applies here: this is not a
573       substitution function.
574
575       The library syntax is gtoser"(x,v)", where "v" is a variable number
576       (i.e. a C integer).
577
578   Set"({x = []})"
579       converts "x" into a set, i.e. into a row vector of character strings,
580       with strictly increasing entries with respect to lexicographic
581       ordering. The components of "x" are put in canonical form (type
582       "t_STR") so as to be easily sorted. To recover an ordinary "GEN" from
583       such an element, you can apply "eval" to it.
584
585       The library syntax is gtoset"(x)".
586
587   Str"({x}*)"
588       converts its argument list into a single character string (type
589       "t_STR", the empty string if "x" is omitted).  To recover an ordinary
590       "GEN" from a string, apply "eval" to it. The arguments of "Str" are
591       evaluated in string context, see "Label se:strings".
592
593         ? x2 = 0; i = 2; Str(x, i)
594         %1 = "x2"
595         ? eval(%)
596         %2 = 0
597
598       This function is mostly useless in library mode. Use the pair
599       "strtoGEN"/"GENtostr" to convert between "GEN" and "char*".  The latter
600       returns a malloced string, which should be freed after usage.
601
602   Strchr"(x)"
603       converts "x" to a string, translating each integer into a character.
604
605         ? Strchr(97)
606         %1 = "a"
607         ? Vecsmall("hello world")
608         %2 = Vecsmall([104, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100])
609         ? Strchr(%)
610         %3 = "hello world"
611
612   Strexpand"({x}*)"
613       converts its argument list into a single character string (type
614       "t_STR", the empty string if "x" is omitted).  Then performe
615       environment expansion, see "Label se:envir".  This feature can be used
616       to read environment variable values.
617
618         ? Strexpand("$HOME/doc")
619         %1 = "/home/pari/doc"
620
621       The individual arguments are read in string context, see "Label
622       se:strings".
623
624   Strtex"({x}*)"
625       translates its arguments to TeX format, and concatenates the results
626       into a single character string (type "t_STR", the empty string if "x"
627       is omitted).
628
629       The individual arguments are read in string context, see "Label
630       se:strings".
631
632   Vec"({x = []})"
633       transforms the object "x" into a row vector.  The vector will be with
634       one component only, except when "x" is a vector or a quadratic form (in
635       which case the resulting vector is simply the initial object considered
636       as a row vector), a matrix (the vector of columns comprising the matrix
637       is return), a character string (a vector of individual characters is
638       returned), but more importantly when "x" is a polynomial or a power
639       series. In the case of a polynomial, the coefficients of the vector
640       start with the leading coefficient of the polynomial, while for power
641       series only the significant coefficients are taken into account, but
642       this time by increasing order of degree.
643
644       The library syntax is gtovec"(x)".
645
646   Vecsmall"({x = []})"
647       transforms the object "x" into a row vector of type "t_VECSMALL". This
648       acts as "Vec", but only on a limited set of objects (the result must be
649       representable as a vector of small integers). In particular,
650       polynomials and power series are forbidden.  If "x" is a character
651       string, a vector of individual characters in ASCII encoding is returned
652       ("Strchr" yields back the character string).
653
654       The library syntax is gtovecsmall"(x)".
655
656   binary"(x)"
657       outputs the vector of the binary digits of "|x|".  Here "x" can be an
658       integer, a real number (in which case the result has two components,
659       one for the integer part, one for the fractional part) or a
660       vector/matrix.
661
662       The library syntax is binaire"(x)".
663
664   bitand"(x,y)"
665        bitwise "and" of two integers "x" and "y", that is the integer
666
667         "sum_i (x_i and y_i) 2^i"
668
669       Negative numbers behave 2-adically, i.e. the result is the 2-adic limit
670       of "bitand""(x_n,y_n)", where "x_n" and "y_n" are non-negative integers
671       tending to "x" and "y" respectively. (The result is an ordinary
672       integer, possibly negative.)
673
674         ? bitand(5, 3)
675         %1 = 1
676         ? bitand(-5, 3)
677         %2 = 3
678         ? bitand(-5, -3)
679         %3 = -7
680
681       The library syntax is gbitand"(x,y)".
682
683   bitneg"(x,{n = -1})"
684       bitwise negation of an integer "x", truncated to "n" bits, that is the
685       integer
686
687         "sum_{i = 0}^{n-1} not(x_i) 2^i"
688
689       The special case "n = -1" means no truncation: an infinite sequence of
690       leading 1 is then represented as a negative number.
691
692       See "Label se:bitand" for the behaviour for negative arguments.
693
694       The library syntax is gbitneg"(x)".
695
696   bitnegimply"(x,y)"
697       bitwise negated imply of two integers "x" and "y" (or "not" "(x ==>
698       y)"), that is the integer
699
700         "sum (x_i and not(y_i)) 2^i"
701
702       See "Label se:bitand" for the behaviour for negative arguments.
703
704       The library syntax is gbitnegimply"(x,y)".
705
706   bitor"(x,y)"
707       bitwise (inclusive) "or" of two integers "x" and "y", that is the
708       integer
709
710         "sum (x_i or y_i) 2^i"
711
712       See "Label se:bitand" for the behaviour for negative arguments.
713
714       The library syntax is gbitor"(x,y)".
715
716   bittest"(x,n)"
717       outputs the "n^{th}" bit of "|x|" starting from the right (i.e. the
718       coefficient of "2^n" in the binary expansion of "x"). The result is 0
719       or 1. To extract several bits at once as a vector, pass a vector for
720       "n".
721
722       The library syntax is bittest"(x,n)", where "n" and the result are
723       "long"s.
724
725   bitxor"(x,y)"
726       bitwise (exclusive) "or" of two integers "x" and "y", that is the
727       integer
728
729         "sum (x_i xor y_i) 2^i"
730
731       See "Label se:bitand" for the behaviour for negative arguments.
732
733       The library syntax is gbitxor"(x,y)".
734
735   ceil"(x)"
736       ceiling of "x". When "x" is in R, the result is the smallest integer
737       greater than or equal to "x". Applied to a rational function, ceil(x)
738       returns the euclidian quotient of the numerator by the denominator.
739
740       The library syntax is gceil"(x)".
741
742   centerlift"(x,{v})"
743       lifts an element "x = a mod n" of "Z/nZ" to "a" in Z, and similarly
744       lifts a polmod to a polynomial. This is the same as "lift" except that
745       in the particular case of elements of "Z/nZ", the lift "y" is such that
746       "-n/2 < y <= n/2". If "x" is of type fraction, complex, quadratic,
747       polynomial, power series, rational function, vector or matrix, the lift
748       is done for each coefficient. Reals are forbidden.
749
750       The library syntax is centerlift0"(x,v)", where "v" is a "long" and an
751       omitted "v" is coded as "-1". Also available is " centerlift(x)" =
752       "centerlift0(x,-1)".
753
754   changevar"(x,y)"
755       creates a copy of the object "x" where its variables are modified
756       according to the permutation specified by the vector "y". For example,
757       assume that the variables have been introduced in the order "x", "a",
758       "b", "c". Then, if "y" is the vector "[x,c,a,b]", the variable "a" will
759       be replaced by "c", "b" by "a", and "c" by "b", "x" being unchanged.
760       Note that the permutation must be completely specified, e.g. "[c,a,b]"
761       would not work, since this would replace "x" by "c", and leave "a" and
762       "b" unchanged (as well as "c" which is the fourth variable of the
763       initial list). In particular, the new variable names must be distinct.
764
765       The library syntax is changevar"(x,y)".
766
767   components of a PARI object
768       There are essentially three ways to extract the components from a PARI
769       object.
770
771       The first and most general, is the function " component(x,n)" which
772       extracts the "n^{th}"-component of "x". This is to be understood as
773       follows: every PARI type has one or two initial code words. The
774       components are counted, starting at 1, after these code words. In
775       particular if "x" is a vector, this is indeed the "n^{th}"-component of
776       "x", if "x" is a matrix, the "n^{th}" column, if "x" is a polynomial,
777       the "n^{th}" coefficient (i.e. of degree "n-1"), and for power series,
778       the "n^{th}" significant coefficient. The use of the function
779       "component" implies the knowledge of the structure of the different
780       PARI types, which can be recalled by typing "\t" under "gp".
781
782       The library syntax is compo"(x,n)", where "n" is a "long".
783
784       The two other methods are more natural but more restricted. The
785       function " polcoeff(x,n)" gives the coefficient of degree "n" of the
786       polynomial or power series "x", with respect to the main variable of
787       "x" (to check variable ordering, or to change it, use the function
788       "reorder", see "Label se:reorder"). In particular if "n" is less than
789       the valuation of "x" or in the case of a polynomial, greater than the
790       degree, the result is zero (contrary to "compo" which would send an
791       error message). If "x" is a power series and "n" is greater than the
792       largest significant degree, then an error message is issued.
793
794       For greater flexibility, vector or matrix types are also accepted for
795       "x", and the meaning is then identical with that of "compo".
796
797       Finally note that a scalar type is considered by "polcoeff" as a
798       polynomial of degree zero.
799
800       The library syntax is truecoeff"(x,n)".
801
802       The third method is specific to vectors or matrices in GP. If "x" is a
803       (row or column) vector, then "x[n]" represents the "n^{th}" component
804       of "x", i.e. "compo(x,n)". It is more natural and shorter to write. If
805       "x" is a matrix, "x[m,n]" represents the coefficient of row "m" and
806       column "n" of the matrix, "x[m,]" represents the "m^{th}" \emph{row} of
807       "x", and "x[,n]" represents the "n^{th}" \emph{column} of "x".
808
809       Finally note that in library mode, the macros gcoeff and gmael are
810       available as direct accessors to a "GEN component". See Chapter 4 for
811       details.
812
813   conj"(x)"
814       conjugate of "x". The meaning of this is clear, except that for real
815       quadratic numbers, it means conjugation in the real quadratic field.
816       This function has no effect on integers, reals, intmods, fractions or
817       "p"-adics. The only forbidden type is polmod (see "conjvec" for this).
818
819       The library syntax is gconj"(x)".
820
821   conjvec"(x)"
822       conjugate vector representation of "x". If "x" is a polmod, equal to
823       "Mod""(a,q)", this gives a vector of length degree(q) containing the
824       complex embeddings of the polmod if "q" has integral or rational
825       coefficients, and the conjugates of the polmod if "q" has some intmod
826       coefficients. The order is the same as that of the "polroots"
827       functions. If "x" is an integer or a rational number, the result
828       is "x". If "x" is a (row or column) vector, the result is a matrix
829       whose columns are the conjugate vectors of the individual elements of
830       "x".
831
832       The library syntax is conjvec"(x,prec)".
833
834   denominator"(x)"
835       denominator of "x". The meaning of this is clear when "x" is a rational
836       number or function. If "x" is an integer or a polynomial, it is treated
837       as a rational number of function, respectively, and the result is equal
838       to 1. For polynomials, you probably want to use
839
840             denominator( content(x) )
841
842       instead. As for modular objects, "t_INTMOD" and "t_PADIC" have
843       denominator 1, and the denominator of a "t_POLMOD" is the denominator
844       of its (minimal degree) polynomial representative.
845
846       If "x" is a recursive structure, for instance a vector or matrix, the
847       lcm of the denominators of its components (a common denominator) is
848       computed.  This also applies for "t_COMPLEX"s and "t_QUAD"s.
849
850       Warning: multivariate objects are created according to variable
851       priorities, with possibly surprising side effects ("x/y" is a
852       polynomial, but "y/x" is a rational function). See "Label se:priority".
853
854       The library syntax is denom"(x)".
855
856   floor"(x)"
857       floor of "x". When "x" is in R, the result is the largest integer
858       smaller than or equal to "x". Applied to a rational function, floor(x)
859       returns the euclidian quotient of the numerator by the denominator.
860
861       The library syntax is gfloor"(x)".
862
863   frac"(x)"
864       fractional part of "x". Identical to "x-floor(x)". If "x" is real, the
865       result is in "[0,1[".
866
867       The library syntax is gfrac"(x)".
868
869   imag"(x)"
870       imaginary part of "x". When "x" is a quadratic number, this is the
871       coefficient of "omega" in the ``canonical'' integral basis "(1,omega)".
872
873       The library syntax is gimag"(x)". This returns a copy of the imaginary
874       part. The internal routine "imag_i" is faster, since it returns the
875       pointer and skips the copy.
876
877   length"(x)"
878       number of non-code words in "x" really used (i.e. the effective length
879       minus 2 for integers and polynomials). In particular, the degree of a
880       polynomial is equal to its length minus 1. If "x" has type "t_STR",
881       output number of letters.
882
883       The library syntax is glength"(x)" and the result is a C long.
884
885   lift"(x,{v})"
886       lifts an element "x = a mod n" of "Z/nZ" to "a" in Z, and similarly
887       lifts a polmod to a polynomial if "v" is omitted.  Otherwise, lifts
888       only polmods whose modulus has main variable "v" (if "v" does not occur
889       in "x", lifts only intmods). If "x" is of recursive (non modular) type,
890       the lift is done coefficientwise. For "p"-adics, this routine acts as
891       "truncate". It is not allowed to have "x" of type "t_REAL".
892
893         ? lift(Mod(5,3))
894         %1 = 2
895         ? lift(3 + O(3^9))
896         %2 = 3
897         ? lift(Mod(x,x^2+1))
898         %3 = x
899         ? lift(x * Mod(1,3) + Mod(2,3))
900         %4 = x + 2
901         ? lift(x * Mod(y,y^2+1) + Mod(2,3))
902         %5 = y*x + Mod(2, 3)   \\ do you understand this one ?
903         ? lift(x * Mod(y,y^2+1) + Mod(2,3), x)
904         %6 = Mod(y, y^2+1) * x + Mod(2, y^2+1)
905
906       The library syntax is lift0"(x,v)", where "v" is a "long" and an
907       omitted "v" is coded as "-1". Also available is " lift(x)" =
908       "lift0(x,-1)".
909
910   norm"(x)"
911       algebraic norm of "x", i.e. the product of "x" with its conjugate (no
912       square roots are taken), or conjugates for polmods. For vectors and
913       matrices, the norm is taken componentwise and hence is not the
914       "L^2"-norm (see "norml2"). Note that the norm of an element of R is its
915       square, so as to be compatible with the complex norm.
916
917       The library syntax is gnorm"(x)".
918
919   norml2"(x)"
920       square of the "L^2"-norm of "x". More precisely, if "x" is a scalar,
921       norml2(x) is defined to be "x * conj(x)".  If "x" is a (row or column)
922       vector or a matrix, norml2(x) is defined recursively as "sum_i
923       norml2(x_i)", where "(x_i)" run through the components of "x". In
924       particular, this yields the usual "sum |x_i|^2" (resp. "sum
925       |x_{i,j}|^2") if "x" is a vector (resp. matrix) with complex
926       components.
927
928         ? norml2( [ 1, 2, 3 ] )      \\ vector
929         %1 = 14
930         ? norml2( [ 1, 2; 3, 4] )   \\ matrix
931         %1 = 30
932         ? norml2( I + x )
933         %3 = x^2 + 1
934         ? norml2( [ [1,2], [3,4], 5, 6 ] )   \\ recursively defined
935         %4 = 91
936
937       The library syntax is gnorml2"(x)".
938
939   numerator"(x)"
940       numerator of "x". The meaning of this is clear when "x" is a rational
941       number or function. If "x" is an integer or a polynomial, it is treated
942       as a rational number of function, respectively, and the result is "x"
943       itself. For polynomials, you probably want to use
944
945             numerator( content(x) )
946
947       instead.
948
949       In other cases, numerator(x) is defined to be "denominator(x)*x". This
950       is the case when "x" is a vector or a matrix, but also for "t_COMPLEX"
951       or "t_QUAD". In particular since a "t_PADIC" or "t_INTMOD" has
952       denominator 1, its numerator is itself.
953
954       Warning: multivariate objects are created according to variable
955       priorities, with possibly surprising side effects ("x/y" is a
956       polynomial, but "y/x" is a rational function). See "Label se:priority".
957
958       The library syntax is numer"(x)".
959
960   numtoperm"(n,k)"
961       generates the "k"-th permutation (as a row vector of length "n") of the
962       numbers 1 to "n". The number "k" is taken modulo "n!", i.e. inverse
963       function of "permtonum".
964
965       The library syntax is numtoperm"(n,k)", where "n" is a "long".
966
967   padicprec"(x,p)"
968       absolute "p"-adic precision of the object "x".  This is the minimum
969       precision of the components of "x". The result is "VERYBIGINT"
970       ("2^{31}-1" for 32-bit machines or "2^{63}-1" for 64-bit machines) if
971       "x" is an exact object.
972
973       The library syntax is padicprec"(x,p)" and the result is a "long"
974       integer.
975
976   permtonum"(x)"
977       given a permutation "x" on "n" elements, gives the number "k" such that
978       "x = numtoperm(n,k)", i.e. inverse function of "numtoperm".
979
980       The library syntax is permtonum"(x)".
981
982   precision"(x,{n})"
983       gives the precision in decimal digits of the PARI object "x". If "x" is
984       an exact object, the largest single precision integer is returned. If
985       "n" is not omitted, creates a new object equal to "x" with a new
986       precision "n". This is to be understood as follows:
987
988       For exact types, no change. For "x" a vector or a matrix, the operation
989       is done componentwise.
990
991       For real "x", "n" is the number of desired significant \emph{decimal}
992       digits.  If "n" is smaller than the precision of "x", "x" is truncated,
993       otherwise "x" is extended with zeros.
994
995       For "x" a "p"-adic or a power series, "n" is the desired number of
996       significant "p"-adic or "X"-adic digits, where "X" is the main variable
997       of "x".
998
999       Note that the function "precision" never changes the type of the
1000       result.  In particular it is not possible to use it to obtain a
1001       polynomial from a power series. For that, see "truncate".
1002
1003       The library syntax is precision0"(x,n)", where "n" is a "long". Also
1004       available are " ggprecision(x)" (result is a "GEN") and " gprec(x,n)",
1005       where "n" is a "long".
1006
1007   random"({N = 2^{31}})"
1008       returns a random integer between 0 and "N-1". "N" is an integer, which
1009       can be arbitrary large. This is an internal PARI function and does not
1010       depend on the system's random number generator.
1011
1012       The resulting integer is obtained by means of linear congruences and
1013       will not be well distributed in arithmetic progressions. The random
1014       seed may be obtained via "getrand", and reset using "setrand".
1015
1016       Note that "random(2^31)" is \emph{not} equivalent to "random()",
1017       although both return an integer between 0 and "2^{31}-1". In fact,
1018       calling "random" with an argument generates a number of random words
1019       (32bit or 64bit depending on the architecture), rescaled to the desired
1020       interval.  The default uses directly a 31-bit generator.
1021
1022       Important technical note: the implementation of this function is
1023       incorrect unless "N" is a power of 2 (integers less than the bound are
1024       not equally likely, some may not even occur). It is kept for backward
1025       compatibility only, and has been rewritten from scratch in the 2.4.x
1026       unstable series. Use the following script for a correct version:
1027
1028         RANDOM(N) =
1029         { local(n, L);
1030
1031           L = 1; while (L < N, L <<= 1;);
1032           /* L/2 < N <= L, L power of 2 */
1033           until(n < N, n = random(L)); n
1034         }
1035
1036       The library syntax is genrand"(N)". Also available are "pari_rand""()"
1037       which returns a random "unsigned long" (32bit or 64bit depending on the
1038       architecture), and "pari_rand31""()" which returns a 31bit "long"
1039       integer.
1040
1041   real"(x)"
1042       real part of "x". In the case where "x" is a quadratic number, this is
1043       the coefficient of 1 in the ``canonical'' integral basis "(1,omega)".
1044
1045       The library syntax is greal"(x)". This returns a copy of the real part.
1046       The internal routine "real_i" is faster, since it returns the pointer
1047       and skips the copy.
1048
1049   round"(x,{&e})"
1050       If "x" is in R, rounds "x" to the nearest integer and sets "e" to the
1051       number of error bits, that is the binary exponent of the difference
1052       between the original and the rounded value (the ``fractional part'').
1053       If the exponent of "x" is too large compared to its precision (i.e. "e
1054       > 0"), the result is undefined and an error occurs if "e" was not
1055       given.
1056
1057       Important remark: note that, contrary to the other truncation
1058       functions, this function operates on every coefficient at every level
1059       of a PARI object. For example
1060
1061         "truncate((2.4*X^2-1.7)/(X)) = 2.4*X,"
1062
1063       whereas
1064
1065         "round((2.4*X^2-1.7)/(X)) = (2*X^2-2)/(X)."
1066
1067       An important use of "round" is to get exact results after a long
1068       approximate computation, when theory tells you that the coefficients
1069       must be integers.
1070
1071       The library syntax is grndtoi"(x,&e)", where "e" is a "long" integer.
1072       Also available is " ground(x)".
1073
1074   simplify"(x)"
1075       this function simplifies "x" as much as it can.  Specifically, a
1076       complex or quadratic number whose imaginary part is an exact 0
1077       (i.e. not an approximate one as a O(3) or "0.E-28") is converted to its
1078       real part, and a polynomial of degree 0 is converted to its constant
1079       term. Simplifications occur recursively.
1080
1081       This function is especially useful before using arithmetic functions,
1082       which expect integer arguments:
1083
1084         ? x = 1 + y - y
1085         %1 = 1
1086         ? divisors(x)
1087           *** divisors: not an integer argument in an arithmetic function
1088         ? type(x)
1089         %2 = "t_POL"
1090         ? type(simplify(x))
1091         %3 = "t_INT"
1092
1093       Note that GP results are simplified as above before they are stored in
1094       the history. (Unless you disable automatic simplification with "\y",
1095       that is.)  In particular
1096
1097         ? type(%1)
1098         %4 = "t_INT"
1099
1100       The library syntax is simplify"(x)".
1101
1102   sizebyte"(x)"
1103       outputs the total number of bytes occupied by the tree representing the
1104       PARI object "x".
1105
1106       The library syntax is taille2"(x)" which returns a "long"; " taille(x)"
1107       returns the number of \emph{words} instead.
1108
1109   sizedigit"(x)"
1110       outputs a quick bound for the number of decimal digits of (the
1111       components of) "x", off by at most 1. If you want the exact value, you
1112       can use "#Str(x)", which is slower.
1113
1114       The library syntax is sizedigit"(x)" which returns a "long".
1115
1116   truncate"(x,{&e})"
1117       truncates "x" and sets "e" to the number of error bits. When "x" is in
1118       R, this means that the part after the decimal point is chopped away,
1119       "e" is the binary exponent of the difference between the original and
1120       the truncated value (the ``fractional part''). If the exponent of "x"
1121       is too large compared to its precision (i.e. "e > 0"), the result is
1122       undefined and an error occurs if "e" was not given. The function
1123       applies componentwise on vector / matrices; "e" is then the maximal
1124       number of error bits. If "x" is a rational function, the result is the
1125       ``integer part'' (Euclidean quotient of numerator by denominator) and
1126       "e" is not set.
1127
1128       Note a very special use of "truncate": when applied to a power series,
1129       it transforms it into a polynomial or a rational function with
1130       denominator a power of "X", by chopping away the "O(X^k)". Similarly,
1131       when applied to a "p"-adic number, it transforms it into an integer or
1132       a rational number by chopping away the "O(p^k)".
1133
1134       The library syntax is gcvtoi"(x,&e)", where "e" is a "long" integer.
1135       Also available is " gtrunc(x)".
1136
1137   valuation"(x,p)"
1138        computes the highest exponent of "p" dividing "x". If "p" is of type
1139       integer, "x" must be an integer, an intmod whose modulus is divisible
1140       by "p", a fraction, a "q"-adic number with "q = p", or a polynomial or
1141       power series in which case the valuation is the minimum of the
1142       valuation of the coefficients.
1143
1144       If "p" is of type polynomial, "x" must be of type polynomial or
1145       rational function, and also a power series if "x" is a monomial.
1146       Finally, the valuation of a vector, complex or quadratic number is the
1147       minimum of the component valuations.
1148
1149       If "x = 0", the result is "VERYBIGINT" ("2^{31}-1" for 32-bit machines
1150       or "2^{63}-1" for 64-bit machines) if "x" is an exact object. If "x" is
1151       a "p"-adic numbers or power series, the result is the exponent of the
1152       zero.  Any other type combinations gives an error.
1153
1154       The library syntax is ggval"(x,p)", and the result is a "long".
1155
1156   variable"(x)"
1157       gives the main variable of the object "x", and "p" if "x" is a "p"-adic
1158       number. Gives an error if "x" has no variable associated to it. Note
1159       that this function is useful only in GP, since in library mode the
1160       function "gvar" is more appropriate.
1161
1162       The library syntax is gpolvar"(x)". However, in library mode, this
1163       function should not be used.  Instead, test whether "x" is a "p"-adic
1164       (type "t_PADIC"), in which case "p" is in "x[2]", or call the function
1165       " gvar(x)" which returns the variable \emph{number} of "x" if it
1166       exists, "BIGINT" otherwise.
1167

Transcendental functions

1169       As a general rule, which of course in some cases may have exceptions,
1170       transcendental functions operate in the following way:
1171
1172       \item If the argument is either an integer, a real, a rational, a
1173       complex or a quadratic number, it is, if necessary, first converted to
1174       a real (or complex) number using the current precision held in the
1175       default "realprecision". Note that only exact arguments are converted,
1176       while inexact arguments such as reals are not.
1177
1178       In GP this is transparent to the user, but when programming in library
1179       mode, care must be taken to supply a meaningful parameter prec as the
1180       last argument of the function if the first argument is an exact object.
1181       This parameter is ignored if the argument is inexact.
1182
1183       Note that in library mode the precision argument prec is a word count
1184       including codewords, i.e. represents the length in words of a real
1185       number, while under "gp" the precision (which is changed by the
1186       metacommand "\p" or using "default(realprecision,...)") is the number
1187       of significant decimal digits.
1188
1189       Note that some accuracies attainable on 32-bit machines cannot be
1190       attained on 64-bit machines for parity reasons. For example the default
1191       "gp" accuracy is 28 decimal digits on 32-bit machines, corresponding to
1192       prec having the value 5, but this cannot be attained on 64-bit
1193       machines.
1194
1195       After possible conversion, the function is computed. Note that even if
1196       the argument is real, the result may be complex (e.g. "acos(2.0)" or
1197       "acosh(0.0)"). Note also that the principal branch is always chosen.
1198
1199       \item If the argument is an intmod or a "p"-adic, at present only a few
1200       functions like "sqrt" (square root), "sqr" (square), "log", "exp",
1201       powering, "teichmuller" (Teichmüller character) and "agm" (arithmetic-
1202       geometric mean) are implemented.
1203
1204       Note that in the case of a 2-adic number, sqr(x) may not be identical
1205       to "x*x": for example if "x = 1+O(2^5)" and "y = 1+O(2^5)" then "x*y =
1206       1+O(2^5)" while "sqr(x) = 1+O(2^6)". Here, "x * x" yields the same
1207       result as sqr(x) since the two operands are known to be
1208       \emph{identical}. The same statement holds true for "p"-adics raised to
1209       the power "n", where "v_p(n) > 0".
1210
1211       Remark: note that if we wanted to be strictly consistent with the PARI
1212       philosophy, we should have "x*y = (4 mod 8)" and "sqr(x) = (4 mod 32)"
1213       when both "x" and "y" are congruent to 2 modulo 4.  However, since
1214       intmod is an exact object, PARI assumes that the modulus must not
1215       change, and the result is hence "(0 mod 4)" in both cases. On the other
1216       hand, "p"-adics are not exact objects, hence are treated differently.
1217
1218       \item If the argument is a polynomial, power series or rational
1219       function, it is, if necessary, first converted to a power series using
1220       the current precision held in the variable "precdl". Under "gp" this
1221       again is transparent to the user. When programming in library mode,
1222       however, the global variable "precdl" must be set before calling the
1223       function if the argument has an exact type (i.e. not a power series).
1224       Here "precdl" is not an argument of the function, but a global
1225       variable.
1226
1227       Then the Taylor series expansion of the function around "X = 0" (where
1228       "X" is the main variable) is computed to a number of terms depending on
1229       the number of terms of the argument and the function being computed.
1230
1231       \item If the argument is a vector or a matrix, the result is the
1232       componentwise evaluation of the function. In particular, transcendental
1233       functions on square matrices, which are not implemented in the present
1234       version /usr/share/libpari23, will have a different name if they are
1235       implemented some day.
1236
1237   ^
1238       If "y" is not of type integer, "x^y" has the same effect as
1239       "exp(y*log(x))". It can be applied to "p"-adic numbers as well as to
1240       the more usual types.
1241
1242       The library syntax is gpow"(x,y,prec)".
1243
1244   Euler
1245       Euler's constant "gamma = 0.57721...". Note that "Euler" is one of the
1246       few special reserved names which cannot be used for variables (the
1247       others are "I" and "Pi", as well as all function names).
1248
1249       The library syntax is mpeuler"(prec)" where "prec" \emph{must} be
1250       given. Note that this creates "gamma" on the PARI stack, but a copy is
1251       also created on the heap for quicker computations next time the
1252       function is called.
1253
1254   I
1255       the complex number " sqrt {-1}".
1256
1257       The library syntax is the global variable "gi" (of type "GEN").
1258
1259   Pi
1260       the constant "Pi" (3.14159...).
1261
1262       The library syntax is mppi"(prec)" where "prec" \emph{must} be given.
1263       Note that this creates "Pi" on the PARI stack, but a copy is also
1264       created on the heap for quicker computations next time the function is
1265       called.
1266
1267   abs"(x)"
1268       absolute value of "x" (modulus if "x" is complex).  Rational functions
1269       are not allowed. Contrary to most transcendental functions, an exact
1270       argument is \emph{not} converted to a real number before applying "abs"
1271       and an exact result is returned if possible.
1272
1273         ? abs(-1)
1274         %1 = 1
1275         ? abs(3/7 + 4/7*I)
1276         %2 = 5/7
1277         ? abs(1 + I)
1278         %3 = 1.414213562373095048801688724
1279
1280       If "x" is a polynomial, returns "-x" if the leading coefficient is real
1281       and negative else returns "x". For a power series, the constant
1282       coefficient is considered instead.
1283
1284       The library syntax is gabs"(x,prec)".
1285
1286   acos"(x)"
1287       principal branch of "cos^{-1}(x)", i.e. such that "Re(acos(x)) belongs
1288       to [0,Pi]". If "x belongs to R" and "|x| > 1", then acos(x) is complex.
1289
1290       The library syntax is gacos"(x,prec)".
1291
1292   acosh"(x)"
1293       principal branch of "cosh^{-1}(x)", i.e. such that "Im(acosh(x))
1294       belongs to [0,Pi]". If "x belongs to R" and "x < 1", then acosh(x) is
1295       complex.
1296
1297       The library syntax is gach"(x,prec)".
1298
1299   agm"(x,y)"
1300       arithmetic-geometric mean of "x" and "y". In the case of complex or
1301       negative numbers, the principal square root is always chosen. "p"-adic
1302       or power series arguments are also allowed. Note that a "p"-adic agm
1303       exists only if "x/y" is congruent to 1 modulo "p" (modulo 16 for "p =
1304       2"). "x" and "y" cannot both be vectors or matrices.
1305
1306       The library syntax is agm"(x,y,prec)".
1307
1308   arg"(x)"
1309       argument of the complex number "x", such that "-Pi < arg(x) <= Pi".
1310
1311       The library syntax is garg"(x,prec)".
1312
1313   asin"(x)"
1314       principal branch of "sin^{-1}(x)", i.e. such that "Re(asin(x)) belongs
1315       to [-Pi/2,Pi/2]". If "x belongs to R" and "|x| > 1" then asin(x) is
1316       complex.
1317
1318       The library syntax is gasin"(x,prec)".
1319
1320   asinh"(x)"
1321       principal branch of "sinh^{-1}(x)", i.e. such that "Im(asinh(x))
1322       belongs to [-Pi/2,Pi/2]".
1323
1324       The library syntax is gash"(x,prec)".
1325
1326   atan"(x)"
1327       principal branch of "tan^{-1}(x)", i.e. such that "Re(atan(x)) belongs
1328       to  ]-Pi/2,Pi/2[".
1329
1330       The library syntax is gatan"(x,prec)".
1331
1332   atanh"(x)"
1333       principal branch of "tanh^{-1}(x)", i.e. such that "Im(atanh(x))
1334       belongs to  ]-Pi/2,Pi/2]". If "x belongs to R" and "|x| > 1" then
1335       atanh(x) is complex.
1336
1337       The library syntax is gath"(x,prec)".
1338
1339   bernfrac"(x)"
1340       Bernoulli number "B_x", where "B_0 = 1", "B_1 = -1/2", "B_2 = 1/6",...,
1341       expressed as a rational number.  The argument "x" should be of type
1342       integer.
1343
1344       The library syntax is bernfrac"(x)".
1345
1346   bernreal"(x)"
1347       Bernoulli number "B_x", as "bernfrac", but "B_x" is returned as a real
1348       number (with the current precision).
1349
1350       The library syntax is bernreal"(x,prec)".
1351
1352   bernvec"(x)"
1353       creates a vector containing, as rational numbers, the Bernoulli numbers
1354       "B_0", "B_2",..., "B_{2x}".  This routine is obsolete. Use "bernfrac"
1355       instead each time you need a Bernoulli number in exact form.
1356
1357       Note: this routine is implemented using repeated independent calls to
1358       "bernfrac", which is faster than the standard recursion in exact
1359       arithmetic. It is only kept for backward compatibility: it is not
1360       faster than individual calls to "bernfrac", its output uses a lot of
1361       memory space, and coping with the index shift is awkward.
1362
1363       The library syntax is bernvec"(x)".
1364
1365   besselh1"(nu,x)"
1366       "H^1"-Bessel function of index nu and argument "x".
1367
1368       The library syntax is hbessel1"(nu,x,prec)".
1369
1370   besselh2"(nu,x)"
1371       "H^2"-Bessel function of index nu and argument "x".
1372
1373       The library syntax is hbessel2"(nu,x,prec)".
1374
1375   besseli"(nu,x)"
1376       "I"-Bessel function of index nu and argument "x". If "x" converts to a
1377       power series, the initial factor "(x/2)^nu/Gamma(nu+1)" is omitted
1378       (since it cannot be represented in PARI when "nu" is not integral).
1379
1380       The library syntax is ibessel"(nu,x,prec)".
1381
1382   besselj"(nu,x)"
1383       "J"-Bessel function of index nu and argument "x". If "x" converts to a
1384       power series, the initial factor "(x/2)^nu/Gamma(nu+1)" is omitted
1385       (since it cannot be represented in PARI when "nu" is not integral).
1386
1387       The library syntax is jbessel"(nu,x,prec)".
1388
1389   besseljh"(n,x)"
1390       "J"-Bessel function of half integral index.  More precisely,
1391       "besseljh(n,x)" computes "J_{n+1/2}(x)" where "n" must be of type
1392       integer, and "x" is any element of C. In the present version
1393       /usr/share/libpari23, this function is not very accurate when "x" is
1394       small.
1395
1396       The library syntax is jbesselh"(n,x,prec)".
1397
1398   besselk"(nu,x,{flag = 0})"
1399       "K"-Bessel function of index nu (which can be complex) and argument
1400       "x". Only real and positive arguments "x" are allowed in the present
1401       version /usr/share/libpari23. If "flag" is equal to 1, uses another
1402       implementation of this function which is faster when "x\gg 1".
1403
1404       The library syntax is kbessel"(nu,x,prec)" and " kbessel2(nu,x,prec)"
1405       respectively.
1406
1407   besseln"(nu,x)"
1408       "N"-Bessel function of index nu and argument "x".
1409
1410       The library syntax is nbessel"(nu,x,prec)".
1411
1412   cos"(x)"
1413       cosine of "x".
1414
1415       The library syntax is gcos"(x,prec)".
1416
1417   cosh"(x)"
1418       hyperbolic cosine of "x".
1419
1420       The library syntax is gch"(x,prec)".
1421
1422   cotan"(x)"
1423       cotangent of "x".
1424
1425       The library syntax is gcotan"(x,prec)".
1426
1427   dilog"(x)"
1428       principal branch of the dilogarithm of "x", i.e. analytic continuation
1429       of the power series " log _2(x) = sum_{n >= 1}x^n/n^2".
1430
1431       The library syntax is dilog"(x,prec)".
1432
1433   eint1"(x,{n})"
1434       exponential integral "int_x^ oo (e^{-t})/(t)dt" ("x belongs to R")
1435
1436       If "n" is present, outputs the "n"-dimensional vector
1437       "[eint1(x),...,eint1(nx)]" ("x >= 0"). This is faster than repeatedly
1438       calling "eint1(i * x)".
1439
1440       The library syntax is veceint1"(x,n,prec)". Also available is "
1441       eint1(x,prec)".
1442
1443   erfc"(x)"
1444       complementary error function "(2/ sqrt Pi)int_x^ oo e^{-t^2}dt" ("x
1445       belongs to R").
1446
1447       The library syntax is erfc"(x,prec)".
1448
1449   eta"(x,{flag = 0})"
1450       Dedekind's "eta" function, without the "q^{1/24}". This means the
1451       following: if "x" is a complex number with positive imaginary part, the
1452       result is "prod_{n = 1}^ oo (1-q^n)", where "q = e^{2iPi x}". If "x" is
1453       a power series (or can be converted to a power series) with positive
1454       valuation, the result is "prod_{n = 1}^ oo (1-x^n)".
1455
1456       If "flag = 1" and "x" can be converted to a complex number (i.e. is not
1457       a power series), computes the true "eta" function, including the
1458       leading "q^{1/24}".
1459
1460       The library syntax is eta"(x,prec)".
1461
1462   exp"(x)"
1463       exponential of "x".  "p"-adic arguments with positive valuation are
1464       accepted.
1465
1466       The library syntax is gexp"(x,prec)".
1467
1468   gammah"(x)"
1469       gamma function evaluated at the argument "x+1/2".
1470
1471       The library syntax is ggamd"(x,prec)".
1472
1473   gamma"(x)"
1474       gamma function of "x".
1475
1476       The library syntax is ggamma"(x,prec)".
1477
1478   hyperu"(a,b,x)"
1479       "U"-confluent hypergeometric function with parameters "a" and "b". The
1480       parameters "a" and "b" can be complex but the present implementation
1481       requires "x" to be positive.
1482
1483       The library syntax is hyperu"(a,b,x,prec)".
1484
1485   incgam"(s,x,{y})"
1486       incomplete gamma function. The argument "x" and "s" are complex numbers
1487       ("x" must be a positive real number if "s = 0").  The result returned
1488       is "int_x^ oo e^{-t}t^{s-1}dt". When "y" is given, assume (of course
1489       without checking!) that "y = Gamma(s)". For small "x", this will speed
1490       up the computation.
1491
1492       The library syntax is incgam"(s,x,prec)" and " incgam0(s,x,y,prec)",
1493       respectively (an omitted "y" is coded as "NULL").
1494
1495   incgamc"(s,x)"
1496       complementary incomplete gamma function.  The arguments "x" and "s" are
1497       complex numbers such that "s" is not a pole of "Gamma" and
1498       "|x|/(|s|+1)" is not much larger than 1 (otherwise the convergence is
1499       very slow). The result returned is "int_0^x e^{-t}t^{s-1}dt".
1500
1501       The library syntax is incgamc"(s,x,prec)".
1502
1503   log"(x)"
1504       principal branch of the natural logarithm of "x", i.e. such that
1505       "Im(log(x)) belongs to  ]-Pi,Pi]". The result is complex (with
1506       imaginary part equal to "Pi") if "x belongs to R" and "x < 0". In
1507       general, the algorithm uses the formula
1508
1509         " log (x)  ~  (Pi)/(2agm(1, 4/s)) - m  log  2, "
1510
1511       if "s = x 2^m" is large enough. (The result is exact to "B" bits
1512       provided "s > 2^{B/2}".) At low accuracies, the series expansion near 1
1513       is used.
1514
1515       "p"-adic arguments are also accepted for "x", with the convention that
1516       " log (p) = 0". Hence in particular " exp ( log (x))/x" is not in
1517       general equal to 1 but to a "(p-1)"-th root of unity (or "+-1" if "p =
1518       2") times a power of "p".
1519
1520       The library syntax is glog"(x,prec)".
1521
1522   lngamma"(x)"
1523       principal branch of the logarithm of the gamma function of "x". This
1524       function is analytic on the complex plane with non-positive integers
1525       removed. Can have much larger arguments than "gamma" itself. The
1526       "p"-adic "lngamma" function is not implemented.
1527
1528       The library syntax is glngamma"(x,prec)".
1529
1530   polylog"(m,x,{flag = 0})"
1531       one of the different polylogarithms, depending on flag:
1532
1533       If "flag = 0" or is omitted: "m^th" polylogarithm of "x", i.e. analytic
1534       continuation of the power series "Li_m(x) = sum_{n >= 1}x^n/n^m" ("x <
1535       1"). Uses the functional equation linking the values at "x" and "1/x"
1536       to restrict to the case "|x| <= 1", then the power series when "|x|^2
1537       <= 1/2", and the power series expansion in " log (x)" otherwise.
1538
1539       Using "flag", computes a modified "m^th" polylogarithm of "x".  We use
1540       Zagier's notations; let " Re _m" denotes " Re " or " Im " depending
1541       whether "m" is odd or even:
1542
1543       If "flag = 1": compute "~ D_m(x)", defined for "|x| <= 1" by
1544
1545         " Re _m(sum_{k = 0}^{m-1} ((- log |x|)^k)/(k!)Li_{m-k}(x) +((- log
1546       |x|)^{m-1})/(m!) log |1-x|)."
1547
1548       If "flag = 2": compute D_m(x), defined for "|x| <= 1" by
1549
1550         " Re _m(sum_{k = 0}^{m-1}((- log |x|)^k)/(k!)Li_{m-k}(x) -(1)/(2)((-
1551       log |x|)^m)/(m!))."
1552
1553       If "flag = 3": compute P_m(x), defined for "|x| <= 1" by
1554
1555         " Re _m(sum_{k = 0}^{m-1}(2^kB_k)/(k!)( log |x|)^kLi_{m-k}(x)
1556       -(2^{m-1}B_m)/(m!)( log |x|)^m)."
1557
1558       These three functions satisfy the functional equation "f_m(1/x) =
1559       (-1)^{m-1}f_m(x)".
1560
1561       The library syntax is polylog0"(m,x,flag,prec)".
1562
1563   psi"(x)"
1564       the "psi"-function of "x", i.e. the logarithmic derivative
1565       "Gamma'(x)/Gamma(x)".
1566
1567       The library syntax is gpsi"(x,prec)".
1568
1569   sin"(x)"
1570       sine of "x".
1571
1572       The library syntax is gsin"(x,prec)".
1573
1574   sinh"(x)"
1575       hyperbolic sine of "x".
1576
1577       The library syntax is gsh"(x,prec)".
1578
1579   sqr"(x)"
1580       square of "x". This operation is not completely straightforward,
1581       i.e. identical to "x * x", since it can usually be computed more
1582       efficiently (roughly one-half of the elementary multiplications can be
1583       saved). Also, squaring a 2-adic number increases its precision. For
1584       example,
1585
1586         ? (1 + O(2^4))^2
1587         %1 = 1 + O(2^5)
1588         ? (1 + O(2^4)) * (1 + O(2^4))
1589         %2 = 1 + O(2^4)
1590
1591       Note that this function is also called whenever one multiplies two
1592       objects which are known to be \emph{identical}, e.g. they are the value
1593       of the same variable, or we are computing a power.
1594
1595         ? x = (1 + O(2^4)); x * x
1596         %3 = 1 + O(2^5)
1597         ? (1 + O(2^4))^4
1598         %4 = 1 + O(2^6)
1599
1600       (note the difference between %2 and %3 above).
1601
1602       The library syntax is gsqr"(x)".
1603
1604   sqrt"(x)"
1605       principal branch of the square root of "x", i.e. such that
1606       "Arg(sqrt(x)) belongs to  ]-Pi/2, Pi/2]", or in other words such that "
1607       Re (sqrt(x)) > 0" or " Re (sqrt(x)) = 0" and " Im (sqrt(x)) >= 0". If
1608       "x belongs to R" and "x < 0", then the result is complex with positive
1609       imaginary part.
1610
1611       Intmod a prime and "p"-adics are allowed as arguments. In that case,
1612       the square root (if it exists) which is returned is the one whose first
1613       "p"-adic digit (or its unique "p"-adic digit in the case of intmods) is
1614       in the interval "[0,p/2]". When the argument is an intmod a non-prime
1615       (or a non-prime-adic), the result is undefined.
1616
1617       The library syntax is gsqrt"(x,prec)".
1618
1619   sqrtn"(x,n,{&z})"
1620       principal branch of the "n"th root of "x", i.e. such that "Arg(sqrt(x))
1621       belongs to  ]-Pi/n, Pi/n]". Intmod a prime and "p"-adics are allowed as
1622       arguments.
1623
1624       If "z" is present, it is set to a suitable root of unity allowing to
1625       recover all the other roots. If it was not possible, z is set to zero.
1626       In the case this argument is present and no square root exist, 0 is
1627       returned instead or raising an error.
1628
1629         ? sqrtn(Mod(2,7), 2)
1630         %1 = Mod(4, 7)
1631         ? sqrtn(Mod(2,7), 2, &z); z
1632         %2 = Mod(6, 7)
1633         ? sqrtn(Mod(2,7), 3)
1634           *** sqrtn: nth-root does not exist in gsqrtn.
1635         ? sqrtn(Mod(2,7), 3,  &z)
1636         %2 = 0
1637         ? z
1638         %3 = 0
1639
1640       The following script computes all roots in all possible cases:
1641
1642         sqrtnall(x,n)=
1643         {
1644           local(V,r,z,r2);
1645           r = sqrtn(x,n, &z);
1646           if (!z, error("Impossible case in sqrtn"));
1647           if (type(x) == "t_INTMOD" || type(x)=="t_PADIC" ,
1648             r2 = r*z; n = 1;
1649             while (r2!=r, r2*=z;n++));
1650           V = vector(n); V[1] = r;
1651           for(i=2, n, V[i] = V[i-1]*z);
1652           V
1653         }
1654         addhelp(sqrtnall,"sqrtnall(x,n):compute the vector of nth-roots of x");
1655
1656       The library syntax is gsqrtn"(x,n,&z,prec)".
1657
1658   tan"(x)"
1659       tangent of "x".
1660
1661       The library syntax is gtan"(x,prec)".
1662
1663   tanh"(x)"
1664       hyperbolic tangent of "x".
1665
1666       The library syntax is gth"(x,prec)".
1667
1668   teichmuller"(x)"
1669       Teichmüller character of the "p"-adic number "x", i.e. the unique
1670       "(p-1)"-th root of unity congruent to "x / p^{v_p(x)}" modulo "p".
1671
1672       The library syntax is teich"(x)".
1673
1674   theta"(q,z)"
1675       Jacobi sine theta-function.
1676
1677       The library syntax is theta"(q,z,prec)".
1678
1679   thetanullk"(q,k)"
1680       "k"-th derivative at "z = 0" of "theta(q,z)".
1681
1682       The library syntax is thetanullk"(q,k,prec)", where "k" is a "long".
1683
1684   weber"(x,{flag = 0})"
1685       one of Weber's three "f" functions.  If "flag = 0", returns
1686
1687         "f(x) =  exp (-iPi/24).eta((x+1)/2)/eta(x)   such that  j =
1688       (f^{24}-16)^3/f^{24},"
1689
1690       where "j" is the elliptic "j"-invariant  (see the function "ellj").  If
1691       "flag = 1", returns
1692
1693         "f_1(x) = eta(x/2)/eta(x)  such that  j = (f_1^{24}+16)^3/f_1^{24}."
1694
1695       Finally, if "flag = 2", returns
1696
1697         "f_2(x) =  sqrt {2}eta(2x)/eta(x)  such that  j =
1698       (f_2^{24}+16)^3/f_2^{24}."
1699
1700       Note the identities "f^8 = f_1^8+f_2^8" and "ff_1f_2 =  sqrt 2".
1701
1702       The library syntax is weber0"(x,flag,prec)". Associated to the various
1703       values of flag, the following functions are also available: "
1704       werberf(x,prec)", " werberf1(x,prec)" or " werberf2(x,prec)".
1705
1706   zeta"(s)"
1707       For "s" a complex number, Riemann's zeta function  "zeta(s) = sum_{n >=
1708       1}n^{-s}", computed using the Euler-Maclaurin summation formula, except
1709       when "s" is of type integer, in which case it is computed using
1710       Bernoulli numbers for "s <= 0" or "s > 0" and even, and using modular
1711       forms for "s > 0" and odd.
1712
1713       For "s" a "p"-adic number, Kubota-Leopoldt zeta function at "s", that
1714       is the unique continuous "p"-adic function on the "p"-adic integers
1715       that interpolates the values of "(1 - p^{-k}) zeta(k)" at negative
1716       integers "k" such that "k = 1 (mod p-1)" (resp. "k" is odd) if "p" is
1717       odd (resp. "p = 2").
1718
1719       The library syntax is gzeta"(s,prec)".
1720

Arithmetic functions

1722       These functions are by definition functions whose natural domain of
1723       definition is either Z (or "Z_{ > 0}"), or sometimes polynomials over a
1724       base ring. Functions which concern polynomials exclusively will be
1725       explained in the next section. The way these functions are used is
1726       completely different from transcendental functions: in general only the
1727       types integer and polynomial are accepted as arguments. If a vector or
1728       matrix type is given, the function will be applied on each coefficient
1729       independently.
1730
1731       In the present version /usr/share/libpari23, all arithmetic functions
1732       in the narrow sense of the word --- Euler's totient function, the
1733       Moebius function, the sums over divisors or powers of divisors etc.---
1734       call, after trial division by small primes, the same versatile
1735       factoring machinery described under "factorint". It includes Shanks
1736       SQUFOF, Pollard Rho, ECM and MPQS stages, and has an early exit option
1737       for the functions moebius and (the integer function underlying)
1738       issquarefree. Note that it relies on a (fairly strong) probabilistic
1739       primality test, see "ispseudoprime".
1740
1741   addprimes"({x = []})"
1742       adds the integers contained in the vector "x" (or the single integer
1743       "x") to a special table of ``user-defined primes'', and returns that
1744       table. Whenever "factor" is subsequently called, it will trial divise
1745       by the elements in this table.  If "x" is empty or omitted, just
1746       returns the current list of extra primes.
1747
1748       The entries in "x" are not checked for primality, and in fact they need
1749       only be positive integers. The algorithm makes sure that all elements
1750       in the table are pairwise coprime, so it may end up containing divisors
1751       of the input integers.
1752
1753       It is a useful trick to add known composite numbers, which the function
1754       "factor(x,0)" was not able to factor. In case the message ``impossible
1755       inverse modulo "<"some INTMOD">"'' shows up afterwards, you have just
1756       stumbled over a non-trivial factor. Note that the arithmetic functions
1757       in the narrow sense, like eulerphi, do \emph{not} use this extra table.
1758
1759       To remove primes from the list use "removeprimes".
1760
1761       The library syntax is addprimes"(x)".
1762
1763   bestappr"(x,A,{B})"
1764       if "B" is omitted, finds the best rational approximation to "x belongs
1765       to R" (or "R[X]", or "R^n",...) with denominator at most equal to "A"
1766       using continued fractions.
1767
1768       If "B" is present, "x" is assumed to be of type "t_INTMOD" modulo "M"
1769       (or a recursive combination of those), and the routine returns the
1770       unique fraction "a/b" in coprime integers "a <= A" and "b <= B" which
1771       is congruent to "x" modulo "M". If "M <= 2AB", uniqueness is not
1772       guaranteed and the function fails with an error message. If rational
1773       reconstruction is not possible (no such "a/b" exists for at least one
1774       component of "x"), returns "-1".
1775
1776       The library syntax is bestappr0"(x,A,B)". Also available is "
1777       bestappr(x,A)" corresponding to an omitted "B".
1778
1779   bezout"(x,y)"
1780       finds "u" and "v" minimal in a natural sense such that "x*u+y*v =
1781       gcd(x,y)". The arguments must be both integers or both polynomials, and
1782       the result is a row vector with three components "u", "v", and
1783       "gcd(x,y)".
1784
1785       The library syntax is vecbezout"(x,y)" to get the vector, or "
1786       gbezout(x,y, &u, &v)" which gives as result the address of the created
1787       gcd, and puts the addresses of the corresponding created objects into
1788       "u" and "v".
1789
1790   bezoutres"(x,y)"
1791       as "bezout", with the resultant of "x" and "y" replacing the gcd.  The
1792       algorithm uses (subresultant) assumes the base ring is a domain.
1793
1794       The library syntax is vecbezoutres"(x,y)" to get the vector, or "
1795       subresext(x,y, &u, &v)" which gives as result the address of the
1796       created gcd, and puts the addresses of the corresponding created
1797       objects into "u" and "v".
1798
1799   bigomega"(x)"
1800       number of prime divisors of "|x|" counted with multiplicity. "x" must
1801       be an integer.
1802
1803       The library syntax is bigomega"(x)", the result is a "long".
1804
1805   binomial"(x,y)"
1806       binomial coefficient "\binom{x}{y}".  Here "y" must be an integer, but
1807       "x" can be any PARI object.
1808
1809       The library syntax is binomial"(x,y)", where "y" must be a "long".
1810
1811   chinese"(x,{y})"
1812       if "x" and "y" are both intmods or both polmods, creates (with the same
1813       type) a "z" in the same residue class as "x" and in the same residue
1814       class as "y", if it is possible.
1815
1816       This function also allows vector and matrix arguments, in which case
1817       the operation is recursively applied to each component of the vector or
1818       matrix.  For polynomial arguments, it is applied to each coefficient.
1819
1820       If "y" is omitted, and "x" is a vector, "chinese" is applied
1821       recursively to the components of "x", yielding a residue belonging to
1822       the same class as all components of "x".
1823
1824       Finally "chinese(x,x) = x" regardless of the type of "x"; this allows
1825       vector arguments to contain other data, so long as they are identical
1826       in both vectors.
1827
1828       The library syntax is chinese"(x,y)". Also available is
1829       "chinese1""(x)", corresponding to an ommitted "y".
1830
1831   content"(x)"
1832       computes the gcd of all the coefficients of "x", when this gcd makes
1833       sense. This is the natural definition if "x" is a polynomial (and by
1834       extension a power series) or a vector/matrix. This is in general a
1835       weaker notion than the \emph{ideal} generated by the coefficients:
1836
1837             ? content(2*x+y)
1838             %1 = 1            \\ = gcd(2,y) over Q[y]
1839
1840       If "x" is a scalar, this simply returns the absolute value of "x" if
1841       "x" is rational ("t_INT" or "t_FRAC"), and either 1 (inexact input) or
1842       "x" (exact input) otherwise; the result should be identical to "gcd(x,
1843       0)".
1844
1845       The content of a rational function is the ratio of the contents of the
1846       numerator and the denominator. In recursive structures, if a matrix or
1847       vector \emph{coefficient} "x" appears, the gcd is taken not with "x",
1848       but with its content:
1849
1850             ? content([ [2], 4*matid(3) ])
1851             %1 = 2
1852
1853       The library syntax is content"(x)".
1854
1855   contfrac"(x,{b},{nmax})"
1856       creates the row vector whose components are the partial quotients of
1857       the continued fraction expansion of "x". That is a result
1858       "[a_0,...,a_n]" means that "x  ~ a_0+1/(a_1+...+1/a_n)...)". The output
1859       is normalized so that "a_n  ! = 1" (unless we also have "n = 0").
1860
1861       The number of partial quotients "n" is limited to "nmax". If "x" is a
1862       real number, the expansion stops at the last significant partial
1863       quotient if "nmax" is omitted. "x" can also be a rational function or a
1864       power series.
1865
1866       If a vector "b" is supplied, the numerators will be equal to the
1867       coefficients of "b" (instead of all equal to 1 as above). The length of
1868       the result is then equal to the length of "b", unless a partial
1869       remainder is encountered which is equal to zero, in which case the
1870       expansion stops. In the case of real numbers, the stopping criterion is
1871       thus different from the one mentioned above since, if "b" is too long,
1872       some partial quotients may not be significant.
1873
1874       If "b" is an integer, the command is understood as "contfrac(x,nmax)".
1875
1876       The library syntax is contfrac0"(x,b,nmax)". Also available are "
1877       gboundcf(x,nmax)", " gcf(x)", or " gcf2(b,x)", where "nmax" is a C
1878       integer.
1879
1880   contfracpnqn"(x)"
1881       when "x" is a vector or a one-row matrix, "x" is considered as the list
1882       of partial quotients "[a_0,a_1,...,a_n]" of a rational number, and the
1883       result is the 2 by 2 matrix "[p_n,p_{n-1};q_n,q_{n-1}]" in the standard
1884       notation of continued fractions, so "p_n/q_n =
1885       a_0+1/(a_1+...+1/a_n)...)". If "x" is a matrix with two rows
1886       "[b_0,b_1,...,b_n]" and "[a_0,a_1,...,a_n]", this is then considered as
1887       a generalized continued fraction and we have similarly "p_n/q_n =
1888       1/b_0(a_0+b_1/(a_1+...+b_n/a_n)...)". Note that in this case one
1889       usually has "b_0 = 1".
1890
1891       The library syntax is pnqn"(x)".
1892
1893   core"(n,{flag = 0})"
1894       if "n" is a non-zero integer written as "n = df^2" with "d" squarefree,
1895       returns "d". If "flag" is non-zero, returns the two-element row vector
1896       "[d,f]".
1897
1898       The library syntax is core0"(n,flag)".  Also available are " core(n)" (
1899       = " core0(n,0)") and " core2(n)" ( = " core0(n,1)").
1900
1901   coredisc"(n,{flag})"
1902       if "n" is a non-zero integer written as "n = df^2" with "d" fundamental
1903       discriminant (including 1), returns "d". If "flag" is non-zero, returns
1904       the two-element row vector "[d,f]". Note that if "n" is not congruent
1905       to 0 or 1 modulo 4, "f" will be a half integer and not an integer.
1906
1907       The library syntax is coredisc0"(n,flag)".  Also available are "
1908       coredisc(n)" ( = " coredisc(n,0)") and " coredisc2(n)" ( = "
1909       coredisc(n,1)").
1910
1911   dirdiv"(x,y)"
1912       "x" and "y" being vectors of perhaps different lengths but with "y[1] !
1913       = 0" considered as Dirichlet series, computes the quotient of "x" by
1914       "y", again as a vector.
1915
1916       The library syntax is dirdiv"(x,y)".
1917
1918   direuler"(p = a,b,expr,{c})"
1919       computes the Dirichlet series associated to the Euler product of
1920       expression expr as "p" ranges through the primes from "a" to "b".  expr
1921       must be a polynomial or rational function in another variable than "p"
1922       (say "X") and "expr(X)" is understood as the local factor
1923       "expr(p^{-s})".
1924
1925       The series is output as a vector of coefficients. If "c" is present,
1926       output only the first "c" coefficients in the series. The following
1927       command computes the sigma function, associated to "zeta(s)zeta(s-1)":
1928
1929         ? direuler(p=2, 10, 1/((1-X)*(1-p*X)))
1930         %1 = [1, 3, 4, 7, 6, 12, 8, 15, 13, 18]
1931
1932       The library syntax is direuler"(void *E, GEN (*eval)(GEN,void*), GEN a,
1933       GEN b)"
1934
1935   dirmul"(x,y)"
1936       "x" and "y" being vectors of perhaps different lengths considered as
1937       Dirichlet series, computes the product of "x" by "y", again as a
1938       vector.
1939
1940       The library syntax is dirmul"(x,y)".
1941
1942   divisors"(x)"
1943       creates a row vector whose components are the divisors of "x". The
1944       factorization of "x" (as output by "factor") can be used instead.
1945
1946       By definition, these divisors are the products of the irreducible
1947       factors of "n", as produced by factor(n), raised to appropriate powers
1948       (no negative exponent may occur in the factorization). If "n" is an
1949       integer, they are the positive divisors, in increasing order.
1950
1951       The library syntax is divisors"(x)".
1952
1953   eulerphi"(x)"
1954       Euler's "phi" (totient) function of "|x|", in other words "|(Z/xZ)^*|".
1955       "x" must be of type integer.
1956
1957       The library syntax is phi"(x)".
1958
1959   factor"(x,{lim = -1})"
1960       general factorization function.  If "x" is of type integer, rational,
1961       polynomial or rational function, the result is a two-column matrix, the
1962       first column being the irreducibles dividing "x" (prime numbers or
1963       polynomials), and the second the exponents.  If "x" is a vector or a
1964       matrix, the factoring is done componentwise (hence the result is a
1965       vector or matrix of two-column matrices). By definition, 0 is factored
1966       as "0^1".
1967
1968       If "x" is of type integer or rational, the factors are pseudoprimes
1969       (see "ispseudoprime"), and in general not rigorously proven primes. In
1970       fact, any factor which is " <= 10^{13}" is a genuine prime number. Use
1971       "isprime" to prove primality of other factors, as in
1972
1973         fa = factor(2^2^7 +1)
1974         isprime( fa[,1] )
1975
1976       An argument lim can be added, meaning that we look only for prime
1977       factors "p < lim", or up to "primelimit", whichever is lowest (except
1978       when "lim = 0" where the effect is identical to setting "lim =
1979       primelimit"). In this case, the remaining part may actually be a proven
1980       composite! See "factorint" for more information about the algorithms
1981       used.
1982
1983       The polynomials or rational functions to be factored must have scalar
1984       coefficients. In particular PARI does \emph{not} know how to factor
1985       multivariate polynomials. See "factormod" and "factorff" for the
1986       algorithms used over finite fields, "factornf" for the algorithms over
1987       number fields. Over Q, van Hoeij's method is used, which is able to
1988       cope with hundreds of modular factors.
1989
1990       Note that PARI tries to guess in a sensible way over which ring you
1991       want to factor. Note also that factorization of polynomials is done up
1992       to multiplication by a constant. In particular, the factors of rational
1993       polynomials will have integer coefficients, and the content of a
1994       polynomial or rational function is discarded and not included in the
1995       factorization. If needed, you can always ask for the content
1996       explicitly:
1997
1998         ? factor(t^2 + 5/2*t + 1)
1999         %1 =
2000         [2*t + 1 1]
2001
2002         [t + 2 1]
2003
2004         ? content(t^2 + 5/2*t + 1)
2005         %2 = 1/2
2006
2007       See also "factornf" and "nffactor".
2008
2009       The library syntax is factor0"(x,lim)", where lim is a C integer.  Also
2010       available are " factor(x)" ( = " factor0(x,-1)"), " smallfact(x)" ( = "
2011       factor0(x,0)").
2012
2013   factorback"(f,{e},{nf})"
2014       gives back the factored object corresponding to a factorization. The
2015       integer 1 corresponds to the empty factorization. If the last argument
2016       is of number field type (e.g. created by "nfinit"), assume we are
2017       dealing with an ideal factorization in the number field. The resulting
2018       ideal product is given in HNF form.
2019
2020       If "e" is present, "e" and "f" must be vectors of the same length ("e"
2021       being integral), and the corresponding factorization is the product of
2022       the "f[i]^{e[i]}".
2023
2024       If not, and "f" is vector, it is understood as in the preceding case
2025       with "e" a vector of 1 (the product of the "f[i]" is returned).
2026       Finally, "f" can be a regular factorization, as produced with any
2027       "factor" command. A few examples:
2028
2029         ? factorback([2,2; 3,1])
2030         %1 = 12
2031         ? factorback([2,2], [3,1])
2032         %2 = 12
2033         ? factorback([5,2,3])
2034         %3 = 30
2035         ? factorback([2,2], [3,1], nfinit(x^3+2))
2036         %4 =
2037         [16 0 0]
2038
2039         [0 16 0]
2040
2041         [0 0 16]
2042         ? nf = nfinit(x^2+1); fa = idealfactor(nf, 10)
2043         %5 =
2044         [[2, [1, 1]~, 2, 1, [1, 1]~] 2]
2045
2046         [[5, [-2, 1]~, 1, 1, [2, 1]~] 1]
2047
2048         [[5, [2, 1]~, 1, 1, [-2, 1]~] 1]
2049         ? factorback(fa)
2050           ***   forbidden multiplication t_VEC * t_VEC.
2051         ? factorback(fa, nf)
2052         %6 =
2053         [10 0]
2054
2055         [0 10]
2056
2057       In the fourth example, 2 and 3 are interpreted as principal ideals in a
2058       cubic field. In the fifth one, "factorback(fa)" is meaningless since we
2059       forgot to indicate the number field, and the entries in the first
2060       column of "fa" can't be multiplied.
2061
2062       The library syntax is factorback0"(f,e,nf)", where an omitted "nf" or
2063       "e" is entered as "NULL". Also available is "factorback""(f,nf)" (case
2064       "e = NULL") where an omitted "nf" is entered as "NULL".
2065
2066   factorcantor"(x,p)"
2067       factors the polynomial "x" modulo the prime "p", using distinct degree
2068       plus Cantor-Zassenhaus. The coefficients of "x" must be operation-
2069       compatible with "Z/pZ". The result is a two-column matrix, the first
2070       column being the irreducible polynomials dividing "x", and the second
2071       the exponents. If you want only the \emph{degrees} of the irreducible
2072       polynomials (for example for computing an "L"-function), use
2073       "factormod(x,p,1)". Note that the "factormod" algorithm is usually
2074       faster than "factorcantor".
2075
2076       The library syntax is factcantor"(x,p)".
2077
2078   factorff"(x,p,a)"
2079       factors the polynomial "x" in the field "F_q" defined by the
2080       irreducible polynomial "a" over "F_p". The coefficients of "x" must be
2081       operation-compatible with "Z/pZ". The result is a two-column matrix:
2082       the first column contains the irreducible factors of "x", and the
2083       second their exponents. If all the coefficients of "x" are in "F_p", a
2084       much faster algorithm is applied, using the computation of isomorphisms
2085       between finite fields.
2086
2087       The library syntax is factorff"(x,p,a)".
2088
2089   factorial"(x)" or "x!"
2090       factorial of "x". The expression "x!"  gives a result which is an
2091       integer, while factorial(x) gives a real number.
2092
2093       The library syntax is mpfact"(x)" for "x!" and " mpfactr(x,prec)" for
2094       factorial(x). "x" must be a "long" integer and not a PARI integer.
2095
2096   factorint"(n,{flag = 0})"
2097       factors the integer "n" into a product of pseudoprimes (see
2098       "ispseudoprime"), using a combination of the Shanks SQUFOF and Pollard
2099       Rho method (with modifications due to Brent), Lenstra's ECM (with
2100       modifications by Montgomery), and MPQS (the latter adapted from the
2101       LiDIA code with the kind permission of the LiDIA maintainers), as well
2102       as a search for pure powers with exponents" <= 10". The output is a
2103       two-column matrix as for "factor". Use "isprime" on the result if you
2104       want to guarantee primality.
2105
2106       This gives direct access to the integer factoring engine called by most
2107       arithmetical functions. flag is optional; its binary digits mean 1:
2108       avoid MPQS, 2: skip first stage ECM (we may still fall back to it
2109       later), 4: avoid Rho and SQUFOF, 8: don't run final ECM (as a result, a
2110       huge composite may be declared to be prime). Note that a (strong)
2111       probabilistic primality test is used; thus composites might (very
2112       rarely) not be detected.
2113
2114       You are invited to play with the flag settings and watch the internals
2115       at work by using "gp"'s "debuglevel" default parameter (level 3 shows
2116       just the outline, 4 turns on time keeping, 5 and above show an
2117       increasing amount of internal details). If you see anything funny
2118       happening, please let us know.
2119
2120       The library syntax is factorint"(n,flag)".
2121
2122   factormod"(x,p,{flag = 0})"
2123       factors the polynomial "x" modulo the prime integer "p", using
2124       Berlekamp. The coefficients of "x" must be operation-compatible with
2125       "Z/pZ". The result is a two-column matrix, the first column being the
2126       irreducible polynomials dividing "x", and the second the exponents. If
2127       "flag" is non-zero, outputs only the \emph{degrees} of the irreducible
2128       polynomials (for example, for computing an "L"-function). A different
2129       algorithm for computing the mod "p" factorization is "factorcantor"
2130       which is sometimes faster.
2131
2132       The library syntax is factormod"(x,p,flag)". Also available are "
2133       factmod(x,p)" (which is equivalent to " factormod(x,p,0)") and "
2134       simplefactmod(x,p)" ( = " factormod(x,p,1)").
2135
2136   fibonacci"(x)"
2137       "x^{th}" Fibonacci number.
2138
2139       The library syntax is fibo"(x)". "x" must be a "long".
2140
2141   ffinit"(p,n,{v = x})"
2142       computes a monic polynomial of degree "n" which is irreducible over
2143       "F_p". For instance if "P = ffinit(3,2,y)", you can represent elements
2144       in "F_{3^2}" as polmods modulo "P". This function uses a fast variant
2145       of Adleman-Lenstra's algorithm.
2146
2147       The library syntax is ffinit"(p,n,v)", where "v" is a variable number.
2148
2149   gcd"(x,{y})"
2150       creates the greatest common divisor of "x" and "y". "x" and "y" can be
2151       of quite general types, for instance both rational numbers. If "y" is
2152       omitted and "x" is a vector, returns the "gcd" of all components of
2153       "x", i.e. this is equivalent to content(x).
2154
2155       When "x" and "y" are both given and one of them is a vector/matrix
2156       type, the GCD is again taken recursively on each component, but in a
2157       different way.  If "y" is a vector, resp. matrix, then the result has
2158       the same type as "y", and components equal to "gcd(x, y[i])",
2159       resp. "gcd(x, y[,i])". Else if "x" is a vector/matrix the result has
2160       the same type as "x" and an analogous definition. Note that for these
2161       types, "gcd" is not commutative.
2162
2163       The algorithm used is a naive Euclid except for the following inputs:
2164
2165       \item integers: use modified right-shift binary (``plus-minus''
2166       variant).
2167
2168       \item univariate polynomials with coeffients in the same number field
2169       (in particular rational): use modular gcd algorithm.
2170
2171       \item general polynomials: use the subresultant algorithm if
2172       coefficient explosion is likely (exact, non modular, coefficients).
2173
2174       The library syntax is ggcd"(x,y)". For general polynomial inputs, "
2175       srgcd(x,y)" is also available. For univariate \emph{rational}
2176       polynomials, one also has " modulargcd(x,y)".
2177
2178   hilbert"(x,y,{p})"
2179       Hilbert symbol of "x" and "y" modulo "p". If "x" and "y" are of type
2180       integer or fraction, an explicit third parameter "p" must be supplied,
2181       "p = 0" meaning the place at infinity.  Otherwise, "p" needs not be
2182       given, and "x" and "y" can be of compatible types integer, fraction,
2183       real, intmod a prime (result is undefined if the modulus is not prime),
2184       or "p"-adic.
2185
2186       The library syntax is hil"(x,y,p)".
2187
2188   isfundamental"(x)"
2189       true (1) if "x" is equal to 1 or to the discriminant of a quadratic
2190       field, false (0) otherwise.
2191
2192       The library syntax is gisfundamental"(x)", but the simpler function "
2193       isfundamental(x)" which returns a "long" should be used if "x" is known
2194       to be of type integer.
2195
2196   ispower"(x,{k}, {&n})"
2197       if "k" is given, returns true (1) if "x" is a "k"-th power, false (0)
2198       if not. In this case, "x" may be an integer or polynomial, a rational
2199       number or function, or an intmod a prime or "p"-adic.
2200
2201       If "k" is omitted, only integers and fractions are allowed and the
2202       function returns the maximal "k >= 2" such that "x = n^k" is a perfect
2203       power, or 0 if no such "k" exist; in particular "ispower(-1)",
2204       ispower(0), and ispower(1) all return 0.
2205
2206       If a third argument &n is given and a "k"-th root was computed in the
2207       process, then "n" is set to that root.
2208
2209       The library syntax is ispower"(x, k, &n)", the result is a "long".
2210       Omitted "k" or "n" are coded as "NULL".
2211
2212   isprime"(x,{flag = 0})"
2213       true (1) if "x" is a (proven) prime number, false (0) otherwise. This
2214       can be very slow when "x" is indeed prime and has more than 1000
2215       digits, say. Use "ispseudoprime" to quickly check for pseudo primality.
2216       See also "factor".
2217
2218       If "flag = 0", use a combination of Baillie-PSW pseudo primality test
2219       (see "ispseudoprime"), Selfridge ``"p-1"'' test if "x-1" is smooth
2220       enough, and Adleman-Pomerance-Rumely-Cohen-Lenstra (APRCL) for general
2221       "x".
2222
2223       If "flag = 1", use Selfridge-Pocklington-Lehmer ``"p-1"'' test and
2224       output a primality certificate as follows: return 0 if "x" is
2225       composite, 1 if "x" is small enough that passing Baillie-PSW test
2226       guarantees its primality (currently "x < 10^{13}"), 2 if "x" is a large
2227       prime whose primality could only sensibly be proven (given the
2228       algorithms implemented in PARI) using the APRCL test. Otherwise ("x" is
2229       large and "x-1" is smooth) output a three column matrix as a primality
2230       certificate. The first column contains the prime factors "p" of "x-1",
2231       the second the corresponding elements "a_p" as in Proposition 8.3.1 in
2232       GTM 138, and the third the output of isprime(p,1). The algorithm fails
2233       if one of the pseudo-prime factors is not prime, which is exceedingly
2234       unlikely (and well worth a bug report).
2235
2236       If "flag = 2", use APRCL.
2237
2238       The library syntax is gisprime"(x,flag)", but the simpler function "
2239       isprime(x)" which returns a "long" should be used if "x" is known to be
2240       of type integer.
2241
2242   ispseudoprime"(x,{flag})"
2243       true (1) if "x" is a strong pseudo prime (see below), false (0)
2244       otherwise. If this function returns false, "x" is not prime; if, on the
2245       other hand it returns true, it is only highly likely that "x" is a
2246       prime number. Use "isprime" (which is of course much slower) to prove
2247       that "x" is indeed prime.
2248
2249       If "flag = 0", checks whether "x" is a Baillie-Pomerance-Selfridge-
2250       Wagstaff pseudo prime (strong Rabin-Miller pseudo prime for base 2,
2251       followed by strong Lucas test for the sequence "(P,-1)", "P" smallest
2252       positive integer such that "P^2 - 4" is not a square mod "x").
2253
2254       There are no known composite numbers passing this test (in particular,
2255       all composites " <= 10^{13}" are correctly detected), although it is
2256       expected that infinitely many such numbers exist.
2257
2258       If "flag > 0", checks whether "x" is a strong Miller-Rabin pseudo prime
2259       for "flag" randomly chosen bases (with end-matching to catch square
2260       roots of "-1").
2261
2262       The library syntax is gispseudoprime"(x,flag)", but the simpler
2263       function " ispseudoprime(x)" which returns a "long" should be used if
2264       "x" is known to be of type integer.
2265
2266   issquare"(x,{&n})"
2267       true (1) if "x" is a square, false (0) if not. What ``being a square''
2268       means depends on the type of "x": all "t_COMPLEX" are squares, as well
2269       as all non-negative "t_REAL"; for exact types such as "t_INT", "t_FRAC"
2270       and "t_INTMOD", squares are numbers of the form "s^2" with "s" in Z, Q
2271       and "Z/NZ" respectively.
2272
2273             ? issquare(3)          \\ as an integer
2274             %1 = 0
2275             ? issquare(3.)         \\ as a real number
2276             %2 = 1
2277             ? issquare(Mod(7, 8))  \\ in Z/8Z
2278             %3 = 0
2279             ? issquare( 5 + O(13^4) )  \\ in Q_13
2280             %4 = 0
2281
2282       If "n" is given and an exact square root had to be computed in the
2283       checking process, puts that square root in "n". This is the case when
2284       "x" is a "t_INT", "t_FRAC", "t_POL" or "t_RFRAC" (or a vector of such
2285       objects):
2286
2287             ? issquare(4, &n)
2288             %1 = 1
2289             ? n
2290             %2 = 2
2291             ? issquare([4, x^2], &n)
2292             %3 = [1, 1]  \\ both are squares
2293             ? n
2294             %4 = [2, x]  \\ the square roots
2295
2296       This will \emph{not} work for "t_INTMOD" (use quadratic reciprocity) or
2297       "t_SER" (only check the leading coefficient).
2298
2299       The library syntax is gissquarerem"(x,&n)". Also available is "
2300       gissquare(x)".
2301
2302   issquarefree"(x)"
2303       true (1) if "x" is squarefree, false (0) if not.  Here "x" can be an
2304       integer or a polynomial.
2305
2306       The library syntax is gissquarefree"(x)", but the simpler function "
2307       issquarefree(x)" which returns a "long" should be used if "x" is known
2308       to be of type integer. This issquarefree is just the square of the
2309       Moebius function, and is computed as a multiplicative arithmetic
2310       function much like the latter.
2311
2312   kronecker"(x,y)"
2313       Kronecker symbol "(x|y)", where "x" and "y" must be of type integer. By
2314       definition, this is the extension of Legendre symbol to "Z  x Z" by
2315       total multiplicativity in both arguments with the following special
2316       rules for "y = 0, -1" or 2:
2317
2318       \item "(x|0) = 1" if "|x |= 1" and 0 otherwise.
2319
2320       \item "(x|-1) = 1" if "x >= 0" and "-1" otherwise.
2321
2322       \item "(x|2) = 0" if "x" is even and 1 if "x = 1,-1 mod 8" and "-1" if
2323       "x = 3,-3 mod 8".
2324
2325       The library syntax is kronecker"(x,y)", the result (0 or "+- 1") is a
2326       "long".
2327
2328   lcm"(x,{y})"
2329       least common multiple of "x" and "y", i.e. such that "lcm(x,y)*gcd(x,y)
2330       = abs(x*y)". If "y" is omitted and "x" is a vector, returns the "lcm"
2331       of all components of "x".
2332
2333       When "x" and "y" are both given and one of them is a vector/matrix
2334       type, the LCM is again taken recursively on each component, but in a
2335       different way.  If "y" is a vector, resp. matrix, then the result has
2336       the same type as "y", and components equal to "lcm(x, y[i])",
2337       resp. "lcm(x, y[,i])". Else if "x" is a vector/matrix the result has
2338       the same type as "x" and an analogous definition. Note that for these
2339       types, "lcm" is not commutative.
2340
2341       Note that lcm(v) is quite different from
2342
2343             l = v[1]; for (i = 1, #v, l = lcm(l, v[i]))
2344
2345       Indeed, lcm(v) is a scalar, but "l" may not be (if one of the "v[i]" is
2346       a vector/matrix). The computation uses a divide-conquer tree and should
2347       be much more efficient, especially when using the GMP multiprecision
2348       kernel (and more subquadratic algorithms become available):
2349
2350             ? v = vector(10^4, i, random);
2351             ? lcm(v);
2352             time = 323 ms.
2353             ? l = v[1]; for (i = 1, #v, l = lcm(l, v[i]))
2354             time = 833 ms.
2355
2356       The library syntax is glcm"(x,y)".
2357
2358   moebius"(x)"
2359       Moebius "mu"-function of "|x|". "x" must be of type integer.
2360
2361       The library syntax is mu"(x)", the result (0 or "+- 1") is a "long".
2362
2363   nextprime"(x)"
2364       finds the smallest pseudoprime (see "ispseudoprime") greater than or
2365       equal to "x". "x" can be of any real type. Note that if "x" is a
2366       pseudoprime, this function returns "x" and not the smallest pseudoprime
2367       strictly larger than "x". To rigorously prove that the result is prime,
2368       use "isprime".
2369
2370       The library syntax is nextprime"(x)".
2371
2372   numdiv"(x)"
2373       number of divisors of "|x|". "x" must be of type integer.
2374
2375       The library syntax is numbdiv"(x)".
2376
2377   numbpart"(n)"
2378       gives the number of unrestricted partitions of "n", usually called p(n)
2379       in the litterature; in other words the number of nonnegative integer
2380       solutions to "a+2b+3c+.. .= n". "n" must be of type integer and "1 <= n
2381       < 10^{15}". The algorithm uses the Hardy-Ramanujan-Rademacher formula.
2382
2383       The library syntax is numbpart"(n)".
2384
2385   omega"(x)"
2386       number of distinct prime divisors of "|x|". "x" must be of type
2387       integer.
2388
2389       The library syntax is omega"(x)", the result is a "long".
2390
2391   precprime"(x)"
2392       finds the largest pseudoprime (see "ispseudoprime") less than or equal
2393       to "x". "x" can be of any real type.  Returns 0 if "x <= 1". Note that
2394       if "x" is a prime, this function returns "x" and not the largest prime
2395       strictly smaller than "x". To rigorously prove that the result is
2396       prime, use "isprime".
2397
2398       The library syntax is precprime"(x)".
2399
2400   prime"(x)"
2401       the "x^{th}" prime number, which must be among the precalculated
2402       primes.
2403
2404       The library syntax is prime"(x)". "x" must be a "long".
2405
2406   primepi"(x)"
2407       the prime counting function. Returns the number of primes "p", "p <=
2408       x". Uses a naive algorithm so that "x" must be less than "primelimit".
2409
2410       The library syntax is primepi"(x)".
2411
2412   primes"(x)"
2413       creates a row vector whose components are the first "x" prime numbers,
2414       which must be among the precalculated primes.
2415
2416       The library syntax is primes"(x)". "x" must be a "long".
2417
2418   qfbclassno"(D,{flag = 0})"
2419       ordinary class number of the quadratic order of discriminant "D". In
2420       the present version /usr/share/libpari23, a "O(D^{1/2})" algorithm is
2421       used for "D > 0" (using Euler product and the functional equation) so
2422       "D" should not be too large, say "D < 10^8", for the time to be
2423       reasonable. On the other hand, for "D < 0" one can reasonably compute
2424       qfbclassno(D) for "|D| < 10^{25}", since the routine uses Shanks's
2425       method which is in "O(|D|^{1/4})". For larger values of "|D|", see
2426       "quadclassunit".
2427
2428       If "flag = 1", compute the class number using Euler products and the
2429       functional equation. However, it is in "O(|D|^{1/2})".
2430
2431       Important warning. For "D < 0", this function may give incorrect
2432       results when the class group has a low exponent (has many cyclic
2433       factors), because implementing Shanks's method in full generality slows
2434       it down immensely. It is therefore strongly recommended to double-check
2435       results using either the version with "flag = 1" or the function
2436       "quadclassunit".
2437
2438       Warning. contrary to what its name implies, this routine does not
2439       compute the number of classes of binary primitive forms of discriminant
2440       "D", which is equal to the \emph{narrow} class number. The two notions
2441       are the same when "D < 0" or the fundamental unit "varepsilon" has
2442       negative norm; when "D > 0" and "Nvarepsilon > 0", the number of
2443       classes of forms is twice the ordinary class number. This is a problem
2444       which we cannot fix for backward compatibility reasons. Use the
2445       following routine if you are only interested in the number of classes
2446       of forms:
2447
2448         QFBclassno(D) =
2449           qfbclassno(D) * if (D < 0 || norm(quadunit(D)) < 0, 1, 2)
2450
2451       Here are a few examples:
2452
2453         %2 = 1
2454         ? qfbclassno(-400000028)
2455         time = 0 ms.
2456         %3 = 7253 \{ much faster}
2457         %2 = 1
2458         ? qfbclassno(-400000028)
2459         time = 0 ms.
2460         %3 = 7253 \{ correct, and fast enough}
2461         ? quadclassunit(-400000028).no
2462         time = 0 ms.
2463         %4 = 7253
2464
2465       The library syntax is qfbclassno0"(D,flag)". Also available: "
2466       classno(D)" ( = " qfbclassno(D)"), " classno2(D)" ( = "
2467       qfbclassno(D,1)"), and finally we have the function " hclassno(D)"
2468       which computes the class number of an imaginary quadratic field by
2469       counting reduced forms, an "O(|D|)" algorithm. See also "qfbhclassno".
2470
2471   qfbcompraw"(x,y)"
2472       composition of the binary quadratic forms "x" and "y", without
2473       reduction of the result. This is useful e.g. to compute a generating
2474       element of an ideal.
2475
2476       The library syntax is compraw"(x,y)".
2477
2478   qfbhclassno"(x)"
2479       Hurwitz class number of "x", where "x" is non-negative and congruent to
2480       0 or 3 modulo 4. For "x > 5.  10^5", we assume the GRH, and use
2481       "quadclassunit" with default parameters.
2482
2483       The library syntax is hclassno"(x)".
2484
2485   qfbnucomp"(x,y,l)"
2486       composition of the primitive positive definite binary quadratic forms
2487       "x" and "y" (type "t_QFI") using the NUCOMP and NUDUPL algorithms of
2488       Shanks, à la Atkin. "l" is any positive constant, but for optimal
2489       speed, one should take "l = |D|^{1/4}", where "D" is the common
2490       discriminant of "x" and "y". When "x" and "y" do not have the same
2491       discriminant, the result is undefined.
2492
2493       The current implementation is straightforward and in general
2494       \emph{slower} than the generic routine (since the latter take
2495       advantadge of asymptotically fast operations and careful
2496       optimizations).
2497
2498       The library syntax is nucomp"(x,y,l)". The auxiliary function "
2499       nudupl(x,l)" can be used when "x = y".
2500
2501   qfbnupow"(x,n)"
2502       "n"-th power of the primitive positive definite binary quadratic form
2503       "x" using Shanks's NUCOMP and NUDUPL algorithms (see "qfbnucomp", in
2504       particular the final warning).
2505
2506       The library syntax is nupow"(x,n)".
2507
2508   qfbpowraw"(x,n)"
2509       "n"-th power of the binary quadratic form "x", computed without doing
2510       any reduction (i.e. using "qfbcompraw").  Here "n" must be non-negative
2511       and "n < 2^{31}".
2512
2513       The library syntax is powraw"(x,n)" where "n" must be a "long" integer.
2514
2515   qfbprimeform"(x,p)"
2516       prime binary quadratic form of discriminant "x" whose first coefficient
2517       is the prime number "p". By abuse of notation, "p = +- 1" is a valid
2518       special case which returns the unit form. Returns an error if "x" is
2519       not a quadratic residue mod "p". In the case where "x > 0", "p < 0" is
2520       allowed, and the ``distance'' component of the form is set equal to
2521       zero according to the current precision. (Note that negative definite
2522       "t_QFI" are not implemented.)
2523
2524       The library syntax is primeform"(x,p,prec)", where the third variable
2525       "prec" is a "long", but is only taken into account when "x > 0".
2526
2527   qfbred"(x,{flag = 0},{D},{isqrtD},{sqrtD})"
2528       reduces the binary quadratic form "x" (updating Shanks's distance
2529       function if "x" is indefinite). The binary digits of "flag" are toggles
2530       meaning
2531
2532         1: perform a single reduction step
2533
2534         2: don't update Shanks's distance
2535
2536       "D", isqrtD, sqrtD, if present, supply the values of the discriminant,
2537       "\floor{ sqrt {D}}", and " sqrt {D}" respectively (no checking is done
2538       of these facts). If "D < 0" these values are useless, and all
2539       references to Shanks's distance are irrelevant.
2540
2541       The library syntax is qfbred0"(x,flag,D,isqrtD,sqrtD)". Use "NULL" to
2542       omit any of "D", isqrtD, sqrtD.
2543
2544       Also available are
2545
2546       " redimag(x)" ( = " qfbred(x)" where "x" is definite),
2547
2548       and for indefinite forms:
2549
2550       " redreal(x)" ( = " qfbred(x)"),
2551
2552       " rhoreal(x)" ( = " qfbred(x,1)"),
2553
2554       " redrealnod(x,sq)" ( = " qfbred(x,2,,isqrtD)"),
2555
2556       " rhorealnod(x,sq)" ( = " qfbred(x,3,,isqrtD)").
2557
2558   qfbsolve"(Q,p)"
2559       Solve the equation "Q(x,y) = p" over the integers, where "Q" is a
2560       binary quadratic form and "p" a prime number.
2561
2562       Return "[x,y]" as a two-components vector, or zero if there is no
2563       solution.  Note that this function returns only one solution and not
2564       all the solutions.
2565
2566       Let "D = \disc Q". The algorithm used runs in probabilistic polynomial
2567       time in "p" (through the computation of a square root of "D" modulo
2568       "p"); it is polynomial time in "D" if "Q" is imaginary, but exponential
2569       time if "Q" is real (through the computation of a full cycle of reduced
2570       forms). In the latter case, note that "bnfisprincipal" provides a
2571       solution in heuristic subexponential time in "D" assuming the GRH.
2572
2573       The library syntax is qfbsolve"(Q,n)".
2574
2575   quadclassunit"(D,{flag = 0},{tech = []})"
2576       Buchmann-McCurley's sub-exponential algorithm for computing the class
2577       group of a quadratic order of discriminant "D".
2578
2579       This function should be used instead of "qfbclassno" or "quadregula"
2580       when "D < -10^{25}", "D > 10^{10}", or when the \emph{structure} is
2581       wanted. It is a special case of "bnfinit", which is slower, but more
2582       robust.
2583
2584       If "flag" is non-zero \emph{and} "D > 0", computes the narrow class
2585       group and regulator, instead of the ordinary (or wide) ones. In the
2586       current version /usr/share/libpari23, this does not work at all: use
2587       the general function "bnfnarrow".
2588
2589       Optional parameter tech is a row vector of the form "[c_1, c_2]", where
2590       "c_1 <= c_2" are positive real numbers which control the execution time
2591       and the stack size. For a given "c_1", set "c_2 = c_1" to get maximum
2592       speed. To get a rigorous result under GRH, you must take "c_2 >= 6".
2593       Reasonable values for "c_1" are between 0.1 and 2. More precisely, the
2594       algorithm will \emph{assume} that prime ideals of norm less than "c_2 (
2595       log  |D|)^2" generate the class group, but the bulk of the work is done
2596       with prime ideals of norm less than "c_1 ( log  |D|)^2". A larger "c_1"
2597       means that relations are easier to find, but more relations are needed
2598       and the linear algebra will be harder.  The default is "c_1 = c_2 =
2599       0.2", so the result is \emph{not} rigorously proven.
2600
2601       The result is a vector "v" with 3 components if "D < 0", and 4
2602       otherwise. The correspond respectively to
2603
2604       \item "v[1]": the class number
2605
2606       \item "v[2]": a vector giving the structure of the class group as a
2607       product of cyclic groups;
2608
2609       \item "v[3]": a vector giving generators of those cyclic groups (as
2610       binary quadratic forms).
2611
2612       \item "v[4]": (omitted if "D < 0") the regulator, computed to an
2613       accuracy which is the maximum of an internal accuracy determined by the
2614       program and the current default (note that once the regulator is known
2615       to a small accuracy it is trivial to compute it to very high accuracy,
2616       see the tutorial).
2617
2618       The library syntax is quadclassunit0"(D,flag,tech)". Also available are
2619       " buchimag(D,c_1,c_2)" and " buchreal(D,flag,c_1,c_2)".
2620
2621   quaddisc"(x)"
2622       discriminant of the quadratic field "Q( sqrt {x})", where "x belongs to
2623       Q".
2624
2625       The library syntax is quaddisc"(x)".
2626
2627   quadhilbert"(D,{pq})"
2628       relative equation defining the Hilbert class field of the quadratic
2629       field of discriminant "D".
2630
2631       If "D < 0", uses complex multiplication (Schertz's variant). The
2632       technical component "pq", if supplied, is a vector "[p,q]" where "p",
2633       "q" are the prime numbers needed for the Schertz's method. More
2634       precisely, prime ideals above "p" and "q" should be non-principal and
2635       coprime to all reduced representatives of the class group. In addition,
2636       if one of these ideals has order 2 in the class group, they should have
2637       the same class. Finally, for efficiency, "gcd(24,(p-1)(q-1))" should be
2638       as large as possible.  The routine returns 0 if "[p,q]" is not
2639       suitable.
2640
2641       If "D > 0" Stark units are used and (in rare cases) a vector of
2642       extensions may be returned whose compositum is the requested class
2643       field. See "bnrstark" for details.
2644
2645       The library syntax is quadhilbert"(D,pq,prec)".
2646
2647   quadgen"(D)"
2648       creates the quadratic number "omega = (a+ sqrt {D})/2" where "a = 0" if
2649       "x = 0 mod 4", "a = 1" if "D = 1 mod 4", so that "(1,omega)" is an
2650       integral basis for the quadratic order of discriminant "D". "D" must be
2651       an integer congruent to 0 or 1 modulo 4, which is not a square.
2652
2653       The library syntax is quadgen"(x)".
2654
2655   quadpoly"(D,{v = x})"
2656       creates the ``canonical'' quadratic polynomial (in the variable "v")
2657       corresponding to the discriminant "D", i.e. the minimal polynomial of
2658       quadgen(D). "D" must be an integer congruent to 0 or 1 modulo 4, which
2659       is not a square.
2660
2661       The library syntax is quadpoly0"(x,v)".
2662
2663   quadray"(D,f,{lambda})"
2664       relative equation for the ray class field of conductor "f" for the
2665       quadratic field of discriminant "D" using analytic methods. A "bnf" for
2666       "x^2 - D" is also accepted in place of "D".
2667
2668       For "D < 0", uses the "sigma" function. If supplied, lambda is is the
2669       technical element "lambda" of "bnf" necessary for Schertz's method. In
2670       that case, returns 0 if "lambda" is not suitable.
2671
2672       For "D > 0", uses Stark's conjecture, and a vector of relative
2673       equations may be returned. See "bnrstark" for more details.
2674
2675       The library syntax is quadray"(D,f,lambda,prec)", where an omitted
2676       "lambda" is coded as "NULL".
2677
2678   quadregulator"(x)"
2679       regulator of the quadratic field of positive discriminant "x". Returns
2680       an error if "x" is not a discriminant (fundamental or not) or if "x" is
2681       a square. See also "quadclassunit" if "x" is large.
2682
2683       The library syntax is regula"(x,prec)".
2684
2685   quadunit"(D)"
2686       fundamental unit of the real quadratic field "Q( sqrt  D)" where  "D"
2687       is the positive discriminant of the field. If "D" is not a fundamental
2688       discriminant, this probably gives the fundamental unit of the
2689       corresponding order. "D" must be an integer congruent to 0 or 1 modulo
2690       4, which is not a square; the result is a quadratic number (see "Label
2691       se:quadgen").
2692
2693       The library syntax is fundunit"(x)".
2694
2695   removeprimes"({x = []})"
2696       removes the primes listed in "x" from the prime number table. In
2697       particular "removeprimes(addprimes)" empties the extra prime table. "x"
2698       can also be a single integer. List the current extra primes if "x" is
2699       omitted.
2700
2701       The library syntax is removeprimes"(x)".
2702
2703   sigma"(x,{k = 1})"
2704       sum of the "k^{th}" powers of the positive divisors of "|x|". "x" and
2705       "k" must be of type integer.
2706
2707       The library syntax is sumdiv"(x)" ( = " sigma(x)") or " gsumdivk(x,k)"
2708       ( = " sigma(x,k)"), where "k" is a C long integer.
2709
2710   sqrtint"(x)"
2711       integer square root of "x", which must be a non-negative integer. The
2712       result is non-negative and rounded towards zero.
2713
2714       The library syntax is sqrti"(x)". Also available is "sqrtremi""(x,&r)"
2715       which returns "s" such that "s^2 = x+r", with "0 <= r <= 2s".
2716
2717   zncoppersmith"(P, N, X, {B = N})"
2718       finds all integers "x_0" with "|x_0| <= X" such that
2719
2720         "gcd(N, P(x_0)) >= B."
2721
2722       If "N" is prime or a prime power, "polrootsmod" or "polrootspadic" will
2723       be much faster. "X" must be smaller than " exp ( log ^2 B / ( deg (P)
2724       log N))".
2725
2726       The library syntax is zncoppersmith"(P, N, X, B)", where an omitted "B"
2727       is coded as "NULL".
2728
2729   znlog"(x,g)"
2730       "g" must be a primitive root mod a prime "p", and the result is the
2731       discrete log of "x" in the multiplicative group "(Z/pZ)^*". This
2732       function uses a simple-minded combination of Pohlig-Hellman algorithm
2733       and Shanks baby-step/giant-step which requires "O( sqrt {q})" storage,
2734       where "q" is the largest prime factor of "p-1". Hence it cannot be used
2735       when the largest prime divisor of "p-1" is greater than about
2736       "10^{13}".
2737
2738       The library syntax is znlog"(x,g)".
2739
2740   znorder"(x,{o})"
2741       "x" must be an integer mod "n", and the result is the order of "x" in
2742       the multiplicative group "(Z/nZ)^*". Returns an error if "x" is not
2743       invertible. If optional parameter "o" is given it is assumed to be a
2744       multiple of the order (used to limit the search space).
2745
2746       The library syntax is znorder"(x,o)", where an omitted "o" is coded as
2747       "NULL". Also available is " order(x)".
2748
2749   znprimroot"(n)"
2750       returns a primitive root (generator) of "(Z/nZ)^*", whenever this
2751       latter group is cyclic ("n = 4" or "n = 2p^k" or "n = p^k", where "p"
2752       is an odd prime and "k >= 0").
2753
2754       The library syntax is gener"(x)".
2755
2756   znstar"(n)"
2757       gives the structure of the multiplicative group "(Z/nZ)^*" as a
2758       3-component row vector "v", where "v[1] = phi(n)" is the order of that
2759       group, "v[2]" is a "k"-component row-vector "d" of integers "d[i]" such
2760       that "d[i] > 1" and "d[i] | d[i-1]" for "i >= 2" and "(Z/nZ)^*  ~
2761       prod_{i = 1}^k(Z/d[i]Z)", and "v[3]" is a "k"-component row vector
2762       giving generators of the image of the cyclic groups "Z/d[i]Z".
2763
2764       The library syntax is znstar"(n)".
2765
2767       We have implemented a number of functions which are useful for number
2768       theorists working on elliptic curves. We always use Tate's notations.
2769       The functions assume that the curve is given by a general Weierstrass
2770       model
2771
2772         " y^2+a_1xy+a_3y = x^3+a_2x^2+a_4x+a_6, "
2773
2774       where a priori the "a_i" can be of any scalar type. This curve can be
2775       considered as a five-component vector "E = [a1,a2,a3,a4,a6]". Points on
2776       "E" are represented as two-component vectors "[x,y]", except for the
2777       point at infinity, i.e. the identity element of the group law,
2778       represented by the one-component vector "[0]".
2779
2780       It is useful to have at one's disposal more information. This is given
2781       by the function "ellinit" (see there), which initalizes and returns an
2782       ell structure by default. If a specific flag is added, a shortened
2783       sell, for small ell, is returned, which is much faster to compute but
2784       contains less information. The following member functions are available
2785       to deal with the output of "ellinit", both ell and sell:
2786
2787         "a1"--"a6", "b2"--"b8", "c4"--"c6"  : coefficients of the elliptic
2788       curve.
2789
2790         "area"  :    volume of the complex lattice defining "E".
2791
2792         "disc"  :   discriminant of the curve.
2793
2794         "j"     :   "j"-invariant of the curve.
2795
2796         "omega" :   "[omega_1,omega_2]", periods forming a basis of the
2797       complex lattice defining "E" ("omega_1" is the
2798
2799                          real period, and "omega_2/omega_1" belongs to
2800       Poincaré's half-plane).
2801
2802         "eta"   :   quasi-periods "[eta_1, eta_2]", such that
2803       "eta_1omega_2-eta_2omega_1 = iPi".
2804
2805         "roots" :   roots of the associated Weierstrass equation.
2806
2807         "tate"  :   "[u^2,u,v]" in the notation of Tate.
2808
2809         "w"  :   Mestre's "w" (this is technical).
2810
2811       The member functions "area", "eta" and "omega" are only available for
2812       curves over Q. Conversely, "tate" and "w" are only available for curves
2813       defined over "Q_p". The use of member functions is best described by an
2814       example:
2815
2816           ? E = ellinit([0,0,0,0,1]); \\ The curve y^2 = x^3 + 1
2817           ? E.a6
2818           %2 = 1
2819           ? E.c6
2820           %3 = -864
2821           ? E.disc
2822           %4 = -432
2823
2824       Some functions, in particular those relative to height computations
2825       (see "ellheight") require also that the curve be in minimal Weierstrass
2826       form, which is duly stressed in their description below. This is
2827       achieved by the function "ellminimalmodel". \emph{Using a non-minimal
2828       model in such a routine will yield a wrong result!}
2829
2830       All functions related to elliptic curves share the prefix "ell", and
2831       the precise curve we are interested in is always the first argument, in
2832       either one of the three formats discussed above, unless otherwise
2833       specified. The requirements are given as the \emph{minimal} ones: any
2834       richer structure may replace the ones requested. For instance, in
2835       functions which have no use for the extra information given by an ell
2836       structure, the curve can be given either as a five-component vector, as
2837       an sell, or as an ell; if an sell is requested, an ell may equally be
2838       given.
2839
2840   elladd"(E,z1,z2)"
2841       sum of the points "z1" and "z2" on the elliptic curve corresponding to
2842       "E".
2843
2844       The library syntax is addell"(E,z1,z2)".
2845
2846   ellak"(E,n)"
2847       computes the coefficient "a_n" of the "L"-function of the elliptic
2848       curve "E", i.e. in principle coefficients of a newform of weight 2
2849       assuming Taniyama-Weil conjecture (which is now known to hold in full
2850       generality thanks to the work of Breuil, Conrad, Diamond, Taylor and
2851       Wiles). "E" must be an sell as output by "ellinit". For this function
2852       to work for every "n" and not just those prime to the conductor, "E"
2853       must be a minimal Weierstrass equation. If this is not the case, use
2854       the function "ellminimalmodel" before using "ellak".
2855
2856       The library syntax is akell"(E,n)".
2857
2858   ellan"(E,n)"
2859       computes the vector of the first "n" "a_k" corresponding to the
2860       elliptic curve "E". All comments in "ellak" description remain valid.
2861
2862       The library syntax is anell"(E,n)", where "n" is a C integer.
2863
2864   ellap"(E,p,{flag = 0})"
2865       computes the "a_p" corresponding to the elliptic curve "E" and the
2866       prime number "p". These are defined by the equation "#E(F_p) = p+1 -
2867       a_p", where "#E(F_p)" stands for the number of points of the curve "E"
2868       over the finite field "F_p". When "flag" is 0, this uses the baby-step
2869       giant-step method and a trick due to Mestre. This runs in time
2870       "O(p^{1/4})" and requires "O(p^{1/4})" storage, hence becomes
2871       unreasonable when "p" has about 30 digits.
2872
2873       If "flag" is 1, computes the "a_p" as a sum of Legendre symbols. This
2874       is slower than the previous method as soon as "p" is greater than 100,
2875       say.
2876
2877       No checking is done that "p" is indeed prime. "E" must be an sell as
2878       output by "ellinit", defined over Q, "F_p" or "Q_p". "E" must be given
2879       by a Weierstrass equation minimal at "p".
2880
2881       The library syntax is ellap0"(E,p,flag)". Also available are "
2882       apell(E,p)", corresponding to "flag = 0", and " apell2(E,p)" ("flag =
2883       1").
2884
2885   ellbil"(E,z1,z2)"
2886       if "z1" and "z2" are points on the elliptic curve "E", assumed to be
2887       integral given by a minimal model, this function computes the value of
2888       the canonical bilinear form on "z1", "z2":
2889
2890         " ( h(E,z1+z2) - h(E,z1) - h(E,z2) ) / 2 "
2891
2892       where "+" denotes of course addition on "E". In addition, "z1" or "z2"
2893       (but not both) can be vectors or matrices.
2894
2895       The library syntax is bilhell"(E,z1,z2,prec)".
2896
2897   ellchangecurve"(E,v)"
2898       changes the data for the elliptic curve "E" by changing the coordinates
2899       using the vector "v = [u,r,s,t]", i.e. if "x'" and "y'" are the new
2900       coordinates, then "x = u^2x'+r", "y = u^3y'+su^2x'+t".  "E" must be an
2901       sell as output by "ellinit".
2902
2903       The library syntax is coordch"(E,v)".
2904
2905   ellchangepoint"(x,v)"
2906       changes the coordinates of the point or vector of points "x" using the
2907       vector "v = [u,r,s,t]", i.e. if "x'" and "y'" are the new coordinates,
2908       then "x = u^2x'+r", "y = u^3y'+su^2x'+t" (see also "ellchangecurve").
2909
2910       The library syntax is pointch"(x,v)".
2911
2912   ellconvertname"(name)"
2913       converts an elliptic curve name, as found in the "elldata" database,
2914       from a string to a triplet "[conductor, isogeny class, index]". It will
2915       also convert a triplet back to a curve name.  Examples:
2916
2917         ? ellconvertname("123b1")
2918         %1 = [123, 1, 1]
2919         ? ellconvertname(%)
2920         %2 = "123b1"
2921
2922       The library syntax is ellconvertname"(name)".
2923
2924   elleisnum"(E,k,{flag = 0})"
2925       "E" being an elliptic curve as output by "ellinit" (or, alternatively,
2926       given by a 2-component vector "[omega_1,omega_2]" representing its
2927       periods), and "k" being an even positive integer, computes the
2928       numerical value of the Eisenstein series of weight "k" at "E", namely
2929
2930         " (2i Pi/omega_2)^k \Big(1 + 2/zeta(1-k) sum_{n >= 0} n^{k-1}q^n /
2931       (1-q^n)\Big), "
2932
2933       where "q = e(omega_1/omega_2)".
2934
2935       When flag is non-zero and "k = 4" or 6, returns the elliptic invariants
2936       "g_2" or "g_3", such that
2937
2938         "y^2 = 4x^3 - g_2 x - g_3"
2939
2940       is a Weierstrass equation for "E".
2941
2942       The library syntax is elleisnum"(E,k,flag)".
2943
2944   elleta"(om)"
2945       returns the two-component row vector "[eta_1,eta_2]" of quasi-periods
2946       associated to "om = [omega_1, omega_2]"
2947
2948       The library syntax is elleta"(om, prec)"
2949
2950   ellgenerators"(E)"
2951       returns a Z-basis of the free part of the Mordell-Weil group associated
2952       to "E".  This function depends on the "elldata" database being
2953       installed and referencing the curve, and so is only available for
2954       curves over Z of small conductors.
2955
2956       The library syntax is ellgenerators"(E)".
2957
2958   ellglobalred"(E)"
2959       calculates the arithmetic conductor, the global minimal model of "E"
2960       and the global Tamagawa number "c".  "E" must be an sell as output by
2961       "ellinit", \emph{and is supposed to have all its coefficients "a_i" in}
2962       Q. The result is a 3 component vector "[N,v,c]". "N" is the arithmetic
2963       conductor of the curve. "v" gives the coordinate change for "E" over Q
2964       to the minimal integral model (see "ellminimalmodel"). Finally "c" is
2965       the product of the local Tamagawa numbers "c_p", a quantity which
2966       enters in the Birch and Swinnerton-Dyer conjecture.
2967
2968       The library syntax is ellglobalred"(E)".
2969
2970   ellheight"(E,z,{flag = 2})"
2971       global Néron-Tate height of the point "z" on the elliptic curve "E"
2972       (defined over Q), given by a standard minimal integral model. "E" must
2973       be an "ell" as output by "ellinit". flag selects the algorithm used to
2974       compute the archimedean local height. If "flag = 0", this computation
2975       is done using sigma and theta-functions and a trick due to J.
2976       Silverman. If "flag = 1", use Tate's "4^n" algorithm. If "flag = 2",
2977       use Mestre's AGM algorithm. The latter is much faster than the other
2978       two, both in theory (converges quadratically) and in practice.
2979
2980       The library syntax is ellheight0"(E,z,flag,prec)". Also available are "
2981       ghell(E,z,prec)" ("flag = 0") and " ghell2(E,z,prec)" ("flag = 1").
2982
2983   ellheightmatrix"(E,x)"
2984       "x" being a vector of points, this function outputs the Gram matrix of
2985       "x" with respect to the Néron-Tate height, in other words, the "(i,j)"
2986       component of the matrix is equal to "ellbil(E,x[i],x[j])". The rank of
2987       this matrix, at least in some approximate sense, gives the rank of the
2988       set of points, and if "x" is a basis of the Mordell-Weil group of "E",
2989       its determinant is equal to the regulator of "E". Note that this matrix
2990       should be divided by 2 to be in accordance with certain normalizations.
2991       "E" is assumed to be integral, given by a minimal model.
2992
2993       The library syntax is mathell"(E,x,prec)".
2994
2995   ellidentify"(E)"
2996       look up the elliptic curve "E" (over Z) in the "elldata" database and
2997       return "[[N, M, G], C]"  where "N" is the name of the curve in J.  E.
2998       Cremona database, "M" the minimal model, "G" a Z-basis of the free part
2999       of the Mordell-Weil group of "E" and "C" the coordinates change (see
3000       "ellchangecurve").
3001
3002       The library syntax is ellidentify"(E)".
3003
3004   ellinit"(E,{flag = 0})"
3005       initialize an "ell" structure, associated to the elliptic curve "E".
3006       "E" is a 5-component vector "[a_1,a_2,a_3,a_4,a_6]" defining the
3007       elliptic curve with Weierstrass equation
3008
3009         " Y^2 + a_1 XY + a_3 Y = X^3 + a_2 X^2 + a_4 X + a_6 "
3010
3011       or a string, in this case the coefficients of the curve with matching
3012       name are looked in the "elldata" database if available. For the time
3013       being, only curves over a prime field "F_p" and over the "p"-adic or
3014       real numbers (including rational numbers) are fully supported. Other
3015       domains are only supported for very basic operations such as point
3016       addition.
3017
3018       The result of "ellinit" is a an ell structure by default, and a shorted
3019       sell if "flag = 1". Both contain the following information in their
3020       components:
3021
3022         " a_1,a_2,a_3,a_4,a_6,b_2,b_4,b_6,b_8,c_4,c_6,Delta,j."
3023
3024       All are accessible via member functions. In particular, the
3025       discriminant is "E.disc", and the "j"-invariant is "E.j".
3026
3027       The other six components are only present if "flag" is 0 or omitted.
3028       Their content depends on whether the curve is defined over R or not:
3029
3030       \item When "E" is defined over R, "E.roots" is a vector whose three
3031       components contain the roots of the right hand side of the associated
3032       Weierstrass equation.
3033
3034         " (y + a_1x/2 + a_3/2)^2 = g(x) "
3035
3036       If the roots are all real, then they are ordered by decreasing value.
3037       If only one is real, it is the first component.
3038
3039       Then "omega_1 = ""E.omega[1]" is the real period of "E" (integral of
3040       "dx/(2y+a_1x+a_3)" over the connected component of the identity element
3041       of the real points of the curve), and "omega_2 = ""E.omega[2]" is a
3042       complex period. In other words, "E.omega" forms a basis of the complex
3043       lattice defining "E", with "tau = (omega_2)/(omega_1)" having positive
3044       imaginary part.
3045
3046       "E.eta" is a row vector containing the corresponding values "eta_1" and
3047       "eta_2" such that "eta_1omega_2-eta_2omega_1 = iPi".
3048
3049       Finally, "E.area" is the volume of the complex lattice defining "E".
3050
3051       \item When "E" is defined over "Q_p", the "p"-adic valuation of "j"
3052       must be negative. Then "E.roots" is the vector with a single component
3053       equal to the "p"-adic root of the associated Weierstrass equation
3054       corresponding to "-1" under the Tate parametrization.
3055
3056       "E.tate" yields the three-component vector "[u^2,u,q]", in the
3057       notations of Tate. If the "u"-component does not belong to "Q_p", it is
3058       set to zero.
3059
3060       "E.w" is Mestre's "w" (this is technical).
3061
3062       For all other base fields or rings, the last six components are
3063       arbitrarily set equal to zero. See also the description of member
3064       functions related to elliptic curves at the beginning of this section.
3065
3066       The library syntax is ellinit0"(E,flag,prec)". Also available are "
3067       initell(E,prec)" ("flag = 0") and " smallinitell(E,prec)" ("flag = 1").
3068
3069   ellisoncurve"(E,z)"
3070       gives 1 (i.e. true) if the point "z" is on the elliptic curve "E", 0
3071       otherwise. If "E" or "z" have imprecise coefficients, an attempt is
3072       made to take this into account, i.e. an imprecise equality is checked,
3073       not a precise one. It is allowed for "z" to be a vector of points in
3074       which case a vector (of the same type) is returned.
3075
3076       The library syntax is ellisoncurve"(E,z)". Also available is "
3077       oncurve(E,z)" which returns a "long" but does not accept vector of
3078       points.
3079
3080   ellj"(x)"
3081       elliptic "j"-invariant. "x" must be a complex number with positive
3082       imaginary part, or convertible into a power series or a "p"-adic number
3083       with positive valuation.
3084
3085       The library syntax is jell"(x,prec)".
3086
3087   elllocalred"(E,p)"
3088       calculates the Kodaira type of the local fiber of the elliptic curve
3089       "E" at the prime "p".  "E" must be an sell as output by "ellinit", and
3090       is assumed to have all its coefficients "a_i" in Z. The result is a
3091       4-component vector "[f,kod,v,c]". Here "f" is the exponent of "p" in
3092       the arithmetic conductor of "E", and "kod" is the Kodaira type which is
3093       coded as follows:
3094
3095       1 means good reduction (type I"_0"), 2, 3 and 4 mean types II, III and
3096       IV respectively, "4+nu" with "nu > 0" means type I"_nu"; finally the
3097       opposite values "-1", "-2", etc. refer to the starred types I"_0^*",
3098       II"^*", etc. The third component "v" is itself a vector "[u,r,s,t]"
3099       giving the coordinate changes done during the local reduction.
3100       Normally, this has no use if "u" is 1, that is, if the given equation
3101       was already minimal.  Finally, the last component "c" is the local
3102       Tamagawa number "c_p".
3103
3104       The library syntax is elllocalred"(E,p)".
3105
3106   elllseries"(E,s,{A = 1})"
3107       "E" being an sell as output by "ellinit", this computes the value of
3108       the L-series of "E" at "s". It is assumed that "E" is defined over Q,
3109       not necessarily minimal. The optional parameter "A" is a cutoff point
3110       for the integral, which must be chosen close to 1 for best speed. The
3111       result must be independent of "A", so this allows some internal
3112       checking of the function.
3113
3114       Note that if the conductor of the curve is large, say greater than
3115       "10^{12}", this function will take an unreasonable amount of time since
3116       it uses an "O(N^{1/2})" algorithm.
3117
3118       The library syntax is elllseries"(E,s,A,prec)" where "prec" is a "long"
3119       and an omitted "A" is coded as "NULL".
3120
3121   ellminimalmodel"(E,{&v})"
3122       return the standard minimal integral model of the rational elliptic
3123       curve "E". If present, sets "v" to the corresponding change of
3124       variables, which is a vector "[u,r,s,t]" with rational components. The
3125       return value is identical to that of "ellchangecurve(E, v)".
3126
3127       The resulting model has integral coefficients, is everywhere minimal,
3128       "a_1" is 0 or 1, "a_2" is 0, 1 or "-1" and "a_3" is 0 or 1. Such a
3129       model is unique, and the vector "v" is unique if we specify that "u" is
3130       positive, which we do.
3131
3132       The library syntax is ellminimalmodel"(E,&v)", where an omitted "v" is
3133       coded as "NULL".
3134
3135   ellorder"(E,z)"
3136       gives the order of the point "z" on the elliptic curve "E" if it is a
3137       torsion point, zero otherwise. In the present version
3138       /usr/share/libpari23, this is implemented only for elliptic curves
3139       defined over Q.
3140
3141       The library syntax is orderell"(E,z)".
3142
3143   ellordinate"(E,x)"
3144       gives a 0, 1 or 2-component vector containing the "y"-coordinates of
3145       the points of the curve "E" having "x" as "x"-coordinate.
3146
3147       The library syntax is ordell"(E,x)".
3148
3149   ellpointtoz"(E,z)"
3150       if "E" is an elliptic curve with coefficients in R, this computes a
3151       complex number "t" (modulo the lattice defining "E") corresponding to
3152       the point "z", i.e. such that, in the standard Weierstrass model, " wp
3153       (t) = z[1], wp '(t) = z[2]". In other words, this is the inverse
3154       function of "ellztopoint". More precisely, if "(w1,w2)" are the real
3155       and complex periods of "E", "t" is such that "0 <=  Re (t) < w1" and "0
3156       <=  Im (t) <  Im (w2)".
3157
3158       If "E" has coefficients in "Q_p", then either Tate's "u" is in "Q_p",
3159       in which case the output is a "p"-adic number "t" corresponding to the
3160       point "z" under the Tate parametrization, or only its square is, in
3161       which case the output is "t+1/t". "E" must be an ell as output by
3162       "ellinit".
3163
3164       The library syntax is zell"(E,z,prec)".
3165
3166   ellpow"(E,z,n)"
3167       computes "n" times the point "z" for the group law on the elliptic
3168       curve "E". Here, "n" can be in Z, or "n" can be a complex quadratic
3169       integer if the curve "E" has complex multiplication by "n" (if not, an
3170       error message is issued).
3171
3172       The library syntax is powell"(E,z,n)".
3173
3174   ellrootno"(E,{p = 1})"
3175       "E" being an sell as output by "ellinit", this computes the local (if
3176       "p ! = 1") or global (if "p = 1") root number of the L-series of the
3177       elliptic curve "E". Note that the global root number is the sign of the
3178       functional equation and conjecturally is the parity of the rank of the
3179       Mordell-Weil group. The equation for "E" must have coefficients in Q
3180       but need \emph{not} be minimal.
3181
3182       The library syntax is ellrootno"(E,p)" and the result (equal to "+-1")
3183       is a "long".
3184
3185   ellsigma"(E,z,{flag = 0})"
3186       value of the Weierstrass "sigma" function of the lattice associated to
3187       "E" as given by "ellinit" (alternatively, "E" can be given as a lattice
3188       "[omega_1,omega_2]").
3189
3190       If "flag = 1", computes an (arbitrary) determination of " log
3191       (sigma(z))".
3192
3193       If "flag = 2,3", same using the product expansion instead of theta
3194       series.  The library syntax is ellsigma"(E,z,flag)"
3195
3196   ellsearch"(N)"
3197       if "N" is an integer, it is taken as a conductor else if "N" is a
3198       string, it can be a curve name ("11a1"), a isogeny class ("11a") or a
3199       conductor "11". This function finds all curves in the "elldata"
3200       database with the given property.
3201
3202       If "N" is a full curve name, the output format is "[N,
3203       [a_1,a_2,a_3,a_4,a_6], G]" where "[a_1,a_2,a_3,a_4,a_6]" are the
3204       coefficients of the Weierstrass equation of the curve and "G" is a
3205       Z-basis of the free part of the Mordell-Weil group associated to the
3206       curve.
3207
3208       If "N" is not a full-curve name, the output is the list (as a vector)
3209       of all matching curves in the above format.
3210
3211       The library syntax is ellsearch"(N)". Also available is "
3212       ellsearchcurve(N)" that only accept complete curve names.
3213
3214   ellsub"(E,z1,z2)"
3215       difference of the points "z1" and "z2" on the elliptic curve
3216       corresponding to "E".
3217
3218       The library syntax is subell"(E,z1,z2)".
3219
3220   elltaniyama"(E)"
3221       computes the modular parametrization of the elliptic curve "E", where
3222       "E" is an sell as output by "ellinit", in the form of a two-component
3223       vector "[u,v]" of power series, given to the current default series
3224       precision. This vector is characterized by the following two
3225       properties. First the point "(x,y) = (u,v)" satisfies the equation of
3226       the elliptic curve. Second, the differential "du/(2v+a_1u+a_3)" is
3227       equal to "f(z)dz", a differential form on "H/Gamma_0(N)" where "N" is
3228       the conductor of the curve. The variable used in the power series for
3229       "u" and "v" is "x", which is implicitly understood to be equal to " exp
3230       (2iPi z)". It is assumed that the curve is a \emph{strong} Weil curve,
3231       and that the Manin constant is equal to 1. The equation of the curve
3232       "E" must be minimal (use "ellminimalmodel" to get a minimal equation).
3233
3234       The library syntax is elltaniyama"(E, prec)", and the precision of the
3235       result is determined by "prec".
3236
3237   elltors"(E,{flag = 0})"
3238       if "E" is an elliptic curve \emph{defined over Q}, outputs the torsion
3239       subgroup of "E" as a 3-component vector "[t,v1,v2]", where "t" is the
3240       order of the torsion group, "v1" gives the structure of the torsion
3241       group as a product of cyclic groups (sorted by decreasing order), and
3242       "v2" gives generators for these cyclic groups. "E" must be an ell as
3243       output by "ellinit".
3244
3245         ?  E = ellinit([0,0,0,-1,0]);
3246         ?  elltors(E)
3247         %1 = [4, [2, 2], [[0, 0], [1, 0]]]
3248
3249       Here, the torsion subgroup is isomorphic to "Z/2Z  x Z/2Z", with
3250       generators "[0,0]" and "[1,0]".
3251
3252       If "flag = 0", use Doud's algorithm: bound torsion by computing
3253       "#E(F_p)" for small primes of good reduction, then look for torsion
3254       points using Weierstrass parametrization (and Mazur's classification).
3255
3256       If "flag = 1", use Lutz-Nagell (\emph{much} slower), "E" is allowed to
3257       be an sell.
3258
3259       The library syntax is elltors0"(E,flag)".
3260
3261   ellwp"(E,{z = x},{flag = 0})"
3262       Computes the value at "z" of the Weierstrass " wp " function attached
3263       to the elliptic curve "E" as given by "ellinit" (alternatively, "E" can
3264       be given as a lattice "[omega_1,omega_2]").
3265
3266       If "z" is omitted or is a simple variable, computes the \emph{power
3267       series} expansion in "z" (starting "z^{-2}+O(z^2)"). The number of
3268       terms to an \emph{even} power in the expansion is the default
3269       serieslength in "gp", and the second argument (C long integer) in
3270       library mode.
3271
3272       Optional flag is (for now) only taken into account when "z" is numeric,
3273       and means 0: compute only " wp (z)", 1: compute "[ wp (z), wp '(z)]".
3274
3275       The library syntax is ellwp0"(E,z,flag,prec,precdl)". Also available is
3276       " weipell(E,precdl)" for the power series.
3277
3278   ellzeta"(E,z)"
3279       value of the Weierstrass "zeta" function of the lattice associated to
3280       "E" as given by "ellinit" (alternatively, "E" can be given as a lattice
3281       "[omega_1,omega_2]").
3282
3283       The library syntax is ellzeta"(E,z)".
3284
3285   ellztopoint"(E,z)"
3286       "E" being an ell as output by "ellinit", computes the coordinates
3287       "[x,y]" on the curve "E" corresponding to the complex number "z". Hence
3288       this is the inverse function of "ellpointtoz". In other words, if the
3289       curve is put in Weierstrass form, "[x,y]" represents the Weierstrass "
3290       wp "-function and its derivative. If "z" is in the lattice defining "E"
3291       over C, the result is the point at infinity "[0]".
3292
3293       The library syntax is pointell"(E,z,prec)".
3294
3296       In this section can be found functions which are used almost
3297       exclusively for working in general number fields. Other less specific
3298       functions can be found in the next section on polynomials. Functions
3299       related to quadratic number fields are found in section "Label
3300       se:arithmetic" (Arithmetic functions).
3301
3302   Number field structures
3303       Let "K = Q[X] / (T)" a number field, "Z_K" its ring of integers, "T
3304       belongs to Z[X]" is monic. Three basic number field structures can be
3305       associated to "K" in GP:
3306
3307       \item "nf" denotes a number field, i.e. a data structure output by
3308       "nfinit". This contains the basic arithmetic data associated to the
3309       number field: signature, maximal order (given by a basis "nf.zk"),
3310       discriminant, defining polynomial "T", etc.
3311
3312       \item "bnf" denotes a ``Buchmann's number field'', i.e. a data
3313       structure output by "bnfinit". This contains "nf" and the deeper
3314       invariants of the field: units U(K), class group "\Cl(K)", as well as
3315       technical data required to solve the two associated discrete logarithm
3316       problems.
3317
3318       \item "bnr" denotes a ``ray number field'', i.e. a data structure
3319       output by "bnrinit", corresponding to the ray class group structure of
3320       the field, for some modulus "f". It contains a bnf, the modulus "f",
3321       the ray class group "\Cl_f(K)" and data associated to the discrete
3322       logarithm problem therein.
3323
3324   Algebraic numbers and ideals
3325       An algebraic number belonging to "K = Q[X]/(T)" is given as
3326
3327       \item a "t_INT", "t_FRAC" or "t_POL" (implicitly modulo "T"), or
3328
3329       \item a "t_POLMOD" (modulo "T"), or
3330
3331       \item a "t_COL" "v" of dimension "N = [K:Q]", representing the element
3332       in terms of the computed integral basis, as "sum(i = 1, N, v[i] *
3333       nf.zk[i])". Note that a "t_VEC" will not be recognized.
3334
3335       An ideal is given in any of the following ways:
3336
3337       \item an algebraic number in one of the above forms, defining a
3338       principal ideal.
3339
3340       \item a prime ideal, i.e. a 5-component vector in the format output by
3341       "idealprimedec".
3342
3343       \item a "t_MAT", square and in Hermite Normal Form (or at least upper
3344       triangular with non-negative coefficients), whose columns represent a
3345       basis of the ideal.
3346
3347       One may use "idealhnf" to convert an ideal to the last (preferred)
3348       format.
3349
3350       Note. Some routines accept non-square matrices, but using this format
3351       is strongly discouraged. Nevertheless, their behaviour is as follows:
3352       If strictly less than "N = [K:Q]" generators are given, it is assumed
3353       they form a "Z_K"-basis. If "N" or more are given, a Z-basis is
3354       assumed. If exactly "N" are given, it is further assumed the matrix is
3355       in HNF. If any of these assumptions is not correct the behaviour of the
3356       routine is undefined.
3357
3358       \item an idele is a 2-component vector, the first being an ideal as
3359       above, the second being a "R_1+R_2"-component row vector giving
3360       Archimedean information, as complex numbers.
3361
3362   Finite abelian groups
3363       A finite abelian group "G" in user-readable format is given by its
3364       Smith Normal Form as a pair "[h,d]" or triple "[h,d,g]".  Here "h" is
3365       the cardinality of "G", "(d_i)" is the vector of elementary divisors,
3366       and "(g_i)" is a vector of generators. In short, "G =  oplus _{i <= n}
3367       (Z/d_iZ) g_i", with "d_n | ... | d_2 | d_1" and "prod d_i = h". This
3368       information can also be retrieved as "G.no", "G.cyc" and "G.gen".
3369
3370       \item a character on the abelian group " oplus  (Z/d_iZ) g_i" is given
3371       by a row vector "chi = [a_1,...,a_n]" such that "chi(prod g_i^{n_i}) =
3372       exp (2iPisum a_i n_i / d_i)".
3373
3374       \item given such a structure, a subgroup "H" is input as a square
3375       matrix, whose column express generators of "H" on the given generators
3376       "g_i".  Note that the absolute value of the determinant of that matrix
3377       is equal to the index "(G:H)".
3378
3379   Relative extensions
3380       When defining a relative extension, the base field "nf" must be defined
3381       by a variable having a lower priority (see "Label se:priority") than
3382       the variable defining the extension. For example, you may use the
3383       variable name "y" to define the base field, and "x" to define the
3384       relative extension.
3385
3386       \item "rnf" denotes a relative number field, i.e. a data structure
3387       output by "rnfinit".
3388
3389       \item A \emph{relative matrix} is a matrix whose entries are elements
3390       of a (fixed) number field "nf", always expressed as column vectors on
3391       the integral basis "nf.zk". Hence it is a matrix of vectors.
3392
3393       \item An ideal list is a row vector of (fractional) ideals of the
3394       number field "nf".
3395
3396       \item A pseudo-matrix is a pair "(A,I)" where "A" is a relative matrix
3397       and "I" an ideal list whose length is the same as the number of columns
3398       of "A". This pair is represented by a 2-component row vector.
3399
3400       \item The projective module generated by a pseudo-matrix "(A,I)" is the
3401       sum "sum_i {a}_j A_j" where the "{a}_j" are the ideals of "I" and "A_j"
3402       is the "j"-th column of "A".
3403
3404       \item A pseudo-matrix "(A,I)" is a pseudo-basis of the module it
3405       generates if "A" is a square matrix with non-zero determinant and all
3406       the ideals of "I" are non-zero. We say that it is in Hermite Normal
3407       Form (HNF) if it is upper triangular and all the elements of the
3408       diagonal are equal to 1.
3409
3410       \item The \emph{determinant} of a pseudo-basis "(A,I)" is the ideal
3411       equal to the product of the determinant of "A" by all the ideals of
3412       "I". The determinant of a pseudo-matrix is the determinant of any
3413       pseudo-basis of the module it generates.
3414
3415   Class field theory
3416       A "modulus", in the sense of class field theory, is a divisor supported
3417       on the non-complex places of "K". In PARI terms, this means either an
3418       ordinary ideal "I" as above (no archimedean component), or a pair
3419       "[I,a]", where "a" is a vector with "r_1" "{0,1}"-components,
3420       corresponding to the infinite part of the divisor. More precisely, the
3421       "i"-th component of "a" corresponds to the real embedding associated to
3422       the "i"-th real root of "K.roots". (That ordering is not canonical, but
3423       well defined once a defining polynomial for "K" is chosen.) For
3424       instance, "[1, [1,1]]" is a modulus for a real quadratic field,
3425       allowing ramification at any of the two places at infinity.
3426
3427       A bid or ``big ideal'' is a structure output by "idealstar" needed to
3428       compute in "(Z_K/I)^*", where "I" is a modulus in the above sense.  If
3429       is a finite abelian group as described above, supplemented by technical
3430       data needed to solve discrete log problems.
3431
3432       Finally we explain how to input ray number fields (or bnr), using class
3433       field theory. These are defined by a triple "a1", "a2", "a3", where the
3434       defining set "[a1,a2,a3]" can have any of the following forms: "[bnr]",
3435       "[bnr,subgroup]", "[bnf,module]", "[bnf,module,subgroup]".
3436
3437       \item "bnf" is as output by "bnfinit", where units are mandatory unless
3438       the modulus is trivial; bnr is as output by "bnrinit". This is the
3439       ground field "K".
3440
3441       \item \emph{module} is a modulus "\goth{f}", as described above.
3442
3443       \item \emph{subgroup} a subgroup of the ray class group modulo
3444       "\goth{f}" of "K". As described above, this is input as a square matrix
3445       expressing generators of a subgroup of the ray class group "bnr.clgp"
3446       on the given generators.
3447
3448       The corresponding bnr is the subfield of the ray class field of "K"
3449       modulo "\goth{f}", fixed by the given subgroup.
3450
3451   General use
3452       All the functions which are specific to relative extensions, number
3453       fields, Buchmann's number fields, Buchmann's number rays, share the
3454       prefix "rnf", "nf", "bnf", "bnr" respectively. They take as first
3455       argument a number field of that precise type, respectively output by
3456       "rnfinit", "nfinit", "bnfinit", and "bnrinit".
3457
3458       However, and even though it may not be specified in the descriptions of
3459       the functions below, it is permissible, if the function expects a "nf",
3460       to use a "bnf" instead, which contains much more information. On the
3461       other hand, if the function requires a "bnf", it will \emph{not} launch
3462       "bnfinit" for you, which is a costly operation. Instead, it will give
3463       you a specific error message. In short, the types
3464
3465         " nf <= bnf <= bnr"
3466
3467       are ordered, each function requires a minimal type to work properly,
3468       but you may always substitute a larger type.
3469
3470       The data types corresponding to the structures described above are
3471       rather complicated. Thus, as we already have seen it with elliptic
3472       curves, GP provides ``member functions'' to retrieve data from these
3473       structures (once they have been initialized of course). The relevant
3474       types of number fields are indicated between parentheses:
3475
3476        "bid"     (bnr, ) :   bid ideal structure.
3477
3478        "bnf"     (bnr,  bnf ) :   Buchmann's number field.
3479
3480        "clgp"   (bnr,  bnf ) :   classgroup. This one admits the following
3481       three subclasses:
3482
3483                "cyc"  :     cyclic decomposition (SNF).
3484
3485                "gen"  : generators.
3486
3487                "no"   :     number of elements.
3488
3489        "diff"   (bnr,  bnf,  nf ) :   the different ideal.
3490
3491        "codiff" (bnr,  bnf,  nf ) :   the codifferent (inverse of the
3492       different in the ideal group).
3493
3494        "disc"  (bnr,  bnf,  nf ) :   discriminant.
3495
3496        "fu"    (bnr,  bnf,  nf ) : fundamental units.
3497
3498        "index"    (bnr,  bnf,  nf ) : index of the power order in the ring of
3499       integers.
3500
3501        "nf"    (bnr,  bnf,  nf ) :   number field.
3502
3503        "r1"  (bnr,  bnf,  nf ) :   the number of real embeddings.
3504
3505        "r2"  (bnr,  bnf,  nf ) :   the number of pairs of complex embeddings.
3506
3507        "reg"   (bnr,  bnf, ) :   regulator.
3508
3509        "roots" (bnr,  bnf,  nf ) :   roots of the polynomial generating the
3510       field.
3511
3512        "t2"    (bnr,  bnf,  nf ) :   the T2 matrix (see "nfinit").
3513
3514        "tu"    (bnr,  bnf, ) :   a generator for the torsion units.
3515
3516        "tufu"  (bnr,  bnf, ) : "[w,u_1,...,u_r]", "(u_i)" is a vector of
3517       fundamental units, "w" generates the torsion units.
3518
3519        "zk"    (bnr,  bnf,  nf ) :   integral basis, i.e. a Z-basis of the
3520       maximal order.
3521
3522       For instance, assume that "bnf = bnfinit(pol)", for some polynomial.
3523       Then "bnf.clgp" retrieves the class group, and "bnf.clgp.no" the class
3524       number. If we had set "bnf = nfinit(pol)", both would have output an
3525       error message. All these functions are completely recursive, thus for
3526       instance "bnr.bnf.nf.zk" will yield the maximal order of bnr, which you
3527       could get directly with a simple "bnr.zk".
3528
3529   Class group, units, and the GRH
3530       Some of the functions starting with "bnf" are implementations of the
3531       sub-exponential algorithms for finding class and unit groups under GRH,
3532       due to Hafner-McCurley, Buchmann and Cohen-Diaz-Olivier. The general
3533       call to the functions concerning class groups of general number fields
3534       (i.e. excluding "quadclassunit") involves a polynomial "P" and a
3535       technical vector
3536
3537         "tech = [c, c2, nrpid ],"
3538
3539       where the parameters are to be understood as follows:
3540
3541       "P" is the defining polynomial for the number field, which must be in
3542       "Z[X]", irreducible and monic. In fact, if you supply a non-monic
3543       polynomial at this point, "gp" issues a warning, then \emph{transforms
3544       your polynomial} so that it becomes monic. The "nfinit" routine will
3545       return a different result in this case: instead of "res", you get a
3546       vector "[res,Mod(a,Q)]", where "Mod(a,Q) = Mod(X,P)" gives the change
3547       of variables. In all other routines, the variable change is simply
3548       lost.
3549
3550       The numbers "c <= c_2" are positive real numbers which control the
3551       execution time and the stack size. For a given "c", set "c_2 = c" to
3552       get maximum speed. To get a rigorous result under GRH you must take "c2
3553       >= 12" (or "c2 >= 6" in "P" is quadratic). Reasonable values for "c"
3554       are between 0.1 and 2. The default is "c = c_2 = 0.3".
3555
3556       "nrpid" is the maximal number of small norm relations associated to
3557       each ideal in the factor base. Set it to 0 to disable the search for
3558       small norm relations. Otherwise, reasonable values are between 4 and
3559       20. The default is 4.
3560
3561       Warning. Make sure you understand the above! By default, most of the
3562       "bnf" routines depend on the correctness of a heuristic assumption
3563       which is stronger than the GRH. In particular, any of the class number,
3564       class group structure, class group generators, regulator and
3565       fundamental units may be wrong, independently of each other. Any result
3566       computed from such a "bnf" may be wrong. The only guarantee is that the
3567       units given generate a subgroup of finite index in the full unit group.
3568       In practice, very few counter-examples are known, requiring unlucky
3569       random seeds. No counter-example has been reported for "c_2 = 0.5"
3570       (which should be almost as fast as "c_2 = 0.3", and shall very probably
3571       become the default). If you use "c_2 = 12", then everything is correct
3572       assuming the GRH holds. You can use "bnfcertify" to certify the
3573       computations unconditionally.
3574
3575       Remarks.
3576
3577       Apart from the polynomial "P", you do not need to supply the technical
3578       parameters (under the library you still need to send at least an empty
3579       vector, coded as "NULL"). However, should you choose to set some of
3580       them, they \emph{must} be given in the requested order. For example, if
3581       you want to specify a given value of nrpid, you must give some values
3582       as well for "c" and "c_2", and provide a vector "[c,c_2,nrpid]".
3583
3584       Note also that you can use an "nf" instead of "P", which avoids
3585       recomputing the integral basis and analogous quantities.
3586
3587   bnfcertify"(bnf)"
3588       "bnf" being as output by "bnfinit", checks whether the result is
3589       correct, i.e. whether it is possible to remove the assumption of the
3590       Generalized Riemann Hypothesis. It is correct if and only if the answer
3591       is 1. If it is incorrect, the program may output some error message, or
3592       loop indefinitely.  You can check its progress by increasing the debug
3593       level.
3594
3595       The library syntax is certifybuchall"(bnf)", and the result is a C
3596       long.
3597
3598   bnfclassunit"(P,{flag = 0},{tech = []})"
3599       \emph{this function is DEPRECATED, use "bnfinit"}.
3600
3601       Buchmann's sub-exponential algorithm for computing the class group, the
3602       regulator and a system of fundamental units of the general algebraic
3603       number field "K" defined by the irreducible polynomial "P" with integer
3604       coefficients.
3605
3606       The result of this function is a vector "v" with many components, which
3607       for ease of presentation is in fact output as a one column matrix. It
3608       is \emph{not} a "bnf", you need "bnfinit" for that. First we describe
3609       the default behaviour ("flag = 0"):
3610
3611       "v[1]" is equal to the polynomial "P".
3612
3613       "v[2]" is the 2-component vector "[r1,r2]", where "r1" and "r2" are as
3614       usual the number of real and half the number of complex embeddings of
3615       the number field "K".
3616
3617       "v[3]" is the 2-component vector containing the field discriminant and
3618       the index.
3619
3620       "v[4]" is an integral basis in Hermite normal form.
3621
3622       "v[5]" ("v.clgp") is a 3-component vector containing the class number
3623       ("v.clgp.no"), the structure of the class group as a product of cyclic
3624       groups of order "n_i" ("v.clgp.cyc"), and the corresponding generators
3625       of the class group of respective orders "n_i" ("v.clgp.gen").
3626
3627       "v[6]" ("v.reg") is the regulator computed to an accuracy which is the
3628       maximum of an internally determined accuracy and of the default.
3629
3630       "v[7]" is deprecated, maintained for backward compatibility and always
3631       equal to 1.
3632
3633       "v[8]" ("v.tu") a vector with 2 components, the first being the number
3634       "w" of roots of unity in "K" and the second a primitive "w"-th root of
3635       unity expressed as a polynomial.
3636
3637       "v[9]" ("v.fu") is a system of fundamental units also expressed as
3638       polynomials.
3639
3640       If "flag = 1", and the precision happens to be insufficient for
3641       obtaining the fundamental units, the internal precision is doubled and
3642       the computation redone, until the exact results are obtained. Be warned
3643       that this can take a very long time when the coefficients of the
3644       fundamental units on the integral basis are very large, for example in
3645       large real quadratic fields.  For this case, there are alternate
3646       compact representations for algebraic numbers, implemented in PARI but
3647       currently not available in GP.
3648
3649       If "flag = 2", the fundamental units and roots of unity are not
3650       computed.  Hence the result has only 7 components, the first seven
3651       ones.
3652
3653       The library syntax is bnfclassunit0"(P,flag,tech,prec)".
3654
3655   bnfclgp"(P,{tech = []})"
3656       as "bnfinit", but only outputs "bnf.clgp", i.e. the class group.
3657
3658       The library syntax is classgrouponly"(P,tech,prec)", where tech is as
3659       described under "bnfinit".
3660
3661   bnfdecodemodule"(nf,m)"
3662       if "m" is a module as output in the first component of an extension
3663       given by "bnrdisclist", outputs the true module.
3664
3665       The library syntax is decodemodule"(nf,m)".
3666
3667   bnfinit"(P,{flag = 0},{tech = []})"
3668       initializes a bnf structure. Used in programs such as "bnfisprincipal",
3669       "bnfisunit" or "bnfnarrow". By default, the results are conditional on
3670       a heuristic strengthening of the GRH, see se:GRHbnf. The result is a
3671       10-component vector bnf.
3672
3673       This implements Buchmann's sub-exponential algorithm for computing the
3674       class group, the regulator and a system of fundamental units of the
3675       general algebraic number field "K" defined by the irreducible
3676       polynomial "P" with integer coefficients.
3677
3678       If the precision becomes insufficient, "gp" outputs a warning
3679       ("fundamental units too large, not given") and does not strive to
3680       compute the units by default ("flag = 0").
3681
3682       When "flag = 1", we insist on finding the fundamental units exactly. Be
3683       warned that this can take a very long time when the coefficients of the
3684       fundamental units on the integral basis are very large. If the
3685       fundamental units are simply too large to be represented in this form,
3686       an error message is issued. They could be obtained using the so-called
3687       compact representation of algebraic numbers as a formal product of
3688       algebraic integers. The latter is implemented internally but not
3689       publicly accessible yet.
3690
3691       When "flag = 2", on the contrary, it is initially agreed that units are
3692       not computed. Note that the resulting bnf will not be suitable for
3693       "bnrinit", and that this flag provides negligible time savings compared
3694       to the default. In short, it is deprecated.
3695
3696       When "flag = 3", computes a very small version of "bnfinit", a ``small
3697       Buchmann's number field'' (or sbnf for short) which contains enough
3698       information to recover the full "bnf" vector very rapidly, but which is
3699       much smaller and hence easy to store and print. It is supposed to be
3700       used in conjunction with "bnfmake".
3701
3702       "tech" is a technical vector (empty by default, see se:GRHbnf).
3703       Careful use of this parameter may speed up your computations
3704       considerably.
3705
3706       The components of a bnf or sbnf are technical and never used by the
3707       casual user. In fact: \emph{never access a component directly, always
3708       use a proper member function.} However, for the sake of completeness
3709       and internal documentation, their description is as follows. We use the
3710       notations explained in the book by H. Cohen, \emph{A Course in
3711       Computational Algebraic Number Theory}, Graduate Texts in Maths 138,
3712       Springer-Verlag, 1993, Section 6.5, and subsection 6.5.5 in particular.
3713
3714       "bnf[1]" contains the matrix "W", i.e. the matrix in Hermite normal
3715       form giving relations for the class group on prime ideal generators "(
3716       wp _i)_{1 <= i <= r}".
3717
3718       "bnf[2]" contains the matrix "B", i.e. the matrix containing the
3719       expressions of the prime ideal factorbase in terms of the " wp _i". It
3720       is an "r x c" matrix.
3721
3722       "bnf[3]" contains the complex logarithmic embeddings of the system of
3723       fundamental units which has been found. It is an "(r_1+r_2) x
3724       (r_1+r_2-1)" matrix.
3725
3726       "bnf[4]" contains the matrix "M''_C" of Archimedean components of the
3727       relations of the matrix "(W|B)".
3728
3729       "bnf[5]" contains the prime factor base, i.e. the list of prime ideals
3730       used in finding the relations.
3731
3732       "bnf[6]" used to contain a permutation of the prime factor base, but
3733       has been obsoleted. It contains a dummy 0.
3734
3735       "bnf[7]" or "bnf.nf" is equal to the number field data "nf" as would be
3736       given by "nfinit".
3737
3738       "bnf[8]" is a vector containing the classgroup "bnf.clgp" as a finite
3739       abelian group, the regulator "bnf.reg", a 1 (used to contain an
3740       obsolete ``check number''), the number of roots of unity and a
3741       generator "bnf.tu", the fundamental units "bnf.fu".
3742
3743       "bnf[9]" is a 3-element row vector used in "bnfisprincipal" only and
3744       obtained as follows. Let "D = U W V" obtained by applying the Smith
3745       normal form algorithm to the matrix "W" ( = "bnf[1]") and let "U_r" be
3746       the reduction of "U" modulo "D". The first elements of the factorbase
3747       are given (in terms of "bnf.gen") by the columns of "U_r", with
3748       Archimedean component "g_a"; let also "GD_a" be the Archimedean
3749       components of the generators of the (principal) ideals defined by the
3750       "bnf.gen[i]^bnf.cyc[i]". Then "bnf[9] = [U_r, g_a, GD_a]".
3751
3752       "bnf[10]" is by default unused and set equal to 0. This field is used
3753       to store further information about the field as it becomes available,
3754       which is rarely needed, hence would be too expensive to compute during
3755       the initial "bnfinit" call. For instance, the generators of the
3756       principal ideals "bnf.gen[i]^bnf.cyc[i]" (during a call to
3757       "bnrisprincipal"), or those corresponding to the relations in "W" and
3758       "B" (when the "bnf" internal precision needs to be increased).
3759
3760       An sbnf is a 12 component vector "v", as follows. Let "bnf" be the
3761       result of a full "bnfinit", complete with units. Then "v[1]" is the
3762       polynomial "P", "v[2]" is the number of real embeddings "r_1", "v[3]"
3763       is the field discriminant, "v[4]" is the integral basis, "v[5]" is the
3764       list of roots as in the sixth component of "nfinit", "v[6]" is the
3765       matrix "MD" of "nfinit" giving a Z-basis of the different, "v[7]" is
3766       the matrix "W = bnf[1]", "v[8]" is the matrix "matalpha = bnf[2]",
3767       "v[9]" is the prime ideal factor base "bnf[5]" coded in a compact way,
3768       and ordered according to the permutation "bnf[6]", "v[10]" is the
3769       2-component vector giving the number of roots of unity and a generator,
3770       expressed on the integral basis, "v[11]" is the list of fundamental
3771       units, expressed on the integral basis, "v[12]" is a vector containing
3772       the algebraic numbers alpha corresponding to the columns of the matrix
3773       "matalpha", expressed on the integral basis.
3774
3775       Note that all the components are exact (integral or rational), except
3776       for the roots in "v[5]". Note also that member functions will
3777       \emph{not} work on sbnf, you have to use "bnfmake" explicitly first.
3778
3779       The library syntax is bnfinit0"(P,flag,tech,prec)".
3780
3781   bnfisintnorm"(bnf,x)"
3782       computes a complete system of solutions (modulo units of positive norm)
3783       of the absolute norm equation "\Norm(a) = x", where "a" is an integer
3784       in "bnf". If "bnf" has not been certified, the correctness of the
3785       result depends on the validity of GRH.
3786
3787       See also "bnfisnorm".
3788
3789       The library syntax is bnfisintnorm"(bnf,x)".
3790
3791   bnfisnorm"(bnf,x,{flag = 1})"
3792       tries to tell whether the rational number "x" is the norm of some
3793       element y in "bnf". Returns a vector "[a,b]" where "x = Norm(a)*b".
3794       Looks for a solution which is an "S"-unit, with "S" a certain set of
3795       prime ideals containing (among others) all primes dividing "x". If
3796       "bnf" is known to be Galois, set "flag = 0" (in this case, "x" is a
3797       norm iff "b = 1"). If "flag" is non zero the program adds to "S" the
3798       following prime ideals, depending on the sign of "flag". If "flag > 0",
3799       the ideals of norm less than "flag". And if "flag < 0" the ideals
3800       dividing "flag".
3801
3802       Assuming GRH, the answer is guaranteed (i.e. "x" is a norm iff "b =
3803       1"), if "S" contains all primes less than "12 log (\disc(Bnf))^2",
3804       where "Bnf" is the Galois closure of "bnf".
3805
3806       See also "bnfisintnorm".
3807
3808       The library syntax is bnfisnorm"(bnf,x,flag,prec)", where "flag" and
3809       "prec" are "long"s.
3810
3811   bnfissunit"(bnf,sfu,x)"
3812       "bnf" being output by "bnfinit", sfu by "bnfsunit", gives the column
3813       vector of exponents of "x" on the fundamental "S"-units and the roots
3814       of unity.  If "x" is not a unit, outputs an empty vector.
3815
3816       The library syntax is bnfissunit"(bnf,sfu,x)".
3817
3818   bnfisprincipal"(bnf,x,{flag = 1})"
3819       "bnf" being the number field data output by "bnfinit", and "x" being
3820       either a Z-basis of an ideal in the number field (not necessarily in
3821       HNF) or a prime ideal in the format output by the function
3822       "idealprimedec", this function tests whether the ideal is principal or
3823       not. The result is more complete than a simple true/false answer: it
3824       gives a row vector "[v_1,v_2]", where
3825
3826       "v_1" is the vector of components "c_i" of the class of the ideal "x"
3827       in the class group, expressed on the generators "g_i" given by
3828       "bnfinit" (specifically "bnf.gen"). The "c_i" are chosen so that "0 <=
3829       c_i < n_i" where "n_i" is the order of "g_i" (the vector of "n_i" being
3830       "bnf.cyc").
3831
3832       "v_2" gives on the integral basis the components of "alpha" such that
3833       "x = alphaprod_ig_i^{c_i}". In particular, "x" is principal if and only
3834       if "v_1" is equal to the zero vector. In the latter case, "x =
3835       alphaZ_K" where "alpha" is given by "v_2". Note that if "alpha" is too
3836       large to be given, a warning message will be printed and "v_2" will be
3837       set equal to the empty vector.
3838
3839       If "flag = 0", outputs only "v_1", which is much easier to compute.
3840
3841       If "flag = 2", does as if "flag" were 0, but doubles the precision
3842       until a result is obtained.
3843
3844       If "flag = 3", as in the default behaviour ("flag = 1"), but doubles
3845       the precision until a result is obtained.
3846
3847       The user is warned that these two last setting may induce \emph{very}
3848       lengthy computations.
3849
3850       The library syntax is isprincipalall"(bnf,x,flag)".
3851
3852   bnfisunit"(bnf,x)"
3853       "bnf" being the number field data output by "bnfinit" and "x" being an
3854       algebraic number (type integer, rational or polmod), this outputs the
3855       decomposition of "x" on the fundamental units and the roots of unity if
3856       "x" is a unit, the empty vector otherwise.  More precisely, if
3857       "u_1",...,"u_r" are the fundamental units, and "zeta" is the generator
3858       of the group of roots of unity ("bnf.tu"), the output is a vector
3859       "[x_1,...,x_r,x_{r+1}]" such that "x = u_1^{x_1}...
3860       u_r^{x_r}.zeta^{x_{r+1}}". The "x_i" are integers for "i <= r" and is
3861       an integer modulo the order of "zeta" for "i = r+1".
3862
3863       The library syntax is isunit"(bnf,x)".
3864
3865   bnfmake"(sbnf)"
3866       sbnf being a ``small "bnf"'' as output by "bnfinit""(x,3)", computes
3867       the complete "bnfinit" information. The result is \emph{not} identical
3868       to what "bnfinit" would yield, but is functionally identical. The
3869       execution time is very small compared to a complete "bnfinit". Note
3870       that if the default precision in "gp" (or "prec" in library mode) is
3871       greater than the precision of the roots "sbnf[5]", these are recomputed
3872       so as to get a result with greater accuracy.
3873
3874       Note that the member functions are \emph{not} available for sbnf, you
3875       have to use "bnfmake" explicitly first.
3876
3877       The library syntax is makebigbnf"(sbnf,prec)", where "prec" is a C long
3878       integer.
3879
3880   bnfnarrow"(bnf)"
3881       "bnf" being as output by "bnfinit", computes the narrow class group of
3882       "bnf". The output is a 3-component row vector "v" analogous to the
3883       corresponding class group component "bnf.clgp" ("bnf[8][1]"): the first
3884       component is the narrow class number "v.no", the second component is a
3885       vector containing the SNF cyclic components "v.cyc" of the narrow class
3886       group, and the third is a vector giving the generators of the
3887       corresponding "v.gen" cyclic groups. Note that this function is a
3888       special case of "bnrinit".
3889
3890       The library syntax is buchnarrow"(bnf)".
3891
3892   bnfsignunit"(bnf)"
3893       "bnf" being as output by "bnfinit", this computes an "r_1 x
3894       (r_1+r_2-1)" matrix having "+-1" components, giving the signs of the
3895       real embeddings of the fundamental units.  The following functions
3896       compute generators for the totally positive units:
3897
3898         /* exponents of totally positive units generators on bnf.tufu */
3899         tpuexpo(bnf)=
3900         { local(S,d,K);
3901
3902           S = bnfsignunit(bnf); d = matsize(S);
3903           S = matrix(d[1],d[2], i,j, if (S[i,j] < 0, 1,0));
3904           S = concat(vectorv(d[1],i,1), S);   \\ add sign(-1)
3905           K = lift(matker(S * Mod(1,2)));
3906           if (K, mathnfmodid(K, 2), 2*matid(d[1]))
3907         }
3908
3909         /* totally positive units */
3910         tpu(bnf)=
3911         { local(vu = bnf.tufu, ex = tpuexpo(bnf));
3912
3913           vector(#ex-1, i, factorback(vu, ex[,i+1]))  \\ ex[,1] is 1
3914         }
3915
3916       The library syntax is signunits"(bnf)".
3917
3918   bnfreg"(bnf)"
3919       "bnf" being as output by "bnfinit", computes its regulator.
3920
3921       The library syntax is regulator"(bnf,tech,prec)", where tech is as in
3922       "bnfinit".
3923
3924   bnfsunit"(bnf,S)"
3925       computes the fundamental "S"-units of the number field "bnf" (output by
3926       "bnfinit"), where "S" is a list of prime ideals (output by
3927       "idealprimedec"). The output is a vector "v" with 6 components.
3928
3929       "v[1]" gives a minimal system of (integral) generators of the "S"-unit
3930       group modulo the unit group.
3931
3932       "v[2]" contains technical data needed by "bnfissunit".
3933
3934       "v[3]" is an empty vector (used to give the logarithmic embeddings of
3935       the generators in "v[1]" in version 2.0.16).
3936
3937       "v[4]" is the "S"-regulator (this is the product of the regulator, the
3938       determinant of "v[2]" and the natural logarithms of the norms of the
3939       ideals in "S").
3940
3941       "v[5]" gives the "S"-class group structure, in the usual format (a row
3942       vector whose three components give in order the "S"-class number, the
3943       cyclic components and the generators).
3944
3945       "v[6]" is a copy of "S".
3946
3947       The library syntax is bnfsunit"(bnf,S,prec)".
3948
3949   bnfunit"(bnf)"
3950       "bnf" being as output by "bnfinit", outputs the vector of fundamental
3951       units of the number field.
3952
3953       This function is mostly useless, since it will only succeed if bnf
3954       contains the units, in which case "bnf.fu" is recommanded instead, or
3955       bnf was produced with "bnfinit(,,2)", which is itself deprecated.
3956
3957       The library syntax is buchfu"(bnf)".
3958
3959   bnrL1"(bnr,{subgroup},{flag = 0})"
3960       bnr being the number field data which is output by "bnrinit(,,1)" and
3961       subgroup being a square matrix defining a congruence subgroup of the
3962       ray class group corresponding to bnr (the trivial congruence subgroup
3963       if omitted), returns for each character "chi" of the ray class group
3964       which is trivial on this subgroup, the value at "s = 1" (or "s = 0") of
3965       the abelian "L"-function associated to "chi". For the value at "s = 0",
3966       the function returns in fact for each character "chi" a vector "[r_chi
3967       , c_chi]" where "r_chi" is the order of "L(s, chi)" at "s = 0" and
3968       "c_chi" the first non-zero term in the expansion of "L(s, chi)" at "s =
3969       0"; in other words
3970
3971         "L(s, chi) = c_chi.s^{r_chi} + O(s^{r_chi + 1})"
3972
3973       near 0. flag is optional, default value is 0; its binary digits mean 1:
3974       compute at "s = 1" if set to 1 or "s = 0" if set to 0, 2: compute the
3975       primitive "L"-functions associated to "chi" if set to 0 or the
3976       "L"-function with Euler factors at prime ideals dividing the modulus of
3977       bnr removed if set to 1 (this is the so-called "L_S(s, chi)" function
3978       where "S" is the set of infinite places of the number field together
3979       with the finite prime ideals dividing the modulus of bnr, see the
3980       example below), 3: returns also the character. Example:
3981
3982         bnf = bnfinit(x^2 - 229);
3983         bnr = bnrinit(bnf,1,1);
3984         bnrL1(bnr)
3985
3986       returns the order and the first non-zero term of the abelian
3987       "L"-functions "L(s, chi)" at "s = 0" where "chi" runs through the
3988       characters of the class group of "Q( sqrt {229})". Then
3989
3990         bnr2 = bnrinit(bnf,2,1);
3991         bnrL1(bnr2,,2)
3992
3993       returns the order and the first non-zero terms of the abelian
3994       "L"-functions "L_S(s, chi)" at "s = 0" where "chi" runs through the
3995       characters of the class group of "Q( sqrt {229})" and "S" is the set of
3996       infinite places of "Q( sqrt {229})" together with the finite prime 2.
3997       Note that the ray class group modulo 2 is in fact the class group, so
3998       "bnrL1(bnr2,0)" returns exactly the same answer as "bnrL1(bnr,0)".
3999
4000       The library syntax is bnrL1"(bnr,subgroup,flag,prec)", where an omitted
4001       subgroup is coded as "NULL".
4002
4003   bnrclass"(bnf,ideal,{flag = 0})"
4004       \emph{this function is DEPRECATED, use "bnrinit"}.
4005
4006       "bnf" being as output by "bnfinit" (the units are mandatory unless the
4007       ideal is trivial), and ideal being a modulus, computes the ray class
4008       group of the number field for the modulus ideal, as a finite abelian
4009       group.
4010
4011       The library syntax is bnrclass0"(bnf,ideal,flag)".
4012
4013   bnrclassno"(bnf,I)"
4014       "bnf" being as output by "bnfinit" (units are mandatory unless the
4015       ideal is trivial), and "I" being a modulus, computes the ray class
4016       number of the number field for the modulus "I". This is faster than
4017       "bnrinit" and should be used if only the ray class number is desired.
4018       See "bnrclassnolist" if you need ray class numbers for all moduli less
4019       than some bound.
4020
4021       The library syntax is bnrclassno"(bnf,I)".
4022
4023   bnrclassnolist"(bnf,list)"
4024       "bnf" being as output by "bnfinit", and list being a list of moduli
4025       (with units) as output by "ideallist" or "ideallistarch", outputs the
4026       list of the class numbers of the corresponding ray class groups. To
4027       compute a single class number, "bnrclassno" is more efficient.
4028
4029         ? bnf = bnfinit(x^2 - 2);
4030         ? L = ideallist(bnf, 100, 2);
4031         ? H = bnrclassnolist(bnf, L);
4032         ? H[98]
4033         %4 = [1, 3, 1]
4034         ? l = L[1][98]; ids = vector(#l, i, l[i].mod[1])
4035         %5 = [[98, 88; 0, 1], [14, 0; 0, 7], [98, 10; 0, 1]]
4036
4037       The weird "l[i].mod[1]", is the first component of "l[i].mod", i.e.
4038       the finite part of the conductor. (This is cosmetic: since by
4039       construction the archimedean part is trivial, I do not want to see it).
4040       This tells us that the ray class groups modulo the ideals of norm 98
4041       (printed as %5) have respectively order 1, 3 and 1. Indeed, we may
4042       check directly :
4043
4044         ? bnrclassno(bnf, ids[2])
4045         %6 = 3
4046
4047       The library syntax is bnrclassnolist"(bnf,list)".
4048
4049   bnrconductor"(a_1,{a_2},{a_3}, {flag = 0})"
4050       conductor "f" of the subfield of a ray class field as defined by
4051       "[a_1,a_2,a_3]" (see "bnr" at the beginning of this section).
4052
4053       If "flag = 0", returns "f".
4054
4055       If "flag = 1", returns "[f, Cl_f, H]", where "Cl_f" is the ray class
4056       group modulo "f", as a finite abelian group; finally "H" is the
4057       subgroup of "Cl_f" defining the extension.
4058
4059       If "flag = 2", returns "[f, bnr(f), H]", as above except "Cl_f" is
4060       replaced by a "bnr" structure, as output by "bnrinit(,f,1)".
4061
4062       The library syntax is conductor"(bnr, subgroup, flag)", where an
4063       omitted subgroup (trivial subgroup, i.e. ray class field) is input as
4064       "NULL", and "flag" is a C long.
4065
4066   bnrconductorofchar"(bnr,chi)"
4067       bnr being a big ray number field as output by "bnrinit", and chi being
4068       a row vector representing a character as expressed on the generators of
4069       the ray class group, gives the conductor of this character as a
4070       modulus.
4071
4072       The library syntax is bnrconductorofchar"(bnr,chi)".
4073
4074   bnrdisc"(a1,{a2},{a3},{flag = 0})"
4075       "a1", "a2", "a3" defining a big ray number field "L" over a ground
4076       field "K" (see "bnr" at the beginning of this section for the meaning
4077       of "a1", "a2", "a3"), outputs a 3-component row vector "[N,R_1,D]",
4078       where "N" is the (absolute) degree of "L", "R_1" the number of real
4079       places of "L", and "D" the discriminant of "L/Q", including sign (if
4080       "flag = 0").
4081
4082       If "flag = 1", as above but outputs relative data. "N" is now the
4083       degree of "L/K", "R_1" is the number of real places of "K" unramified
4084       in "L" (so that the number of real places of "L" is equal to "R_1"
4085       times the relative degree "N"), and "D" is the relative discriminant
4086       ideal of "L/K".
4087
4088       If "flag = 2", as the default case, except that if the modulus is not
4089       the exact conductor corresponding to the "L", no data is computed and
4090       the result is 0.
4091
4092       If "flag = 3", as case 2, but output relative data.
4093
4094       The library syntax is bnrdisc0"(a1,a2,a3,flag)".
4095
4096   bnrdisclist"(bnf,bound,{arch})"
4097       "bnf" being as output by "bnfinit" (with units), computes a list of
4098       discriminants of Abelian extensions of the number field by increasing
4099       modulus norm up to bound bound. The ramified Archimedean places are
4100       given by arch; all possible values are taken if arch is omitted.
4101
4102       The alternative syntax "bnrdisclist(bnf,list)" is supported, where list
4103       is as output by "ideallist" or "ideallistarch" (with units), in which
4104       case arch is disregarded.
4105
4106       The output "v" is a vector of vectors, where "v[i][j]" is understood to
4107       be in fact "V[2^{15}(i-1)+j]" of a unique big vector "V". (This akward
4108       scheme allows for larger vectors than could be otherwise represented.)
4109
4110       "V[k]" is itself a vector "W", whose length is the number of ideals of
4111       norm "k". We consider first the case where arch was specified. Each
4112       component of "W" corresponds to an ideal "m" of norm "k", and gives
4113       invariants associated to the ray class field "L" of "bnf" of conductor
4114       "[m, arch]". Namely, each contains a vector "[m,d,r,D]" with the
4115       following meaning: "m" is the prime ideal factorization of the modulus,
4116       "d = [L:Q]" is the absolute degree of "L", "r" is the number of real
4117       places of "L", and "D" is the factorization of its absolute
4118       discriminant. We set "d = r = D = 0" if "m" is not the finite part of a
4119       conductor.
4120
4121       If arch was omitted, all "t = 2^{r_1}" possible values are taken and a
4122       component of "W" has the form "[m, [[d_1,r_1,D_1],...,
4123       [d_t,r_t,D_t]]]", where "m" is the finite part of the conductor as
4124       above, and "[d_i,r_i,D_i]" are the invariants of the ray class field of
4125       conductor "[m,v_i]", where "v_i" is the "i"-th archimedean component,
4126       ordered by inverse lexicographic order; so "v_1 = [0,...,0]", "v_2 =
4127       [1,0...,0]", etc. Again, we set "d_i = r_i = D_i = 0" if "[m,v_i]" is
4128       not a conductor.
4129
4130       Finally, each prime ideal "pr = [p,alpha,e,f,beta]" in the prime
4131       factorization "m" is coded as the integer "p.n^2+(f-1).n+(j-1)", where
4132       "n" is the degree of the base field and "j" is such that
4133
4134       "pr = idealprimedec(nf,p)[j]".
4135
4136       "m" can be decoded using "bnfdecodemodule".
4137
4138       Note that to compute such data for a single field, either "bnrclassno"
4139       or "bnrdisc" is more efficient.
4140
4141       The library syntax is bnrdisclist0"(bnf,bound,arch)".
4142
4143   bnrinit"(bnf,f,{flag = 0})"
4144       "bnf" is as output by "bnfinit", "f" is a modulus, initializes data
4145       linked to the ray class group structure corresponding to this module, a
4146       so-called bnr structure. The following member functions are available
4147       on the result: ".bnf" is the underlying bnf, ".mod" the modulus, ".bid"
4148       the bid structure associated to the modulus; finally, ".clgp", ".no",
4149       ".cyc", "clgp" refer to the ray class group (as a finite abelian
4150       group), its cardinality, its elementary divisors, its generators.
4151
4152       The last group of functions are different from the members of the
4153       underlying bnf, which refer to the class group; use "bnr.bnf.xxx" to
4154       access these, e.g. "bnr.bnf.cyc" to get the cyclic decomposition of the
4155       class group.
4156
4157       They are also different from the members of the underlying bid, which
4158       refer to "(\O_K/f)^*"; use "bnr.bid.xxx" to access these,
4159       e.g. "bnr.bid.no" to get "phi(f)".
4160
4161       If "flag = 0" (default), the generators of the ray class group are not
4162       computed, which saves time. Hence "bnr.gen" would produce an error.
4163
4164       If "flag = 1", as the default, except that generators are computed.
4165
4166       The library syntax is bnrinit0"(bnf,f,flag)".
4167
4168   bnrisconductor"(a1,{a2},{a3})"
4169       "a1", "a2", "a3" represent an extension of the base field, given by
4170       class field theory for some modulus encoded in the parameters. Outputs
4171       1 if this modulus is the conductor, and 0 otherwise. This is slightly
4172       faster than "bnrconductor".
4173
4174       The library syntax is bnrisconductor"(a1,a2,a3)" and the result is a
4175       "long".
4176
4177   bnrisprincipal"(bnr,x,{flag = 1})"
4178       bnr being the number field data which is output by "bnrinit""(,,1)" and
4179       "x" being an ideal in any form, outputs the components of "x" on the
4180       ray class group generators in a way similar to "bnfisprincipal". That
4181       is a 2-component vector "v" where "v[1]" is the vector of components of
4182       "x" on the ray class group generators, "v[2]" gives on the integral
4183       basis an element "alpha" such that "x = alphaprod_ig_i^{x_i}".
4184
4185       If "flag = 0", outputs only "v_1". In that case, bnr need not contain
4186       the ray class group generators, i.e. it may be created with
4187       "bnrinit""(,,0)"
4188
4189       The library syntax is bnrisprincipal"(bnr,x,flag)".
4190
4191   bnrrootnumber"(bnr,chi,{flag = 0})"
4192       if "chi = chi" is a (not necessarily primitive) character over bnr, let
4193       "L(s,chi) = sum_{id} chi(id) N(id)^{-s}" be the associated Artin
4194       L-function. Returns the so-called Artin root number, i.e. the complex
4195       number "W(chi)" of modulus 1 such that
4196
4197         "Lambda(1-s,chi) = W(chi) Lambda(s,\overline{chi})"
4198
4199       where "Lambda(s,chi) = A(chi)^{s/2}gamma_chi(s) L(s,chi)" is the
4200       enlarged L-function associated to "L".
4201
4202       The generators of the ray class group are needed, and you can set "flag
4203       = 1" if the character is known to be primitive. Example:
4204
4205         bnf = bnfinit(x^2 - 145);
4206         bnr = bnrinit(bnf,7,1);
4207         bnrrootnumber(bnr, [5])
4208
4209       returns the root number of the character "chi" of "\Cl_7(Q( sqrt
4210       {145}))" such that "chi(g) = zeta^5", where "g" is the generator of the
4211       ray-class field and "zeta = e^{2iPi/N}" where "N" is the order of "g"
4212       ("N = 12" as "bnr.cyc" readily tells us).
4213
4214       The library syntax is bnrrootnumber"(bnf,chi,flag)"
4215
4216   bnrstark"{(bnr,{subgroup})}"
4217       bnr being as output by "bnrinit(,,1)", finds a relative equation for
4218       the class field corresponding to the modulus in bnr and the given
4219       congruence subgroup (as usual, omit "subgroup" if you want the whole
4220       ray class group).
4221
4222       The routine uses Stark units and needs to find a suitable auxilliary
4223       conductor, which may not exist when the class field is not cyclic over
4224       the base. In this case "bnrstark" is allowed to return a vector of
4225       polynomials defining \emph{independent} relative extensions, whose
4226       compositum is the requested class field. It was decided that it was
4227       more useful to keep the extra information thus made available, hence
4228       the user has to take the compositum herself.
4229
4230       The main variable of bnr must not be "x", and the ground field and the
4231       class field must be totally real. When the base field is Q, the vastly
4232       simpler "galoissubcyclo" is used instead. Here is an example:
4233
4234         bnf = bnfinit(y^2 - 3);
4235         bnr = bnrinit(bnf, 5, 1);
4236         pol = bnrstark(bnr)
4237
4238       returns the ray class field of "Q( sqrt {3})" modulo 5. Usually, one
4239       wants to apply to the result one of
4240
4241         rnfpolredabs(bnf, pol, 16 + 2) \\ compute a reduced relative polynomial
4242         rnfpolredabs(bnf, pol, 16 + 2) \\ compute a reduced absolute polynomial
4243
4244       The library syntax is bnrstark"(bnr,subgroup)", where an omitted
4245       subgroup is coded by "NULL".
4246
4247   dirzetak"(nf,b)"
4248       gives as a vector the first "b" coefficients of the Dedekind zeta
4249       function of the number field "nf" considered as a Dirichlet series.
4250
4251       The library syntax is dirzetak"(nf,b)".
4252
4253   factornf"(x,t)"
4254       factorization of the univariate polynomial "x" over the number field
4255       defined by the (univariate) polynomial "t". "x" may have coefficients
4256       in Q or in the number field. The algorithm reduces to factorization
4257       over Q (Trager's trick). The direct approach of "nffactor", which uses
4258       van Hoeij's method in a relative setting, is in general faster.
4259
4260       The main variable of "t" must be of \emph{lower} priority than that of
4261       "x" (see "Label se:priority"). However if non-rational number field
4262       elements occur (as polmods or polynomials) as coefficients of "x", the
4263       variable of these polmods \emph{must} be the same as the main variable
4264       of "t". For example
4265
4266         ? factornf(x^2 + Mod(y, y^2+1), y^2+1);
4267         ? factornf(x^2 + y, y^2+1); \\ these two are OK
4268         ? factornf(x^2 + Mod(z,z^2+1), y^2+1)
4269           *** factornf: inconsistent data in rnf function.
4270         ? factornf(x^2 + z, y^2+1)
4271           *** factornf: incorrect variable in rnf function.
4272
4273       The library syntax is polfnf"(x,t)".
4274
4275   galoisexport"(gal,{flag = 0})"
4276       gal being be a Galois field as output by "galoisinit", export the
4277       underlying permutation group as a string suitable for (no flags or
4278       "flag = 0") GAP or ("flag = 1") Magma. The following example compute
4279       the index of the underlying abstract group in the GAP library:
4280
4281         ? G = galoisinit(x^6+108);
4282         ? s = galoisexport(G)
4283         %2 = "Group((1, 2, 3)(4, 5, 6), (1, 4)(2, 6)(3, 5))"
4284         ? extern("echo \"IdGroup("s");\" | gap -q")
4285         %3 = [6, 1]
4286         ? galoisidentify(G)
4287         %4 = [6, 1]
4288
4289       This command also accepts subgroups returned by "galoissubgroups".
4290
4291       The library syntax is galoisexport"(gal,flag)".
4292
4293   galoisfixedfield"(gal,perm,{flag = 0},{v = y}))"
4294       gal being be a Galois field as output by "galoisinit" and perm an
4295       element of "gal.group" or a vector of such elements, computes the fixed
4296       field of gal by the automorphism defined by the permutations perm of
4297       the roots "gal.roots". "P" is guaranteed to be squarefree modulo
4298       "gal.p".
4299
4300       If no flags or "flag = 0", output format is the same as for
4301       "nfsubfield", returning "[P,x]" such that "P" is a polynomial defining
4302       the fixed field, and "x" is a root of "P" expressed as a polmod in
4303       "gal.pol".
4304
4305       If "flag = 1" return only the polynomial "P".
4306
4307       If "flag = 2" return "[P,x,F]" where "P" and "x" are as above and "F"
4308       is the factorization of "gal.pol" over the field defined by "P", where
4309       variable "v" ("y" by default) stands for a root of "P". The priority of
4310       "v" must be less than the priority of the variable of "gal.pol" (see
4311       "Label se:priority"). Example:
4312
4313         ? G = galoisinit(x^4+1);
4314         ? galoisfixedfield(G,G.group[2],2)
4315         %2 = [x^2 + 2, Mod(x^3 + x, x^4 + 1), [x^2 - y*x - 1, x^2 + y*x - 1]]
4316
4317       computes the factorization  "x^4+1 = (x^2- sqrt {-2}x-1)(x^2+ sqrt
4318       {-2}x-1)"
4319
4320       The library syntax is galoisfixedfield"(gal,perm,flag,"v")", where "v"
4321       is a variable number, an omitted "v" being coded by "-1".
4322
4323   galoisidentify"(gal)"
4324       gal being be a Galois field as output by "galoisinit", output the
4325       isomorphism class of the underlying abstract group as a two-components
4326       vector "[o,i]", where "o" is the group order, and "i" is the group
4327       index in the GAP4 Small Group library, by Hans Ulrich Besche, Bettina
4328       Eick and Eamonn O'Brien.
4329
4330       This command also accepts subgroups returned by "galoissubgroups".
4331
4332       The current implementation is limited to degree less or equal to 127.
4333       Some larger ``easy'' orders are also supported.
4334
4335       The output is similar to the output of the function "IdGroup" in GAP4.
4336       Note that GAP4 "IdGroup" handles all groups of order less than 2000
4337       except 1024, so you can use "galoisexport" and GAP4 to identify large
4338       Galois groups.
4339
4340       The library syntax is galoisidentify"(gal)".
4341
4342   galoisinit"(pol,{den})"
4343       computes the Galois group and all necessary information for computing
4344       the fixed fields of the Galois extension "K/Q" where "K" is the number
4345       field defined by "pol" (monic irreducible polynomial in "Z[X]" or a
4346       number field as output by "nfinit"). The extension "K/Q" must be Galois
4347       with Galois group ``weakly'' super-solvable (see "nfgaloisconj")
4348
4349       This is a prerequisite for most of the "galois""xxx" routines. For
4350       instance:
4351
4352           P = x^6 + 108;
4353           G = galoisinit(P);
4354           L = galoissubgroups(G);
4355           vector(#L, i, galoisisabelian(L[i],1))
4356           vector(#L, i, galoisidentify(L[i]))
4357
4358       The output is an 8-component vector gal.
4359
4360       "gal[1]" contains the polynomial pol ("gal.pol").
4361
4362       "gal[2]" is a three-components vector "[p,e,q]" where "p" is a prime
4363       number ("gal.p") such that pol totally split modulo "p" , "e" is an
4364       integer and "q = p^e" ("gal.mod") is the modulus of the roots in
4365       "gal.roots".
4366
4367       "gal[3]" is a vector "L" containing the "p"-adic roots of pol as
4368       integers implicitly modulo "gal.mod".  ("gal.roots").
4369
4370       "gal[4]" is the inverse of the Van der Monde matrix of the "p"-adic
4371       roots of pol, multiplied by "gal[5]".
4372
4373       "gal[5]" is a multiple of the least common denominator of the
4374       automorphisms expressed as polynomial in a root of pol.
4375
4376       "gal[6]" is the Galois group "G" expressed as a vector of permutations
4377       of "L" ("gal.group").
4378
4379       "gal[7]" is a generating subset "S = [s_1,...,s_g]" of "G" expressed as
4380       a vector of permutations of "L" ("gal.gen").
4381
4382       "gal[8]" contains the relative orders "[o_1,...,o_g]" of the generators
4383       of "S" ("gal.orders").
4384
4385       Let "H" be the maximal normal supersolvable subgroup of "G", we have
4386       the following properties:
4387
4388         \item if "G/H ~  A_4" then "[o_1,...,o_g]" ends by "[2,2,3]".
4389
4390         \item if "G/H ~  S_4" then "[o_1,...,o_g]" ends by "[2,2,3,2]".
4391
4392         \item else "G" is super-solvable.
4393
4394         \item for "1 <= i <= g" the subgroup of "G" generated by
4395       "[s_1,...,s_g]" is normal, with the exception of "i = g-2" in the
4396       second case and of "i = g-3" in the third.
4397
4398         \item the relative order "o_i" of "s_i" is its order in the quotient
4399       group "G/<s_1,...,s_{i-1}>", with the same exceptions.
4400
4401         \item for any "x belongs to G" there exists a unique family
4402       "[e_1,...,e_g]" such that (no exceptions):
4403
4404       -- for "1 <= i <= g" we have "0 <= e_i < o_i"
4405
4406       -- "x = g_1^{e_1}g_2^{e_2}...g_n^{e_n}"
4407
4408       If present "den" must be a suitable value for "gal[5]".
4409
4410       The library syntax is galoisinit"(gal,den)".
4411
4412   galoisisabelian"(gal,{fl = 0})"
4413       gal being as output by "galoisinit", return 0 if gal is not an abelian
4414       group, and the HNF matrix of gal over "gal.gen" if "fl = 0", 1 if "fl =
4415       1".
4416
4417       This command also accepts subgroups returned by "galoissubgroups".
4418
4419       The library syntax is galoisisabelian"(gal,fl)" where fl is a C long
4420       integer.
4421
4422   galoispermtopol"(gal,perm)"
4423       gal being a Galois field as output by "galoisinit" and perm a element
4424       of "gal.group", return the polynomial defining the Galois automorphism,
4425       as output by "nfgaloisconj", associated with the permutation perm of
4426       the roots "gal.roots". perm can also be a vector or matrix, in this
4427       case, "galoispermtopol" is applied to all components recursively.
4428
4429       Note that
4430
4431         G = galoisinit(pol);
4432         galoispermtopol(G, G[6])~
4433
4434       is equivalent to "nfgaloisconj(pol)", if degree of pol is greater or
4435       equal to 2.
4436
4437       The library syntax is galoispermtopol"(gal,perm)".
4438
4439   galoissubcyclo"(N,H,{fl = 0},{v})"
4440       computes the subextension of "Q(zeta_n)" fixed by the subgroup "H
4441       \subset (Z/nZ)^*". By the Kronecker-Weber theorem, all abelian number
4442       fields can be generated in this way (uniquely if "n" is taken to be
4443       minimal).
4444
4445       The pair "(n, H)" is deduced from the parameters "(N, H)" as follows
4446
4447       \item "N" an integer: then "n = N"; "H" is a generator, i.e. an integer
4448       or an integer modulo "n"; or a vector of generators.
4449
4450       \item "N" the output of znstar(n). "H" as in the first case above, or a
4451       matrix, taken to be a HNF left divisor of the SNF for "(Z/nZ)^*" (of
4452       type "N.cyc"), giving the generators of "H" in terms of "N.gen".
4453
4454       \item "N" the output of "bnrinit(bnfinit(y), m, 1)" where "m" is a
4455       module. "H" as in the first case, or a matrix taken to be a HNF left
4456       divisor of the SNF for the ray class group modulo "m" (of type
4457       "N.cyc"), giving the generators of "H" in terms of "N.gen".
4458
4459       In this last case, beware that "H" is understood relatively to "N"; in
4460       particular, if the infinite place does not divide the module, e.g if
4461       "m" is an integer, then it is not a subgroup of "(Z/nZ)^*", but of its
4462       quotient by "{+- 1}".
4463
4464       If "fl = 0", compute a polynomial (in the variable v) defining the the
4465       subfield of "Q(zeta_n)" fixed by the subgroup H of "(Z/nZ)^*".
4466
4467       If "fl = 1", compute only the conductor of the abelian extension, as a
4468       module.
4469
4470       If "fl = 2", output "[pol, N]", where "pol" is the polynomial as output
4471       when "fl = 0" and "N" the conductor as output when "fl = 1".
4472
4473       The following function can be used to compute all subfields of
4474       "Q(zeta_n)" (of exact degree "d", if "d" is set):
4475
4476         subcyclo(n, d = -1)=
4477         {
4478           local(bnr,L,IndexBound);
4479           IndexBound = if (d < 0, n, [d]);
4480           bnr = bnrinit(bnfinit(y), [n,[1]], 1);
4481           L = subgrouplist(bnr, IndexBound, 1);
4482           vector(#L,i, galoissubcyclo(bnr,L[i]));
4483         }
4484
4485       Setting "L = subgrouplist(bnr, IndexBound)" would produce subfields of
4486       exact conductor "n oo ".
4487
4488       The library syntax is galoissubcyclo"(N,H,fl,v)" where fl is a C long
4489       integer, and v a variable number.
4490
4491   galoissubfields"(G,{fl = 0},{v})"
4492       Output all the subfields of the Galois group G, as a vector.  This
4493       works by applying "galoisfixedfield" to all subgroups. The meaning of
4494       the flag fl is the same as for "galoisfixedfield".
4495
4496       The library syntax is galoissubfields"(G,fl,v)", where fl is a long and
4497       v a variable number.
4498
4499   galoissubgroups"(gal)"
4500       Output all the subgroups of the Galois group "gal". A subgroup is a
4501       vector [gen, orders], with the same meaning as for "gal.gen" and
4502       "gal.orders". Hence gen is a vector of permutations generating the
4503       subgroup, and orders is the relatives orders of the generators. The
4504       cardinal of a subgroup is the product of the relative orders. Such
4505       subgroup can be used instead of a Galois group in the following
4506       command: "galoisisabelian", "galoissubgroups", "galoisexport" and
4507       "galoisidentify".
4508
4509       To get the subfield fixed by a subgroup sub of gal, use
4510
4511         galoisfixedfield(gal,sub[1])
4512
4513       The library syntax is galoissubgroups"(gal)".
4514
4515   idealadd"(nf,x,y)"
4516       sum of the two ideals "x" and "y" in the number field "nf". When "x"
4517       and "y" are given by Z-bases, this does not depend on "nf" and can be
4518       used to compute the sum of any two Z-modules. The result is given in
4519       HNF.
4520
4521       The library syntax is idealadd"(nf,x,y)".
4522
4523   idealaddtoone"(nf,x,{y})"
4524       "x" and "y" being two co-prime integral ideals (given in any form),
4525       this gives a two-component row vector "[a,b]" such that "a belongs to
4526       x", "b belongs to y" and "a+b = 1".
4527
4528       The alternative syntax "idealaddtoone(nf,v)", is supported, where "v"
4529       is a "k"-component vector of ideals (given in any form) which sum to
4530       "Z_K". This outputs a "k"-component vector "e" such that "e[i] belongs
4531       to x[i]" for "1 <= i <= k" and "sum_{1 <= i <= k}e[i] = 1".
4532
4533       The library syntax is idealaddtoone0"(nf,x,y)", where an omitted "y" is
4534       coded as "NULL".
4535
4536   idealappr"(nf,x,{flag = 0})"
4537       if "x" is a fractional ideal (given in any form), gives an element
4538       "alpha" in "nf" such that for all prime ideals " wp " such that the
4539       valuation of "x" at " wp " is non-zero, we have "v_{ wp }(alpha) = v_{
4540       wp }(x)", and. "v_{ wp }(alpha) >= 0" for all other "{ wp }".
4541
4542       If "flag" is non-zero, "x" must be given as a prime ideal
4543       factorization, as output by "idealfactor", but possibly with zero or
4544       negative exponents.  This yields an element "alpha" such that for all
4545       prime ideals " wp " occurring in "x", "v_{ wp }(alpha)" is equal to the
4546       exponent of " wp " in "x", and for all other prime ideals, "v_{ wp
4547       }(alpha) >= 0". This generalizes "idealappr(nf,x,0)" since zero
4548       exponents are allowed. Note that the algorithm used is slightly
4549       different, so that "idealappr(nf,idealfactor(nf,x))" may not be the
4550       same as "idealappr(nf,x,1)".
4551
4552       The library syntax is idealappr0"(nf,x,flag)".
4553
4554   idealchinese"(nf,x,y)"
4555       "x" being a prime ideal factorization (i.e. a 2 by 2 matrix whose first
4556       column contain prime ideals, and the second column integral exponents),
4557       "y" a vector of elements in "nf" indexed by the ideals in "x", computes
4558       an element "b" such that
4559
4560       "v_ wp (b - y_ wp ) >= v_ wp (x)" for all prime ideals in "x" and "v_
4561       wp (b) >= 0" for all other " wp ".
4562
4563       The library syntax is idealchinese"(nf,x,y)".
4564
4565   idealcoprime"(nf,x,y)"
4566       given two integral ideals "x" and "y" in the number field "nf", finds a
4567       "beta" in the field, expressed on the integral basis "nf[7]", such that
4568       "beta.x" is an integral ideal coprime to "y".
4569
4570       The library syntax is idealcoprime"(nf,x,y)".
4571
4572   idealdiv"(nf,x,y,{flag = 0})"
4573       quotient "x.y^{-1}" of the two ideals "x" and "y" in the number field
4574       "nf". The result is given in HNF.
4575
4576       If "flag" is non-zero, the quotient "x.y^{-1}" is assumed to be an
4577       integral ideal. This can be much faster when the norm of the quotient
4578       is small even though the norms of "x" and "y" are large.
4579
4580       The library syntax is idealdiv0"(nf,x,y,flag)". Also available are "
4581       idealdiv(nf,x,y)" ("flag = 0") and " idealdivexact(nf,x,y)" ("flag =
4582       1").
4583
4584   idealfactor"(nf,x)"
4585       factors into prime ideal powers the ideal "x" in the number field "nf".
4586       The output format is similar to the "factor" function, and the prime
4587       ideals are represented in the form output by the "idealprimedec"
4588       function, i.e. as 5-element vectors.
4589
4590       The library syntax is idealfactor"(nf,x)".
4591
4592   idealhnf"(nf,a,{b})"
4593       gives the Hermite normal form matrix of the ideal "a". The ideal can be
4594       given in any form whatsoever (typically by an algebraic number if it is
4595       principal, by a "Z_K"-system of generators, as a prime ideal as given
4596       by "idealprimedec", or by a Z-basis).
4597
4598       If "b" is not omitted, assume the ideal given was "aZ_K+bZ_K", where
4599       "a" and "b" are elements of "K" given either as vectors on the integral
4600       basis "nf[7]" or as algebraic numbers.
4601
4602       The library syntax is idealhnf0"(nf,a,b)" where an omitted "b" is coded
4603       as "NULL".  Also available is " idealhermite(nf,a)" ("b" omitted).
4604
4605   idealintersect"(nf,A,B)"
4606       intersection of the two ideals "A" and "B" in the number field "nf".
4607       The result is given in HNF.
4608
4609             ? nf = nfinit(x^2+1);
4610             ? idealintersect(nf, 2, x+1)
4611             %2 =
4612             [2 0]
4613
4614             [0 2]
4615
4616       This function does not apply to general Z-modules, e.g. orders, since
4617       its arguments are replaced by the ideals they generate. The following
4618       script intersects Z-modules "A" and "B" given by matrices of compatible
4619       dimensions with integer coefficients:
4620
4621             ZM_intersect(A,B) =
4622             { local( Ker = matkerint(concat(A,B)) );
4623               mathnf(A * vecextract(Ker, Str("..", #A), ".."))
4624             }
4625
4626       The library syntax is idealintersect"(nf,A,B)".
4627
4628   idealinv"(nf,x)"
4629       inverse of the ideal "x" in the number field "nf". The result is the
4630       Hermite normal form of the inverse of the ideal, together with the
4631       opposite of the Archimedean information if it is given.
4632
4633       The library syntax is idealinv"(nf,x)".
4634
4635   ideallist"(nf,bound,{flag = 4})"
4636       computes the list of all ideals of norm less or equal to bound in the
4637       number field nf. The result is a row vector with exactly bound
4638       components.  Each component is itself a row vector containing the
4639       information about ideals of a given norm, in no specific order,
4640       depending on the value of "flag":
4641
4642       The possible values of "flag" are:
4643
4644         0: give the bid associated to the ideals, without generators.
4645
4646         1: as 0, but include the generators in the bid.
4647
4648         2: in this case, nf must be a bnf with units. Each component is of
4649       the form "[bid,U]", where bid is as case 0 and "U" is a vector of
4650       discrete logarithms of the units. More precisely, it gives the
4651       "ideallog"s with respect to bid of "bnf.tufu".  This structure is
4652       technical, and only meant to be used in conjunction with
4653       "bnrclassnolist" or "bnrdisclist".
4654
4655         3: as 2, but include the generators in the bid.
4656
4657         4: give only the HNF of the ideal.
4658
4659         ? #L[65]
4660         %4 = 4               \\ A single ideal of norm 1
4661         ? #L[65]
4662         %4 = 4               \\ There are 4 ideals of norm 4 in Z[i]
4663
4664       If one wants more information, one could do instead:
4665
4666         ? nf = nfinit(x^2+1);
4667         ? L = ideallist(nf, 100, 0);
4668         ? l = L[25]; vector(#l, i, l[i].clgp)
4669         %3 = [[20, [20]], [16, [4, 4]], [20, [20]]]
4670         ? l[1].mod
4671         %4 = [[25, 18; 0, 1], []]
4672         ? l[2].mod
4673         %5 = [[5, 0; 0, 5], []]
4674         ? l[3].mod
4675         %6 = [[25, 7; 0, 1], []]
4676
4677       where we ask for the structures of the "(Z[i]/I)^*" for all three
4678       ideals of norm 25. In fact, for all moduli with finite part of norm 25
4679       and trivial archimedean part, as the last 3 commands show. See
4680       "ideallistarch" to treat general moduli.
4681
4682       The library syntax is ideallist0"(nf,bound,flag)", where bound must be
4683       a C long integer. Also available is " ideallist(nf,bound)",
4684       corresponding to the case "flag = 4".
4685
4686   ideallistarch"(nf,list,arch)"
4687       list is a vector of vectors of bid's, as output by "ideallist" with
4688       flag 0 to 3. Return a vector of vectors with the same number of
4689       components as the original list. The leaves give information about
4690       moduli whose finite part is as in original list, in the same order, and
4691       archimedean part is now arch (it was originally trivial). The
4692       information contained is of the same kind as was present in the input;
4693       see "ideallist", in particular the meaning of flag.
4694
4695         ? L = ideallist(bnf, 100, 0);
4696         ? l = L[98]; vector(#l, i, l[i].clgp)
4697         %4 = [[42, [42]], [36, [6, 6]], [42, [42]]]
4698         ? La = ideallistarch(bnf, L, [1,1]); \\ two places at infinity
4699         ? L = ideallist(bnf, 100, 0);
4700         ? l = L[98]; vector(#l, i, l[i].clgp)
4701         %4 = [[42, [42]], [36, [6, 6]], [42, [42]]]
4702         ? La = ideallistarch(bnf, L, [1,1]); \\ add them to the modulus
4703         ? l = La[98]; vector(#l, i, l[i].clgp)
4704         %6 = [[168, [42, 2, 2]], [144, [6, 6, 2, 2]], [168, [42, 2, 2]]]
4705
4706       Of course, the results above are obvious: adding "t" places at infinity
4707       will add "t" copies of "Z/2Z" to the ray class group. The following
4708       application is more typical:
4709
4710         ? L = ideallist(bnf, 100, 2);        \\ units are required now
4711         ? La = ideallistarch(bnf, L, [1,1]);
4712         ? H = bnrclassnolist(bnf, La);
4713         ? H[98];
4714         %6 = [2, 12, 2]
4715
4716       The library syntax is ideallistarch"(nf,list,arch)".
4717
4718   ideallog"(nf,x,bid)"
4719       "nf" is a number field, bid a ``big ideal'' as output by "idealstar"
4720       and "x" a non-necessarily integral element of nf which must have
4721       valuation equal to 0 at all prime ideals dividing "I = bid[1]". This
4722       function computes the ``discrete logarithm'' of "x" on the generators
4723       given in "bid[2]". In other words, if "g_i" are these generators, of
4724       orders "d_i" respectively, the result is a column vector of integers
4725       "(x_i)" such that "0 <= x_i < d_i" and
4726
4727         "x = prod_ig_i^{x_i} (mod ^*I) ."
4728
4729       Note that when "I" is a module, this implies also sign conditions on
4730       the embeddings.
4731
4732       The library syntax is zideallog"(nf,x,bid)".
4733
4734   idealmin"(nf,x,{vdir})"
4735       computes a minimum of the ideal "x" in the direction vdir in the number
4736       field nf.
4737
4738       The library syntax is minideal"(nf,x,vdir,prec)", where an omitted vdir
4739       is coded as "NULL".
4740
4741   idealmul"(nf,x,y,{flag = 0})"
4742       ideal multiplication of the ideals "x" and "y" in the number field nf.
4743       The result is a generating set for the ideal product with at most "n"
4744       elements, and is in Hermite normal form if either "x" or "y" is in HNF
4745       or is a prime ideal as output by "idealprimedec", and this is given
4746       together with the sum of the Archimedean information in "x" and "y" if
4747       both are given.
4748
4749       If "flag" is non-zero, reduce the result using "idealred".
4750
4751       The library syntax is idealmul"(nf,x,y)" ("flag = 0") or "
4752       idealmulred(nf,x,y,prec)" ("flag ! = 0"), where as usual, "prec" is a C
4753       long integer representing the precision.
4754
4755   idealnorm"(nf,x)"
4756       computes the norm of the ideal "x" in the number field "nf".
4757
4758       The library syntax is idealnorm"(nf, x)".
4759
4760   idealpow"(nf,x,k,{flag = 0})"
4761       computes the "k"-th power of the ideal "x" in the number field "nf".
4762       "k" can be positive, negative or zero. The result is NOT reduced, it is
4763       really the "k"-th ideal power, and is given in HNF.
4764
4765       If "flag" is non-zero, reduce the result using "idealred". Note however
4766       that this is NOT the same as as "idealpow(nf,x,k)" followed by
4767       reduction, since the reduction is performed throughout the powering
4768       process.
4769
4770       The library syntax corresponding to "flag = 0" is " idealpow(nf,x,k)".
4771       If "k" is a "long", you can use " idealpows(nf,x,k)". Corresponding to
4772       "flag = 1" is " idealpowred(nf,vp,k,prec)", where "prec" is a "long".
4773
4774   idealprimedec"(nf,p)"
4775       computes the prime ideal decomposition of the prime number "p" in the
4776       number field "nf". "p" must be a (positive) prime number. Note that the
4777       fact that "p" is prime is not checked, so if a non-prime "p" is given
4778       the result is undefined.
4779
4780       The result is a vector of pr structures, each representing one of the
4781       prime ideals above "p" in the number field "nf". The representation "P
4782       = [p,a,e,f,b]" of a prime ideal means the following. The prime ideal is
4783       equal to "pZ_K+alphaZ_K" where "Z_K" is the ring of integers of the
4784       field and "alpha = sum_i a_iomega_i" where the "omega_i" form the
4785       integral basis "nf.zk", "e" is the ramification index, "f" is the
4786       residual index, and "b" represents a "beta belongs to Z_K" such that
4787       "P^{-1} = Z_K+beta/pZ_K" which will be useful for computing valuations,
4788       but which the user can ignore. The number "alpha" is guaranteed to have
4789       a valuation equal to 1 at the prime ideal (this is automatic if "e >
4790       1").
4791
4792       The components of "P" should be accessed by member functions: "P.p",
4793       "P.e", "P.f", and "P.gen" (returns the vector "[p,a]").
4794
4795       The library syntax is primedec"(nf,p)".
4796
4797   idealprincipal"(nf,x)"
4798       creates the principal ideal generated by the algebraic number "x"
4799       (which must be of type integer, rational or polmod) in the number field
4800       "nf". The result is a one-column matrix.
4801
4802       The library syntax is principalideal"(nf,x)".
4803
4804   idealred"(nf,I,{vdir = 0})"
4805       LLL reduction of the ideal "I" in the number field nf, along the
4806       direction vdir.  If vdir is present, it must be an "r1+r2"-component
4807       vector ("r1" and "r2" number of real and complex places of nf as
4808       usual).
4809
4810       This function finds a ``small'' "a" in "I" (it is an LLL pseudo-minimum
4811       along direction vdir). The result is the Hermite normal form of the
4812       LLL-reduced ideal "r I/a", where "r" is a rational number such that the
4813       resulting ideal is integral and primitive. This is often, but not
4814       always, a reduced ideal in the sense of Buchmann. If "I" is an idele,
4815       the logarithmic embeddings of "a" are subtracted to the Archimedean
4816       part.
4817
4818       More often than not, a principal ideal will yield the identity matrix.
4819       This is a quick and dirty way to check if ideals are principal without
4820       computing a full "bnf" structure, but it's not a necessary condition;
4821       hence, a non-trivial result doesn't prove the ideal is non-trivial in
4822       the class group.
4823
4824       Note that this is \emph{not} the same as the LLL reduction of the
4825       lattice "I" since ideal operations are involved.
4826
4827       The library syntax is ideallllred"(nf,x,vdir,prec)", where an omitted
4828       vdir is coded as "NULL".
4829
4830   idealstar"(nf,I,{flag = 1})"
4831       outputs a bid structure, necessary for computing in the finite abelian
4832       group "G = (Z_K/I)^*". Here, nf is a number field and "I" is a modulus:
4833       either an ideal in any form, or a row vector whose first component is
4834       an ideal and whose second component is a row vector of "r_1" 0 or 1.
4835
4836       This bid is used in "ideallog" to compute discrete logarithms. It also
4837       contains useful information which can be conveniently retrieved as
4838       "bid.mod" (the modulus), "bid.clgp" ("G" as a finite abelian group),
4839       "bid.no" (the cardinality of "G"), "bid.cyc" (elementary divisors) and
4840       "bid.gen" (generators).
4841
4842       If "flag = 1" (default), the result is a bid structure without
4843       generators.
4844
4845       If "flag = 2", as "flag = 1", but including generators, which wastes
4846       some time.
4847
4848       If "flag = 0", \emph{deprecated}. Only outputs "(Z_K/I)^*" as an
4849       abelian group, i.e as a 3-component vector "[h,d,g]": "h" is the order,
4850       "d" is the vector of SNF cyclic components and "g" the corresponding
4851       generators. This flag is deprecated: it is in fact slightly faster to
4852       compute a true bid structure, which contains much more information.
4853
4854       The library syntax is idealstar0"(nf,I,flag)".
4855
4856   idealtwoelt"(nf,x,{a})"
4857       computes a two-element representation of the ideal "x" in the number
4858       field "nf", using a straightforward (exponential time) search. "x" can
4859       be an ideal in any form, (including perhaps an Archimedean part, which
4860       is ignored) and the result is a row vector "[a,alpha]" with two
4861       components such that "x = aZ_K+alphaZ_K" and "a belongs to Z", where
4862       "a" is the one passed as argument if any. If "x" is given by at least
4863       two generators, "a" is chosen to be the positive generator of "x cap
4864       Z".
4865
4866       Note that when an explicit "a" is given, we use an asymptotically
4867       faster method, however in practice it is usually slower.
4868
4869       The library syntax is ideal_two_elt0"(nf,x,a)", where an omitted "a" is
4870       entered as "NULL".
4871
4872   idealval"(nf,x,vp)"
4873       gives the valuation of the ideal "x" at the prime ideal vp in the
4874       number field "nf", where vp must be a 5-component vector as given by
4875       "idealprimedec".
4876
4877       The library syntax is idealval"(nf,x,vp)", and the result is a "long"
4878       integer.
4879
4880   ideleprincipal"(nf,x)"
4881       creates the principal idele generated by the algebraic number "x"
4882       (which must be of type integer, rational or polmod) in the number field
4883       "nf". The result is a two-component vector, the first being a one-
4884       column matrix representing the corresponding principal ideal, and the
4885       second being the vector with "r_1+r_2" components giving the complex
4886       logarithmic embedding of "x".
4887
4888       The library syntax is principalidele"(nf,x)".
4889
4890   matalgtobasis"(nf,x)"
4891       "nf" being a number field in "nfinit" format, and "x" a matrix whose
4892       coefficients are expressed as polmods in "nf", transforms this matrix
4893       into a matrix whose coefficients are expressed on the integral basis of
4894       "nf". This is the same as applying "nfalgtobasis" to each entry, but it
4895       would be dangerous to use the same name.
4896
4897       The library syntax is matalgtobasis"(nf,x)".
4898
4899   matbasistoalg"(nf,x)"
4900       "nf" being a number field in "nfinit" format, and "x" a matrix whose
4901       coefficients are expressed as column vectors on the integral basis of
4902       "nf", transforms this matrix into a matrix whose coefficients are
4903       algebraic numbers expressed as polmods. This is the same as applying
4904       "nfbasistoalg" to each entry, but it would be dangerous to use the same
4905       name.
4906
4907       The library syntax is matbasistoalg"(nf,x)".
4908
4909   modreverse"(a)"
4910       "a" being a polmod A(X) modulo T(X), finds the ``reverse polmod'' B(X)
4911       modulo Q(X), where "Q" is the minimal polynomial of "a", which must be
4912       equal to the degree of "T", and such that if "theta" is a root of "T"
4913       then "theta = B(alpha)" for a certain root "alpha" of "Q".
4914
4915       This is very useful when one changes the generating element in
4916       algebraic extensions.
4917
4918       The library syntax is polmodrecip"(x)".
4919
4920   newtonpoly"(x,p)"
4921       gives the vector of the slopes of the Newton polygon of the polynomial
4922       "x" with respect to the prime number "p". The "n" components of the
4923       vector are in decreasing order, where "n" is equal to the degree of
4924       "x". Vertical slopes occur iff the constant coefficient of "x" is zero
4925       and are denoted by "VERYBIGINT", the biggest single precision integer
4926       representable on the machine ("2^{31}-1" (resp. "2^{63}-1") on 32-bit
4927       (resp. 64-bit) machines), see "Label se:valuation".
4928
4929       The library syntax is newtonpoly"(x,p)".
4930
4931   nfalgtobasis"(nf,x)"
4932       this is the inverse function of "nfbasistoalg". Given an object "x"
4933       whose entries are expressed as algebraic numbers in the number field
4934       "nf", transforms it so that the entries are expressed as a column
4935       vector on the integral basis "nf.zk".
4936
4937       The library syntax is algtobasis"(nf,x)".
4938
4939   nfbasis"(x,{flag = 0},{fa})"
4940       integral basis of the number field defined by the irreducible,
4941       preferably monic, polynomial "x", using a modified version of the round
4942       4 algorithm by default, due to David Ford, Sebastian Pauli and Xavier
4943       Roblot. The binary digits of "flag" have the following meaning:
4944
4945       1: assume that no square of a prime greater than the default
4946       "primelimit" divides the discriminant of "x", i.e. that the index of
4947       "x" has only small prime divisors.
4948
4949       2: use round 2 algorithm. For small degrees and coefficient size, this
4950       is sometimes a little faster. (This program is the translation into C
4951       of a program written by David Ford in Algeb.)
4952
4953       Thus for instance, if "flag = 3", this uses the round 2 algorithm and
4954       outputs an order which will be maximal at all the small primes.
4955
4956       If fa is present, we assume (without checking!) that it is the two-
4957       column matrix of the factorization of the discriminant of the
4958       polynomial "x". Note that it does \emph{not} have to be a complete
4959       factorization. This is especially useful if only a local integral basis
4960       for some small set of places is desired: only factors with exponents
4961       greater or equal to 2 will be considered.
4962
4963       The library syntax is nfbasis0"(x,flag,fa)". An extended version is "
4964       nfbasis(x,&d,flag,fa)", where "d" receives the discriminant of the
4965       number field (\emph{not} of the polynomial "x"), and an omitted fa is
4966       input as "NULL". Also available are " base(x,&d)" ("flag = 0"), "
4967       base2(x,&d)" ("flag = 2") and " factoredbase(x,fa,&d)".
4968
4969   nfbasistoalg"(nf,x)"
4970       this is the inverse function of "nfalgtobasis". Given an object "x"
4971       whose entries are expressed on the integral basis "nf.zk", transforms
4972       it into an object whose entries are algebraic numbers (i.e. polmods).
4973
4974       The library syntax is basistoalg"(nf,x)".
4975
4976   nfdetint"(nf,x)"
4977       given a pseudo-matrix "x", computes a non-zero ideal contained in
4978       (i.e. multiple of) the determinant of "x". This is particularly useful
4979       in conjunction with "nfhnfmod".
4980
4981       The library syntax is nfdetint"(nf,x)".
4982
4983   nfdisc"(x,{flag = 0},{fa})"
4984       field discriminant of the number field defined by the integral,
4985       preferably monic, irreducible polynomial "x". "flag" and "fa" are
4986       exactly as in "nfbasis". That is, "fa" provides the matrix of a partial
4987       factorization of the discriminant of "x", and binary digits of "flag"
4988       are as follows:
4989
4990       1: assume that no square of a prime greater than "primelimit" divides
4991       the discriminant.
4992
4993       2: use the round 2 algorithm, instead of the default round 4. This
4994       should be slower except maybe for polynomials of small degree and
4995       coefficients.
4996
4997       The library syntax is nfdiscf0"(x,flag,fa)" where an omitted "fa" is
4998       input as "NULL". You can also use " discf(x)" ("flag = 0").
4999
5000   nfeltdiv"(nf,x,y)"
5001       given two elements "x" and "y" in nf, computes their quotient "x/y" in
5002       the number field "nf".
5003
5004       The library syntax is element_div"(nf,x,y)".
5005
5006   nfeltdiveuc"(nf,x,y)"
5007       given two elements "x" and "y" in nf, computes an algebraic integer "q"
5008       in the number field "nf" such that the components of "x-qy" are
5009       reasonably small. In fact, this is functionally identical to
5010       "round(nfeltdiv(nf,x,y))".
5011
5012       The library syntax is nfdiveuc"(nf,x,y)".
5013
5014   nfeltdivmodpr"(nf,x,y,pr)"
5015       given two elements "x" and "y" in nf and pr a prime ideal in "modpr"
5016       format (see "nfmodprinit"), computes their quotient "x / y" modulo the
5017       prime ideal pr.
5018
5019       The library syntax is element_divmodpr"(nf,x,y,pr)".
5020
5021   nfeltdivrem"(nf,x,y)"
5022       given two elements "x" and "y" in nf, gives a two-element row vector
5023       "[q,r]" such that "x = qy+r", "q" is an algebraic integer in "nf", and
5024       the components of "r" are reasonably small.
5025
5026       The library syntax is nfdivrem"(nf,x,y)".
5027
5028   nfeltmod"(nf,x,y)"
5029       given two elements "x" and "y" in nf, computes an element "r" of "nf"
5030       of the form "r = x-qy" with "q" and algebraic integer, and such that
5031       "r" is small. This is functionally identical to
5032
5033         "x - nfeltmul(nf,round(nfeltdiv(nf,x,y)),y)."
5034
5035       The library syntax is nfmod"(nf,x,y)".
5036
5037   nfeltmul"(nf,x,y)"
5038       given two elements "x" and "y" in nf, computes their product "x*y" in
5039       the number field "nf".
5040
5041       The library syntax is element_mul"(nf,x,y)".
5042
5043   nfeltmulmodpr"(nf,x,y,pr)"
5044       given two elements "x" and "y" in nf and pr a prime ideal in "modpr"
5045       format (see "nfmodprinit"), computes their product "x*y" modulo the
5046       prime ideal pr.
5047
5048       The library syntax is element_mulmodpr"(nf,x,y,pr)".
5049
5050   nfeltpow"(nf,x,k)"
5051       given an element "x" in nf, and a positive or negative integer "k",
5052       computes "x^k" in the number field "nf".
5053
5054       The library syntax is element_pow"(nf,x,k)".
5055
5056   nfeltpowmodpr"(nf,x,k,pr)"
5057       given an element "x" in nf, an integer "k" and a prime ideal pr in
5058       "modpr" format (see "nfmodprinit"), computes "x^k" modulo the prime
5059       ideal pr.
5060
5061       The library syntax is element_powmodpr"(nf,x,k,pr)".
5062
5063   nfeltreduce"(nf,x,ideal)"
5064       given an ideal in Hermite normal form and an element "x" of the number
5065       field "nf", finds an element "r" in "nf" such that "x-r" belongs to the
5066       ideal and "r" is small.
5067
5068       The library syntax is element_reduce"(nf,x,ideal)".
5069
5070   nfeltreducemodpr"(nf,x,pr)"
5071       given an element "x" of the number field "nf" and a prime ideal pr in
5072       "modpr" format compute a canonical representative for the class of "x"
5073       modulo pr.
5074
5075       The library syntax is nfreducemodpr"(nf,x,pr)".
5076
5077   nfeltval"(nf,x,pr)"
5078       given an element "x" in nf and a prime ideal pr in the format output by
5079       "idealprimedec", computes their the valuation at pr of the element "x".
5080       The same result could be obtained using "idealval(nf,x,pr)" (since "x"
5081       would then be converted to a principal ideal), but it would be less
5082       efficient.
5083
5084       The library syntax is element_val"(nf,x,pr)", and the result is a
5085       "long".
5086
5087   nffactor"(nf,x)"
5088       factorization of the univariate polynomial "x" over the number field
5089       "nf" given by "nfinit". "x" has coefficients in "nf" (i.e. either
5090       scalar, polmod, polynomial or column vector). The main variable of "nf"
5091       must be of \emph{lower} priority than that of "x" (see "Label
5092       se:priority"). However if the polynomial defining the number field
5093       occurs explicitly  in the coefficients of "x" (as modulus of a
5094       "t_POLMOD"), its main variable must be \emph{the same} as the main
5095       variable of "x". For example,
5096
5097         ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\  OK
5098         ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\  OK
5099         ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\  WRONG
5100
5101       The library syntax is nffactor"(nf,x)".
5102
5103   nffactormod"(nf,x,pr)"
5104       factorization of the univariate polynomial "x" modulo the prime ideal
5105       pr in the number field "nf". "x" can have coefficients in the number
5106       field (scalar, polmod, polynomial, column vector) or modulo the prime
5107       ideal (intmod modulo the rational prime under pr, polmod or polynomial
5108       with intmod coefficients, column vector of intmod). The prime ideal pr
5109       \emph{must} be in the format output by "idealprimedec". The main
5110       variable of "nf" must be of lower priority than that of "x" (see "Label
5111       se:priority"). However if the coefficients of the number field occur
5112       explicitly (as polmods) as coefficients of "x", the variable of these
5113       polmods \emph{must} be the same as the main variable of "t" (see
5114       "nffactor").
5115
5116       The library syntax is nffactormod"(nf,x,pr)".
5117
5118   nfgaloisapply"(nf,aut,x)"
5119       "nf" being a number field as output by "nfinit", and aut being a Galois
5120       automorphism of "nf" expressed either as a polynomial or a polmod (such
5121       automorphisms being found using for example one of the variants of
5122       "nfgaloisconj"), computes the action of the automorphism aut on the
5123       object "x" in the number field. "x" can be an element (scalar, polmod,
5124       polynomial or column vector) of the number field, an ideal (either
5125       given by "Z_K"-generators or by a Z-basis), a prime ideal (given as a
5126       5-element row vector) or an idele (given as a 2-element row vector).
5127       Because of possible confusion with elements and ideals, other vector or
5128       matrix arguments are forbidden.
5129
5130       The library syntax is galoisapply"(nf,aut,x)".
5131
5132   nfgaloisconj"(nf,{flag = 0},{d})"
5133       "nf" being a number field as output by "nfinit", computes the
5134       conjugates of a root "r" of the non-constant polynomial "x = nf[1]"
5135       expressed as polynomials in "r". This can be used even if the number
5136       field "nf" is not Galois since some conjugates may lie in the field.
5137
5138       "nf" can simply be a polynomial if "flag ! = 1".
5139
5140       If no flags or "flag = 0", if "nf" is a number field use a combination
5141       of flag 4 and 1 and the result is always complete, else use a
5142       combination of flag 4 and 2 and the result is subject to the
5143       restriction of "flag = 2", but a warning is issued when it is not
5144       proven complete.
5145
5146       If "flag = 1", use "nfroots" (require a number field).
5147
5148       If "flag = 2", use complex approximations to the roots and an integral
5149       LLL. The result is not guaranteed to be complete: some conjugates may
5150       be missing (no warning issued), especially so if the corresponding
5151       polynomial has a huge index. In that case, increasing the default
5152       precision may help.
5153
5154       If "flag = 4", use Allombert's algorithm and permutation testing. If
5155       the field is Galois with ``weakly'' super solvable Galois group, return
5156       the complete list of automorphisms, else only the identity element. If
5157       present, "d" is assumed to be a multiple of the least common
5158       denominator of the conjugates expressed as polynomial in a root of pol.
5159
5160       A group G is ``weakly'' super solvable (WKSS) if it contains a super
5161       solvable normal subgroup "H" such that "G = H" , or "G/H  ~  A_4" , or
5162       "G/H  ~ S_4". Abelian and nilpotent groups are WKSS. In practice,
5163       almost all groups of small order are WKSS, the exceptions having order
5164       36(1 exception), 48(2), 56(1), 60(1), 72(5), 75(1), 80(1), 96(10) and "
5165       >= 108".
5166
5167       Hence "flag = 4" permits to quickly check whether a polynomial of order
5168       strictly less than 36 is Galois or not. This method is much faster than
5169       "nfroots" and can be applied to polynomials of degree larger than 50.
5170
5171       This routine can only compute Q-automorphisms, but it may be used to
5172       get "K"-automorphism for any base field "K" as follows:
5173
5174           rnfgaloisconj(nfK, R) = \\ K-automorphisms of L = K[X] / (R)
5175           { local(polabs, N, H);
5176             R *= Mod(1, nfK.pol);             \\ convert coeffs to polmod elts of K
5177             polabs = rnfequation(nfK, R);
5178             N = nfgaloisconj(polabs) % R;     \\ Q-automorphisms of L
5179             H = [];
5180             for(i=1, #N,                      \\ select the ones that fix K
5181               if (subst(R, variable(R), Mod(N[i],R)) == 0,
5182                 H = concat(H,N[i])
5183               )
5184             ); H
5185           }
5186           K  = nfinit(y^2 + 7);
5187           polL = x^4 - y*x^3 - 3*x^2 + y*x + 1;
5188           rnfgaloisconj(K, polL)             \\ K-automorphisms of L
5189
5190       The library syntax is galoisconj0"(nf,flag,d,prec)". Also available are
5191       " galoisconj(nf)" for "flag = 0", " galoisconj2(nf,n,prec)" for "flag =
5192       2" where "n" is a bound on the number of conjugates, and  "
5193       galoisconj4(nf,d)" corresponding to "flag = 4".
5194
5195   nfhilbert"(nf,a,b,{pr})"
5196       if pr is omitted, compute the global Hilbert symbol "(a,b)" in "nf",
5197       that is 1 if "x^2 - a y^2 - b z^2" has a non trivial solution "(x,y,z)"
5198       in "nf", and "-1" otherwise. Otherwise compute the local symbol modulo
5199       the prime ideal pr (as output by "idealprimedec").
5200
5201       The library syntax is nfhilbert"(nf,a,b,pr)", where an omitted pr is
5202       coded as "NULL".
5203
5204   nfhnf"(nf,x)"
5205       given a pseudo-matrix "(A,I)", finds a pseudo-basis in Hermite normal
5206       form of the module it generates.
5207
5208       The library syntax is nfhermite"(nf,x)".
5209
5210   nfhnfmod"(nf,x,detx)"
5211       given a pseudo-matrix "(A,I)" and an ideal detx which is contained in
5212       (read integral multiple of) the determinant of "(A,I)", finds a pseudo-
5213       basis in Hermite normal form of the module generated by "(A,I)". This
5214       avoids coefficient explosion.  detx can be computed using the function
5215       "nfdetint".
5216
5217       The library syntax is nfhermitemod"(nf,x,detx)".
5218
5219   nfinit"(pol,{flag = 0})"
5220       pol being a non-constant, preferably monic, irreducible polynomial in
5221       "Z[X]", initializes a \emph{number field} structure ("nf") associated
5222       to the field "K" defined by pol. As such, it's a technical object
5223       passed as the first argument to most "nf"xxx functions, but it contains
5224       some information which may be directly useful. Access to this
5225       information via \emph{member functions} is preferred since the specific
5226       data organization specified below may change in the future. Currently,
5227       "nf" is a row vector with 9 components:
5228
5229       "nf[1]" contains the polynomial pol ("nf.pol").
5230
5231       "nf[2]" contains "[r1,r2]" ("nf.sign", "nf.r1", "nf.r2"), the number of
5232       real and complex places of "K".
5233
5234       "nf[3]" contains the discriminant d(K) ("nf.disc") of "K".
5235
5236       "nf[4]" contains the index of "nf[1]" ("nf.index"), i.e. "[Z_K :
5237       Z[theta]]", where "theta" is any root of "nf[1]".
5238
5239       "nf[5]" is a vector containing 7 matrices "M", "G", "T2", "T", "MD",
5240       "TI", "MDI" useful for certain computations in the number field "K".
5241
5242         \item "M" is the "(r1+r2) x n" matrix whose columns represent the
5243       numerical values of the conjugates of the elements of the integral
5244       basis.
5245
5246         \item "G" is such that "T2 = ^t G G", where "T2" is the quadratic
5247       form "T_2(x) = sum |sigma(x)|^2", "sigma" running over the embeddings
5248       of "K" into C.
5249
5250         \item The "T2" component is deprecated and currently unused.
5251
5252         \item "T" is the "n x n" matrix whose coefficients are
5253       "Tr(omega_iomega_j)" where the "omega_i" are the elements of the
5254       integral basis. Note also that " det (T)" is equal to the discriminant
5255       of the field "K".
5256
5257         \item The columns of "MD" ("nf.diff") express a Z-basis of the
5258       different of "K" on the integral basis.
5259
5260         \item "TI" is equal to "d(K)T^{-1}", which has integral coefficients.
5261       Note that, understood as as ideal, the matrix "T^{-1}" generates the
5262       codifferent ideal.
5263
5264         \item Finally, "MDI" is a two-element representation (for faster
5265       ideal product) of d(K) times the codifferent ideal
5266       ("nf.disc*nf.codiff", which is an integral ideal). "MDI" is only used
5267       in "idealinv".
5268
5269       "nf[6]" is the vector containing the "r1+r2" roots ("nf.roots") of
5270       "nf[1]" corresponding to the "r1+r2" embeddings of the number field
5271       into C (the first "r1" components are real, the next "r2" have positive
5272       imaginary part).
5273
5274       "nf[7]" is an integral basis for "Z_K" ("nf.zk") expressed on the
5275       powers of "theta". Its first element is guaranteed to be 1. This basis
5276       is LLL-reduced with respect to "T_2" (strictly speaking, it is a
5277       permutation of such a basis, due to the condition that the first
5278       element be 1).
5279
5280       "nf[8]" is the "n x n" integral matrix expressing the power basis in
5281       terms of the integral basis, and finally
5282
5283       "nf[9]" is the "n x n^2" matrix giving the multiplication table of the
5284       integral basis.
5285
5286       If a non monic polynomial is input, "nfinit" will transform it into a
5287       monic one, then reduce it (see "flag = 3"). It is allowed, though not
5288       very useful given the existence of "nfnewprec", to input a "nf" or a
5289       "bnf" instead of a polynomial.
5290
5291           ? nf = nfinit(x^3 - 12); \\ initialize number field Q[X] / (X^3 - 12)
5292           ? nf.pol   \\ defining polynomial
5293           %2 = x^3 - 12
5294           ? nf.disc  \\ field discriminant
5295           %3 = -972
5296           ? nf.index \\ index of power basis order in maximal order
5297           %4 = 2
5298           ? nf.zk    \\ integer basis, lifted to Q[X]
5299           %5 = [1, x, 1/2*x^2]
5300           ? nf.sign  \\ signature
5301           %6 = [1, 1]
5302           ? factor(abs(nf.disc ))  \\ determines ramified primes
5303           %7 =
5304           [2 2]
5305
5306           [3 5]
5307           ? idealfactor(nf, 2)
5308           %8 =
5309           [[2, [0, 0, -1]~, 3, 1, [0, 1, 0]~] 3]  \\  \goth{P}_2^3
5310
5311       In case pol has a huge discriminant which is difficult to factor, the
5312       special input format "[pol,B]" is also accepted where pol is a
5313       polynomial as above and "B" is the integer basis, as would be computed
5314       by "nfbasis". This is useful if the integer basis is known in advance,
5315       or was computed conditionnally.
5316
5317           ? pol = polcompositum(x^5 - 101, polcyclo(7))[1];
5318           ? B = nfbasis(pol, 1);   \\ faster than nfbasis(pol), but conditional
5319           ? nf = nfinit( [pol, B] );
5320           ? factor( abs(nf.disc) )
5321           [5 18]
5322
5323           [7 25]
5324
5325           [101 24]
5326
5327       "B" is conditional when its discriminant, which is "nf.disc", can't be
5328       factored. In this example, the above factorization proves the
5329       correctness of the computation.
5330
5331       If "flag = 2": pol is changed into another polynomial "P" defining the
5332       same number field, which is as simple as can easily be found using the
5333       "polred" algorithm, and all the subsequent computations are done using
5334       this new polynomial. In particular, the first component of the result
5335       is the modified polynomial.
5336
5337       If "flag = 3", does a "polred" as in case 2, but outputs
5338       "[nf,Mod(a,P)]", where "nf" is as before and "Mod(a,P) = Mod(x,pol)"
5339       gives the change of variables. This is implicit when pol is not monic:
5340       first a linear change of variables is performed, to get a monic
5341       polynomial, then a "polred" reduction.
5342
5343       If "flag = 4", as 2 but uses a partial "polred".
5344
5345       If "flag = 5", as 3 using a partial "polred".
5346
5347       The library syntax is nfinit0"(x,flag,prec)".
5348
5349   nfisideal"(nf,x)"
5350       returns 1 if "x" is an ideal in the number field "nf", 0 otherwise.
5351
5352       The library syntax is isideal"(x)".
5353
5354   nfisincl"(x,y)"
5355       tests whether the number field "K" defined by the polynomial "x" is
5356       conjugate to a subfield of the field "L" defined by "y" (where "x" and
5357       "y" must be in "Q[X]"). If they are not, the output is the number 0. If
5358       they are, the output is a vector of polynomials, each polynomial "a"
5359       representing an embedding of "K" into "L", i.e. being such that "y | x
5360       o a".
5361
5362       If "y" is a number field (nf), a much faster algorithm is used
5363       (factoring "x" over "y" using "nffactor"). Before version 2.0.14, this
5364       wasn't guaranteed to return all the embeddings, hence was triggered by
5365       a special flag. This is no more the case.
5366
5367       The library syntax is nfisincl"(x,y,flag)".
5368
5369   nfisisom"(x,y)"
5370       as "nfisincl", but tests for isomorphism. If either "x" or "y" is a
5371       number field, a much faster algorithm will be used.
5372
5373       The library syntax is nfisisom"(x,y,flag)".
5374
5375   nfnewprec"(nf)"
5376       transforms the number field "nf" into the corresponding data using
5377       current (usually larger) precision. This function works as expected if
5378       "nf" is in fact a "bnf" (update "bnf" to current precision) but may be
5379       quite slow (many generators of principal ideals have to be computed).
5380
5381       The library syntax is nfnewprec"(nf,prec)".
5382
5383   nfkermodpr"(nf,a,pr)"
5384       kernel of the matrix "a" in "Z_K/pr", where pr is in modpr format (see
5385       "nfmodprinit").
5386
5387       The library syntax is nfkermodpr"(nf,a,pr)".
5388
5389   nfmodprinit"(nf,pr)"
5390       transforms the prime ideal pr into "modpr" format necessary for all
5391       operations modulo pr in the number field nf.
5392
5393       The library syntax is nfmodprinit"(nf,pr)".
5394
5395   nfsubfields"(pol,{d = 0})"
5396       finds all subfields of degree "d" of the number field defined by the
5397       (monic, integral) polynomial pol (all subfields if "d" is null or
5398       omitted). The result is a vector of subfields, each being given by
5399       "[g,h]", where "g" is an absolute equation and "h" expresses one of the
5400       roots of "g" in terms of the root "x" of the polynomial defining "nf".
5401       This routine uses J. Klüners's algorithm in the general case, and
5402       B. Allombert's "galoissubfields" when nf is Galois (with weakly
5403       supersolvable Galois group).
5404
5405       The library syntax is subfields"(nf,d)".
5406
5407   nfroots"({nf},x)"
5408       roots of the polynomial "x" in the number field "nf" given by "nfinit"
5409       without multiplicity (in Q if "nf" is omitted). "x" has coefficients in
5410       the number field (scalar, polmod, polynomial, column vector). The main
5411       variable of "nf" must be of lower priority than that of "x" (see "Label
5412       se:priority"). However if the coefficients of the number field occur
5413       explicitly (as polmods) as coefficients of "x", the variable of these
5414       polmods \emph{must} be the same as the main variable of "t" (see
5415       "nffactor").
5416
5417       The library syntax is nfroots"(nf,x)".
5418
5419   nfrootsof1"(nf)"
5420       computes the number of roots of unity "w" and a primitive "w"-th root
5421       of unity (expressed on the integral basis) belonging to the number
5422       field "nf". The result is a two-component vector "[w,z]" where "z" is a
5423       column vector expressing a primitive "w"-th root of unity on the
5424       integral basis "nf.zk".
5425
5426       The library syntax is rootsof1"(nf)".
5427
5428   nfsnf"(nf,x)"
5429       given a torsion module "x" as a 3-component row vector "[A,I,J]" where
5430       "A" is a square invertible "n x n" matrix, "I" and "J" are two ideal
5431       lists, outputs an ideal list "d_1,...,d_n" which is the Smith normal
5432       form of "x". In other words, "x" is isomorphic to "Z_K/d_1 oplus ...
5433       oplus Z_K/d_n" and "d_i" divides "d_{i-1}" for "i >= 2".  The link
5434       between "x" and "[A,I,J]" is as follows: if "e_i" is the canonical
5435       basis of "K^n", "I = [b_1,...,b_n]" and "J = [a_1,...,a_n]", then "x"
5436       is isomorphic to
5437
5438         " (b_1e_1 oplus ... oplus  b_ne_n) / (a_1A_1 oplus ... oplus  a_nA_n)
5439        , "
5440
5441       where the "A_j" are the columns of the matrix "A". Note that every
5442       finitely generated torsion module can be given in this way, and even
5443       with "b_i = Z_K" for all "i".
5444
5445       The library syntax is nfsmith"(nf,x)".
5446
5447   nfsolvemodpr"(nf,a,b,pr)"
5448       solution of "a.x = b" in "Z_K/pr", where "a" is a matrix and "b" a
5449       column vector, and where pr is in modpr format (see "nfmodprinit").
5450
5451       The library syntax is nfsolvemodpr"(nf,a,b,pr)".
5452
5453   polcompositum"(P,Q,{flag = 0})"
5454       "P" and "Q" being squarefree polynomials in "Z[X]" in the same
5455       variable, outputs the simple factors of the étale Q-algebra "A = Q(X,
5456       Y) / (P(X), Q(Y))".  The factors are given by a list of polynomials "R"
5457       in "Z[X]", associated to the number field "Q(X)/ (R)", and sorted by
5458       increasing degree (with respect to lexicographic ordering for factors
5459       of equal degrees). Returns an error if one of the polynomials is not
5460       squarefree.
5461
5462       Note that it is more efficient to reduce to the case where "P" and "Q"
5463       are irreducible first. The routine will not perform this for you, since
5464       it may be expensive, and the inputs are irreducible in most
5465       applications anyway.  Assuming "P" is irreducible (of smaller degree
5466       than "Q" for efficiency), it is in general \emph{much} faster to
5467       proceed as follows
5468
5469            nf = nfinit(P); L = nffactor(nf, Q)[,1];
5470            vector(#L, i, rnfequation(nf, L[i]))
5471
5472       to obtain the same result. If you are only interested in the degrees of
5473       the simple factors, the "rnfequation" instruction can be replaced by a
5474       trivial "poldegree(P) * poldegree(L[i])".
5475
5476       If "flag = 1", outputs a vector of 4-component vectors "[R,a,b,k]",
5477       where "R" ranges through the list of all possible compositums as above,
5478       and "a" (resp. "b") expresses the root of "P" (resp. "Q") as an element
5479       of "Q(X)/(R)". Finally, "k" is a small integer such that "b + ka = X"
5480       modulo "R".
5481
5482       A compositum is quite often defined by a complicated polynomial, which
5483       it is advisable to reduce before further work. Here is a simple example
5484       involving the field "Q(zeta_5, 5^{1/5})":
5485
5486         ? pol = z[1]
5487         %5 = x^20 + 25*x^10 + 5
5488         ? a = subst(a.pol, x, z[2])  \\ pol defines the compositum
5489         ? pol = z[1]
5490         %5 = x^20 + 25*x^10 + 5
5491         ? a = subst(a.pol, x, z[2])  \\ a is a fifth root of 5
5492         ? pol = z[1]
5493         %5 = x^20 + 25*x^10 + 5
5494         ? a = subst(a.pol, x, z[2])  \\ look for a simpler polynomial
5495         ? pol = z[1]
5496         %5 = x^20 + 25*x^10 + 5
5497         ? a = subst(a.pol, x, z[2])  \\ a in the new coordinates
5498         %6 = Mod(-5/22*x^19 + 1/22*x^14 - 123/22*x^9 + 9/11*x^4, x^20 + 25*x^10 + 5)
5499
5500       The library syntax is polcompositum0"(P,Q,flag)".
5501
5502   polgalois"(x)"
5503       Galois group of the non-constant polynomial "x belongs to Q[X]". In the
5504       present version /usr/share/libpari23, "x" must be irreducible and the
5505       degree of "x" must be less than or equal to 7. On certain versions for
5506       which the data file of Galois resolvents has been installed (available
5507       in the Unix distribution as a separate package), degrees 8, 9, 10 and
5508       11 are also implemented.
5509
5510       The output is a 4-component vector "[n,s,k,name]" with the following
5511       meaning: "n" is the cardinality of the group, "s" is its signature ("s
5512       = 1" if the group is a subgroup of the alternating group "A_n", "s =
5513       -1" otherwise) and name is a character string containing name of the
5514       transitive group according to the GAP 4 transitive groups library by
5515       Alexander Hulpke.
5516
5517       "k" is more arbitrary and the choice made up to version 2.2.3 of PARI
5518       is rather unfortunate: for "n > 7", "k" is the numbering of the group
5519       among all transitive subgroups of "S_n", as given in ``The transitive
5520       groups of degree up to eleven'', G. Butler and J. McKay,
5521       \emph{Communications in Algebra}, vol. 11, 1983, pp. 863--911 (group
5522       "k" is denoted "T_k" there). And for "n <= 7", it was ad hoc, so as to
5523       ensure that a given triple would design a unique group.  Specifically,
5524       for polynomials of degree " <= 7", the groups are coded as follows,
5525       using standard notations
5526
5527       In degree 1: "S_1 = [1,1,1]".
5528
5529       In degree 2: "S_2 = [2,-1,1]".
5530
5531       In degree 3: "A_3 = C_3 = [3,1,1]", "S_3 = [6,-1,1]".
5532
5533       In degree 4: "C_4 = [4,-1,1]", "V_4 = [4,1,1]", "D_4 = [8,-1,1]", "A_4
5534       = [12,1,1]", "S_4 = [24,-1,1]".
5535
5536       In degree 5: "C_5 = [5,1,1]", "D_5 = [10,1,1]", "M_{20} = [20,-1,1]",
5537       "A_5 = [60,1,1]", "S_5 = [120,-1,1]".
5538
5539       In degree 6: "C_6 = [6,-1,1]", "S_3 = [6,-1,2]", "D_6 = [12,-1,1]",
5540       "A_4 = [12,1,1]", "G_{18} = [18,-1,1]", "S_4^ -= [24,-1,1]", "A_4 x C_2
5541       = [24,-1,2]", "S_4^ += [24,1,1]", "G_{36}^ -= [36,-1,1]", "G_{36}^ +=
5542       [36,1,1]", "S_4 x C_2 = [48,-1,1]", "A_5 = PSL_2(5) = [60,1,1]",
5543       "G_{72} = [72,-1,1]", "S_5 = PGL_2(5) = [120,-1,1]", "A_6 = [360,1,1]",
5544       "S_6 = [720,-1,1]".
5545
5546       In degree 7: "C_7 = [7,1,1]", "D_7 = [14,-1,1]", "M_{21} = [21,1,1]",
5547       "M_{42} = [42,-1,1]", "PSL_2(7) = PSL_3(2) = [168,1,1]", "A_7 =
5548       [2520,1,1]", "S_7 = [5040,-1,1]".
5549
5550       This is deprecated and obsolete, but for reasons of backward
5551       compatibility, we cannot change this behaviour yet. So you can use the
5552       default "new_galois_format" to switch to a consistent naming scheme,
5553       namely "k" is always the standard numbering of the group among all
5554       transitive subgroups of "S_n". If this default is in effect, the above
5555       groups will be coded as:
5556
5557       In degree 1: "S_1 = [1,1,1]".
5558
5559       In degree 2: "S_2 = [2,-1,1]".
5560
5561       In degree 3: "A_3 = C_3 = [3,1,1]", "S_3 = [6,-1,2]".
5562
5563       In degree 4: "C_4 = [4,-1,1]", "V_4 = [4,1,2]", "D_4 = [8,-1,3]", "A_4
5564       = [12,1,4]", "S_4 = [24,-1,5]".
5565
5566       In degree 5: "C_5 = [5,1,1]", "D_5 = [10,1,2]", "M_{20} = [20,-1,3]",
5567       "A_5 = [60,1,4]", "S_5 = [120,-1,5]".
5568
5569       In degree 6: "C_6 = [6,-1,1]", "S_3 = [6,-1,2]", "D_6 = [12,-1,3]",
5570       "A_4 = [12,1,4]", "G_{18} = [18,-1,5]", "A_4 x C_2 = [24,-1,6]", "S_4^
5571       += [24,1,7]", "S_4^ -= [24,-1,8]", "G_{36}^ -= [36,-1,9]", "G_{36}^ +=
5572       [36,1,10]", "S_4 x C_2 = [48,-1,11]", "A_5 = PSL_2(5) = [60,1,12]",
5573       "G_{72} = [72,-1,13]", "S_5 = PGL_2(5) = [120,-1,14]", "A_6 =
5574       [360,1,15]", "S_6 = [720,-1,16]".
5575
5576       In degree 7: "C_7 = [7,1,1]", "D_7 = [14,-1,2]", "M_{21} = [21,1,3]",
5577       "M_{42} = [42,-1,4]", "PSL_2(7) = PSL_3(2) = [168,1,5]", "A_7 =
5578       [2520,1,6]", "S_7 = [5040,-1,7]".
5579
5580       Warning: The method used is that of resolvent polynomials and is
5581       sensitive to the current precision. The precision is updated internally
5582       but, in very rare cases, a wrong result may be returned if the initial
5583       precision was not sufficient.
5584
5585       The library syntax is polgalois"(x,prec)". To enable the new format in
5586       library mode, set the global variable "new_galois_format" to 1.
5587
5588   polred"(x,{flag = 0},{fa})"
5589       finds polynomials with reasonably small coefficients defining subfields
5590       of the number field defined by "x".  One of the polynomials always
5591       defines Q (hence is equal to "x-1"), and another always defines the
5592       same number field as "x" if "x" is irreducible.  All "x" accepted by
5593       "nfinit" are also allowed here (e.g. non-monic polynomials, "nf",
5594       "bnf", "[x,Z_K_basis]").
5595
5596       The following binary digits of "flag" are significant:
5597
5598       1: possibly use a suborder of the maximal order. The primes dividing
5599       the index of the order chosen are larger than "primelimit" or divide
5600       integers stored in the "addprimes" table.
5601
5602       2: gives also elements. The result is a two-column matrix, the first
5603       column giving the elements defining these subfields, the second giving
5604       the corresponding minimal polynomials.
5605
5606       If "fa" is given, it is assumed that it is the two-column matrix of the
5607       factorization of the discriminant of the polynomial "x".
5608
5609       The library syntax is polred0"(x,flag,fa)", where an omitted "fa" is
5610       coded by "NULL". Also available are " polred(x)" and "
5611       factoredpolred(x,fa)", both corresponding to "flag = 0".
5612
5613   polredabs"(x,{flag = 0})"
5614       finds one of the polynomial defining the same number field as the one
5615       defined by "x", and such that the sum of the squares of the modulus of
5616       the roots (i.e. the "T_2"-norm) is minimal.  All "x" accepted by
5617       "nfinit" are also allowed here (e.g. non-monic polynomials, "nf",
5618       "bnf", "[x,Z_K_basis]").
5619
5620       Warning: this routine uses an exponential-time algorithm to enumerate
5621       all potential generators, and may be exceedingly slow when the number
5622       field has many subfields, hence a lot of elements of small "T_2"-norm.
5623       E.g. do not try it on the compositum of many quadratic fields, use
5624       "polred" instead.
5625
5626       The binary digits of "flag" mean
5627
5628       1: outputs a two-component row vector "[P,a]", where "P" is the default
5629       output and "a" is an element expressed on a root of the polynomial "P",
5630       whose minimal polynomial is equal to "x".
5631
5632       4: gives \emph{all} polynomials of minimal "T_2" norm (of the two
5633       polynomials P(x) and "P(-x)", only one is given).
5634
5635       16: possibly use a suborder of the maximal order. The primes dividing
5636       the index of the order chosen are larger than "primelimit" or divide
5637       integers stored in the "addprimes" table. In that case it may happen
5638       that the output polynomial does not have minimal "T_2" norm.
5639
5640       The library syntax is polredabs0"(x,flag)".
5641
5642   polredord"(x)"
5643       finds polynomials with reasonably small coefficients and of the same
5644       degree as that of "x" defining suborders of the order defined by "x".
5645       One of the polynomials always defines Q (hence is equal to "(x-1)^n",
5646       where "n" is the degree), and another always defines the same order as
5647       "x" if "x" is irreducible.
5648
5649       The library syntax is ordred"(x)".
5650
5651   poltschirnhaus"(x)"
5652       applies a random Tschirnhausen transformation to the polynomial "x",
5653       which is assumed to be non-constant and separable, so as to obtain a
5654       new equation for the étale algebra defined by "x". This is for instance
5655       useful when computing resolvents, hence is used by the "polgalois"
5656       function.
5657
5658       The library syntax is tschirnhaus"(x)".
5659
5660   rnfalgtobasis"(rnf,x)"
5661       expresses "x" on the relative integral basis. Here, "rnf" is a relative
5662       number field extension "L/K" as output by "rnfinit", and "x" an element
5663       of "L" in absolute form, i.e.  expressed as a polynomial or polmod with
5664       polmod coefficients, \emph{not} on the relative integral basis.
5665
5666       The library syntax is rnfalgtobasis"(rnf,x)".
5667
5668   rnfbasis"(bnf, M)"
5669       let "K" the field represented by bnf, as output by "bnfinit". "M" is a
5670       projective "Z_K"-module given by a pseudo-basis, as output by
5671       "rnfhnfbasis". The routine returns either a true "Z_K"-basis of "M" if
5672       it exists, or an "n+1"-element generating set of "M" if not, where "n"
5673       is the rank of "M" over "K".  (Note that "n" is the size of the pseudo-
5674       basis.)
5675
5676       It is allowed to use a polynomial "P" with coefficients in "K" instead
5677       of "M", in which case, "M" is defined as the ring of integers of
5678       "K[X]/(P)" ("P" is assumed irreducible over "K"), viewed as a
5679       "Z_K"-module.
5680
5681       The library syntax is rnfbasis"(bnf,x)".
5682
5683   rnfbasistoalg"(rnf,x)"
5684       computes the representation of "x" as a polmod with polmods
5685       coefficients. Here, "rnf" is a relative number field extension "L/K" as
5686       output by "rnfinit", and "x" an element of "L" expressed on the
5687       relative integral basis.
5688
5689       The library syntax is rnfbasistoalg"(rnf,x)".
5690
5691   rnfcharpoly"(nf,T,a,{v = x})"
5692       characteristic polynomial of "a" over "nf", where "a" belongs to the
5693       algebra defined by "T" over "nf", i.e. "nf[X]/(T)". Returns a
5694       polynomial in variable "v" ("x" by default).
5695
5696       The library syntax is rnfcharpoly"(nf,T,a,v)", where "v" is a variable
5697       number.
5698
5699   rnfconductor"(bnf,pol,{flag = 0})"
5700       given "bnf" as output by "bnfinit", and pol a relative polynomial
5701       defining an Abelian extension, computes the class field theory
5702       conductor of this Abelian extension. The result is a 3-component vector
5703       "[conductor,rayclgp,subgroup]", where conductor is the conductor of the
5704       extension given as a 2-component row vector "[f_0,f_ oo ]", rayclgp is
5705       the full ray class group corresponding to the conductor given as a
5706       3-component vector [h,cyc,gen] as usual for a group, and subgroup is a
5707       matrix in HNF defining the subgroup of the ray class group on the given
5708       generators gen. If "flag" is non-zero, check that pol indeed defines an
5709       Abelian extension, return 0 if it does not.
5710
5711       The library syntax is rnfconductor"(rnf,pol,flag)".
5712
5713   rnfdedekind"(nf,pol,pr)"
5714       given a number field "nf" as output by "nfinit" and a polynomial pol
5715       with coefficients in "nf" defining a relative extension "L" of "nf",
5716       evaluates the relative Dedekind criterion over the order defined by a
5717       root of pol for the prime ideal pr and outputs a 3-component vector as
5718       the result. The first component is a flag equal to 1 if the enlarged
5719       order could be proven to be pr-maximal and to 0 otherwise (it may be
5720       maximal in the latter case if pr is ramified in "L"), the second
5721       component is a pseudo-basis of the enlarged order and the third
5722       component is the valuation at pr of the order discriminant.
5723
5724       The library syntax is rnfdedekind"(nf,pol,pr)".
5725
5726   rnfdet"(nf,M)"
5727       given a pseudo-matrix "M" over the maximal order of "nf", computes its
5728       determinant.
5729
5730       The library syntax is rnfdet"(nf,M)".
5731
5732   rnfdisc"(nf,pol)"
5733       given a number field "nf" as output by "nfinit" and a polynomial pol
5734       with coefficients in "nf" defining a relative extension "L" of "nf",
5735       computes the relative discriminant of "L". This is a two-element row
5736       vector "[D,d]", where "D" is the relative ideal discriminant and "d" is
5737       the relative discriminant considered as an element of "nf^*/{nf^*}^2".
5738       The main variable of "nf" \emph{must} be of lower priority than that of
5739       pol, see "Label se:priority".
5740
5741       The library syntax is rnfdiscf"(bnf,pol)".
5742
5743   rnfeltabstorel"(rnf,x)"
5744       "rnf" being a relative number field extension "L/K" as output by
5745       "rnfinit" and "x" being an element of "L" expressed as a polynomial
5746       modulo the absolute equation "rnf.pol", computes "x" as an element of
5747       the relative extension "L/K" as a polmod with polmod coefficients.
5748
5749       The library syntax is rnfelementabstorel"(rnf,x)".
5750
5751   rnfeltdown"(rnf,x)"
5752       "rnf" being a relative number field extension "L/K" as output by
5753       "rnfinit" and "x" being an element of "L" expressed as a polynomial or
5754       polmod with polmod coefficients, computes "x" as an element of "K" as a
5755       polmod, assuming "x" is in "K" (otherwise an error will occur). If "x"
5756       is given on the relative integral basis, apply "rnfbasistoalg" first,
5757       otherwise PARI will believe you are dealing with a vector.
5758
5759       The library syntax is rnfelementdown"(rnf,x)".
5760
5761   rnfeltreltoabs"(rnf,x)"
5762       "rnf" being a relative number field extension "L/K" as output by
5763       "rnfinit" and "x" being an element of "L" expressed as a polynomial or
5764       polmod with polmod coefficients, computes "x" as an element of the
5765       absolute extension "L/Q" as a polynomial modulo the absolute equation
5766       "rnf.pol". If "x" is given on the relative integral basis, apply
5767       "rnfbasistoalg" first, otherwise PARI will believe you are dealing with
5768       a vector.
5769
5770       The library syntax is rnfelementreltoabs"(rnf,x)".
5771
5772   rnfeltup"(rnf,x)"
5773       "rnf" being a relative number field extension "L/K" as output by
5774       "rnfinit" and "x" being an element of "K" expressed as a polynomial or
5775       polmod, computes "x" as an element of the absolute extension "L/Q" as a
5776       polynomial modulo the absolute equation "rnf.pol". If "x" is given on
5777       the integral basis of "K", apply "nfbasistoalg" first, otherwise PARI
5778       will believe you are dealing with a vector.
5779
5780       The library syntax is rnfelementup"(rnf,x)".
5781
5782   rnfequation"(nf,pol,{flag = 0})"
5783       given a number field "nf" as output by "nfinit" (or simply a
5784       polynomial) and a polynomial pol with coefficients in "nf" defining a
5785       relative extension "L" of "nf", computes the absolute equation of "L"
5786       over Q.
5787
5788       If "flag" is non-zero, outputs a 3-component row vector "[z,a,k]",
5789       where "z" is the absolute equation of "L" over Q, as in the default
5790       behaviour, "a" expresses as an element of "L" a root "alpha" of the
5791       polynomial defining the base field "nf", and "k" is a small integer
5792       such that "theta = beta+kalpha" where "theta" is a root of "z" and
5793       "beta" a root of "pol".
5794
5795       The main variable of "nf" \emph{must} be of lower priority than that of
5796       pol (see "Label se:priority"). Note that for efficiency, this does not
5797       check whether the relative equation is irreducible over "nf", but only
5798       if it is squarefree. If it is reducible but squarefree, the result will
5799       be the absolute equation of the étale algebra defined by pol. If pol is
5800       not squarefree, an error message will be issued.
5801
5802       The library syntax is rnfequation0"(nf,pol,flag)".
5803
5804   rnfhnfbasis"(bnf,x)"
5805       given "bnf" as output by "bnfinit", and either a polynomial "x" with
5806       coefficients in "bnf" defining a relative extension "L" of "bnf", or a
5807       pseudo-basis "x" of such an extension, gives either a true "bnf"-basis
5808       of "L" in upper triangular Hermite normal form, if it exists, and
5809       returns 0 otherwise.
5810
5811       The library syntax is rnfhnfbasis"(nf,x)".
5812
5813   rnfidealabstorel"(rnf,x)"
5814       let "rnf" be a relative number field extension "L/K" as output by
5815       "rnfinit", and "x" an ideal of the absolute extension "L/Q" given by a
5816       Z-basis of elements of "L".  Returns the relative pseudo-matrix in HNF
5817       giving the ideal "x" considered as an ideal of the relative extension
5818       "L/K".
5819
5820       If "x" is an ideal in HNF form, associated to an nf structure, for
5821       instance as output by "idealhnf(nf,...)", use "rnfidealabstorel(rnf,
5822       nf.zk * x)" to convert it to a relative ideal.
5823
5824       The library syntax is rnfidealabstorel"(rnf,x)".
5825
5826   rnfidealdown"(rnf,x)"
5827       let "rnf" be a relative number field extension "L/K" as output by
5828       "rnfinit", and "x" an ideal of "L", given either in relative form or by
5829       a Z-basis of elements of "L" (see "Label se:rnfidealabstorel"), returns
5830       the ideal of "K" below "x", i.e. the intersection of "x" with "K".
5831
5832       The library syntax is rnfidealdown"(rnf,x)".
5833
5834   rnfidealhnf"(rnf,x)"
5835       "rnf" being a relative number field extension "L/K" as output by
5836       "rnfinit" and "x" being a relative ideal (which can be, as in the
5837       absolute case, of many different types, including of course elements),
5838       computes the HNF pseudo-matrix associated to "x", viewed as a
5839       "Z_K"-module.
5840
5841       The library syntax is rnfidealhermite"(rnf,x)".
5842
5843   rnfidealmul"(rnf,x,y)"
5844       "rnf" being a relative number field extension "L/K" as output by
5845       "rnfinit" and "x" and "y" being ideals of the relative extension "L/K"
5846       given by pseudo-matrices, outputs the ideal product, again as a
5847       relative ideal.
5848
5849       The library syntax is rnfidealmul"(rnf,x,y)".
5850
5851   rnfidealnormabs"(rnf,x)"
5852       "rnf" being a relative number field extension "L/K" as output by
5853       "rnfinit" and "x" being a relative ideal (which can be, as in the
5854       absolute case, of many different types, including of course elements),
5855       computes the norm of the ideal "x" considered as an ideal of the
5856       absolute extension "L/Q". This is identical to
5857       "idealnorm(rnfidealnormrel(rnf,x))", but faster.
5858
5859       The library syntax is rnfidealnormabs"(rnf,x)".
5860
5861   rnfidealnormrel"(rnf,x)"
5862       "rnf" being a relative number field extension "L/K" as output by
5863       "rnfinit" and "x" being a relative ideal (which can be, as in the
5864       absolute case, of many different types, including of course elements),
5865       computes the relative norm of "x" as a ideal of "K" in HNF.
5866
5867       The library syntax is rnfidealnormrel"(rnf,x)".
5868
5869   rnfidealreltoabs"(rnf,x)"
5870       "rnf" being a relative number field extension "L/K" as output by
5871       "rnfinit" and "x" being a relative ideal, gives the ideal "xZ_L" as an
5872       absolute ideal of "L/Q", in the form of a Z-basis, given by a vector of
5873       polynomials (modulo "rnf.pol").  The following routine might be useful:
5874
5875             \\ return y = rnfidealreltoabs(rnf,...) as an ideal in HNF form
5876             \\ associated to nf = nfinit( rnf.pol );
5877             idealgentoHNF(nf, y) = mathnf( Mat( nfalgtobasis(nf, y) ) );
5878
5879       The library syntax is rnfidealreltoabs"(rnf,x)".
5880
5881   rnfidealtwoelt"(rnf,x)"
5882       "rnf" being a relative number field extension "L/K" as output by
5883       "rnfinit" and "x" being an ideal of the relative extension "L/K" given
5884       by a pseudo-matrix, gives a vector of two generators of "x" over "Z_L"
5885       expressed as polmods with polmod coefficients.
5886
5887       The library syntax is rnfidealtwoelement"(rnf,x)".
5888
5889   rnfidealup"(rnf,x)"
5890       "rnf" being a relative number field extension "L/K" as output by
5891       "rnfinit" and "x" being an ideal of "K", gives the ideal "xZ_L" as an
5892       absolute ideal of "L/Q", in the form of a Z-basis, given by a vector of
5893       polynomials (modulo "rnf.pol").  The following routine might be useful:
5894
5895             \\ return y = rnfidealup(rnf,...) as an ideal in HNF form
5896             \\ associated to nf = nfinit( rnf.pol );
5897             idealgentoHNF(nf, y) = mathnf( Mat( nfalgtobasis(nf, y) ) );
5898
5899       The library syntax is rnfidealup"(rnf,x)".
5900
5901   rnfinit"(nf,pol)"
5902       "nf" being a number field in "nfinit" format considered as base field,
5903       and pol a polynomial defining a relative extension over "nf", this
5904       computes all the necessary data to work in the relative extension. The
5905       main variable of pol must be of higher priority (see "Label
5906       se:priority") than that of "nf", and the coefficients of pol must be in
5907       "nf".
5908
5909       The result is a row vector, whose components are technical. In the
5910       following description, we let "K" be the base field defined by "nf",
5911       "m" the degree of the base field, "n" the relative degree, "L" the
5912       large field (of relative degree "n" or absolute degree "nm"), "r_1" and
5913       "r_2" the number of real and complex places of "K".
5914
5915       "rnf[1]" contains the relative polynomial pol.
5916
5917       "rnf[2]" is currently unused.
5918
5919       "rnf[3]" is a two-component row vector "[\goth{d}(L/K),s]" where
5920       "\goth{d}(L/K)" is the relative ideal discriminant of "L/K" and "s" is
5921       the discriminant of "L/K" viewed as an element of "K^*/(K^*)^2", in
5922       other words it is the output of "rnfdisc".
5923
5924       "rnf[4]" is the ideal index "\goth{f}", i.e. such that "d(pol)Z_K =
5925       \goth{f}^2\goth{d}(L/K)".
5926
5927       "rnf[5]" is currently unused.
5928
5929       "rnf[6]" is currently unused.
5930
5931       "rnf[7]" is a two-component row vector, where the first component is
5932       the relative integral pseudo basis expressed as polynomials (in the
5933       variable of "pol") with polmod coefficients in "nf", and the second
5934       component is the ideal list of the pseudobasis in HNF.
5935
5936       "rnf[8]" is the inverse matrix of the integral basis matrix, with
5937       coefficients polmods in "nf".
5938
5939       "rnf[9]" is currently unused.
5940
5941       "rnf[10]" is "nf".
5942
5943       "rnf[11]" is the output of "rnfequation(nf, pol, 1)". Namely, a vector
5944       vabs with 3 entries describing the \emph{absolute} extension "L/Q".
5945       "vabs[1]" is an absolute equation, more conveniently obtained as
5946       "rnf.pol". "vabs[2]" expresses the generator "alpha" of the number
5947       field "nf" as a polynomial modulo the absolute equation "vabs[1]".
5948       "vabs[3]" is a small integer "k" such that, if "beta" is an abstract
5949       root of pol and "alpha" the generator of "nf", the generator whose root
5950       is vabs will be "beta + k alpha". Note that one must be very careful if
5951       "k ! = 0" when dealing simultaneously with absolute and relative
5952       quantities since the generator chosen for the absolute extension is not
5953       the same as for the relative one. If this happens, one can of course go
5954       on working, but we strongly advise to change the relative polynomial so
5955       that its root will be "beta + k alpha". Typically, the GP instruction
5956       would be
5957
5958       "pol = subst(pol, x, x - k*Mod(y,nf.pol))"
5959
5960       "rnf[12]" is by default unused and set equal to 0. This field is used
5961       to store further information about the field as it becomes available
5962       (which is rarely needed, hence would be too expensive to compute during
5963       the initial "rnfinit" call).
5964
5965       The library syntax is rnfinitalg"(nf,pol,prec)".
5966
5967   rnfisfree"(bnf,x)"
5968       given "bnf" as output by "bnfinit", and either a polynomial "x" with
5969       coefficients in "bnf" defining a relative extension "L" of "bnf", or a
5970       pseudo-basis "x" of such an extension, returns true (1) if "L/bnf" is
5971       free, false (0) if not.
5972
5973       The library syntax is rnfisfree"(bnf,x)", and the result is a "long".
5974
5975   rnfisnorm"(T,a,{flag = 0})"
5976       similar to "bnfisnorm" but in the relative case. "T" is as output by
5977       "rnfisnorminit" applied to the extension "L/K". This tries to decide
5978       whether the element "a" in "K" is the norm of some "x" in the extension
5979       "L/K".
5980
5981       The output is a vector "[x,q]", where "a = \Norm(x)*q". The algorithm
5982       looks for a solution "x" which is an "S"-integer, with "S" a list of
5983       places of "K" containing at least the ramified primes, the generators
5984       of the class group of "L", as well as those primes dividing "a". If
5985       "L/K" is Galois, then this is enough; otherwise, "flag" is used to add
5986       more primes to "S": all the places above the primes "p <= flag"
5987       (resp. "p|flag") if "flag > 0" (resp. "flag < 0").
5988
5989       The answer is guaranteed (i.e. "a" is a norm iff "q = 1") if the field
5990       is Galois, or, under GRH, if "S" contains all primes less than "12 log
5991       ^2|\disc(M)|", where "M" is the normal closure of "L/K".
5992
5993       If "rnfisnorminit" has determined (or was told) that "L/K" is Galois,
5994       and "flag  ! = 0", a Warning is issued (so that you can set "flag = 1"
5995       to check whether "L/K" is known to be Galois, according to "T").
5996       Example:
5997
5998         bnf = bnfinit(y^3 + y^2 - 2*y - 1);
5999         p = x^2 + Mod(y^2 + 2*y + 1, bnf.pol);
6000         T = rnfisnorminit(bnf, p);
6001         rnfisnorm(T, 17)
6002
6003       checks whether 17 is a norm in the Galois extension "Q(beta) /
6004       Q(alpha)", where "alpha^3 + alpha^2 - 2alpha - 1 = 0" and "beta^2 +
6005       alpha^2 + 2alpha + 1 = 0" (it is).
6006
6007       The library syntax is rnfisnorm"(T,x,flag)".
6008
6009   rnfisnorminit"(pol,polrel,{flag = 2})"
6010       let "K" be defined by a root of pol, and "L/K" the extension defined by
6011       the polynomial polrel. As usual, pol can in fact be an nf, or bnf, etc;
6012       if pol has degree 1 (the base field is Q), polrel is also allowed to be
6013       an nf, etc. Computes technical data needed by "rnfisnorm" to solve norm
6014       equations "Nx = a", for "x" in "L", and "a" in "K".
6015
6016       If "flag = 0", do not care whether "L/K" is Galois or not.
6017
6018       If "flag = 1", "L/K" is assumed to be Galois (unchecked), which speeds
6019       up "rnfisnorm".
6020
6021       If "flag = 2", let the routine determine whether "L/K" is Galois.
6022
6023       The library syntax is rnfisnorminit"(pol,polrel,flag)".
6024
6025   rnfkummer"(bnr,{subgroup},{deg = 0})"
6026       bnr being as output by "bnrinit", finds a relative equation for the
6027       class field corresponding to the module in bnr and the given congruence
6028       subgroup (the full ray class field if subgroup is omitted).  If deg is
6029       positive, outputs the list of all relative equations of degree deg
6030       contained in the ray class field defined by bnr, with the \emph{same}
6031       conductor as "(bnr, subgroup)".
6032
6033       Warning: this routine only works for subgroups of prime index. It uses
6034       Kummer theory, adjoining necessary roots of unity (it needs to compute
6035       a tough "bnfinit" here), and finds a generator via Hecke's
6036       characterization of ramification in Kummer extensions of prime degree.
6037       If your extension does not have prime degree, for the time being, you
6038       have to split it by hand as a tower / compositum of such extensions.
6039
6040       The library syntax is rnfkummer"(bnr,subgroup,deg,prec)", where deg is
6041       a "long" and an omitted subgroup is coded as "NULL"
6042
6043   rnflllgram"(nf,pol,order)"
6044       given a polynomial pol with coefficients in nf defining a relative
6045       extension "L" and a suborder order of "L" (of maximal rank), as output
6046       by "rnfpseudobasis""(nf,pol)" or similar, gives "[[neworder],U]", where
6047       neworder is a reduced order and "U" is the unimodular transformation
6048       matrix.
6049
6050       The library syntax is rnflllgram"(nf,pol,order,prec)".
6051
6052   rnfnormgroup"(bnr,pol)"
6053       bnr being a big ray class field as output by "bnrinit" and pol a
6054       relative polynomial defining an Abelian extension, computes the norm
6055       group (alias Artin or Takagi group) corresponding to the Abelian
6056       extension of "bnf = bnr[1]" defined by pol, where the module
6057       corresponding to bnr is assumed to be a multiple of the conductor
6058       (i.e. pol defines a subextension of bnr). The result is the HNF
6059       defining the norm group on the given generators of "bnr[5][3]". Note
6060       that neither the fact that pol defines an Abelian extension nor the
6061       fact that the module is a multiple of the conductor is checked. The
6062       result is undefined if the assumption is not correct.
6063
6064       The library syntax is rnfnormgroup"(bnr,pol)".
6065
6066   rnfpolred"(nf,pol)"
6067       relative version of "polred".  Given a monic polynomial pol with
6068       coefficients in "nf", finds a list of relative polynomials defining
6069       some subfields, hopefully simpler and containing the original field. In
6070       the present version /usr/share/libpari23, this is slower and less
6071       efficient than "rnfpolredabs".
6072
6073       The library syntax is rnfpolred"(nf,pol,prec)".
6074
6075   rnfpolredabs"(nf,pol,{flag = 0})"
6076       relative version of "polredabs". Given a monic polynomial pol with
6077       coefficients in "nf", finds a simpler relative polynomial defining the
6078       same field. The binary digits of "flag" mean
6079
6080       1: returns "[P,a]" where "P" is the default output and "a" is an
6081       element expressed on a root of "P" whose characteristic polynomial is
6082       pol
6083
6084       2: returns an absolute polynomial (same as
6085       "rnfequation(nf,rnfpolredabs(nf,pol))" but faster).
6086
6087       16: possibly use a suborder of the maximal order. This is slower than
6088       the default when the relative discriminant is smooth, and much faster
6089       otherwise.  See "Label se:polredabs".
6090
6091       Remark. In the present implementation, this is both faster and much
6092       more efficient than "rnfpolred", the difference being more dramatic
6093       than in the absolute case. This is because the implementation of
6094       "rnfpolred" is based on (a partial implementation of) an incomplete
6095       reduction theory of lattices over number fields, the function
6096       "rnflllgram", which deserves to be improved.
6097
6098       The library syntax is rnfpolredabs"(nf,pol,flag,prec)".
6099
6100   rnfpseudobasis"(nf,pol)"
6101       given a number field "nf" as output by "nfinit" and a polynomial pol
6102       with coefficients in "nf" defining a relative extension "L" of "nf",
6103       computes a pseudo-basis "(A,I)" for the maximal order "Z_L" viewed as a
6104       "Z_K"-module, and the relative discriminant of "L". This is output as a
6105       four-element row vector "[A,I,D,d]", where "D" is the relative ideal
6106       discriminant and "d" is the relative discriminant considered as an
6107       element of "nf^*/{nf^*}^2".
6108
6109       The library syntax is rnfpseudobasis"(nf,pol)".
6110
6111   rnfsteinitz"(nf,x)"
6112       given a number field "nf" as output by "nfinit" and either a polynomial
6113       "x" with coefficients in "nf" defining a relative extension "L" of
6114       "nf", or a pseudo-basis "x" of such an extension as output for example
6115       by "rnfpseudobasis", computes another pseudo-basis "(A,I)" (not in HNF
6116       in general) such that all the ideals of "I" except perhaps the last one
6117       are equal to the ring of integers of "nf", and outputs the four-
6118       component row vector "[A,I,D,d]" as in "rnfpseudobasis". The name of
6119       this function comes from the fact that the ideal class of the last
6120       ideal of "I", which is well defined, is the Steinitz class of the
6121       "Z_K"-module "Z_L" (its image in "SK_0(Z_K)").
6122
6123       The library syntax is rnfsteinitz"(nf,x)".
6124
6125   subgrouplist"(bnr,{bound},{flag = 0})"
6126       bnr being as output by "bnrinit" or a list of cyclic components of a
6127       finite Abelian group "G", outputs the list of subgroups of "G".
6128       Subgroups are given as HNF left divisors of the SNF matrix
6129       corresponding to "G".
6130
6131       Warning: the present implementation cannot treat a group "G" where any
6132       cyclic factor has more than "2^{31}", resp. "2^{63}" elements on a
6133       32-bit, resp. 64-bit architecture. "forsubgroup" is a bit more general
6134       and can handle "G" if all "p"-Sylow subgroups of "G" satisfy the
6135       condition above.
6136
6137       If "flag = 0" (default) and bnr is as output by "bnrinit", gives only
6138       the subgroups whose modulus is the conductor. Otherwise, the modulus is
6139       not taken into account.
6140
6141       If bound is present, and is a positive integer, restrict the output to
6142       subgroups of index less than bound. If bound is a vector containing a
6143       single positive integer "B", then only subgroups of index exactly equal
6144       to "B" are computed. For instance
6145
6146         %2 = [[2, 1; 0, 1], [1, 0; 0, 2], [2, 0; 0, 1], [3, 0; 0, 1], [1, 0; 0, 1]]
6147         ? subgrouplist([6,2],[3])  \\ index less than 3
6148         %2 = [[2, 1; 0, 1], [1, 0; 0, 2], [2, 0; 0, 1], [3, 0; 0, 1], [1, 0; 0, 1]]
6149         ? subgrouplist([6,2],[3])  \\ index 3
6150         %3 = [[3, 0; 0, 1]]
6151         ? bnr = bnrinit(bnfinit(x), [120,[1]], 1);
6152         ? L = subgrouplist(bnr, [8]);
6153
6154       In the last example, "L" corresponds to the 24 subfields of
6155       "Q(zeta_{120})", of degree 8 and conductor "120 oo " (by setting flag,
6156       we see there are a total of 43 subgroups of degree 8).
6157
6158         ? vector(#L, i, galoissubcyclo(bnr, L[i]))
6159
6160       will produce their equations. (For a general base field, you would have
6161       to rely on "bnrstark", or "rnfkummer".)
6162
6163       The library syntax is subgrouplist0"(bnr,bound,flag)", where "flag" is
6164       a long integer, and an omitted bound is coded by "NULL".
6165
6166   zetak"(znf,x,{flag = 0})"
6167       znf being a number field initialized by "zetakinit" (\emph{not} by
6168       "nfinit"), computes the value of the Dedekind zeta function of the
6169       number field at the complex number "x". If "flag = 1" computes Dedekind
6170       "Lambda" function instead (i.e. the product of the Dedekind zeta
6171       function by its gamma and exponential factors).
6172
6173       CAVEAT. This implementation is not satisfactory and must be rewritten.
6174       In particular
6175
6176       "*" The accuracy of the result depends in an essential way on the
6177       accuracy of both the "zetakinit" program and the current accuracy.  Be
6178       wary in particular that "x" of large imaginary part or, on the
6179       contrary, very close to an ordinary integer will suffer from precision
6180       loss, yielding fewer significant digits than expected. Computing with
6181       28 eight digits of relative accuracy, we have
6182
6183         ? zeta(3)
6184             %1 = 1.202056903159594285399738161
6185             ? zeta(3-1e-20)
6186             %2 = 1.202056903159594285401719424
6187             ? zetak(zetakinit(x), 3-1e-20)
6188             %3 = 1.2020569031595952919  \\ 5 digits are wrong
6189             ? zetak(zetakinit(x), 3-1e-28)
6190             %4 = -25.33411749           \\ junk
6191
6192       "*" As the precision increases, results become unexpectedly completely
6193       wrong:
6194
6195             ? \p100
6196             ? zetak(zetakinit(x^2-5), -1) - 1/30
6197             %1 = 7.26691813 E-108    \\ perfect
6198             ? \p150
6199             ? zetak(zetakinit(x^2-5), -1) - 1/30
6200             %2 = -2.486113578 E-156  \\ perfect
6201             ? \p200
6202             ? zetak(zetakinit(x^2-5), -1) - 1/30
6203             %3 = 4.47... E-75        \\ more than half of the digits are wrong
6204             ? \p250
6205             ? zetak(zetakinit(x^2-5), -1) - 1/30
6206             %4 = 1.6 E43             \\ junk
6207
6208       The library syntax is glambdak"(znf,x,prec)" or " gzetak(znf,x,prec)".
6209
6210   zetakinit"(x)"
6211       computes a number of initialization data concerning the number field
6212       defined by the polynomial "x" so as to be able to compute the Dedekind
6213       zeta and lambda functions (respectively zetak(x) and "zetak(x,1)").
6214       This function calls in particular the "bnfinit" program. The result is
6215       a 9-component vector "v" whose components are very technical and cannot
6216       really be used by the user except through the "zetak" function. The
6217       only component which can be used if it has not been computed already is
6218       "v[1][4]" which is the result of the "bnfinit" call.
6219
6220       This function is very inefficient and should be rewritten. It needs to
6221       computes millions of coefficients of the corresponding Dirichlet series
6222       if the precision is big. Unless the discriminant is small it will not
6223       be able to handle more than 9 digits of relative precision. For
6224       instance, "zetakinit(x^8 - 2)" needs 440MB of memory at default
6225       precision.
6226
6227       The library syntax is initzeta"(x)".
6228

Polynomials and power series

6230       We group here all functions which are specific to polynomials or power
6231       series. Many other functions which can be applied on these objects are
6232       described in the other sections. Also, some of the functions described
6233       here can be applied to other types.
6234
6235   O"(p^e)"
6236       if "p" is an integer greater than 2, returns a "p"-adic 0 of precision
6237       "e". In all other cases, returns a power series zero with precision
6238       given by "e v", where "v" is the "X"-adic valuation of "p" with respect
6239       to its main variable.
6240
6241       The library syntax is zeropadic"(p,e)" for a "p"-adic and "
6242       zeroser(v,e)" for a power series zero in variable "v", which is a
6243       "long". The precision "e" is a "long".
6244
6245   deriv"(x,{v})"
6246       derivative of "x" with respect to the main variable if "v" is omitted,
6247       and with respect to "v" otherwise. The derivative of a scalar type is
6248       zero, and the derivative of a vector or matrix is done componentwise.
6249       One can use "x'" as a shortcut if the derivative is with respect to the
6250       main variable of "x".
6251
6252       By definition, the main variable of a "t_POLMOD" is the main variable
6253       among the coefficients from its two polynomial components
6254       (representative and modulus); in other words, assuming a polmod
6255       represents an element of "R[X]/(T(X))", the variable "X" is a mute
6256       variable and the derivative is taken with respect to the main variable
6257       used in the base ring "R".
6258
6259       The library syntax is deriv"(x,v)", where "v" is a "long", and an
6260       omitted "v" is coded as "-1". When "x" is a "t_POL", derivpol(x) is a
6261       shortcut for "deriv(x, -1)".
6262
6263   eval"(x)"
6264       replaces in "x" the formal variables by the values that have been
6265       assigned to them after the creation of "x". This is mainly useful in
6266       GP, and not in library mode. Do not confuse this with substitution (see
6267       "subst").
6268
6269       If "x" is a character string, eval(x) executes "x" as a GP command, as
6270       if directly input from the keyboard, and returns its output. For
6271       convenience, "x" is evaluated as if "strictmatch" was off. In
6272       particular, unused characters at the end of "x" do not prevent its
6273       evaluation:
6274
6275             ? eval("1a")
6276             % 1 = 1
6277
6278       The library syntax is geval"(x)". The more basic functions "
6279       poleval(q,x)", " qfeval(q,x)", and " hqfeval(q,x)" evaluate "q" at "x",
6280       where "q" is respectively assumed to be a polynomial, a quadratic form
6281       (a symmetric matrix), or an Hermitian form (an Hermitian complex
6282       matrix).
6283
6284   factorpadic"(pol,p,r,{flag = 0})"
6285       "p"-adic factorization of the polynomial pol to precision "r", the
6286       result being a two-column matrix as in "factor". The factors are
6287       normalized so that their leading coefficient is a power of "p". "r"
6288       must be strictly larger than the "p"-adic valuation of the discriminant
6289       of pol for the result to make any sense. The method used is a modified
6290       version of the round 4 algorithm of Zassenhaus.
6291
6292       If "flag = 1", use an algorithm due to Buchmann and Lenstra, which is
6293       usually less efficient.
6294
6295       The library syntax is factorpadic4"(pol,p,r)", where "r" is a "long"
6296       integer.
6297
6298   intformal"(x,{v})"
6299       formal integration of "x" with respect to the main variable if "v" is
6300       omitted, with respect to the variable "v" otherwise. Since PARI does
6301       not know about ``abstract'' logarithms (they are immediately evaluated,
6302       if only to a power series), logarithmic terms in the result will yield
6303       an error. "x" can be of any type. When "x" is a rational function, it
6304       is assumed that the base ring is an integral domain of characteristic
6305       zero.
6306
6307       The library syntax is integ"(x,v)", where "v" is a "long" and an
6308       omitted "v" is coded as "-1".
6309
6310   padicappr"(pol,a)"
6311       vector of "p"-adic roots of the polynomial "pol" congruent to the
6312       "p"-adic number "a" modulo "p", and with the same "p"-adic precision as
6313       "a". The number "a" can be an ordinary "p"-adic number (type "t_PADIC",
6314       i.e. an element of "Z_p") or can be an integral element of a finite
6315       extension of "Q_p", given as a "t_POLMOD" at least one of whose
6316       coefficients is a "t_PADIC". In this case, the result is the vector of
6317       roots belonging to the same extension of "Q_p" as "a".
6318
6319       The library syntax is padicappr"(pol,a)".
6320
6321   polcoeff"(x,s,{v})"
6322       coefficient of degree "s" of the polynomial "x", with respect to the
6323       main variable if "v" is omitted, with respect to "v" otherwise. Also
6324       applies to power series, scalars (polynomial of degree 0), and to
6325       rational functions provided the denominator is a monomial.
6326
6327       The library syntax is polcoeff0"(x,s,v)", where "v" is a "long" and an
6328       omitted "v" is coded as "-1". Also available is " truecoeff(x,v)".
6329
6330   poldegree"(x,{v})"
6331       degree of the polynomial "x" in the main variable if "v" is omitted, in
6332       the variable "v" otherwise.
6333
6334       The degree of 0 is a fixed negative number, whose exact value should
6335       not be used. The degree of a non-zero scalar is 0. Finally, when "x" is
6336       a non-zero polynomial or rational function, returns the ordinary degree
6337       of "x". Raise an error otherwise.
6338
6339       The library syntax is poldegree"(x,v)", where "v" and the result are
6340       "long"s (and an omitted "v" is coded as "-1"). Also available is "
6341       degree(x)", which is equivalent to "poldegree(x,-1)".
6342
6343   polcyclo"(n,{v = x})"
6344       "n"-th cyclotomic polynomial, in variable "v" ("x" by default). The
6345       integer "n" must be positive.
6346
6347       The library syntax is cyclo"(n,v)", where "n" and "v" are "long"
6348       integers ("v" is a variable number, usually obtained through "varn").
6349
6350   poldisc"(pol,{v})"
6351       discriminant of the polynomial pol in the main variable is "v" is
6352       omitted, in "v" otherwise. The algorithm used is the subresultant
6353       algorithm.
6354
6355       The library syntax is poldisc0"(x,v)". Also available is " discsr(x)",
6356       equivalent to "poldisc0(x,-1)".
6357
6358   poldiscreduced"(f)"
6359       reduced discriminant vector of the (integral, monic) polynomial "f".
6360       This is the vector of elementary divisors of
6361       "Z[alpha]/f'(alpha)Z[alpha]", where "alpha" is a root of the polynomial
6362       "f". The components of the result are all positive, and their product
6363       is equal to the absolute value of the discriminant of "f".
6364
6365       The library syntax is reduceddiscsmith"(x)".
6366
6367   polhensellift"(x, y, p, e)"
6368       given a prime "p", an integral polynomial "x" whose leading coefficient
6369       is a "p"-unit, a vector "y" of integral polynomials that are pairwise
6370       relatively prime modulo "p", and whose product is congruent to "x"
6371       modulo "p", lift the elements of "y" to polynomials whose product is
6372       congruent to "x" modulo "p^e".
6373
6374       The library syntax is polhensellift"(x,y,p,e)" where "e" must be a
6375       "long".
6376
6377   polinterpolate"(xa,{ya},{v = x},{&e})"
6378       given the data vectors "xa" and "ya" of the same length "n" ("xa"
6379       containing the "x"-coordinates, and "ya" the corresponding
6380       "y"-coordinates), this function finds the interpolating polynomial
6381       passing through these points and evaluates it at "v". If "ya" is
6382       omitted, return the polynomial interpolating the "(i,xa[i])". If
6383       present, "e" will contain an error estimate on the returned value.
6384
6385       The library syntax is polint"(xa,ya,v,&e)", where "e" will contain an
6386       error estimate on the returned value.
6387
6388   polisirreducible"(pol)"
6389       pol being a polynomial (univariate in the present version
6390       /usr/share/libpari23), returns 1 if pol is non-constant and
6391       irreducible, 0 otherwise. Irreducibility is checked over the smallest
6392       base field over which pol seems to be defined.
6393
6394       The library syntax is gisirreducible"(pol)".
6395
6396   pollead"(x,{v})"
6397       leading coefficient of the polynomial or power series "x". This is
6398       computed with respect to the main variable of "x" if "v" is omitted,
6399       with respect to the variable "v" otherwise.
6400
6401       The library syntax is pollead"(x,v)", where "v" is a "long" and an
6402       omitted "v" is coded as "-1". Also available is " leading_term(x)".
6403
6404   pollegendre"(n,{v = x})"
6405       creates the "n^{th}" Legendre polynomial, in variable "v".
6406
6407       The library syntax is legendre"(n)", where "x" is a "long".
6408
6409   polrecip"(pol)"
6410       reciprocal polynomial of pol, i.e. the coefficients are in reverse
6411       order. pol must be a polynomial.
6412
6413       The library syntax is polrecip"(x)".
6414
6415   polresultant"(x,y,{v},{flag = 0})"
6416       resultant of the two polynomials "x" and "y" with exact entries, with
6417       respect to the main variables of "x" and "y" if "v" is omitted, with
6418       respect to the variable "v" otherwise. The algorithm assumes the base
6419       ring is a domain.
6420
6421       If "flag = 0", uses the subresultant algorithm.
6422
6423       If "flag = 1", uses the determinant of Sylvester's matrix instead (here
6424       "x" and "y" may have non-exact coefficients).
6425
6426       If "flag = 2", uses Ducos's modified subresultant algorithm. It should
6427       be much faster than the default if the coefficient ring is complicated
6428       (e.g multivariate polynomials or huge coefficients), and slightly
6429       slower otherwise.
6430
6431       The library syntax is polresultant0"(x,y,v,flag)", where "v" is a
6432       "long" and an omitted "v" is coded as "-1". Also available are "
6433       subres(x,y)" ("flag = 0") and " resultant2(x,y)" ("flag = 1").
6434
6435   polroots"(pol,{flag = 0})"
6436       complex roots of the polynomial pol, given as a column vector where
6437       each root is repeated according to its multiplicity. The precision is
6438       given as for transcendental functions: in GP it is kept in the variable
6439       "realprecision" and is transparent to the user, but it must be
6440       explicitly given as a second argument in library mode.
6441
6442       The algorithm used is a modification of A. Schönhage's root-finding
6443       algorithm, due to and implemented by X. Gourdon. Barring bugs, it is
6444       guaranteed to converge and to give the roots to the required accuracy.
6445
6446       If "flag = 1", use a variant of the Newton-Raphson method, which is
6447       \emph{not} guaranteed to converge, but is rather fast. If you get the
6448       messages ``too many iterations in roots'' or ``INTERNAL ERROR:
6449       incorrect result in roots'', use the default algorithm. This used to be
6450       the default root-finding function in PARI until version 1.39.06.
6451
6452       The library syntax is roots"(pol,prec)" or " rootsold(pol,prec)".
6453
6454   polrootsmod"(pol,p,{flag = 0})"
6455       row vector of roots modulo "p" of the polynomial pol. The particular
6456       non-prime value "p = 4" is accepted, mainly for 2-adic computations.
6457       Multiple roots are \emph{not} repeated.
6458
6459       If "p" is very small, you may try setting "flag = 1", which uses a
6460       naive search.
6461
6462       The library syntax is rootmod"(pol,p)" ("flag = 0") or "
6463       rootmod2(pol,p)" ("flag = 1").
6464
6465   polrootspadic"(pol,p,r)"
6466       row vector of "p"-adic roots of the polynomial pol, given to "p"-adic
6467       precision "r". Multiple roots are \emph{not} repeated. "p" is assumed
6468       to be a prime, and pol to be non-zero modulo "p". Note that this is not
6469       the same as the roots in "Z/p^rZ", rather it gives approximations in
6470       "Z/p^rZ" of the true roots living in "Q_p".
6471
6472       If pol has inexact "t_PADIC" coefficients, this is not always well-
6473       defined; in this case, the equation is first made integral, then lifted
6474       to Z. Hence the roots given are approximations of the roots of a
6475       polynomial which is "p"-adically close to the input.
6476
6477       The library syntax is rootpadic"(pol,p,r)", where "r" is a "long".
6478
6479   polsturm"(pol,{a},{b})"
6480       number of real roots of the real polynomial pol in the interval
6481       "]a,b]", using Sturm's algorithm. "a" (resp. "b") is taken to be "- oo
6482       " (resp. "+ oo ") if omitted.
6483
6484       The library syntax is sturmpart"(pol,a,b)". Use "NULL" to omit an
6485       argument.  " sturm(pol)" is equivalent to " sturmpart(pol,NULL,NULL)".
6486       The result is a "long".
6487
6488   polsubcyclo"(n,d,{v = x})"
6489       gives polynomials (in variable "v") defining the sub-Abelian extensions
6490       of degree "d" of the cyclotomic field "Q(zeta_n)", where "d | phi(n)".
6491
6492       If there is exactly one such extension the output is a polynomial, else
6493       it is a vector of polynomials, eventually empty.
6494
6495       To be sure to get a vector, you can use "concat([],polsubcyclo(n,d))"
6496
6497       The function "galoissubcyclo" allows to specify more closely which sub-
6498       Abelian extension should be computed.
6499
6500       The library syntax is polsubcyclo"(n,d,v)", where "n", "d" and "v" are
6501       "long" and "v" is a variable number. When "(Z/nZ)^*" is cyclic, you can
6502       use " subcyclo(n,d,v)", where "n", "d" and "v" are "long" and "v" is a
6503       variable number.
6504
6505   polsylvestermatrix"(x,y)"
6506       forms the Sylvester matrix corresponding to the two polynomials "x" and
6507       "y", where the coefficients of the polynomials are put in the columns
6508       of the matrix (which is the natural direction for solving equations
6509       afterwards). The use of this matrix can be essential when dealing with
6510       polynomials with inexact entries, since polynomial Euclidean division
6511       doesn't make much sense in this case.
6512
6513       The library syntax is sylvestermatrix"(x,y)".
6514
6515   polsym"(x,n)"
6516       creates the vector of the symmetric powers of the roots of the
6517       polynomial "x" up to power "n", using Newton's formula.
6518
6519       The library syntax is polsym"(x)".
6520
6521   poltchebi"(n,{v = x})"
6522       creates the "n^{th}" Chebyshev polynomial "T_n" of the first kind in
6523       variable "v".
6524
6525       The library syntax is tchebi"(n,v)", where "n" and "v" are "long"
6526       integers ("v" is a variable number).
6527
6528   polzagier"(n,m)"
6529       creates Zagier's polynomial "P_n^{(m)}" used in the functions "sumalt"
6530       and "sumpos" (with "flag = 1"). One must have "m <= n". The exact
6531       definition can be found in ``Convergence acceleration of alternating
6532       series'', Cohen et al., Experiment. Math., vol. 9, 2000, pp. 3--12.
6533
6534       The library syntax is polzagreel"(n,m,prec)" if the result is only
6535       wanted as a polynomial with real coefficients to the precision "prec",
6536       or " polzag(n,m)" if the result is wanted exactly, where "n" and "m"
6537       are "long"s.
6538
6539   serconvol"(x,y)"
6540       convolution (or Hadamard product) of the two power series "x" and "y";
6541       in other words if "x = sum a_k*X^k" and "y = sum b_k*X^k" then
6542       "serconvol(x,y) = sum a_k*b_k*X^k".
6543
6544       The library syntax is convol"(x,y)".
6545
6546   serlaplace"(x)"
6547       "x" must be a power series with non-negative exponents. If "x = sum
6548       (a_k/k!)*X^k" then the result is "sum a_k*X^k".
6549
6550       The library syntax is laplace"(x)".
6551
6552   serreverse"(x)"
6553       reverse power series (i.e. "x^{-1}", not "1/x") of "x". "x" must be a
6554       power series whose valuation is exactly equal to one.
6555
6556       The library syntax is recip"(x)".
6557
6558   subst"(x,y,z)"
6559       replace the simple variable "y" by the argument "z" in the
6560       ``polynomial'' expression "x". Every type is allowed for "x", but if it
6561       is not a genuine polynomial (or power series, or rational function),
6562       the substitution will be done as if the scalar components were
6563       polynomials of degree zero. In particular, beware that:
6564
6565         ? subst(1, x, [1,2; 3,4])
6566         %1 =
6567         [1 0]
6568
6569         [0 1]
6570
6571         ? subst(1, x, Mat([0,1]))
6572           ***   forbidden substitution by a non square matrix
6573
6574       If "x" is a power series, "z" must be either a polynomial, a power
6575       series, or a rational function.
6576
6577       The library syntax is gsubst"(x,y,z)", where "y" is the variable
6578       number.
6579
6580   substpol"(x,y,z)"
6581       replace the ``variable'' "y" by the argument "z" in the ``polynomial''
6582       expression "x". Every type is allowed for "x", but the same behaviour
6583       as "subst" above apply.
6584
6585       The difference with "subst" is that "y" is allowed to be any polynomial
6586       here. The substitution is done as per the following script:
6587
6588            subst_poly(pol, from, to) =
6589            { local(t = 'subst_poly_t, M = from - t);
6590
6591              subst(lift(Mod(pol,M), variable(M)), t, to)
6592            }
6593
6594       For instance
6595
6596         ? substpol(x^4 + x^2 + 1, x^2, y)
6597         %1 = y^2 + y + 1
6598         ? substpol(x^4 + x^2 + 1, x^3, y)
6599         %2 = x^2 + y*x + 1
6600         ? substpol(x^4 + x^2 + 1, (x+1)^2, y)
6601         %3 = (-4*y - 6)*x + (y^2 + 3*y - 3)
6602
6603       The library syntax is gsubstpol"(x,y,z)".
6604
6605   substvec"(x,v,w)"
6606       "v" being a vector of monomials (variables), "w" a vector of
6607       expressions of the same length, replace in the expression "x" all
6608       occurences of "v_i" by "w_i". The substitutions are done
6609       simultaneously; more precisely, the "v_i" are first replaced by new
6610       variables in "x", then these are replaced by the "w_i":
6611
6612         ? substvec([x,y], [x,y], [y,x])
6613         %1 = [y, x]
6614         ? substvec([x,y], [x,y], [y,x+y])
6615         %2 = [y, x + y]     \\ not [y, 2*y]
6616
6617       The library syntax is gsubstvec"(x,v,w)".
6618
6619   taylor"(x,y)"
6620       Taylor expansion around 0 of "x" with respect to the simple variable
6621       "y". "x" can be of any reasonable type, for example a rational
6622       function. The number of terms of the expansion is transparent to the
6623       user in GP, but must be given as a second argument in library mode.
6624
6625       The library syntax is tayl"(x,y,n)", where the "long" integer "n" is
6626       the desired number of terms in the expansion.
6627
6628   thue"(tnf,a,{sol})"
6629       solves the equation "P(x,y) = a" in integers "x" and "y", where tnf was
6630       created with thueinit(P). sol, if present, contains the solutions of
6631       "\Norm(x) = a" modulo units of positive norm in the number field
6632       defined by "P" (as computed by "bnfisintnorm"). If the result is
6633       conditional (on the GRH or some heuristic strenghtening), a Warning is
6634       printed. Otherwise, the result is unconditional, barring bugs.  For
6635       instance, here's how to solve the Thue equation "x^{13} - 5y^{13} = -
6636       4":
6637
6638         ? tnf = thueinit(x^13 - 5);
6639         ? thue(tnf, -4)
6640         %1 = [[1, 1]]
6641
6642       Hence, the only solution is "x = 1", "y = 1" and the result is
6643       unconditional. On the other hand:
6644
6645         ? tnf = thueinit(x^3-2*x^2+3*x-17);
6646         ? thue(tnf, -15)
6647           *** thue: Warning: Non trivial conditional class group.
6648           *** May miss solutions of the norm equation.
6649         %2 = [[1, 1]]
6650
6651       This time the result is conditional. All results computed using this
6652       tnf are likewise conditional, \emph{except} for a right-hand side of
6653       "+- 1".
6654
6655       The library syntax is thue"(tnf,a,sol)", where an omitted sol is coded
6656       as "NULL".
6657
6658   thueinit"(P,{flag = 0})"
6659       initializes the tnf corresponding to "P". It is meant to be used in
6660       conjunction with "thue" to solve Thue equations "P(x,y) = a", where "a"
6661       is an integer. If "flag" is non-zero, certify the result
6662       unconditionnally. Otherwise, assume GRH, this being much faster of
6663       course.
6664
6665       \emph{If} the conditional computed class group is trivial \emph{or} you
6666       are only interested in the case "a = +-1", then results are
6667       unconditional anyway. So one should only use the flag is "thue" prints
6668       a Warning (see the example there).
6669
6670       The library syntax is thueinit"(P,flag,prec)".
6671

Vectors, matrices, linear algebra and sets

6673       Note that most linear algebra functions operating on subspaces defined
6674       by generating sets (such as "mathnf", "qflll", etc.) take matrices as
6675       arguments. As usual, the generating vectors are taken to be the
6676       \emph{columns} of the given matrix.
6677
6678       Since PARI does not have a strong typing system, scalars live in
6679       unspecified commutative base rings. It is very difficult to write
6680       robust linear algebra routines in such a general setting. The
6681       developpers's choice has been to assume the base ring is a domain and
6682       work over its field of fractions. If the base ring is \emph{not} a
6683       domain, one gets an error as soon as a non-zero pivot turns out to be
6684       non-invertible. Some functions, e.g. "mathnf" or "mathnfmod",
6685       specifically assume the base ring is Z.
6686
6687   algdep"(x,k,{flag = 0})"
6688        "x" being real/complex, or "p"-adic, finds a polynomial of degree at
6689       most "k" with integer coefficients having "x" as approximate root.
6690       Note that the polynomial which is obtained is not necessarily the
6691       ``correct'' one. In fact it is not even guaranteed to be irreducible.
6692       One can check the closeness either by a polynomial evaluation (use
6693       "subst"), or by computing the roots of the polynomial given by "algdep"
6694       (use "polroots").
6695
6696       Internally, "lindep""([1,x,...,x^k], flag)" is used. If "lindep" is not
6697       able to find a relation and returns a lower bound for the sup norm of
6698       the smallest relation, "algdep" returns that bound instead.  A suitable
6699       non-zero value of "flag" may improve on the default behaviour:
6700
6701         \\\\\\\\\ LLL
6702         ? \p200
6703         ? algdep(2^(1/6)+3^(1/5), 30);      \\ wrong in 3.8s
6704         ? algdep(2^(1/6)+3^(1/5), 30, 100); \\ wrong in 1s
6705         ? algdep(2^(1/6)+3^(1/5), 30, 170); \\ right in 3.3s
6706         ? algdep(2^(1/6)+3^(1/5), 30, 200); \\ wrong in 2.9s
6707         ? \p250
6708         ? algdep(2^(1/6)+3^(1/5), 30);      \\ right in 2.8s
6709         ? algdep(2^(1/6)+3^(1/5), 30, 200); \\ right in 3.4s
6710         \\\\\\\\\ PSLQ
6711         ? \p200
6712         ? algdep(2^(1/6)+3^(1/5), 30, -3);  \\ failure in 14s.
6713         ? \p250
6714         ? algdep(2^(1/6)+3^(1/5), 30, -3);  \\ right in 18s
6715
6716       Proceeding by increments of 5 digits of accuracy, "algdep" with default
6717       flag produces its first correct result at 205 digits, and from then on
6718       a steady stream of correct results. Interestingly enough, our PSLQ also
6719       reliably succeeds from 205 digits on (and is 5 times slower at that
6720       accuracy).
6721
6722       The above example is the testcase studied in a 2000 paper by Borwein
6723       and Lisonek, Applications of integer relation algorithms,
6724       \emph{Discrete Math.}, 217, p. 65--82. The paper conludes in the
6725       superiority of the PSLQ algorithm, which either shows that PARI's
6726       implementation of PSLQ is lacking, or that its LLL is extremely good.
6727       The version of PARI tested there was 1.39, which succeeded reliably
6728       from precision 265 on, in about 60 as much time as the current version.
6729
6730       The library syntax is algdep0"(x,k,flag,prec)", where "k" and "flag"
6731       are "long"s.  Also available is " algdep(x,k,prec)" ("flag = 0").
6732
6733   charpoly"(A,{v = x},{flag = 0})"
6734       characteristic polynomial of "A" with respect to the variable "v",
6735       i.e. determinant of "v*I-A" if "A" is a square matrix. If "A" is not a
6736       square matrix, it returns the characteristic polynomial of the map
6737       ``multiplication by "A"'' if "A" is a scalar, in particular a polmod.
6738       E.g. "charpoly(I) = x^2+1".
6739
6740       The value of "flag" is only significant for matrices.
6741
6742       If "flag = 0", the method used is essentially the same as for computing
6743       the adjoint matrix, i.e. computing the traces of the powers of "A".
6744
6745       If "flag = 1", uses Lagrange interpolation which is almost always
6746       slower.
6747
6748       If "flag = 2", uses the Hessenberg form. This is faster than the
6749       default when the coefficients are intmod a prime or real numbers, but
6750       is usually slower in other base rings.
6751
6752       The library syntax is charpoly0"(A,v,flag)", where "v" is the variable
6753       number. Also available are the functions " caract(A,v)" ("flag = 1"), "
6754       carhess(A,v)" ("flag = 2"), and " caradj(A,v,pt)" where, in this last
6755       case, pt is a "GEN*" which, if not equal to "NULL", will receive the
6756       address of the adjoint matrix of "A" (see "matadjoint"), so both can be
6757       obtained at once.
6758
6759   concat"(x,{y})"
6760       concatenation of "x" and "y". If "x" or "y" is not a vector or matrix,
6761       it is considered as a one-dimensional vector. All types are allowed for
6762       "x" and "y", but the sizes must be compatible. Note that matrices are
6763       concatenated horizontally, i.e. the number of rows stays the same.
6764       Using transpositions, it is easy to concatenate them vertically.
6765
6766       To concatenate vectors sideways (i.e. to obtain a two-row or two-column
6767       matrix), use "Mat" instead (see the example there). Concatenating a row
6768       vector to a matrix having the same number of columns will add the row
6769       to the matrix (top row if the vector is "x", i.e. comes first, and
6770       bottom row otherwise).
6771
6772       The empty matrix "[;]" is considered to have a number of rows
6773       compatible with any operation, in particular concatenation. (Note that
6774       this is definitely \emph{not} the case for empty vectors "[ ]" or
6775       "[ ]~".)
6776
6777       If "y" is omitted, "x" has to be a row vector or a list, in which case
6778       its elements are concatenated, from left to right, using the above
6779       rules.
6780
6781         ? concat([1,2], [3,4])
6782         %1 = [1, 2, 3, 4]
6783         ? a = [[1,2]~, [3,4]~]; concat(a)
6784         %2 =
6785         [1 3]
6786
6787         [2 4]
6788
6789         ? concat([1,2; 3,4], [5,6]~)
6790         %3 =
6791         [1 2 5]
6792
6793         [3 4 6]
6794         ? concat([%, [7,8]~, [1,2,3,4]])
6795         %5 =
6796         [1 2 5 7]
6797
6798         [3 4 6 8]
6799
6800         [1 2 3 4]
6801
6802       The library syntax is concat"(x,y)".
6803
6804   lindep"(x,{flag = 0})"
6805       "x" being a vector with "p"-adic or real/complex coefficients, finds a
6806       small integral linear combination among these coefficients.
6807
6808       If "x" is "p"-adic, "flag" is meaningless and the algorithm LLL-reduces
6809       a suitable (dual) lattice.
6810
6811       Otherwise, the value of "flag" determines the algorithm used; in the
6812       current version of PARI, we suggest to use \emph{non-negative} values,
6813       since it is by far the fastest and most robust implementation. See the
6814       detailed example in "Label se:algdep" ("algdep").
6815
6816       If "flag >= 0", uses a floating point (variable precision) LLL
6817       algorithm.  This is in general much faster than the other variants.  If
6818       "flag = 0" the accuracy is chosen internally using a crude heuristic.
6819       If "flag > 0" the computation is done with an accuracy of "flag"
6820       decimal digits.  In that case, the parameter "flag" should be between
6821       0.6 and 0.9 times the number of correct decimal digits in the input.
6822
6823       If "flag = -1", uses a variant of the LLL algorithm due to Hastad,
6824       Lagarias and Schnorr (STACS 1986). If the precision is too low, the
6825       routine may enter an infinite loop.
6826
6827       If "flag = -2", "x" is allowed to be (and in any case interpreted as) a
6828       matrix.  Returns a non trivial element of the kernel of "x", or 0 if
6829       "x" has trivial kernel. The element is defined over the field of
6830       coefficients of "x", and is in general not integral.
6831
6832       If "flag = -3", uses the PSLQ algorithm. This may return a real number
6833       "B", indicating that the input accuracy was exhausted and that no
6834       relation exist whose sup norm is less than "B".
6835
6836       If "flag = -4", uses an experimental 2-level PSLQ, which does not work
6837       at all.  (Should be rewritten.)
6838
6839       The library syntax is lindep0"(x,flag,prec)". Also available is "
6840       lindep(x,prec)" ("flag = 0").
6841
6842   listcreate"(n)"
6843       creates an empty list of maximal length "n".
6844
6845       This function is useless in library mode.
6846
6847   listinsert"(list,x,n)"
6848       inserts the object "x" at position "n" in list (which must be of type
6849       "t_LIST"). All the remaining elements of list (from position "n+1"
6850       onwards) are shifted to the right. This and "listput" are the only
6851       commands which enable you to increase a list's effective length (as
6852       long as it remains under the maximal length specified at the time of
6853       the "listcreate").
6854
6855       This function is useless in library mode.
6856
6857   listkill"(list)"
6858       kill list. This deletes all elements from list and sets its effective
6859       length to 0. The maximal length is not affected.
6860
6861       This function is useless in library mode.
6862
6863   listput"(list,x,{n})"
6864       sets the "n"-th element of the list list (which must be of type
6865       "t_LIST") equal to "x". If "n" is omitted, or greater than the list
6866       current effective length, just appends "x". This and "listinsert" are
6867       the only commands which enable you to increase a list's effective
6868       length (as long as it remains under the maximal length specified at the
6869       time of the "listcreate").
6870
6871       If you want to put an element into an occupied cell, i.e. if you don't
6872       want to change the effective length, you can consider the list as a
6873       vector and use the usual "list[n] = x" construct.
6874
6875       This function is useless in library mode.
6876
6877   listsort"(list,{flag = 0})"
6878       sorts list (which must be of type "t_LIST") in place. If "flag" is non-
6879       zero, suppresses all repeated coefficients. This is much faster than
6880       the "vecsort" command since no copy has to be made.
6881
6882       This function is useless in library mode.
6883
6884   matadjoint"(x)"
6885       adjoint matrix of "x", i.e. the matrix "y" of cofactors of "x",
6886       satisfying "x*y =  det (x)*\Id". "x" must be a (non-necessarily
6887       invertible) square matrix.
6888
6889       The library syntax is adj"(x)".
6890
6891   matcompanion"(x)"
6892       the left companion matrix to the polynomial "x".
6893
6894       The library syntax is assmat"(x)".
6895
6896   matdet"(x,{flag = 0})"
6897       determinant of "x". "x" must be a square matrix.
6898
6899       If "flag = 0", uses Gauss-Bareiss.
6900
6901       If "flag = 1", uses classical Gaussian elimination, which is better
6902       when the entries of the matrix are reals or integers for example, but
6903       usually much worse for more complicated entries like multivariate
6904       polynomials.
6905
6906       The library syntax is det"(x)" ("flag = 0") and " det2(x)" ("flag =
6907       1").
6908
6909   matdetint"(x)"
6910       "x" being an "m x n" matrix with integer coefficients, this function
6911       computes a \emph{multiple} of the determinant of the lattice generated
6912       by the columns of "x" if it is of rank "m", and returns zero otherwise.
6913       This function can be useful in conjunction with the function
6914       "mathnfmod" which needs to know such a multiple. To obtain the exact
6915       determinant (assuming the rank is maximal), you can compute
6916       "matdet(mathnfmod(x, matdetint(x)))".
6917
6918       Note that as soon as one of the dimensions gets large ("m" or "n" is
6919       larger than 20, say), it will often be much faster to use "mathnf(x,
6920       1)" or "mathnf(x, 4)" directly.
6921
6922       The library syntax is detint"(x)".
6923
6924   matdiagonal"(x)"
6925       "x" being a vector, creates the diagonal matrix whose diagonal entries
6926       are those of "x".
6927
6928       The library syntax is diagonal"(x)".
6929
6930   mateigen"(x)"
6931       gives the eigenvectors of "x" as columns of a matrix.
6932
6933       The library syntax is eigen"(x)".
6934
6935   matfrobenius"(M,{flag = 0},{v = x})"
6936       returns the Frobenius form of the square matrix "M". If "flag = 1",
6937       returns only the elementary divisors as a vectr of polynomials in the
6938       variable "v".  If "flag = 2", returns a two-components vector [F,B]
6939       where "F" is the Frobenius form and "B" is the basis change so that "M
6940       = B^{-1}FB".
6941
6942       The library syntax is matfrobenius"(M,flag,v)", where "v" is the
6943       variable number.
6944
6945   mathess"(x)"
6946       Hessenberg form of the square matrix "x".
6947
6948       The library syntax is hess"(x)".
6949
6950   mathilbert"(x)"
6951       "x" being a "long", creates the Hilbert matrixof order "x", i.e. the
6952       matrix whose coefficient ("i","j") is "1/ (i+j-1)".
6953
6954       The library syntax is mathilbert"(x)".
6955
6956   mathnf"(x,{flag = 0})"
6957       if "x" is a (not necessarily square) matrix with integer entries, finds
6958       the \emph{upper triangular} Hermite normal form of "x". If the rank of
6959       "x" is equal to its number of rows, the result is a square matrix. In
6960       general, the columns of the result form a basis of the lattice spanned
6961       by the columns of "x".
6962
6963       If "flag = 0", uses the naive algorithm. This should never be used if
6964       the dimension is at all large (larger than 10, say). It is recommanded
6965       to use either "mathnfmod(x, matdetint(x))" (when "x" has maximal rank)
6966       or "mathnf(x, 1)". Note that the latter is in general faster than
6967       "mathnfmod", and also provides a base change matrix.
6968
6969       If "flag = 1", uses Batut's algorithm, which is much faster than the
6970       default.  Outputs a two-component row vector "[H,U]", where "H" is the
6971       \emph{upper triangular} Hermite normal form of "x" defined as above,
6972       and "U" is the unimodular transformation matrix such that "xU = [0|H]".
6973       "U" has in general huge coefficients, in particular when the kernel is
6974       large.
6975
6976       If "flag = 3", uses Batut's algorithm, but outputs "[H,U,P]", such that
6977       "H" and "U" are as before and "P" is a permutation of the rows such
6978       that "P" applied to "xU" gives "H". The matrix "U" is smaller than with
6979       "flag = 1", but may still be large.
6980
6981       If "flag = 4", as in case 1 above, but uses a heuristic variant of LLL
6982       reduction along the way. The matrix "U" is in general close to optimal
6983       (in terms of smallest "L_2" norm), but the reduction is slower than in
6984       case 1.
6985
6986       The library syntax is mathnf0"(x,flag)". Also available are " hnf(x)"
6987       ("flag = 0") and " hnfall(x)" ("flag = 1"). To reduce \emph{huge} (say
6988       "400  x 400" and more) relation matrices (sparse with small entries),
6989       you can use the pair "hnfspec" / "hnfadd". Since this is rather
6990       technical and the calling interface may change, they are not documented
6991       yet. Look at the code in "basemath/alglin1.c".
6992
6993   mathnfmod"(x,d)"
6994       if "x" is a (not necessarily square) matrix of maximal rank with
6995       integer entries, and "d" is a multiple of the (non-zero) determinant of
6996       the lattice spanned by the columns of "x", finds the \emph{upper
6997       triangular} Hermite normal form of "x".
6998
6999       If the rank of "x" is equal to its number of rows, the result is a
7000       square matrix. In general, the columns of the result form a basis of
7001       the lattice spanned by the columns of "x". This is much faster than
7002       "mathnf" when "d" is known.
7003
7004       The library syntax is hnfmod"(x,d)".
7005
7006   mathnfmodid"(x,d)"
7007       outputs the (upper triangular) Hermite normal form of "x" concatenated
7008       with "d" times the identity matrix. Assumes that "x" has integer
7009       entries.
7010
7011       The library syntax is hnfmodid"(x,d)".
7012
7013   matid"(n)"
7014       creates the "n x n" identity matrix.
7015
7016       The library syntax is matid"(n)" where "n" is a "long".
7017
7018       Related functions are " gscalmat(x,n)", which creates "x" times the
7019       identity matrix ("x" being a "GEN" and "n" a "long"), and "
7020       gscalsmat(x,n)" which is the same when "x" is a "long".
7021
7022   matimage"(x,{flag = 0})"
7023       gives a basis for the image of the matrix "x" as columns of a matrix. A
7024       priori the matrix can have entries of any type. If "flag = 0", use
7025       standard Gauss pivot. If "flag = 1", use "matsupplement".
7026
7027       The library syntax is matimage0"(x,flag)". Also available is "
7028       image(x)" ("flag = 0").
7029
7030   matimagecompl"(x)"
7031       gives the vector of the column indices which are not extracted by the
7032       function "matimage". Hence the number of components of matimagecompl(x)
7033       plus the number of columns of matimage(x) is equal to the number of
7034       columns of the matrix "x".
7035
7036       The library syntax is imagecompl"(x)".
7037
7038   matindexrank"(x)"
7039       "x" being a matrix of rank "r", gives two vectors "y" and "z" of length
7040       "r" giving a list of rows and columns respectively (starting from 1)
7041       such that the extracted matrix obtained from these two vectors using
7042       "vecextract(x,y,z)" is invertible.
7043
7044       The library syntax is indexrank"(x)".
7045
7046   matintersect"(x,y)"
7047       "x" and "y" being two matrices with the same number of rows each of
7048       whose columns are independent, finds a basis of the Q-vector space
7049       equal to the intersection of the spaces spanned by the columns of "x"
7050       and "y" respectively. See also the function "idealintersect", which
7051       does the same for free Z-modules.
7052
7053       The library syntax is intersect"(x,y)".
7054
7055   matinverseimage"(M,y)"
7056       gives a column vector belonging to the inverse image "z" of the column
7057       vector or matrix "y" by the matrix "M" if one exists (i.e such that "Mz
7058       = y"), the empty vector otherwise. To get the complete inverse image,
7059       it suffices to add to the result any element of the kernel of "x"
7060       obtained for example by "matker".
7061
7062       The library syntax is inverseimage"(x,y)".
7063
7064   matisdiagonal"(x)"
7065       returns true (1) if "x" is a diagonal matrix, false (0) if not.
7066
7067       The library syntax is isdiagonal"(x)", and this returns a "long"
7068       integer.
7069
7070   matker"(x,{flag = 0})"
7071       gives a basis for the kernel of the matrix "x" as columns of a matrix.
7072       A priori the matrix can have entries of any type.
7073
7074       If "x" is known to have integral entries, set "flag = 1".
7075
7076       Note: The library function "FpM_ker(x, p)", where "x" has integer
7077       entries \emph{reduced mod p} and "p" is prime, is equivalent to, but
7078       orders of magnitude faster than, "matker(x*Mod(1,p))" and needs much
7079       less stack space. To use it under "gp", type "install(FpM_ker, GG)"
7080       first.
7081
7082       The library syntax is matker0"(x,flag)". Also available are " ker(x)"
7083       ("flag = 0"), " keri(x)" ("flag = 1").
7084
7085   matkerint"(x,{flag = 0})"
7086       gives an LLL-reduced Z-basis for the lattice equal to the kernel of the
7087       matrix "x" as columns of the matrix "x" with integer entries (rational
7088       entries are not permitted).
7089
7090       If "flag = 0", uses a modified integer LLL algorithm.
7091
7092       If "flag = 1", uses "matrixqz(x,-2)". If LLL reduction of the final
7093       result is not desired, you can save time using "matrixqz(matker(x),-2)"
7094       instead.
7095
7096       The library syntax is matkerint0"(x,flag)". Also available is "
7097       kerint(x)" ("flag = 0").
7098
7099   matmuldiagonal"(x,d)"
7100       product of the matrix "x" by the diagonal matrix whose diagonal entries
7101       are those of the vector "d". Equivalent to, but much faster than
7102       "x*matdiagonal(d)".
7103
7104       The library syntax is matmuldiagonal"(x,d)".
7105
7106   matmultodiagonal"(x,y)"
7107       product of the matrices "x" and "y" assuming that the result is a
7108       diagonal matrix. Much faster than "x*y" in that case. The result is
7109       undefined if "x*y" is not diagonal.
7110
7111       The library syntax is matmultodiagonal"(x,y)".
7112
7113   matpascal"(x,{q})"
7114       creates as a matrix the lower triangular Pascal triangle of order "x+1"
7115       (i.e. with binomial coefficients up to "x"). If "q" is given, compute
7116       the "q"-Pascal triangle (i.e. using "q"-binomial coefficients).
7117
7118       The library syntax is matqpascal"(x,q)", where "x" is a "long" and "q =
7119       NULL" is used to omit "q". Also available is " matpascal(x)".
7120
7121   matrank"(x)"
7122       rank of the matrix "x".
7123
7124       The library syntax is rank"(x)", and the result is a "long".
7125
7126   matrix"(m,n,{X},{Y},{expr = 0})"
7127       creation of the "m x n" matrix whose coefficients are given by the
7128       expression expr. There are two formal parameters in expr, the first one
7129       ("X") corresponding to the rows, the second ("Y") to the columns, and
7130       "X" goes from 1 to "m", "Y" goes from 1 to "n". If one of the last 3
7131       parameters is omitted, fill the matrix with zeroes.
7132
7133       The library syntax is matrice"(GEN nlig,GEN ncol,entree *e1,entree
7134       *e2,char *expr)".
7135
7136   matrixqz"(x,p)"
7137       "x" being an "m x n" matrix with "m >= n" with rational or integer
7138       entries, this function has varying behaviour depending on the sign of
7139       "p":
7140
7141       If "p >= 0", "x" is assumed to be of maximal rank. This function
7142       returns a matrix having only integral entries, having the same image as
7143       "x", such that the GCD of all its "n x n" subdeterminants is equal to 1
7144       when "p" is equal to 0, or not divisible by "p" otherwise. Here "p"
7145       must be a prime number (when it is non-zero). However, if the function
7146       is used when "p" has no small prime factors, it will either work or
7147       give the message ``impossible inverse modulo'' and a non-trivial
7148       divisor of "p".
7149
7150       If "p = -1", this function returns a matrix whose columns form a basis
7151       of the lattice equal to "Z^n" intersected with the lattice generated by
7152       the columns of "x".
7153
7154       If "p = -2", returns a matrix whose columns form a basis of the lattice
7155       equal to "Z^n" intersected with the Q-vector space generated by the
7156       columns of "x".
7157
7158       The library syntax is matrixqz0"(x,p)".
7159
7160   matsize"(x)"
7161       "x" being a vector or matrix, returns a row vector with two components,
7162       the first being the number of rows (1 for a row vector), the second the
7163       number of columns (1 for a column vector).
7164
7165       The library syntax is matsize"(x)".
7166
7167   matsnf"(X,{flag = 0})"
7168       if "X" is a (singular or non-singular) matrix outputs the vector of
7169       elementary divisors of "X" (i.e. the diagonal of the Smith normal form
7170       of "X").
7171
7172       The binary digits of flag mean:
7173
7174       1 (complete output): if set, outputs "[U,V,D]", where "U" and "V" are
7175       two unimodular matrices such that "UXV" is the diagonal matrix "D".
7176       Otherwise output only the diagonal of "D".
7177
7178       2 (generic input): if set, allows polynomial entries, in which case the
7179       input matrix must be square. Otherwise, assume that "X" has integer
7180       coefficients with arbitrary shape.
7181
7182       4 (cleanup): if set, cleans up the output. This means that elementary
7183       divisors equal to 1 will be deleted, i.e. outputs a shortened vector
7184       "D'" instead of "D". If complete output was required, returns
7185       "[U',V',D']" so that "U'XV' = D'" holds. If this flag is set, "X" is
7186       allowed to be of the form "D" or "[U,V,D]" as would normally be output
7187       with the cleanup flag unset.
7188
7189       The library syntax is matsnf0"(X,flag)". Also available is " smith(X)"
7190       ("flag = 0").
7191
7192   matsolve"(x,y)"
7193       "x" being an invertible matrix and "y" a column vector, finds the
7194       solution "u" of "x*u = y", using Gaussian elimination. This has the
7195       same effect as, but is a bit faster, than "x^{-1}*y".
7196
7197       The library syntax is gauss"(x,y)".
7198
7199   matsolvemod"(m,d,y,{flag = 0})"
7200       "m" being any integral matrix, "d" a vector of positive integer moduli,
7201       and "y" an integral column vector, gives a small integer solution to
7202       the system of congruences "sum_i m_{i,j}x_j = y_i (mod d_i)" if one
7203       exists, otherwise returns zero. Shorthand notation: "y" (resp. "d") can
7204       be given as a single integer, in which case all the "y_i" (resp. "d_i")
7205       above are taken to be equal to "y" (resp. "d").
7206
7207           ? m = [1,2;3,4];
7208           ? matsolvemod(m, [3,4], [1,2]~)
7209           %2 = [-2, 0]~
7210           ? matsolvemod(m, 3, 1) \\ m X = [1,1]~ over F_3
7211           %3 = [-1, 1]~
7212
7213       If "flag = 1", all solutions are returned in the form of a two-
7214       component row vector "[x,u]", where "x" is a small integer solution to
7215       the system of congruences and "u" is a matrix whose columns give a
7216       basis of the homogeneous system (so that all solutions can be obtained
7217       by adding "x" to any linear combination of columns of "u"). If no
7218       solution exists, returns zero.
7219
7220       The library syntax is matsolvemod0"(m,d,y,flag)". Also available are "
7221       gaussmodulo(m,d,y)" ("flag = 0") and " gaussmodulo2(m,d,y)" ("flag =
7222       1").
7223
7224   matsupplement"(x)"
7225       assuming that the columns of the matrix "x" are linearly independent
7226       (if they are not, an error message is issued), finds a square
7227       invertible matrix whose first columns are the columns of "x",
7228       i.e. supplement the columns of "x" to a basis of the whole space.
7229
7230       The library syntax is suppl"(x)".
7231
7232   mattranspose"(x)" or "x~"
7233       transpose of "x".  This has an effect only on vectors and matrices.
7234
7235       The library syntax is gtrans"(x)".
7236
7237   minpoly"(A,{v = x},{flag = 0})"
7238       minimal polynomial of "A" with respect to the variable "v"., i.e. the
7239       monic polynomial "P" of minimal degree (in the variable "v") such that
7240       "P(A) = 0".
7241
7242       The library syntax is minpoly"(A,v)", where "v" is the variable number.
7243
7244   qfgaussred"(q)"
7245       decomposition into squares of the quadratic form represented by the
7246       symmetric matrix "q". The result is a matrix whose diagonal entries are
7247       the coefficients of the squares, and the non-diagonal entries represent
7248       the bilinear forms. More precisely, if "(a_{ij})" denotes the output,
7249       one has
7250
7251         " q(x) = sum_i a_{ii} (x_i + sum_{j > i} a_{ij} x_j)^2 "
7252
7253       The library syntax is sqred"(x)".
7254
7255   qfjacobi"(x)"
7256       "x" being a real symmetric matrix, this gives a vector having two
7257       components: the first one is the vector of eigenvalues of "x", the
7258       second is the corresponding orthogonal matrix of eigenvectors of "x".
7259       The method used is Jacobi's method for symmetric matrices.
7260
7261       The library syntax is jacobi"(x)".
7262
7263   qflll"(x,{flag = 0})"
7264       LLL algorithm applied to the \emph{columns} of the matrix "x". The
7265       columns of "x" must be linearly independent, unless specified otherwise
7266       below. The result is a unimodular transformation matrix "T" such that
7267       "x.T" is an LLL-reduced basis of the lattice generated by the column
7268       vectors of "x".
7269
7270       If "flag = 0" (default), the computations are done with floating point
7271       numbers, using Householder matrices for orthogonalization. If "x" has
7272       integral entries, then computations are nonetheless approximate, with
7273       precision varying as needed (Lehmer's trick, as generalized by
7274       Schnorr).
7275
7276       If "flag = 1", it is assumed that "x" is integral. The computation is
7277       done entirely with integers. In this case, "x" needs not be of maximal
7278       rank, but if it is not, "T" will not be square. This is slower and no
7279       more accurate than "flag = 0" above if "x" has small dimension (say 100
7280       or less).
7281
7282       If "flag = 2", "x" should be an integer matrix whose columns are
7283       linearly independent. Returns a partially reduced basis for "x", using
7284       an unpublished algorithm by Peter Montgomery: a basis is said to be
7285       \emph{partially reduced} if "|v_i +- v_j| >= |v_i|" for any two
7286       distinct basis vectors "v_i, v_j".
7287
7288       This is significantly faster than "flag = 1", esp. when one row is huge
7289       compared to the other rows. Note that the resulting basis is \emph{not}
7290       LLL-reduced in general.
7291
7292       If "flag = 4", "x" is assumed to have integral entries, but needs not
7293       be of maximal rank. The result is a two-component vector of matrices:
7294       the columns of the first matrix represent a basis of the integer kernel
7295       of "x" (not necessarily LLL-reduced) and the second matrix is the
7296       transformation matrix "T" such that "x.T" is an LLL-reduced Z-basis of
7297       the image of the matrix "x".
7298
7299       If "flag = 5", case as case 4, but "x" may have polynomial
7300       coefficients.
7301
7302       If "flag = 8", same as case 0, but "x" may have polynomial
7303       coefficients.
7304
7305       The library syntax is qflll0"(x,flag,prec)". Also available are "
7306       lll(x,prec)" ("flag = 0"), " lllint(x)" ("flag = 1"), and "
7307       lllkerim(x)" ("flag = 4").
7308
7309   qflllgram"(G,{flag = 0})"
7310       same as "qflll", except that the matrix "G = x~ * x" is the Gram matrix
7311       of some lattice vectors "x", and not the coordinates of the vectors
7312       themselves. In particular, "G" must now be a square symmetric real
7313       matrix, corresponding to a positive definite quadratic form. The result
7314       is a unimodular transformation matrix "T" such that "x.T" is an LLL-
7315       reduced basis of the lattice generated by the column vectors of "x".
7316
7317       If "flag = 0" (default): the computations are done with floating point
7318       numbers, using Householder matrices for orthogonalization. If "G" has
7319       integral entries, then computations are nonetheless approximate, with
7320       precision varying as needed (Lehmer's trick, as generalized by
7321       Schnorr).
7322
7323       If "flag = 1": "G" has integer entries, still positive but not
7324       necessarily definite (i.e "x" needs not have maximal rank). The
7325       computations are all done in integers and should be slower than the
7326       default, unless the latter triggers accuracy problems.
7327
7328       "flag = 4": "G" has integer entries, gives the kernel and reduced image
7329       of "x".
7330
7331       "flag = 5": same as case 4, but "G" may have polynomial coefficients.
7332
7333       The library syntax is qflllgram0"(G,flag,prec)". Also available are "
7334       lllgram(G,prec)" ("flag = 0"), " lllgramint(G)" ("flag = 1"), and "
7335       lllgramkerim(G)" ("flag = 4").
7336
7337   qfminim"(x,{b},{m},{flag = 0})"
7338       "x" being a square and symmetric matrix representing a positive
7339       definite quadratic form, this function deals with the vectors of "x"
7340       whose norm is less than or equal to "b", enumerated using the Fincke-
7341       Pohst algorithm. The function searches for the minimal non-zero vectors
7342       if "b" is omitted. The precise behaviour depends on "flag".
7343
7344       If "flag = 0" (default), seeks at most "2m" vectors. The result is a
7345       three-component vector, the first component being the number of vectors
7346       found, the second being the maximum norm found, and the last vector is
7347       a matrix whose columns are the vectors found, only one being given for
7348       each pair "+- v" (at most "m" such pairs). The vectors are returned in
7349       no particular order. In this variant, an explicit "m" must be provided.
7350
7351       If "flag = 1", ignores "m" and returns the first vector whose norm is
7352       less than "b". In this variant, an explicit "b" must be provided.
7353
7354       In both these cases, "x" is assumed to have integral entries. The
7355       implementation uses low precision floating point computations for
7356       maximal speed, which gives incorrect result when "x" has large entries.
7357       (The condition is checked in the code and the routine will raise an
7358       error if large rounding errors occur.) A more robust, but much slower,
7359       implementation is chosen if the following flag is used:
7360
7361       If "flag = 2", "x" can have non integral real entries. In this case, if
7362       "b" is omitted, the ``minimal'' vectors only have approximately the
7363       same norm.  If "b" is omitted, "m" is an upper bound for the number of
7364       vectors that will be stored and returned, but all minimal vectors are
7365       nevertheless enumerated. If "m" is omitted, all vectors found are
7366       stored and returned; note that this may be a huge vector!
7367
7368       The library syntax is qfminim0"(x,b,m,flag,prec)", also available are "
7369       minim(x,b,m)" ("flag = 0"), " minim2(x,b,m)" ("flag = 1"). In all
7370       cases, an omitted "b" or "m" is coded as "NULL".
7371
7372   qfperfection"(x)"
7373       "x" being a square and symmetric matrix with integer entries
7374       representing a positive definite quadratic form, outputs the perfection
7375       rank of the form. That is, gives the rank of the family of the "s"
7376       symmetric matrices "v_iv_i^t", where "s" is half the number of minimal
7377       vectors and the "v_i" ("1 <= i <= s") are the minimal vectors.
7378
7379       As a side note to old-timers, this used to fail bluntly when "x" had
7380       more than 5000 minimal vectors. Beware that the computations can now be
7381       very lengthy when "x" has many minimal vectors.
7382
7383       The library syntax is perf"(x)".
7384
7385   qfrep"(q, B, {flag = 0})"
7386       "q" being a square and symmetric matrix with integer entries
7387       representing a positive definite quadratic form, outputs the vector
7388       whose "i"-th entry, "1 <= i <= B" is half the number of vectors "v"
7389       such that "q(v) = i". This routine uses a naive algorithm based on
7390       "qfminim", and will fail if any entry becomes larger than "2^{31}".
7391
7392       The binary digits of flag mean:
7393
7394       \item 1: count vectors of even norm from 1 to "2B".
7395
7396       \item 2: return a "t_VECSMALL" instead of a "t_GEN"
7397
7398       The library syntax is qfrep0"(q, B, flag)".
7399
7400   qfsign"(x)"
7401       signature of the quadratic form represented by the symmetric matrix
7402       "x". The result is a two-component vector.
7403
7404       The library syntax is signat"(x)".
7405
7406   setintersect"(x,y)"
7407       intersection of the two sets "x" and "y".
7408
7409       The library syntax is setintersect"(x,y)".
7410
7411   setisset"(x)"
7412       returns true (1) if "x" is a set, false (0) if not. In PARI, a set is
7413       simply a row vector whose entries are strictly increasing. To convert
7414       any vector (and other objects) into a set, use the function "Set".
7415
7416       The library syntax is setisset"(x)", and this returns a "long".
7417
7418   setminus"(x,y)"
7419       difference of the two sets "x" and "y", i.e. set of elements of "x"
7420       which do not belong to "y".
7421
7422       The library syntax is setminus"(x,y)".
7423
7424   setsearch"(x,y,{flag = 0})"
7425       searches if "y" belongs to the set "x". If it does and "flag" is zero
7426       or omitted, returns the index "j" such that "x[j] = y", otherwise
7427       returns 0. If "flag" is non-zero returns the index "j" where "y" should
7428       be inserted, and 0 if it already belongs to "x" (this is meant to be
7429       used in conjunction with "listinsert").
7430
7431       This function works also if "x" is a \emph{sorted} list (see
7432       "listsort").
7433
7434       The library syntax is setsearch"(x,y,flag)" which returns a "long"
7435       integer.
7436
7437   setunion"(x,y)"
7438       union of the two sets "x" and "y".
7439
7440       The library syntax is setunion"(x,y)".
7441
7442   trace"(x)"
7443       this applies to quite general "x". If "x" is not a matrix, it is equal
7444       to the sum of "x" and its conjugate, except for polmods where it is the
7445       trace as an algebraic number.
7446
7447       For "x" a square matrix, it is the ordinary trace. If "x" is a non-
7448       square matrix (but not a vector), an error occurs.
7449
7450       The library syntax is gtrace"(x)".
7451
7452   vecextract"(x,y,{z})"
7453       extraction of components of the vector or matrix "x" according to "y".
7454       In case "x" is a matrix, its components are as usual the \emph{columns}
7455       of "x". The parameter "y" is a component specifier, which is either an
7456       integer, a string describing a range, or a vector.
7457
7458       If "y" is an integer, it is considered as a mask: the binary bits of
7459       "y" are read from right to left, but correspond to taking the
7460       components from left to right. For example, if "y = 13 = (1101)_2" then
7461       the components 1,3 and 4 are extracted.
7462
7463       If "y" is a vector, which must have integer entries, these entries
7464       correspond to the component numbers to be extracted, in the order
7465       specified.
7466
7467       If "y" is a string, it can be
7468
7469       \item a single (non-zero) index giving a component number (a negative
7470       index means we start counting from the end).
7471
7472       \item a range of the form "a..b", where "a" and "b" are indexes as
7473       above. Any of "a" and "b" can be omitted; in this case, we take as
7474       default values "a = 1" and "b = -1", i.e. the first and last components
7475       respectively. We then extract all components in the interval "[a,b]",
7476       in reverse order if "b < a".
7477
7478       In addition, if the first character in the string is "^", the
7479       complement of the given set of indices is taken.
7480
7481       If "z" is not omitted, "x" must be a matrix. "y" is then the
7482       \emph{line} specifier, and "z" the \emph{column} specifier, where the
7483       component specifier is as explained above.
7484
7485         %4 = [e, d, c]
7486         ? vecextract(v, "^2")       \\ mask
7487         %4 = [e, d, c]
7488         ? vecextract(v, "^2")       \\ component list
7489         %4 = [e, d, c]
7490         ? vecextract(v, "^2")       \\ interval
7491         %4 = [e, d, c]
7492         ? vecextract(v, "^2")       \\ interval + reverse order
7493         %4 = [e, d, c]
7494         ? vecextract(v, "^2")       \\ complement
7495         %5 = [a, c, d, e]
7496         ? vecextract(matid(3), "2..", "..")
7497         %6 =
7498         [0 1 0]
7499
7500         [0 0 1]
7501
7502       The library syntax is extract"(x,y)" or " matextract(x,y,z)".
7503
7504   vecsort"(x,{k},{flag = 0})"
7505       sorts the vector "x" in ascending order, using a mergesort method. "x"
7506       must be a vector, and its components integers, reals, or fractions.
7507
7508       If "k" is present and is an integer, sorts according to the value of
7509       the "k"-th subcomponents of the components of "x". Note that mergesort
7510       is stable, hence is the initial ordering of "equal" entries (with
7511       respect to the sorting criterion) is not changed.
7512
7513       "k" can also be a vector, in which case the sorting is done
7514       lexicographically according to the components listed in the vector "k".
7515       For example, if "k = [2,1,3]", sorting will be done with respect to the
7516       second component, and when these are equal, with respect to the first,
7517       and when these are equal, with respect to the third.
7518
7519       The binary digits of flag mean:
7520
7521       \item 1: indirect sorting of the vector "x", i.e. if "x" is an
7522       "n"-component vector, returns a permutation of "[1,2,...,n]" which
7523       applied to the components of "x" sorts "x" in increasing order.  For
7524       example, "vecextract(x, vecsort(x,,1))" is equivalent to vecsort(x).
7525
7526       \item 2: sorts "x" by ascending lexicographic order (as per the "lex"
7527       comparison function).
7528
7529       \item 4: use descending instead of ascending order.
7530
7531       The library syntax is vecsort0"(x,k,flag)". To omit "k", use "NULL"
7532       instead. You can also use the simpler functions
7533
7534       " sort(x)" ( = " vecsort0(x,NULL,0)").
7535
7536       " indexsort(x)" ( = " vecsort0(x,NULL,1)").
7537
7538       " lexsort(x)" ( = " vecsort0(x,NULL,2)").
7539
7540       Also available are " sindexsort(x)" and " sindexlexsort(x)" which
7541       return a "t_VECSMALL" "v", where "v[1]...v[n]" contain the indices.
7542
7543   vector"(n,{X},{expr = 0})"
7544       creates a row vector (type "t_VEC") with "n" components whose
7545       components are the expression expr evaluated at the integer points
7546       between 1 and "n". If one of the last two arguments is omitted, fill
7547       the vector with zeroes.
7548
7549       Avoid modifying "X" within expr; if you do, the formal variable still
7550       runs from 1 to "n". In particular, "vector(n,i,expr)" is not equivalent
7551       to
7552
7553             v = vector(n)
7554             for (i = 1, n, v[i] = expr)
7555
7556       as the following example shows:
7557
7558             n = 3
7559             v = vector(n); vector(n, i, i++)            ----> [2, 3, 4]
7560             v = vector(n); for (i = 1, n, v[i] = i++)   ----> [2, 0, 4]
7561
7562       The library syntax is vecteur"(GEN nmax, entree *ep, char *expr)".
7563
7564   vectorsmall"(n,{X},{expr = 0})"
7565       creates a row vector of small integers (type "t_VECSMALL") with "n"
7566       components whose components are the expression expr evaluated at the
7567       integer points between 1 and "n". If one of the last two arguments is
7568       omitted, fill the vector with zeroes.
7569
7570       The library syntax is vecteursmall"(GEN nmax, entree *ep, char *expr)".
7571
7572   vectorv"(n,X,expr)"
7573       as "vector", but returns a column vector (type "t_COL").
7574
7575       The library syntax is vvecteur"(GEN nmax, entree *ep, char *expr)".
7576

Sums, products, integrals and similar functions

7578       Although the "gp" calculator is programmable, it is useful to have
7579       preprogrammed a number of loops, including sums, products, and a
7580       certain number of recursions. Also, a number of functions from
7581       numerical analysis like numerical integration and summation of series
7582       will be described here.
7583
7584       One of the parameters in these loops must be the control variable,
7585       hence a simple variable name. In the descriptions, the letter "X" will
7586       always denote any simple variable name, and represents the formal
7587       parameter used in the function. The expression to be summed,
7588       integrated, etc. is any legal PARI expression, including of course
7589       expressions using loops.
7590
7591       Library mode.  Since it is easier to program directly the loops in
7592       library mode, these functions are mainly useful for GP programming.
7593       Using them in library mode is tricky and we will not give any details,
7594       although the reader can try and figure it out by himself by checking
7595       the example given for "sum".
7596
7597       On the other hand, numerical routines code a function (to be
7598       integrated, summed, etc.) with two parameters named
7599
7600           GEN (*eval)(GEN,void*)
7601           void *E;
7602
7603       The second is meant to contain all auxilliary data needed by your
7604       function.  The first is such that "eval(x, E)" returns your function
7605       evaluated at "x". For instance, one may code the family of functions
7606       "f_t: x \to (x+t)^2" via
7607
7608         GEN f(GEN x, void *t) { return gsqr(gadd(x, (GEN)t)); }
7609
7610       One can then integrate "f_1" between "a" and "b" with the call
7611
7612         intnum((void*)stoi(1), &fun, a, b, NULL, prec);
7613
7614       Since you can set "E" to a pointer to any "struct" (typecast to
7615       "void*") the above mechanism handles arbitrary functions. For simple
7616       functions without extra parameters, you may set "E = NULL" and ignore
7617       that argument in your function definition.
7618
7619       Numerical integration.  Starting with version 2.2.9 the powerful
7620       ``double exponential'' univariate integration method is implemented in
7621       "intnum" and its variants. Romberg integration is still available under
7622       the name "intnumromb", but superseded. It is possible to compute
7623       numerically integrals to thousands of decimal places in reasonable
7624       time, as long as the integrand is regular. It is also reasonable to
7625       compute numerically integrals in several variables, although more than
7626       two becomes lengthy. The integration domain may be non-compact, and the
7627       integrand may have reasonable singularities at endpoints. To use
7628       "intnum", the user must split the integral into a sum of subintegrals
7629       where the function has (possible) singularities only at the endpoints.
7630       Polynomials in logarithms are not considered singular, and neglecting
7631       these logs, singularities are assumed to be algebraic (in other words
7632       asymptotic to "C(x-a)^{-alpha}" for some "alpha" such that "alpha > -1"
7633       when "x" is close to "a"), or to correspond to simple discontinuities
7634       of some (higher) derivative of the function. For instance, the point 0
7635       is a singularity of abs(x).
7636
7637       See also the discrete summation methods below (sharing the prefix
7638       "sum").
7639
7640   intcirc"(X = a,R,expr, {tab})"
7641       numerical integration of expr with respect to "X" on the circle "|X-a
7642       |= R", divided by "2iPi". In other words, when expr is a meromorphic
7643       function, sum of the residues in the corresponding disk. tab is as in
7644       "intnum", except that if computed with "intnuminit" it should be with
7645       the endpoints "[-1, 1]".
7646
7647         ? \p105
7648         ? intcirc(s=1, 0.5, zeta(s)) - 1
7649         time = 3,460 ms.
7650         %1 = -2.40... E-104 - 2.7... E-106*I
7651
7652       The library syntax is intcirc"(void *E, GEN (*eval)(GEN,void*), GEN
7653       a,GEN R,GEN tab, long prec)".
7654
7655   intfouriercos"(X = a,b,z,expr,{tab})"
7656       numerical integration of "expr(X) cos (2Pi zX)" from "a" to "b", in
7657       other words Fourier cosine transform (from "a" to "b") of the function
7658       represented by expr. "a" and "b" are coded as in "intnum", and are not
7659       necessarily at infinity, but if they are, oscillations (i.e.
7660       "[[+-1],alpha I]") are forbidden.
7661
7662       The library syntax is intfouriercos"(void *E, GEN (*eval)(GEN,void*),
7663       GEN a, GEN b, GEN z, GEN tab, long prec)".
7664
7665   intfourierexp"(X = a,b,z,expr,{tab})"
7666       numerical integration of "expr(X) exp (-2Pi zX)" from "a" to "b", in
7667       other words Fourier transform (from "a" to "b") of the function
7668       represented by expr. Note the minus sign. "a" and "b" are coded as in
7669       "intnum", and are not necessarily at infinity but if they are,
7670       oscillations (i.e.  "[[+-1],alpha I]") are forbidden.
7671
7672       The library syntax is intfourierexp"(void *E, GEN (*eval)(GEN,void*),
7673       GEN a, GEN b, GEN z, GEN tab, long prec)".
7674
7675   intfouriersin"(X = a,b,z,expr,{tab})"
7676       numerical integration of "expr(X) sin (2Pi zX)" from "a" to "b", in
7677       other words Fourier sine transform (from "a" to "b") of the function
7678       represented by expr. "a" and "b" are coded as in "intnum", and are not
7679       necessarily at infinity but if they are, oscillations (i.e.
7680       "[[+-1],alpha I]") are forbidden.
7681
7682       The library syntax is intfouriersin"(void *E, GEN (*eval)(GEN,void*),
7683       GEN a, GEN b, GEN z, GEN tab, long prec)".
7684
7685   intfuncinit"(X = a,b,expr,{flag = 0},{m = 0})"
7686       initalize tables for use with integral transforms such as
7687       "intmellininv", etc., where "a" and "b" are coded as in "intnum",
7688       "expr" is the function s(X) to which the integral transform is to be
7689       applied (which will multiply the weights of integration) and "m" is as
7690       in "intnuminit". If "flag" is nonzero, assumes that "s(-X) =
7691       \overline{s(X)}", which makes the computation twice as fast. See
7692       "intmellininvshort" for examples of the use of this function, which is
7693       particularly useful when the function s(X) is lengthy to compute, such
7694       as a gamma product.
7695
7696       The library syntax is intfuncinit"(void *E, GEN (*eval)(GEN,void*), GEN
7697       a,GEN b,long m, long flag, long prec)".  Note that the order of "m" and
7698       "flag" are reversed compared to the "GP" syntax.
7699
7700   intlaplaceinv"(X = sig,z,expr,{tab})"
7701       numerical integration of "expr(X)e^{Xz}" with respect to "X" on the
7702       line " Re (X) = sig", divided by "2iPi", in other words, inverse
7703       Laplace transform of the function corresponding to expr at the value
7704       "z".
7705
7706       "sig" is coded as follows. Either it is a real number "sigma", equal to
7707       the abcissa of integration, and then the function to be integrated is
7708       assumed to be slowly decreasing when the imaginary part of the variable
7709       tends to "+- oo ". Or it is a two component vector "[sigma,alpha]",
7710       where "sigma" is as before, and either "alpha = 0" for slowly
7711       decreasing functions, or "alpha > 0" for functions decreasing like "
7712       exp (-alpha t)". Note that it is not necessary to choose the exact
7713       value of "alpha". tab is as in "intnum".
7714
7715       It is often a good idea to use this function with a value of "m" one or
7716       two higher than the one chosen by default (which can be viewed thanks
7717       to the function "intnumstep"), or to increase the abcissa of
7718       integration "sigma". For example:
7719
7720         ? intlaplaceinv(x=100, 1, 1/x) - 1
7721         time = 330 ms.
7722         %7 = 1.07... E-72 + 3.2... E-72*I \\ not so good
7723         ? intlaplaceinv(x=100, 1, 1/x) - 1
7724         time = 330 ms.
7725         %7 = 1.07... E-72 + 3.2... E-72*I \\ better
7726         ? intlaplaceinv(x=100, 1, 1/x) - 1
7727         time = 330 ms.
7728         %7 = 1.07... E-72 + 3.2... E-72*I \\ perfect but slow.
7729         ? intlaplaceinv(x=100, 1, 1/x) - 1
7730         time = 330 ms.
7731         %7 = 1.07... E-72 + 3.2... E-72*I \\ better than %1
7732         ? intlaplaceinv(x=100, 1, 1/x) - 1
7733         time = 330 ms.
7734         %7 = 1.07... E-72 + 3.2... E-72*I \\ perfect, fast.
7735         ? intlaplaceinv(x=100, 1, 1/x) - 1
7736         time = 330 ms.
7737         %7 = 1.07... E-72 + 3.2... E-72*I \\ perfect, fastest, but why sig = 10?
7738         ? intlaplaceinv(x=100, 1, 1/x) - 1
7739         time = 330 ms.
7740         %7 = 1.07... E-72 + 3.2... E-72*I \\ too far now...
7741
7742       The library syntax is intlaplaceinv"(void *E, GEN (*eval)(GEN,void*),
7743       GEN sig,GEN z, GEN tab, long prec)".
7744
7745   intmellininv"(X = sig,z,expr,{tab})"
7746       numerical integration of "expr(X)z^{-X}" with respect to "X" on the
7747       line " Re (X) = sig", divided by "2iPi", in other words, inverse Mellin
7748       transform of the function corresponding to expr at the value "z".
7749
7750       "sig" is coded as follows. Either it is a real number "sigma", equal to
7751       the abcissa of integration, and then the function to be integrated is
7752       assumed to decrease exponentially fast, of the order of " exp (-t)"
7753       when the imaginary part of the variable tends to "+- oo ". Or it is a
7754       two component vector "[sigma,alpha]", where "sigma" is as before, and
7755       either "alpha = 0" for slowly decreasing functions, or "alpha > 0" for
7756       functions decreasing like " exp (-alpha t)", such as gamma products.
7757       Note that it is not necessary to choose the exact value of "alpha", and
7758       that "alpha = 1" (equivalent to "sig" alone) is usually sufficient. tab
7759       is as in "intnum".
7760
7761       As all similar functions, this function is provided for the convenience
7762       of the user, who could use "intnum" directly. However it is in general
7763       better to use "intmellininvshort".
7764
7765         ? \p 308
7766         ? intmellininv(s=2,4, gamma(s)^3);
7767         time = 51,300 ms. \\ reasonable.
7768         ? \p 308
7769         ? intmellininv(s=2,4, gamma(s)^3);
7770         time = 51,300 ms. \\ slow because of Gamma(s)^3.
7771
7772       The library syntax is intmellininv"(void *E, GEN (*eval)(GEN,void*),
7773       GEN sig, GEN z, GEN tab, long prec)".
7774
7775   intmellininvshort"(sig,z,tab)"
7776       numerical integration of "s(X)z^{-X}" with respect to "X" on the line "
7777       Re (X) = sig", divided by "2iPi", in other words, inverse Mellin
7778       transform of s(X) at the value "z".  Here s(X) is implicitly contained
7779       in tab in "intfuncinit" format, typically
7780
7781           tab = intfuncinit(T = [-1], [1], s(sig + I*T))
7782
7783       or similar commands. Take the example of the inverse Mellin transform
7784       of "Gamma(s)^3" given in "intmellininv":
7785
7786         ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7787         ? intmellininvshort(2,4, tab2)
7788         %6 = -1.2...E-42 - 3.2...E-109*I  \\ for clarity
7789         ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7790         ? intmellininvshort(2,4, tab2)
7791         %6 = -1.2...E-42 - 3.2...E-109*I  \\ not too fast because of Gamma(s)^3.
7792         ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7793         ? intmellininvshort(2,4, tab2)
7794         %6 = -1.2...E-42 - 3.2...E-109*I  \\ function of real type, decreasing as exp(-3Pi/2.|t|)
7795         ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7796         ? intmellininvshort(2,4, tab2)
7797         %6 = -1.2...E-42 - 3.2...E-109*I  \\ 50 times faster than A and perfect.
7798         ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7799         ? intmellininvshort(2,4, tab2)
7800         %6 = -1.2...E-42 - 3.2...E-109*I  \\ 63 digits lost
7801
7802       In the computation of tab, it was not essential to include the
7803       \emph{exact} exponential decrease of "Gamma(2+it)^3". But as the last
7804       example shows, a rough indication \emph{must} be given, otherwise slow
7805       decrease is assumed, resulting in catastrophic loss of accuracy.
7806
7807       The library syntax is intmellininvshort"(GEN sig, GEN z, GEN tab, long
7808       prec)".
7809
7810   intnum"(X = a,b,expr,{tab})"
7811       numerical integration of expr on "[a,b]" (possibly infinite interval)
7812       with respect to "X", where "a" and "b" are coded as explained below.
7813       The integrand may have values belonging to a vector space over the real
7814       numbers; in particular, it can be complex-valued or vector-valued.
7815
7816       If tab is omitted, necessary integration tables are computed using
7817       "intnuminit" according to the current precision. It may be a positive
7818       integer "m", and tables are computed assuming the integration step is
7819       "1/2^m". Finally tab can be a table output by "intnuminit", in which
7820       case it is used directly. This is important if several integrations of
7821       the same type are performed (on the same kind of interval and
7822       functions, and the same accuracy), since it saves expensive
7823       precomputations.
7824
7825       If tab is omitted the algorithm guesses a reasonable value for "m"
7826       depending on the current precision. That value may be obtained as
7827
7828           intnumstep()
7829
7830       However this value may be off from the optimal one, and this is
7831       important since the integration time is roughly proportional to "2^m".
7832       One may try consecutive values of "m" until they give the same value up
7833       to an accepted error.
7834
7835       The endpoints "a" and "b" are coded as follows. If "a" is not at "+- oo
7836       ", it is either coded as a scalar (real or complex), or as a two
7837       component vector "[a,alpha]", where the function is assumed to have a
7838       singularity of the form "(x-a)^{alpha+\epsilon}" at "a", where
7839       "\epsilon" indicates that powers of logarithms are neglected. In
7840       particular, "[a,alpha]" with "alpha >= 0" is equivalent to "a". If a
7841       wrong singularity exponent is used, the result will lose a catastrophic
7842       number of decimals, for instance approximately half the number of
7843       digits will be correct if "alpha = -1/2" is omitted.
7844
7845       The endpoints of integration can be "+- oo ", which is coded as "[+-
7846       1]" or as "[[+-1],alpha]". Here "alpha" codes the behaviour of the
7847       function at "+- oo " as follows.
7848
7849       \item "alpha = 0" (or no "alpha" at all, i.e. simply "[+-1]") assumes
7850       that the function to be integrated tends to zero, but not exponentially
7851       fast, and not oscillating such as " sin (x)/x".
7852
7853       \item "alpha > 0" assumes that the function tends to zero exponentially
7854       fast approximately as " exp (-alpha x)", including reasonably
7855       oscillating functions such as " exp (-x) sin (x)". The precise choice
7856       of "alpha", while useful in extreme cases, is not critical, and may be
7857       off by a \emph{factor} of 10 or more from the correct value.
7858
7859       \item "alpha < -1" assumes that the function tends to 0 slowly, like
7860       "x^{alpha}". Here it is essential to give the correct "alpha", if
7861       possible, but on the other hand "alpha <= -2" is equivalent to "alpha =
7862       0", in other words to no "alpha" at all.
7863
7864       The last two codes are reserved for oscillating functions.  Let "k > 0"
7865       real, and g(x) a nonoscillating function tending to 0, then
7866
7867       \item "alpha = k I" assumes that the function behaves like " cos
7868       (kx)g(x)".
7869
7870       \item "alpha = -kI" assumes that the function behaves like " sin
7871       (kx)g(x)".
7872
7873       Here it is critical to give the exact value of "k". If the oscillating
7874       part is not a pure sine or cosine, one must expand it into a Fourier
7875       series, use the above codings, and sum the resulting contributions.
7876       Otherwise you will get nonsense. Note that " cos (kx)" (and similarly "
7877       sin (kx)") means that very function, and not a translated version such
7878       as " cos (kx+a)".
7879
7880       If for instance "f(x) =  cos (kx)g(x)" where g(x) tends to zero
7881       exponentially fast as " exp (-alpha x)", it is up to the user to choose
7882       between "[[+-1],alpha]" and "[[+-1],kI]", but a good rule of thumb is
7883       that if the oscillations are much weaker than the exponential decrease,
7884       choose "[[+-1],alpha]", otherwise choose "[[+-1],kI]", although the
7885       latter can reasonably be used in all cases, while the former cannot. To
7886       take a specific example, in the inverse Mellin transform, the function
7887       to be integrated is almost always exponentially decreasing times
7888       oscillating. If we choose the oscillating type of integral we perhaps
7889       obtain the best results, at the expense of having to recompute our
7890       functions for a different value of the variable "z" giving the
7891       transform, preventing us to use a function such as "intmellininvshort".
7892       On the other hand using the exponential type of integral, we obtain
7893       less accurate results, but we skip expensive recomputations. See
7894       "intmellininvshort" and "intfuncinit" for more explanations.
7895
7896       Note. If you do not like the code "[+-1]" for "+- oo ", you are welcome
7897       to set, e.g "oo = [1]" or "INFINITY = [1]", then using "+oo", "-oo",
7898       "-INFINITY", etc. will have the expected behaviour.
7899
7900       We shall now see many examples to get a feeling for what the various
7901       parameters achieve. All examples below assume precision is set to 105
7902       decimal digits. We first type
7903
7904         ? \p 105
7905         ? oo = [1]  \\ for clarity
7906
7907       Apparent singularities. Even if the function f(x) represented by expr
7908       has no singularities, it may be important to define the function
7909       differently near special points. For instance, if "f(x) = 1 /( exp
7910       (x)-1) -  exp (-x)/x", then "int_0^ oo f(x)dx = gamma", Euler's
7911       constant "Euler". But
7912
7913         ? f(x) = 1/(exp(x)-1) - exp(-x)/x
7914         ? intnum(x = 0, [oo,1],  f(x)) - Euler
7915         %1 = 6.00... E-67
7916
7917       thus only correct to 76 decimal digits. This is because close to 0 the
7918       function "f" is computed with an enormous loss of accuracy.  A better
7919       solution is
7920
7921         ? intnum(x = 0, [oo,1],  g(x)) - Euler
7922         %2 = 0.E-106 \\ expansion around t = 0
7923         ? intnum(x = 0, [oo,1],  g(x)) - Euler
7924         %2 = 0.E-106 \\ note that 6.18 > 105
7925         ? intnum(x = 0, [oo,1],  g(x)) - Euler
7926         %2 = 0.E-106 \\ perfect
7927
7928       It is up to the user to determine constants such as the "10^{-18}" and
7929       7 used above.
7930
7931       True singularities. With true singularities the result is much worse.
7932       For instance
7933
7934         ? intnum(x = [0,-1/2], 1,  1/sqrt(x)) - 2
7935         %2 = 0.E-105 \\ only 59 correct decimals
7936
7937         ? intnum(x = [0,-1/2], 1,  1/sqrt(x)) - 2
7938         %2 = 0.E-105 \\ better
7939
7940       Oscillating functions.
7941
7942         ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7943         %6 = 0.0092... \\ nonsense
7944
7945         ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7946         %6 = 0.0092... \\ bad
7947
7948         ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7949         %6 = 0.0092... \\ perfect
7950
7951         ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7952         %6 = 0.0092... \\ oops, wrong k
7953
7954         ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7955         %6 = 0.0092... \\ perfect
7956
7957         ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7958         %6 = 0.0092... \\ bad
7959         ? sin(x)^3 - (3*sin(x)-sin(3*x))/4
7960         %7 = O(x^17)
7961
7962       We may use the above linearization and compute two oscillating
7963       integrals with ``infinite endpoints'' "[oo, -I]" and "[oo, -3*I]"
7964       respectively, or notice the obvious change of variable, and reduce to
7965       the single integral "(1/2)int_0^ oo  sin (x)/xdx". We finish with some
7966       more complicated examples:
7967
7968         ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7969         %6 = 5.45... E-107 \\ bad
7970         ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7971         %6 = 5.45... E-107 \\ OK
7972         ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7973         %6 = 5.45... E-107 \\ OK
7974         ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7975         %6 = 5.45... E-107 \\ lost 16 decimals. Try higher m:
7976         ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7977         %6 = 5.45... E-107 \\ the value of m actually used above.
7978         ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7979         %6 = 5.45... E-107 \\ try m one higher.
7980         ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7981         %6 = 5.45... E-107 \\ OK this time.
7982
7983       Warning. Like "sumalt", "intnum" often assigns a reasonable value to
7984       diverging integrals. Use these values at your own risk!  For example:
7985
7986         ? intnum(x = 0, [oo, -I], x^2*sin(x))
7987         %1 = -2.0000000000...
7988
7989       Note the formula
7990
7991         " int_0^ oo  sin (x)/x^sdx =  cos (Pi s/2) Gamma(1-s) , "
7992
7993       a priori valid only for "0 <  Re (s) < 2", but the right hand side
7994       provides an analytic continuation which may be evaluated at "s = -2"...
7995
7996       Multivariate integration.  Using successive univariate integration with
7997       respect to different formal parameters, it is immediate to do naive
7998       multivariate integration. But it is important to use a suitable
7999       "intnuminit" to precompute data for the \emph{internal} integrations at
8000       least!
8001
8002       For example, to compute the double integral on the unit disc "x^2+y^2
8003       <= 1" of the function "x^2+y^2", we can write
8004
8005         ? tab = intnuminit(-1,1);
8006         ? intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2, tab), tab)
8007
8008       The first tab is essential, the second optional. Compare:
8009
8010         ? intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2, tab), tab);
8011         time = 7,210 ms.  \\ slow
8012         ? intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2, tab), tab);
8013         time = 7,210 ms.  \\ faster
8014
8015       However, the "intnuminit" program is usually pessimistic when it comes
8016       to choosing the integration step "2^{-m}". It is often possible to
8017       improve the speed by trial and error. Continuing the above example:
8018
8019         ? test(m - 3)
8020         time = 120 ms.
8021         %3 = -7.23... E-60 \\ what value of m did it take ?
8022         ? test(m - 3)
8023         time = 120 ms.
8024         %3 = -7.23... E-60 \\ 4 = 2^2 times faster and still OK.
8025         ? test(m - 3)
8026         time = 120 ms.
8027         %3 = -7.23... E-60 \\ 16 = 2^4 times faster and still OK.
8028         ? test(m - 3)
8029         time = 120 ms.
8030         %3 = -7.23... E-60 \\ 64 = 2^6 times faster, lost 45 decimals.
8031
8032       The library syntax is intnum"(void *E, GEN (*eval)(GEN,void*), GEN
8033       a,GEN b,GEN tab, long prec)", where an omitted tab is coded as "NULL".
8034
8035   intnuminit"(a,b,{m = 0})"
8036       initialize tables for integration from "a" to "b", where "a" and "b"
8037       are coded as in "intnum". Only the compactness, the possible existence
8038       of singularities, the speed of decrease or the oscillations at infinity
8039       are taken into account, and not the values.  For instance
8040       "intnuminit(-1,1)" is equivalent to "intnuminit(0,Pi)", and
8041       "intnuminit([0,-1/2],[1])" is equivalent to "
8042       intnuminit([-1],[-1,-1/2])". If "m" is not given, it is computed
8043       according to the current precision. Otherwise the integration step is
8044       "1/2^m". Reasonable values of "m" are "m = 6" or "m = 7" for 100
8045       decimal digits, and "m = 9" for 1000 decimal digits.
8046
8047       The result is technical, but in some cases it is useful to know the
8048       output.  Let "x = phi(t)" be the change of variable which is used.
8049       tab[1] contains the integer "m" as above, either given by the user or
8050       computed from the default precision, and can be recomputed directly
8051       using the function "intnumstep".  tab[2] and tab[3] contain
8052       respectively the abcissa and weight corresponding to "t = 0" ("phi(0)"
8053       and "phi'(0)"). tab[4] and tab[5] contain the abcissas and weights
8054       corresponding to positive "t = nh" for "1 <= n <= N" and "h = 1/2^m"
8055       ("phi(nh)" and "phi'(nh)"). Finally tab[6] and tab[7] contain either
8056       the abcissas and weights corresponding to negative "t = nh" for "-N <=
8057       n <= -1", or may be empty (but not always) if "phi(t)" is an odd
8058       function (implicitly we would have "tab[6] = -tab[4]" and "tab[7] =
8059       tab[5]").
8060
8061       The library syntax is intnuminit"(GEN a, GEN b, long m, long prec)".
8062
8063   intnumromb"(X = a,b,expr,{flag = 0})"
8064       numerical integration of expr (smooth in "]a,b["), with respect to "X".
8065       This function is deprecated, use "intnum" instead.
8066
8067       Set "flag = 0" (or omit it altogether) when "a" and "b" are not too
8068       large, the function is smooth, and can be evaluated exactly everywhere
8069       on the interval "[a,b]".
8070
8071       If "flag = 1", uses a general driver routine for doing numerical
8072       integration, making no particular assumption (slow).
8073
8074       "flag = 2" is tailored for being used when "a" or "b" are infinite. One
8075       \emph{must} have "ab > 0", and in fact if for example "b = + oo ", then
8076       it is preferable to have "a" as large as possible, at least "a >= 1".
8077
8078       If "flag = 3", the function is allowed to be undefined (but continuous)
8079       at "a" or "b", for example the function " sin (x)/x" at "x = 0".
8080
8081       The user should not require too much accuracy: 18 or 28 decimal digits
8082       is OK, but not much more. In addition, analytical cleanup of the
8083       integral must have been done: there must be no singularities in the
8084       interval or at the boundaries. In practice this can be accomplished
8085       with a simple change of variable. Furthermore, for improper integrals,
8086       where one or both of the limits of integration are plus or minus
8087       infinity, the function must decrease sufficiently rapidly at infinity.
8088       This can often be accomplished through integration by parts. Finally,
8089       the function to be integrated should not be very small (compared to the
8090       current precision) on the entire interval. This can of course be
8091       accomplished by just multiplying by an appropriate constant.
8092
8093       Note that infinity can be represented with essentially no loss of
8094       accuracy by 1e1000. However beware of real underflow when dealing with
8095       rapidly decreasing functions. For example, if one wants to compute the
8096       "int_0^ oo e^{-x^2}dx" to 28 decimal digits, then one should set
8097       infinity equal to 10 for example, and certainly not to 1e1000.
8098
8099       The library syntax is intnumromb"(void *E, GEN (*eval)(GEN,void*), GEN
8100       a, GEN b, long flag, long prec)", where "eval(x, E)" returns the value
8101       of the function at "x".  You may store any additional information
8102       required by "eval" in "E", or set it to "NULL".
8103
8104   intnumstep"()"
8105       give the value of "m" used in all the "intnum" and "sumnum" programs,
8106       hence such that the integration step is equal to "1/2^m".
8107
8108       The library syntax is intnumstep"(long prec)".
8109
8110   prod"(X = a,b,expr,{x = 1})"
8111       product of expression expr, initialized at "x", the formal parameter
8112       "X" going from "a" to "b". As for "sum", the main purpose of the
8113       initialization parameter "x" is to force the type of the operations
8114       being performed. For example if it is set equal to the integer 1,
8115       operations will start being done exactly. If it is set equal to the
8116       real 1., they will be done using real numbers having the default
8117       precision. If it is set equal to the power series "1+O(X^k)" for a
8118       certain "k", they will be done using power series of precision at most
8119       "k".  These are the three most common initializations.
8120
8121       As an extreme example, compare
8122
8123         ? prod(i=1, 100, 1 - X^i);  \\ this has degree 5050 !!
8124         time = 3,335 ms.
8125         ? prod(i=1, 100, 1 - X^i, 1 + O(X^101))
8126         time = 43 ms.
8127         %2 = 1 - X - X^2 + X^5 + X^7 - X^12 - X^15 + X^22 + X^26 - X^35 - X^40 + \
8128           X^51 + X^57 - X^70 - X^77 + X^92 + X^100 + O(X^101)
8129
8130       The library syntax is produit"(entree *ep, GEN a, GEN b, char *expr,
8131       GEN x)".
8132
8133   prodeuler"(X = a,b,expr)"
8134       product of expression expr, initialized at 1. (i.e. to a \emph{real}
8135       number equal to 1 to the current "realprecision"), the formal parameter
8136       "X" ranging over the prime numbers between "a" and "b".
8137
8138       The library syntax is prodeuler"(void *E, GEN (*eval)(GEN,void*), GEN
8139       a,GEN b, long prec)".
8140
8141   prodinf"(X = a,expr,{flag = 0})"
8142       infinite product of expression expr, the formal parameter "X" starting
8143       at "a". The evaluation stops when the relative error of the expression
8144       minus 1 is less than the default precision. The expressions must always
8145       evaluate to an element of C.
8146
8147       If "flag = 1", do the product of the ("1+expr") instead.
8148
8149       The library syntax is prodinf"(void *E, GEN (*eval)(GEN, void*), GEN a,
8150       long prec)" ("flag = 0"), or prodinf1 with the same arguments ("flag =
8151       1").
8152
8153   solve"(X = a,b,expr)"
8154       find a real root of expression expr between "a" and "b", under the
8155       condition "expr(X = a) * expr(X = b) <= 0".  This routine uses Brent's
8156       method and can fail miserably if expr is not defined in the whole of
8157       "[a,b]" (try "solve(x = 1, 2, tan(x)").
8158
8159       The library syntax is zbrent"(void *E,GEN (*eval)(GEN,void*),GEN a,GEN
8160       b,long prec)".
8161
8162   sum"(X = a,b,expr,{x = 0})"
8163       sum of expression expr, initialized at "x", the formal parameter going
8164       from "a" to "b". As for "prod", the initialization parameter "x" may be
8165       given to force the type of the operations being performed.
8166
8167       As an extreme example, compare
8168
8169         ? sum(i=1, 5000, 1/i); \\ rational number: denominator has 2166 digits.
8170         time = 1,241 ms.
8171         ? sum(i=1, 5000, 1/i, 0.)
8172         time = 158 ms.
8173         %2 = 9.094508852984436967261245533
8174
8175       The library syntax is somme"(entree *ep, GEN a, GEN b, char *expr, GEN
8176       x)". This is to be used as follows: "ep" represents the dummy variable
8177       used in the expression "expr"
8178
8179         /* compute a^2 + ... + b^2 */
8180         {
8181           /* define the dummy variable "i" */
8182           entree *ep = is_entry("i");
8183           /* sum for a <= i <= b */
8184           return somme(ep, a, b, "i^2", gen_0);
8185         }
8186
8187   sumalt"(X = a,expr,{flag = 0})"
8188       numerical summation of the series expr, which should be an alternating
8189       series, the formal variable "X" starting at "a". Use an algorithm of
8190       F. Villegas as modified by D. Zagier (improves on Euler-Van Wijngaarden
8191       method).
8192
8193       If "flag = 1", use a variant with slightly different polynomials.
8194       Sometimes faster.
8195
8196       Divergent alternating series can sometimes be summed by this method, as
8197       well as series which are not exactly alternating (see for example
8198       "Label se:user_defined"). If the series already converges
8199       geometrically, "suminf" is often a better choice:
8200
8201         ? \p28
8202         ? sumalt(i = 1, -(-1)^i / i)  - log(2)
8203         time = 0 ms.
8204         %1 = -2.524354897 E-29
8205         ? suminf(i = 1, -(-1)^i / i)
8206           *** suminf: user interrupt after 10min, 20,100 ms.
8207         ? \p1000
8208         ? sumalt(i = 1, -(-1)^i / i)  - log(2)
8209         time = 90 ms.
8210         %2 = 4.459597722 E-1002
8211
8212         ? sumalt(i = 0, (-1)^i / i!) - exp(-1)
8213         time = 670 ms.
8214         %3 = -4.03698781490633483156497361352190615794353338591897830587 E-944
8215         ? suminf(i = 0, (-1)^i / i!) - exp(-1)
8216         time = 110 ms.
8217         %4 = -8.39147638 E-1000   \\  faster and more accurate
8218
8219       The library syntax is sumalt"(void *E, GEN (*eval)(GEN,void*),GEN
8220       a,long prec)". Also available is "sumalt2" with the same arguments
8221       ("flag = 1").
8222
8223   sumdiv"(n,X,expr)"
8224       sum of expression expr over the positive divisors of "n".
8225
8226       Arithmetic functions like "sigma" use the multiplicativity of the
8227       underlying expression to speed up the computation. In the present
8228       version /usr/share/libpari23, there is no way to indicate that expr is
8229       multiplicative in "n", hence specialized functions should be preferred
8230       whenever possible.
8231
8232       The library syntax is divsum"(entree *ep, GEN num, char *expr)".
8233
8234   suminf"(X = a,expr)"
8235       infinite sum of expression expr, the formal parameter "X" starting at
8236       "a". The evaluation stops when the relative error of the expression is
8237       less than the default precision for 3 consecutive evaluations. The
8238       expressions must always evaluate to a complex number.
8239
8240       If the series converges slowly, make sure "realprecision" is low (even
8241       28 digits may be too much). In this case, if the series is alternating
8242       or the terms have a constant sign, "sumalt" and "sumpos" should be used
8243       instead.
8244
8245         ? \p28
8246         ? suminf(i = 1, -(-1)^i / i)
8247           *** suminf: user interrupt after 10min, 20,100 ms.
8248         ? sumalt(i = 1, -(-1)^i / i) - log(2)
8249         time = 0 ms.
8250         %1 = -2.524354897 E-29
8251
8252       The library syntax is suminf"(void *E, GEN (*eval)(GEN,void*), GEN a,
8253       long prec)".
8254
8255   sumnum"(X = a,sig,expr,{tab}),{flag = 0}"
8256       numerical summation of expr, the variable "X" taking integer values
8257       from ceiling of "a" to "+ oo ", where expr is assumed to be a
8258       holomorphic function f(X) for " Re (X) >= sigma".
8259
8260       The parameter "sigma belongs to R" is coded in the argument "sig" as
8261       follows: it is either
8262
8263       \item a real number "sigma". Then the function "f" is assumed to
8264       decrease at least as "1/X^2" at infinity, but not exponentially;
8265
8266       \item a two-component vector "[sigma,alpha]", where "sigma" is as
8267       before, "alpha < -1". The function "f" is assumed to decrease like
8268       "X^{alpha}". In particular, "alpha <= -2" is equivalent to no "alpha"
8269       at all.
8270
8271       \item a two-component vector "[sigma,alpha]", where "sigma" is as
8272       before, "alpha > 0". The function "f" is assumed to decrease like " exp
8273       (-alpha X)". In this case it is essential that "alpha" be exactly the
8274       rate of exponential decrease, and it is usually a good idea to increase
8275       the default value of "m" used for the integration step. In practice, if
8276       the function is exponentially decreasing "sumnum" is slower and less
8277       accurate than "sumpos" or "suminf", so should not be used.
8278
8279       The function uses the "intnum" routines and integration on the line "
8280       Re (s) = sigma". The optional argument tab is as in intnum, except it
8281       must be initialized with "sumnuminit" instead of "intnuminit".
8282
8283       When tab is not precomputed, "sumnum" can be slower than "sumpos", when
8284       the latter is applicable. It is in general faster for slowly decreasing
8285       functions.
8286
8287       Finally, if "flag" is nonzero, we assume that the function "f" to be
8288       summed is of real type, i.e. satisfies "\overline{f(z)} =
8289       f(\overline{z})", which speeds up the computation.
8290
8291         ? d - c
8292         time = 0 ms.
8293         %5 = 1.97... E-306 \\ slower but done once and for all.
8294         ? d - c
8295         time = 0 ms.
8296         %5 = 1.97... E-306 \\ 3 times as fast as sumpos
8297         ? d - c
8298         time = 0 ms.
8299         %5 = 1.97... E-306 \\ perfect.
8300         ? d - c
8301         time = 0 ms.
8302         %5 = 1.97... E-306 \\ function of real type
8303         ? d - c
8304         time = 0 ms.
8305         %5 = 1.97... E-306 \\ twice as fast, no imaginary part.
8306         ? d - c
8307         time = 0 ms.
8308         %5 = 1.97... E-306 \\ fast
8309         ? d - c
8310         time = 0 ms.
8311         %5 = 1.97... E-306 \\ slow.
8312         ? d - c
8313         time = 0 ms.
8314         %5 = 1.97... E-306 \\ perfect.
8315
8316       For slowly decreasing function, we must indicate singularities:
8317
8318         time = 12,210 ms.
8319         ? b - zeta(4/3)
8320         %3 = 1.05... E-300 \\ slow because of the computation of n^{-4/3}.
8321         time = 12,210 ms.
8322         ? b - zeta(4/3)
8323         %3 = 1.05... E-300 \\ lost 200 decimals because of singularity at  oo
8324         time = 12,210 ms.
8325         ? b - zeta(4/3)
8326         %3 = 1.05... E-300 \\ of real type
8327         time = 12,210 ms.
8328         ? b - zeta(4/3)
8329         %3 = 1.05... E-300 \\ better
8330
8331       Since the \emph{complex} values of the function are used, beware of
8332       determination problems. For instance:
8333
8334         ? sumnum(n=1,[2,-3/2], 1/n^(3/2), tab,1) - zeta(3/2)
8335         time = 8,990 ms.
8336         %3 = -1.19... E-305 \\ fast and correct
8337         ? sumnum(n=1,[2,-3/2], 1/n^(3/2), tab,1) - zeta(3/2)
8338         time = 8,990 ms.
8339         %3 = -1.19... E-305 \\ nonsense. However
8340         ? sumnum(n=1,[2,-3/2], 1/n^(3/2), tab,1) - zeta(3/2)
8341         time = 8,990 ms.
8342         %3 = -1.19... E-305 \\ perfect, as 1/(n*sqrt{n}) above but much slower
8343
8344       For exponentially decreasing functions, "sumnum" is given for
8345       completeness, but one of "suminf" or "sumpos" should always be
8346       preferred. If you experiment with such functions and "sumnum" anyway,
8347       indicate the exact rate of decrease and increase "m" by 1 or 2:
8348
8349         ? m = intnumstep()
8350         %4 = 9
8351         ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8352         time = 11,770 ms.
8353         %5 = -1.9... E-305 \\ fast and perfect
8354         ? m = intnumstep()
8355         %4 = 9
8356         ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8357         time = 11,770 ms.
8358         %5 = -1.9... E-305 \\ also fast and perfect
8359         ? m = intnumstep()
8360         %4 = 9
8361         ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8362         time = 11,770 ms.
8363         %5 = -1.9... E-305 \\ nonsense
8364         ? m = intnumstep()
8365         %4 = 9
8366         ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8367         time = 11,770 ms.
8368         %5 = -1.9... E-305 \\ of real type
8369         ? m = intnumstep()
8370         %4 = 9
8371         ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8372         time = 11,770 ms.
8373         %5 = -1.9... E-305 \\ slow and lost 70 decimals
8374         ? m = intnumstep()
8375         %4 = 9
8376         ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8377         time = 11,770 ms.
8378         %5 = -1.9... E-305 \\ now perfect, but slow.
8379
8380       The library syntax is sumnum"(void *E, GEN (*eval)(GEN,void*), GEN
8381       a,GEN sig,GEN tab,long flag, long prec)".
8382
8383   sumnumalt"(X = a,sig,expr,{tab},{flag = 0})"
8384       numerical summation of "(-1)^Xexpr(X)", the variable "X" taking integer
8385       values from ceiling of "a" to "+ oo ", where expr is assumed to be a
8386       holomorphic function for " Re (X) >= sig" (or "sig[1]").
8387
8388       Warning. This function uses the "intnum" routines and is orders of
8389       magnitude slower than "sumalt". It is only given for completeness and
8390       should not be used in practice.
8391
8392       Warning2. The expression expr must \emph{not} include the "(-1)^X"
8393       coefficient. Thus "sumalt(n = a,(-1)^nf(n))" is (approximately) equal
8394       to "sumnumalt(n = a,sig,f(n))".
8395
8396       "sig" is coded as in "sumnum". However for slowly decreasing functions
8397       (where "sig" is coded as "[sigma,alpha]" with "alpha < -1"), it is not
8398       really important to indicate "alpha". In fact, as for "sumalt", the
8399       program will often give meaningful results (usually analytic
8400       continuations) even for divergent series. On the other hand the
8401       exponential decrease must be indicated.
8402
8403       tab is as in "intnum", but if used must be initialized with
8404       "sumnuminit". If "flag" is nonzero, assumes that the function "f" to be
8405       summed is of real type, i.e. satisfies "\overline{f(z)} =
8406       f(\overline{z})", and then twice faster when tab is precomputed.
8407
8408         ? a - b
8409         time = 0 ms.
8410         %1 = -1.66... E-308 \\ abcissa sigma = 2, alternating sums.
8411         ? a - b
8412         time = 0 ms.
8413         %1 = -1.66... E-308 \\ slow, but done once and for all.
8414         ? a - b
8415         time = 0 ms.
8416         %1 = -1.66... E-308 \\ similar speed to sumnum
8417         ? a - b
8418         time = 0 ms.
8419         %1 = -1.66... E-308 \\ infinitely faster!
8420         ? a - b
8421         time = 0 ms.
8422         %1 = -1.66... E-308 \\ perfect
8423
8424       The library syntax is sumnumalt"(void *E, GEN (*eval)(GEN,void*), GEN
8425       a, GEN sig, GEN tab, long flag, long prec)".
8426
8427   sumnuminit"(sig,{m = 0},{sgn = 1})"
8428       initialize tables for numerical summation using "sumnum" (with "sgn =
8429       1") or "sumnumalt" (with "sgn = -1"), "sig" is the abcissa of
8430       integration coded as in "sumnum", and "m" is as in "intnuminit".
8431
8432       The library syntax is sumnuminit"(GEN sig, long m, long sgn, long
8433       prec)".
8434
8435   sumpos"(X = a,expr,{flag = 0})"
8436       numerical summation of the series expr, which must be a series of terms
8437       having the same sign, the formal variable "X" starting at "a". The
8438       algorithm used is Van Wijngaarden's trick for converting such a series
8439       into an alternating one, and is quite slow. For regular functions, the
8440       function "sumnum" is in general much faster once the initializations
8441       have been made using "sumnuminit".
8442
8443       If "flag = 1", use slightly different polynomials. Sometimes faster.
8444
8445       The library syntax is sumpos"(void *E, GEN (*eval)(GEN,void*),GEN
8446       a,long prec)". Also available is "sumpos2" with the same arguments
8447       ("flag = 1").
8448

Plotting functions

8450       Although plotting is not even a side purpose of PARI, a number of
8451       plotting functions are provided. Moreover, a lot of people suggested
8452       ideas or submitted patches for this section of the code. Among these,
8453       special thanks go to Klaus-Peter Nischke who suggested the recursive
8454       plotting and the forking/resizing stuff under X11, and Ilya Zakharevich
8455       who undertook a complete rewrite of the graphic code, so that most of
8456       it is now platform-independent and should be easy to port or expand.
8457       There are three types of graphic functions.
8458
8459   High-level plotting functions
8460       (all the functions starting with "ploth") in which the user has little
8461       to do but explain what type of plot he wants, and whose syntax is
8462       similar to the one used in the preceding section.
8463
8464   Low-level plotting functions
8465       (called rectplot functions, sharing the prefix "plot"), where every
8466       drawing primitive (point, line, box, etc.) is specified by the user.
8467       These low-level functions work as follows. You have at your disposal 16
8468       virtual windows which are filled independently, and can then be
8469       physically ORed on a single window at user-defined positions. These
8470       windows are numbered from 0 to 15, and must be initialized before being
8471       used by the function "plotinit", which specifies the height and width
8472       of the virtual window (called a rectwindow in the sequel). At all
8473       times, a virtual cursor (initialized at "[0,0]") is associated to the
8474       window, and its current value can be obtained using the function
8475       "plotcursor".
8476
8477       A number of primitive graphic objects (called rect objects) can then be
8478       drawn in these windows, using a default color associated to that window
8479       (which can be changed under X11, using the "plotcolor" function, black
8480       otherwise) and only the part of the object which is inside the window
8481       will be drawn, with the exception of polygons and strings which are
8482       drawn entirely.  The ones sharing the prefix "plotr" draw relatively to
8483       the current position of the virtual cursor, the others use absolute
8484       coordinates. Those having the prefix "plotrecth" put in the rectwindow
8485       a large batch of rect objects corresponding to the output of the
8486       related "ploth" function.
8487
8488       Finally, the actual physical drawing is done using the function
8489       "plotdraw". The rectwindows are preserved so that further drawings
8490       using the same windows at different positions or different windows can
8491       be done without extra work. To erase a window (and free the
8492       corresponding memory), use the function "plotkill". It is not possible
8493       to partially erase a window. Erase it completely, initialize it again
8494       and then fill it with the graphic objects that you want to keep.
8495
8496       In addition to initializing the window, you may use a scaled window to
8497       avoid unnecessary conversions. For this, use the function "plotscale"
8498       below. As long as this function is not called, the scaling is simply
8499       the number of pixels, the origin being at the upper left and the
8500       "y"-coordinates going downwards.
8501
8502       Note that in the present version /usr/share/libpari23 all plotting
8503       functions (both low and high level) are written for the X11-window
8504       system (hence also for GUI's based on X11 such as Openwindows and
8505       Motif) only, though little code remains which is actually platform-
8506       dependent. It is also possible to compile "gp" with either of the Qt or
8507       FLTK graphical libraries. A Suntools/Sunview, Macintosh, and an
8508       Atari/Gem port were provided for previous versions, but are now
8509       obsolete.
8510
8511       Under X11, the physical window (opened by "plotdraw" or any of the
8512       "ploth*" functions) is completely separated from "gp" (technically, a
8513       "fork" is done, and the non-graphical memory is immediately freed in
8514       the child process), which means you can go on working in the current
8515       "gp" session, without having to kill the window first. Under X11, this
8516       window can be closed, enlarged or reduced using the standard window
8517       manager functions.  No zooming procedure is implemented though (yet).
8518
8519   Functions for PostScript output:
8520       in the same way that "printtex" allows you to have a TeX output
8521       corresponding to printed results, the functions starting with "ps"
8522       allow you to have "PostScript" output of the plots. This will not be
8523       absolutely identical with the screen output, but will be sufficiently
8524       close. Note that you can use PostScript output even if you do not have
8525       the plotting routines enabled. The PostScript output is written in a
8526       file whose name is derived from the "psfile" default ("./pari.ps" if
8527       you did not tamper with it). Each time a new PostScript output is asked
8528       for, the PostScript output is appended to that file. Hence you probably
8529       want to remove this file, or change the value of "psfile", in between
8530       plots. On the other hand, in this manner, as many plots as desired can
8531       be kept in a single file.
8532
8533   And library mode ?
8534       \emph{None of the graphic functions are available within the PARI
8535       library, you must be under "gp" to use them}. The reason for that is
8536       that you really should not use PARI for heavy-duty graphical work,
8537       there are better specialized alternatives around. This whole set of
8538       routines was only meant as a convenient, but simple-minded, visual aid.
8539       If you really insist on using these in your program (we warned you),
8540       the source ("plot*.c") should be readable enough for you to achieve
8541       something.
8542
8543   plot"(X = a,b,expr,{Ymin},{Ymax})"
8544       crude ASCII plot of the function represented by expression expr from
8545       "a" to "b", with Y ranging from Ymin to Ymax. If Ymin (resp. Ymax) is
8546       not given, the minima (resp. the maxima) of the computed values of the
8547       expression is used instead.
8548
8549   plotbox"(w,x2,y2)"
8550       let "(x1,y1)" be the current position of the virtual cursor. Draw in
8551       the rectwindow "w" the outline of the rectangle which is such that the
8552       points "(x1,y1)" and "(x2,y2)" are opposite corners. Only the part of
8553       the rectangle which is in "w" is drawn. The virtual cursor does
8554       \emph{not} move.
8555
8556   plotclip"(w)"
8557       `clips' the content of rectwindow "w", i.e remove all parts of the
8558       drawing that would not be visible on the screen.  Together with
8559       "plotcopy" this function enables you to draw on a scratchpad before
8560       commiting the part you're interested in to the final picture.
8561
8562   plotcolor"(w,c)"
8563       set default color to "c" in rectwindow "w".  In present version
8564       /usr/share/libpari23, this is only implemented for the X11 window
8565       system, and you only have the following palette to choose from:
8566
8567       1 = black, 2 = blue, 3 = sienna, 4 = red, 5 = green, 6 = grey, 7 =
8568       gainsborough.
8569
8570       Note that it should be fairly easy for you to hardwire some more colors
8571       by tweaking the files "rect.h" and "plotX.c". User-defined colormaps
8572       would be nice, and \emph{may} be available in future versions.
8573
8574   plotcopy"(w1,w2,dx,dy)"
8575       copy the contents of rectwindow "w1" to rectwindow "w2", with offset
8576       "(dx,dy)".
8577
8578   plotcursor"(w)"
8579       give as a 2-component vector the current (scaled) position of the
8580       virtual cursor corresponding to the rectwindow "w".
8581
8582   plotdraw"(list)"
8583       physically draw the rectwindows given in "list" which must be a vector
8584       whose number of components is divisible by 3. If "list =
8585       [w1,x1,y1,w2,x2,y2,...]", the windows "w1", "w2", etc. are physically
8586       placed with their upper left corner at physical position "(x1,y1)",
8587       "(x2,y2)",...respectively, and are then drawn together.  Overlapping
8588       regions will thus be drawn twice, and the windows are considered
8589       transparent. Then display the whole drawing in a special window on your
8590       screen.
8591
8592   ploth"(X = a,b,expr,{flag = 0},{n = 0})"
8593       high precision plot of the function "y = f(x)" represented by the
8594       expression expr, "x" going from "a" to "b". This opens a specific
8595       window (which is killed whenever you click on it), and returns a four-
8596       component vector giving the coordinates of the bounding box in the form
8597       "[xmin,xmax,ymin,ymax]".
8598
8599       Important note: Since this may involve a lot of function calls, it is
8600       advised to keep the current precision to a minimum (e.g. 9) before
8601       calling this function.
8602
8603       "n" specifies the number of reference point on the graph (0 means use
8604       the hardwired default values, that is: 1000 for general plot, 1500 for
8605       parametric plot, and 15 for recursive plot).
8606
8607       If no "flag" is given, expr is either a scalar expression f(X), in
8608       which case the plane curve "y = f(X)" will be drawn, or a vector
8609       "[f_1(X),...,f_k(X)]", and then all the curves "y = f_i(X)" will be
8610       drawn in the same window.
8611
8612       The binary digits of "flag" mean:
8613
8614       \item "1 = Parametric": parametric plot. Here expr must be a vector
8615       with an even number of components. Successive pairs are then understood
8616       as the parametric coordinates of a plane curve. Each of these are then
8617       drawn.
8618
8619       For instance:
8620
8621       "ploth(X = 0,2*Pi,[sin(X),cos(X)],1)" will draw a circle.
8622
8623       "ploth(X = 0,2*Pi,[sin(X),cos(X)])" will draw two entwined sinusoidal
8624       curves.
8625
8626       "ploth(X = 0,2*Pi,[X,X,sin(X),cos(X)],1)" will draw a circle and the
8627       line "y = x".
8628
8629       \item "2 = Recursive": recursive plot. If this flag is set, only
8630       \emph{one} curve can be drawn at a time, i.e. expr must be either a
8631       two-component vector (for a single parametric curve, and the parametric
8632       flag \emph{has} to be set), or a scalar function. The idea is to choose
8633       pairs of successive reference points, and if their middle point is not
8634       too far away from the segment joining them, draw this as a local
8635       approximation to the curve. Otherwise, add the middle point to the
8636       reference points. This is fast, and usually more precise than usual
8637       plot. Compare the results of
8638
8639         "ploth(X = -1,1,sin(1/X),2)  and  ploth(X = -1,1,sin(1/X))"
8640
8641       for instance. But beware that if you are extremely unlucky, or choose
8642       too few reference points, you may draw some nice polygon bearing little
8643       resemblance to the original curve. For instance you should \emph{never}
8644       plot recursively an odd function in a symmetric interval around 0. Try
8645
8646           ploth(x = -20, 20, sin(x), 2)
8647
8648       to see why. Hence, it's usually a good idea to try and plot the same
8649       curve with slightly different parameters.
8650
8651       The other values toggle various display options:
8652
8653       \item "4 = no_Rescale": do not rescale plot according to the computed
8654       extrema. This is meant to be used when graphing multiple functions on a
8655       rectwindow (as a "plotrecth" call), in conjunction with "plotscale".
8656
8657       \item "8 = no_X_axis": do not print the "x"-axis.
8658
8659       \item "16 = no_Y_axis": do not print the "y"-axis.
8660
8661       \item "32 = no_Frame": do not print frame.
8662
8663       \item "64 = no_Lines": only plot reference points, do not join them.
8664
8665       \item "128 = Points_too": plot both lines and points.
8666
8667       \item "256 = Splines": use splines to interpolate the points.
8668
8669       \item "512 = no_X_ticks": plot no "x"-ticks.
8670
8671       \item "1024 = no_Y_ticks": plot no "y"-ticks.
8672
8673       \item "2048 = Same_ticks": plot all ticks with the same length.
8674
8675   plothraw"(listx,listy,{flag = 0})"
8676       given listx and listy two vectors of equal length, plots (in high
8677       precision) the points whose "(x,y)"-coordinates are given in listx and
8678       listy. Automatic positioning and scaling is done, but with the same
8679       scaling factor on "x" and "y". If "flag" is 1, join points, other non-0
8680       flags toggle display options and should be combinations of bits "2^k",
8681       "k
8682        >= 3" as in "ploth".
8683
8684   plothsizes"()"
8685       return data corresponding to the output window in the form of a
8686       6-component vector: window width and height, sizes for ticks in
8687       horizontal and vertical directions (this is intended for the "gnuplot"
8688       interface and is currently not significant), width and height of
8689       characters.
8690
8691   plotinit"(w,x,y,{flag})"
8692       initialize the rectwindow "w", destroying any rect objects you may have
8693       already drawn in "w". The virtual cursor is set to "(0,0)". The
8694       rectwindow size is set to width "x" and height "y". If "flag = 0", "x"
8695       and "y" represent pixel units. Otherwise, "x" and "y" are understood as
8696       fractions of the size of the current output device (hence must be
8697       between 0 and 1) and internally converted to pixels.
8698
8699       The plotting device imposes an upper bound for "x" and "y", for
8700       instance the number of pixels for screen output. These bounds are
8701       available through the "plothsizes" function. The following sequence
8702       initializes in a portable way (i.e independent of the output device) a
8703       window of maximal size, accessed through coordinates in the "[0,1000]
8704       x [0,1000]" range:
8705
8706         s = plothsizes();
8707         plotinit(0, s[1]-1, s[2]-1);
8708         plotscale(0, 0,1000, 0,1000);
8709
8710   plotkill"(w)"
8711       erase rectwindow "w" and free the corresponding memory. Note that if
8712       you want to use the rectwindow "w" again, you have to use "plotinit"
8713       first to specify the new size. So it's better in this case to use
8714       "plotinit" directly as this throws away any previous work in the given
8715       rectwindow.
8716
8717   plotlines"(w,X,Y,{flag = 0})"
8718       draw on the rectwindow "w" the polygon such that the (x,y)-coordinates
8719       of the vertices are in the vectors of equal length "X" and "Y". For
8720       simplicity, the whole polygon is drawn, not only the part of the
8721       polygon which is inside the rectwindow. If "flag" is non-zero, close
8722       the polygon. In any case, the virtual cursor does not move.
8723
8724       "X" and "Y" are allowed to be scalars (in this case, both have to).
8725       There, a single segment will be drawn, between the virtual cursor
8726       current position and the point "(X,Y)". And only the part thereof which
8727       actually lies within the boundary of "w". Then \emph{move} the virtual
8728       cursor to "(X,Y)", even if it is outside the window. If you want to
8729       draw a line from "(x1,y1)" to "(x2,y2)" where "(x1,y1)" is not
8730       necessarily the position of the virtual cursor, use "plotmove(w,x1,y1)"
8731       before using this function.
8732
8733   plotlinetype"(w,type)"
8734       change the type of lines subsequently plotted in rectwindow "w". type
8735       "-2" corresponds to frames, "-1" to axes, larger values may correspond
8736       to something else. "w = -1" changes highlevel plotting. This is only
8737       taken into account by the "gnuplot" interface.
8738
8739   plotmove"(w,x,y)"
8740       move the virtual cursor of the rectwindow "w" to position "(x,y)".
8741
8742   plotpoints"(w,X,Y)"
8743       draw on the rectwindow "w" the points whose "(x,y)"-coordinates are in
8744       the vectors of equal length "X" and "Y" and which are inside "w". The
8745       virtual cursor does \emph{not} move. This is basically the same
8746       function as "plothraw", but either with no scaling factor or with a
8747       scale chosen using the function "plotscale".
8748
8749       As was the case with the "plotlines" function, "X" and "Y" are allowed
8750       to be (simultaneously) scalar. In this case, draw the single point
8751       "(X,Y)" on the rectwindow "w" (if it is actually inside "w"), and in
8752       any case \emph{move} the virtual cursor to position "(x,y)".
8753
8754   plotpointsize"(w,size)"
8755       changes the ``size'' of following points in rectwindow "w". If "w =
8756       -1", change it in all rectwindows.  This only works in the "gnuplot"
8757       interface.
8758
8759   plotpointtype"(w,type)"
8760       change the type of points subsequently plotted in rectwindow "w". "type
8761       = -1" corresponds to a dot, larger values may correspond to something
8762       else. "w = -1" changes highlevel plotting. This is only taken into
8763       account by the "gnuplot" interface.
8764
8765   plotrbox"(w,dx,dy)"
8766       draw in the rectwindow "w" the outline of the rectangle which is such
8767       that the points "(x1,y1)" and "(x1+dx,y1+dy)" are opposite corners,
8768       where "(x1,y1)" is the current position of the cursor.  Only the part
8769       of the rectangle which is in "w" is drawn. The virtual cursor does
8770       \emph{not} move.
8771
8772   plotrecth"(w,X = a,b,expr,{flag = 0},{n = 0})"
8773       writes to rectwindow "w" the curve output of "ploth""(w,X =
8774       a,b,expr,flag,n)".
8775
8776   plotrecthraw"(w,data,{flag = 0})"
8777       plot graph(s) for data in rectwindow "w". "flag" has the same
8778       significance here as in "ploth", though recursive plot is no more
8779       significant.
8780
8781       data is a vector of vectors, each corresponding to a list a
8782       coordinates.  If parametric plot is set, there must be an even number
8783       of vectors, each successive pair corresponding to a curve. Otherwise,
8784       the first one contains the "x" coordinates, and the other ones contain
8785       the "y"-coordinates of curves to plot.
8786
8787   plotrline"(w,dx,dy)"
8788       draw in the rectwindow "w" the part of the segment
8789       "(x1,y1)-(x1+dx,y1+dy)" which is inside "w", where "(x1,y1)" is the
8790       current position of the virtual cursor, and move the virtual cursor to
8791       "(x1+dx,y1+dy)" (even if it is outside the window).
8792
8793   plotrmove"(w,dx,dy)"
8794       move the virtual cursor of the rectwindow "w" to position
8795       "(x1+dx,y1+dy)", where "(x1,y1)" is the initial position of the cursor
8796       (i.e. to position "(dx,dy)" relative to the initial cursor).
8797
8798   plotrpoint"(w,dx,dy)"
8799       draw the point "(x1+dx,y1+dy)" on the rectwindow "w" (if it is inside
8800       "w"), where "(x1,y1)" is the current position of the cursor, and in any
8801       case move the virtual cursor to position "(x1+dx,y1+dy)".
8802
8803   plotscale"(w,x1,x2,y1,y2)"
8804       scale the local coordinates of the rectwindow "w" so that "x" goes from
8805       "x1" to "x2" and "y" goes from "y1" to "y2" ("x2 < x1" and "y2 < y1"
8806       being allowed). Initially, after the initialization of the rectwindow
8807       "w" using the function "plotinit", the default scaling is the graphic
8808       pixel count, and in particular the "y" axis is oriented downwards since
8809       the origin is at the upper left. The function "plotscale" allows to
8810       change all these defaults and should be used whenever functions are
8811       graphed.
8812
8813   plotstring"(w,x,{flag = 0})"
8814       draw on the rectwindow "w" the String "x" (see "Label se:strings"), at
8815       the current position of the cursor.
8816
8817       flag is used for justification: bits 1 and 2 regulate horizontal
8818       alignment: left if 0, right if 2, center if 1. Bits 4 and 8 regulate
8819       vertical alignment: bottom if 0, top if 8, v-center if 4. Can insert
8820       additional small gap between point and string: horizontal if bit 16 is
8821       set, vertical if bit 32 is set (see the tutorial for an example).
8822
8823   psdraw"(list)"
8824       same as "plotdraw", except that the output is a PostScript program
8825       appended to the "psfile".
8826
8827   psploth"(X = a,b,expr)"
8828       same as "ploth", except that the output is a PostScript program
8829       appended to the "psfile".
8830
8831   psplothraw"(listx,listy)"
8832       same as "plothraw", except that the output is a PostScript program
8833       appended to the "psfile".
8834

Programming in GP

8836       =head2 Control statements.
8837
8838       A number of control statements are available in GP. They are simpler
8839       and have a syntax slightly different from their C counterparts, but are
8840       quite powerful enough to write any kind of program. Some of them are
8841       specific to GP, since they are made for number theorists. As usual, "X"
8842       will denote any simple variable name, and seq will always denote a
8843       sequence of expressions, including the empty sequence.
8844
8845       Caveat: in constructs like
8846
8847             for (X = a,b, seq)
8848
8849       the variable "X" is considered local to the loop, leading to possibly
8850       unexpected behaviour:
8851
8852             n = 5;
8853             for (n = 1, 10,
8854               if (something_nice(), break);
8855             );
8856             \\  at this point n is 5 !
8857
8858       If the sequence "seq" modifies the loop index, then the loop is
8859       modified accordingly:
8860
8861             ? for (n = 1, 10, n += 2; print(n))
8862             3
8863             6
8864             9
8865             12
8866
8867       break"({n = 1})"
8868           interrupts execution of current seq, and immediately exits from the
8869           "n" innermost enclosing loops, within the current function call (or
8870           the top level loop). "n" must be bigger than 1.  If "n" is greater
8871           than the number of enclosing loops, all enclosing loops are exited.
8872
8873       for"(X = a,b,seq)"
8874           evaluates seq, where the formal variable "X" goes from "a" to "b".
8875           Nothing is done if "a > b".  "a" and "b" must be in R.
8876
8877       fordiv"(n,X,seq)"
8878           evaluates seq, where the formal variable "X" ranges through the
8879           divisors of "n" (see "divisors", which is used as a subroutine). It
8880           is assumed that "factor" can handle "n", without negative
8881           exponents. Instead of "n", it is possible to input a factorization
8882           matrix, i.e. the output of factor(n).
8883
8884           This routine uses "divisors" as a subroutine, then loops over the
8885           divisors. In particular, if "n" is an integer, divisors are sorted
8886           by increasing size.
8887
8888           To avoid storing all divisors, possibly using a lot of memory, the
8889           following (much slower) routine loops over the divisors using
8890           essentially constant space:
8891
8892                 FORDIV(N)=
8893                 { local(P, E);
8894
8895                   P = factor(N); E = P[,2]; P = P[,1];
8896                   forvec( v = vector(#E, i, [0,E[i]]),
8897                     X = factorback(P, v)
8898                     \\ ...
8899                   );
8900                 }
8901                 ? for(i=1,10^5, FORDIV(i))
8902                 time = 3,445 ms.
8903                 ? for(i=1,10^5, fordiv(i, d, ))
8904                 time = 490 ms.
8905
8906       forell"(E,a,b,seq)"
8907           evaluates seq, where the formal variable "E" ranges through all
8908           elliptic curves of conductors from "a" to "b". Th "elldata"
8909           database must be installed and contain data for the specified
8910           conductors.
8911
8912       forprime"(X = a,b,seq)"
8913           evaluates seq, where the formal variable "X" ranges over the prime
8914           numbers between "a" to "b" (including "a" and "b" if they are
8915           prime). More precisely, the value of "X" is incremented to the
8916           smallest prime strictly larger than "X" at the end of each
8917           iteration. Nothing is done if "a > b". Note that "a" and "b" must
8918           be in R.
8919
8920             ? { forprime(p = 2, 12,
8921                   print(p);
8922                   if (p == 3, p = 6);
8923                 )
8924               }
8925             2
8926             3
8927             7
8928             11
8929
8930       forstep"(X = a,b,s,seq)"
8931           evaluates seq, where the formal variable "X" goes from "a" to "b",
8932           in increments of "s".  Nothing is done if "s > 0" and "a > b" or if
8933           "s < 0" and "a < b". "s" must be in "R^*" or a vector of steps
8934           "[s_1,...,s_n]". In the latter case, the successive steps are used
8935           in the order they appear in "s".
8936
8937             ? forstep(x=5, 20, [2,4], print(x))
8938             5
8939             7
8940             11
8941             13
8942             17
8943             19
8944
8945       forsubgroup"(H = G,{B},seq)"
8946           evaluates seq for each subgroup "H" of the \emph{abelian} group "G"
8947           (given in SNF form or as a vector of elementary divisors), whose
8948           index is bounded by "B". The subgroups are not ordered in any
8949           obvious way, unless "G" is a "p"-group in which case Birkhoff's
8950           algorithm produces them by decreasing index. A subgroup is given as
8951           a matrix whose columns give its generators on the implicit
8952           generators of "G". For example, the following prints all subgroups
8953           of index less than 2 in "G = Z/2Z g_1  x Z/2Z g_2":
8954
8955             ? G = [2,2]; forsubgroup(H=G, 2, print(H))
8956             [1; 1]
8957             [1; 2]
8958             [2; 1]
8959             [1, 0; 1, 1]
8960
8961           The last one, for instance is generated by "(g_1, g_1 + g_2)". This
8962           routine is intended to treat huge groups, when "subgrouplist" is
8963           not an option due to the sheer size of the output.
8964
8965           For maximal speed the subgroups have been left as produced by the
8966           algorithm.  To print them in canonical form (as left divisors of
8967           "G" in HNF form), one can for instance use
8968
8969             ? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H))))
8970             [2, 1; 0, 1]
8971             [1, 0; 0, 2]
8972             [2, 0; 0, 1]
8973             [1, 0; 0, 1]
8974
8975           Note that in this last representation, the index "[G:H]" is given
8976           by the determinant. See "galoissubcyclo" and "galoisfixedfield" for
8977           "nfsubfields" applications to Galois theory.
8978
8979           Warning: the present implementation cannot treat a group "G", if
8980           one of its "p"-Sylow subgroups has a cyclic factor with more than
8981           "2^{31}", resp. "2^{63}" elements on a 32-bit, resp. 64-bit
8982           architecture.
8983
8984       forvec"(X = v,seq,{flag = 0})"
8985           Let "v" be an "n"-component vector (where "n" is arbitrary) of two-
8986           component vectors "[a_i,b_i]" for "1 <= i <= n". This routine
8987           evaluates seq, where the formal variables "X[1],..., X[n]" go from
8988           "a_1" to "b_1",..., from "a_n" to "b_n", i.e. "X" goes from
8989           "[a_1,...,a_n]" to "[b_1,...,b_n]" with respect to the
8990           lexicographic ordering. (The formal variable with the highest index
8991           moves the fastest.) If "flag = 1", generate only nondecreasing
8992           vectors "X", and if "flag = 2", generate only strictly increasing
8993           vectors "X".
8994
8995       if"(a,{seq1},{seq2})"
8996           evaluates the expression sequence seq1 if "a" is non-zero,
8997           otherwise the expression seq2. Of course, seq1 or seq2 may be
8998           empty:
8999
9000           "if (a,seq)" evaluates seq if "a" is not equal to zero (you don't
9001           have to write the second comma), and does nothing otherwise,
9002
9003           "if (a,,seq)" evaluates seq if "a" is equal to zero, and does
9004           nothing otherwise. You could get the same result using the "!"
9005           ("not") operator: "if (!a,seq)".
9006
9007           Note that the boolean operators "&&" and "||" are evaluated
9008           according to operator precedence as explained in "Label
9009           se:operators", but that, contrary to other operators, the
9010           evaluation of the arguments is stopped as soon as the final truth
9011           value has been determined. For instance
9012
9013                 if (reallydoit && longcomplicatedfunction(), ...)%
9014
9015           is a perfectly safe statement.
9016
9017           Recall that functions such as "break" and "next" operate on
9018           \emph{loops} (such as "forxxx", "while", "until"). The "if"
9019           statement is \emph{not} a loop (obviously!).
9020
9021       next"({n = 1})"
9022           interrupts execution of current "seq", resume the next iteration of
9023           the innermost enclosing loop, within the current function call (or
9024           top level loop). If "n" is specified, resume at the "n"-th
9025           enclosing loop. If "n" is bigger than the number of enclosing
9026           loops, all enclosing loops are exited.
9027
9028       return"({x = 0})"
9029           returns from current subroutine, with result "x". If "x" is
9030           omitted, return the "(void)" value (return no result, like
9031           "print").
9032
9033       until"(a,seq)"
9034           evaluates seq until "a" is not equal to 0 (i.e. until "a" is true).
9035           If "a" is initially not equal to 0, seq is evaluated once (more
9036           generally, the condition on "a" is tested \emph{after} execution of
9037           the seq, not before as in "while").
9038
9039       while"(a,seq)"
9040           while "a" is non-zero, evaluates the expression sequence seq. The
9041           test is made \emph{before} evaluating the "seq", hence in
9042           particular if "a" is initially equal to zero the seq will not be
9043           evaluated at all.
9044
9045   Specific functions used in GP programming
9046       In addition to the general PARI functions, it is necessary to have some
9047       functions which will be of use specifically for "gp", though a few of
9048       these can be accessed under library mode. Before we start describing
9049       these, we recall the difference between \emph{strings} and
9050       \emph{keywords} (see "Label se:strings"): the latter don't get expanded
9051       at all, and you can type them without any enclosing quotes. The former
9052       are dynamic objects, where everything outside quotes gets immediately
9053       expanded.
9054
9055       addhelp"(S,str)"
9056            changes the help message for the symbol "S". The string str is
9057           expanded on the spot and stored as the online help for "S". If "S"
9058           is a function \emph{you} have defined, its definition will still be
9059           printed before the message str.  It is recommended that you
9060           document global variables and user functions in this way. Of course
9061           "gp" will not protest if you skip this.
9062
9063           Nothing prevents you from modifying the help of built-in PARI
9064           functions. (But if you do, we would like to hear why you needed to
9065           do it!)
9066
9067       alias"(newkey,key)"
9068           defines the keyword newkey as an alias for keyword key. key must
9069           correspond to an existing \emph{function} name. This is different
9070           from the general user macros in that alias expansion takes place
9071           immediately upon execution, without having to look up any function
9072           code, and is thus much faster. A sample alias file "misc/gpalias"
9073           is provided with the standard distribution. Alias commands are
9074           meant to be read upon startup from the ".gprc" file, to cope with
9075           function names you are dissatisfied with, and should be useless in
9076           interactive usage.
9077
9078       allocatemem"({x = 0})"
9079           this is a very special operation which allows the user to change
9080           the stack size \emph{after} initialization. "x" must be a non-
9081           negative integer. If "x  ! = 0", a new stack of size
9082           "16*\ceil{x/16}" bytes is allocated, all the PARI data on the old
9083           stack is moved to the new one, and the old stack is discarded. If
9084           "x = 0", the size of the new stack is twice the size of the old
9085           one.
9086
9087           Although it is a function, "allocatemem" cannot be used in loop-
9088           like constructs, or as part of a larger expression, e.g "2 +
9089           allocatemem()".  Such an attempt will raise an error. The technical
9090           reason is that this routine usually moves the stack, so objects
9091           from the current expression may not be correct anymore, e.g. loop
9092           indexes.
9093
9094           The library syntax is allocatemoremem"(x)", where "x" is an
9095           unsigned long, and the return type is void. "gp" uses a variant
9096           which makes sure it was not called within a loop.
9097
9098       default"({key},{val})"
9099           returns the default corresponding to keyword key. If val is
9100           present, sets the default to val first (which is subject to string
9101           expansion first). Typing "default()" (or "\d") yields the complete
9102           default list as well as their current values.  See "Label
9103           se:defaults" for a list of available defaults, and "Label se:meta"
9104           for some shortcut alternatives. Note that the shortcut are meant
9105           for interactive use and usually display more information than
9106           "default".
9107
9108           The library syntax is gp_default"(key, val)", where key and val are
9109           "char *".
9110
9111       error"({str}*)"
9112           outputs its argument list (each of them interpreted as a string),
9113           then interrupts the running "gp" program, returning to the input
9114           prompt. For instance
9115
9116             error("n = ", n, " is not squarefree !")
9117
9118       extern"(str)"
9119           the string str is the name of an external command (i.e. one you
9120           would type from your UNIX shell prompt).  This command is
9121           immediately run and its input fed into "gp", just as if read from a
9122           file.
9123
9124           The library syntax is extern0"(str)", where str is a "char *".
9125
9126       getheap"()"
9127           returns a two-component row vector giving the number of objects on
9128           the heap and the amount of memory they occupy in long words. Useful
9129           mainly for debugging purposes.
9130
9131           The library syntax is getheap"()".
9132
9133       getrand"()"
9134           returns the current value of the random number seed. Useful mainly
9135           for debugging purposes.
9136
9137           The library syntax is getrand"()", returns a C long.
9138
9139       getstack"()"
9140           returns the current value of "top-avma", i.e. the number of bytes
9141           used up to now on the stack.  Should be equal to 0 in between
9142           commands. Useful mainly for debugging purposes.
9143
9144           The library syntax is getstack"()", returns a C long.
9145
9146       gettime"()"
9147           returns the time (in milliseconds) elapsed since either the last
9148           call to "gettime", or to the beginning of the containing GP
9149           instruction (if inside "gp"), whichever came last.
9150
9151           The library syntax is gettime"()", returns a C long.
9152
9153       global"(list of variables)"
9154
9155           declares the corresponding variables to be global. From now on, you
9156           will be forbidden to use them as formal parameters for function
9157           definitions or as loop indexes. This is especially useful when
9158           patching together various scripts, possibly written with different
9159           naming conventions. For instance the following situation is
9160           dangerous:
9161
9162             p = 3   \\ fix characteristic
9163             ...
9164             forprime(p = 2, N, ...)
9165             f(p) = ...
9166
9167           since within the loop or within the function's body (even worse: in
9168           the subroutines called in that scope), the true global value of "p"
9169           will be hidden. If the statement "global(p = 3)" appears at the
9170           beginning of the script, then both expressions will trigger syntax
9171           errors.
9172
9173           Calling "global" without arguments prints the list of global
9174           variables in use. In particular, "eval(global)" will output the
9175           values of all global variables.
9176
9177       input"()"
9178           reads a string, interpreted as a GP expression, from the input
9179           file, usually standard input (i.e. the keyboard). If a sequence of
9180           expressions is given, the result is the result of the last
9181           expression of the sequence. When using this instruction, it is
9182           useful to prompt for the string by using the "print1" function.
9183           Note that in the present version 2.19 of "pari.el", when using "gp"
9184           under GNU Emacs (see "Label se:emacs") one \emph{must} prompt for
9185           the string, with a string which ends with the same prompt as any of
9186           the previous ones (a "? " will do for instance).
9187
9188       install"(name,code,{gpname},{lib})"
9189           loads from dynamic library lib the function name. Assigns to it the
9190           name gpname in this "gp" session, with argument code code (see the
9191           Libpari Manual for an explanation of those). If lib is omitted,
9192           uses "libpari.so". If gpname is omitted, uses name.
9193
9194           This function is useful for adding custom functions to the "gp"
9195           interpreter, or picking useful functions from unrelated libraries.
9196           For instance, it makes the function "system" obsolete:
9197
9198             ? install(system, vs, sys, "libc.so")
9199             ? sys("ls gp*")
9200             gp.c            gp.h            gp_rl.c
9201
9202           But it also gives you access to all (non static) functions defined
9203           in the PARI library. For instance, the function "GEN addii(GEN x,
9204           GEN y)" adds two PARI integers, and is not directly accessible
9205           under "gp" (it's eventually called by the "+" operator of course):
9206
9207             ? install("addii", "GG")
9208             ? addii(1, 2)
9209             %1 = 3
9210
9211           Re-installing a function will print a Warning, and update the
9212           prototype code if needed, but will reload a symbol from the
9213           library, even it the latter has been recompiled.
9214
9215           Caution: This function may not work on all systems, especially when
9216           "gp" has been compiled statically. In that case, the first use of
9217           an installed function will provoke a Segmentation Fault, i.e. a
9218           major internal blunder (this should never happen with a dynamically
9219           linked executable).  Hence, if you intend to use this function,
9220           please check first on some harmless example such as the ones above
9221           that it works properly on your machine.
9222
9223       kill"(s)"
9224            kills the present value of the variable, alias or user-defined
9225           function "s". The corresponding identifier can now be used to name
9226           any GP object (variable or function). This is the only way to
9227           replace a variable by a function having the same name (or the other
9228           way round), as in the following example:
9229
9230             ? f = 1
9231             %1 = 1
9232             ? f(x) = 0
9233               ***   unused characters: f(x)=0
9234                                         ^----
9235             ? kill(f)
9236             ? f(x) = 0
9237             ? f()
9238             %2 = 0
9239
9240           When you kill a variable, all objects that used it become invalid.
9241           You can still display them, even though the killed variable will be
9242           printed in a funny way. For example:
9243
9244             ? a^2 + 1
9245             %1 = a^2 + 1
9246             ? kill(a)
9247             ? %1
9248             %2 = #<1>^2 + 1
9249
9250           If you simply want to restore a variable to its ``undefined'' value
9251           (monomial of degree one), use the quote operator: "a = 'a".
9252           Predefined symbols ("x" and GP function names) cannot be killed.
9253
9254       print"({str}*)"
9255           outputs its (string) arguments in raw format, ending with a
9256           newline.
9257
9258       print1"({str}*)"
9259           outputs its (string) arguments in raw format, without ending with a
9260           newline (note that you can still embed newlines within your
9261           strings, using the "\n" notation !).
9262
9263       printp"({str}*)"
9264           outputs its (string) arguments in prettyprint (beautified) format,
9265           ending with a newline.
9266
9267       printp1"({str}*)"
9268           outputs its (string) arguments in prettyprint (beautified) format,
9269           without ending with a newline.
9270
9271       printtex"({str}*)"
9272           outputs its (string) arguments in TeX format. This output can then
9273           be used in a TeX manuscript.  The printing is done on the standard
9274           output. If you want to print it to a file you should use "writetex"
9275           (see there).
9276
9277           Another possibility is to enable the "log" default (see "Label
9278           se:defaults").  You could for instance do:
9279
9280             default(logfile, "new.tex");
9281             default(log, 1);
9282             printtex(result);
9283
9284       quit"()"
9285           exits "gp".
9286
9287       read"({filename})"
9288           reads in the file filename (subject to string expansion). If
9289           filename is omitted, re-reads the last file that was fed into "gp".
9290           The return value is the result of the last expression evaluated.
9291
9292           If a GP "binary file" is read using this command (see "Label
9293           se:writebin"), the file is loaded and the last object in the file
9294           is returned.
9295
9296       readvec"({str})"
9297           reads in the file filename (subject to string expansion). If
9298           filename is omitted, re-reads the last file that was fed into "gp".
9299           The return value is a vector whose components are the evaluation of
9300           all sequences of instructions contained in the file. For instance,
9301           if file contains
9302
9303               1
9304               2
9305               3
9306
9307           then we will get:
9308
9309               ? \r a
9310               %1 = 1
9311               %2 = 2
9312               %3 = 3
9313               ? read(a)
9314               %4 = 3
9315               ? readvec(a)
9316               %5 = [1, 2, 3]
9317
9318           In general a sequence is just a single line, but as usual braces
9319           and "\\" may be used to enter multiline sequences.
9320
9321       reorder"({x = []})"
9322           "x" must be a vector. If "x" is the empty vector, this gives the
9323           vector whose components are the existing variables in increasing
9324           order (i.e. in decreasing importance). Killed variables (see
9325           "kill") will be shown as 0. If "x" is non-empty, it must be a
9326           permutation of variable names, and this permutation gives a new
9327           order of importance of the variables, \emph{for output only}. For
9328           example, if the existing order is "[x,y,z]", then after
9329           "reorder([z,x])" the order of importance of the variables, with
9330           respect to output, will be "[z,y,x]". The internal representation
9331           is unaffected.
9332
9333       setrand"(n)"
9334           reseeds the random number generator to the value "n". The initial
9335           seed is "n = 1".
9336
9337           The library syntax is setrand"(n)", where "n" is a "long". Returns
9338           "n".
9339
9340       system"(str)"
9341           str is a string representing a system command. This command is
9342           executed, its output written to the standard output (this won't get
9343           into your logfile), and control returns to the PARI system. This
9344           simply calls the C "system" command.
9345
9346       trap"({e}, {rec}, {seq})"
9347           tries to evaluate seq, trapping error "e", that is effectively
9348           preventing it from aborting computations in the usual way; the
9349           recovery sequence rec is executed if the error occurs and the
9350           evaluation of rec becomes the result of the command. If "e" is
9351           omitted, all exceptions are trapped. Note in particular that
9352           hitting "^C" (Control-C) raises an exception. See "Label
9353           se:errorrec" for an introduction to error recovery under "gp".
9354
9355             ? \\ trap division by 0
9356             ? inv(x) = trap (gdiver, INFINITY, 1/x)
9357             ? inv(2)
9358             %1 = 1/2
9359             ? inv(0)
9360             %2 = INFINITY
9361
9362           If seq is omitted, defines rec as a default action when catching
9363           exception "e", provided no other trap as above intercepts it first.
9364           The error message is printed, as well as the result of the
9365           evaluation of rec, and control is given back to the "gp" prompt. In
9366           particular, current computation is then lost.
9367
9368           The following error handler prints the list of all user variables,
9369           then stores in a file their name and their values:
9370
9371             ? { trap( ,
9372                   print(reorder);
9373                   writebin("crash")) }
9374
9375           If no recovery code is given (rec is omitted) a break loop will be
9376           started (see "Label se:breakloop"). In particular
9377
9378             ? trap()
9379
9380           by itself installs a default error handler, that will start a break
9381           loop whenever an exception is raised.
9382
9383           If rec is the empty string "" the default handler (for that error
9384           if "e" is present) is disabled.
9385
9386           Note: The interface is currently not adequate for trapping
9387           individual exceptions. In the current version /usr/share/libpari23,
9388           the following keywords are recognized, but the name list will be
9389           expanded and changed in the future (all library mode errors can be
9390           trapped: it's a matter of defining the keywords to "gp", and there
9391           are currently far too many useless ones):
9392
9393           "accurer": accuracy problem
9394
9395           "archer": not available on this architecture or operating system
9396
9397           "errpile": the PARI stack overflows
9398
9399           "gdiver": division by 0
9400
9401           "invmoder": impossible inverse modulo
9402
9403           "siginter": SIGINT received (usually from Control-C)
9404
9405           "talker": miscellaneous error
9406
9407           "typeer": wrong type
9408
9409           "user": user error (from the "error" function)
9410
9411       type"(x)"
9412           this is useful only under "gp". Returns the internal type name of
9413           the PARI object "x" as a  string. Check out existing type names
9414           with the metacommand "\t".  For example type(1) will return
9415           ""t_INT"".
9416
9417           The library syntax is type0"(x)", though the macro "typ" is usually
9418           simpler to use since it return an integer that can easily be
9419           matched with the symbols "t_*".  The name "type" was avoided due to
9420           the fact that "type" is a reserved identifier for some C(++)
9421           compilers.
9422
9423       version"()"
9424           Returns the current version number as a "t_VEC" with three integer
9425           components: major version number, minor version number and
9426           patchlevel. To check against a particular version number, you can
9427           use:
9428
9429                if (lex(version(), [2,2,0]) >= 0,
9430                  \\ code to be executed if we are running 2.2.0 or more recent.
9431                ,
9432                  \\ compatibility code
9433                );
9434
9435       whatnow"(key)"
9436           if keyword key is the name of a function that was present in GP
9437           version 1.39.15 or lower, outputs the new function name and syntax,
9438           if it changed at all (387 out of 560 did).
9439
9440       write"(filename,{str}*)"
9441           writes (appends) to filename the remaining arguments, and appends a
9442           newline (same output as "print").
9443
9444       write1"(filename,{str}*)"
9445           writes (appends) to filename the remaining arguments without a
9446           trailing newline (same output as "print1").
9447
9448       writebin"(filename,{x})"
9449           writes (appends) to filename the object "x" in binary format. This
9450           format is not human readable, but contains the exact internal
9451           structure of "x", and is much faster to save/load than a string
9452           expression, as would be produced by "write". The binary file format
9453           includes a magic number, so that such a file can be recognized and
9454           correctly input by the regular "read" or "\r" function. If saved
9455           objects refer to (polynomial) variables that are not defined in the
9456           new session, they will be displayed in a funny way (see "Label
9457           se:kill").
9458
9459           If "x" is omitted, saves all user variables from the session,
9460           together with their names. Reading such a ``named object'' back in
9461           a "gp" session will set the corresponding user variable to the
9462           saved value. E.g after
9463
9464             x = 1; writebin("log")
9465
9466           reading "log" into a clean session will set "x" to 1.  The relative
9467           variables priorities (see "Label se:priority") of new variables set
9468           in this way remain the same (preset variables retain their former
9469           priority, but are set to the new value). In particular, reading
9470           such a session log into a clean session will restore all variables
9471           exactly as they were in the original one.
9472
9473           User functions, installed functions and history objects can not be
9474           saved via this function. Just as a regular input file, a binary
9475           file can be compressed using "gzip", provided the file name has the
9476           standard ".gz" extension.
9477
9478           In the present implementation, the binary files are architecture
9479           dependent and compatibility with future versions of "gp" is not
9480           guaranteed. Hence binary files should not be used for long term
9481           storage (also, they are larger and harder to compress than text
9482           files).
9483
9484       writetex"(filename,{str}*)"
9485           as "write", in TeX format.
9486

POD ERRORS

9488       Hey! The above document had some coding errors, which are explained
9489       below:
9490
9491       Around line 9532:
9492           '=item' outside of any '=over'
9493
9494       Around line 9723:
9495           You forgot a '=back' before '=head2'
9496
9497       Around line 9734:
9498           '=item' outside of any '=over'
9499
9500           =over without closing =back
9501
9502
9503
9504perl v5.34.0                      2021-07-22                        libPARI(3)
Impressum