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

NAME

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

Standard monadic or dyadic operators

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

Conversions and similar elementary functions or commands

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

Transcendental functions

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

Arithmetic functions

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

Polynomials and power series

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

Vectors, matrices, linear algebra and sets

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

Sums, products, integrals and similar functions

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

Plotting functions

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

Programming in GP

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

POD ERRORS

9483       Hey! The above document had some coding errors, which are explained
9484       below:
9485
9486       Around line 9529:
9487           '=item' outside of any '=over'
9488
9489       Around line 9720:
9490           You forgot a '=back' before '=head2'
9491
9492       Around line 9731:
9493           '=item' outside of any '=over'
9494
9495           =over without closing =back
9496
9497
9498
9499perl v5.28.0                      2018-09-17                        libPARI(3)
Impressum