1libPARI(3) User Contributed Perl Documentation libPARI(3)
2
6 libPARI - Functions and Operations Available in PARI and GP
7
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 foo"(x,{flag = 0})": short description.
20 The library syntax is foo"(x,flag)".
22 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 " foo({x = 1},{y = 2},{z = 3}), "
36 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 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 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 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 \item generic: all valid values for the flag are individually described
62 (``If flag is equal to 1, then...'').
63 \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 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 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 fun(x, {flag = 0} ):
86 If flag is equal to 1 = AGM, use an agm formula\dots
88 which means that one can use indifferently "fun(x, 1)" or "fun(x,
90 AGM)".
91 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 Binary digits of flags mean: C<1 = Parametric>,
100 C<2 = Recursive>,...
101 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 Pointers.\varsidx{pointer} If a parameter in the function prototype is
107 prefixed with a & sign, as in
108 foo"(x,&e)"
110 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 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 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
137 +"/"-
138 The expressions "+""x" and "-""x" refer to monadic operators (the first
139 does nothing, the second negates "x").
140 The library syntax is gneg"(x)" for "-""x".
142 +, "-"
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 The library syntax is gadd"(x,y)" "x" "+" "y", " gsub(x,y)" for "x" "-"
151 "y".
152 *
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 If "x" and "y" are binary quadratic forms, compose them. See also
166 "qfbnucomp" and "qfbnupow".
167 The library syntax is gmul"(x,y)" for "x" "*" "y". Also available is "
169 gsqr(x)" for "x" "*" "x" (faster of course!).
170 /
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 The library syntax is gdiv"(x,y)" for "x" "/" "y".
188 \
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|[". quotient"
194 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 The library syntax is gdivent"(x,y)" for "x" "\" "y".
200 \/
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 When "x" is a vector or matrix, the operator is applied componentwise.
209 The library syntax is gdivround"(x,y)" for "x" "\/" "y".
211 %
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 ? (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 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 The library syntax is gmod"(x,y)" for "x" "%" "y".
234 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 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 ? 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 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 ^
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 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 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 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 ? 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 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 ? Mod(4,6)^(-1)
297 *** impossible inverse modulo: Mod(2, 6).
298 (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 For non-invertible "t_POLMOD", this will fail without exhibiting a
307 factor.
308 ? Mod(x^2, x^3-x)^(-1)
310 *** non-invertible polynomial in RgXQ_inv.
311 ? 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 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 ? 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 This is not guaranteed to work either since it must invert pivots. See
332 "Label se:linear_algebra".
333 The library syntax is gpow"(x,n,prec)" for "x^n".
335 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 See "Label se:bitand" for the behaviour at negative arguments.
343 The library syntax is bittest"(x,n)", where "n" and the result are
345 "long"s.
346 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 The library syntax is gshift"(x,n)" where "n" is a "long".
356 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 The library syntax is gmul2n"(x,n)" where "n" is a "long".
365 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 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 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 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 Also note that the "gcmp" and "gequal" functions return a C-integer,
394 and \emph{not} a "GEN" like "gle" etc.
395 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. and bitwise or"
403 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 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 ? 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 The library syntax is lexcmp"(x,y)".
426 sign"(x)"
428 sign (0, 1 or "-1") of "x", which must be of type integer, real or
429 fraction.
430 The library syntax is gsigne"(x)". The result is a "long".
432 max"(x,y)" and " min(x,y)"
434 creates the maximum and minimum of "x" and "y" when they can be
435 compared.
436 The library syntax is gmax"(x,y)" and " gmin(x,y)".
438 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 The library syntax is vecmax"(x)".
444 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 The library syntax is vecmin"(x)".
450
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 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 The library syntax is gtocol"(x)".
471 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 This is useless in library mode.
477 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 ? 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 [0 1 0]
497 [0 0 1]
499 ? Col( [1,2; 3,4] )
500 %4 = [[1, 2], [3, 4]]~
501 ? Mat(%)
502 %5 =
503 [1 2]
504 [3 4]
506 The library syntax is gtomat"(x)".
508 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 This function is not the same as "x" "%" "y", the result of which is an
517 integer or a polynomial.
518 "flag" is obsolete and should not be used.
520 The library syntax is gmodulo"(x,y)".
522 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 Warning: this is \emph{not} a substitution function. It will not
532 transform an object containing variables of higher priority than "v".
533 ? Pol(x + y, y)
535 *** Pol: variable must have higher priority in gtopoly.
536 The library syntax is gtopoly"(x,v)", where "v" is a variable number.
538 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 The library syntax is gtopolyrev"(x,v)", where "v" is a variable
549 number.
550 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 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 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 The warning given for "Pol" also applies here: this is not a
572 substitution function.
573 The library syntax is gtoser"(x,v)", where "v" is a variable number
575 (i.e. a C integer).
576 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 The library syntax is gtoset"(x)".
585 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 ? x2 = 0; i = 2; Str(x, i)
593 %1 = "x2"
594 ? eval(%)
595 %2 = 0
596 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 Strchr"(x)"
602 converts "x" to a string, translating each integer into a character.
603 ? 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 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 ? Strexpand("$HOME/doc")
618 %1 = "/home/pari/doc"
619 The individual arguments are read in string context, see "Label
621 se:strings".
622 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 The individual arguments are read in string context, see "Label
629 se:strings".
630 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 The library syntax is gtovec"(x)".
644 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 The library syntax is gtovecsmall"(x)".
654 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 The library syntax is binaire"(x)".
662 bitand"(x,y)"
664 bitwise "and" of two integers "x" and "y", that is the integer
665 "sum_i (x_i and y_i) 2^i"
667 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 ? bitand(5, 3)
674 %1 = 1
675 ? bitand(-5, 3)
676 %2 = 3
677 ? bitand(-5, -3)
678 %3 = -7
679 The library syntax is gbitand"(x,y)".
681 bitneg"(x,{n = -1})"
683 bitwise negation of an integer "x", truncated to "n" bits, that is the
684 integer
685 "sum_{i = 0}^{n-1} not(x_i) 2^i"
687 The special case "n = -1" means no truncation: an infinite sequence of
689 leading 1 is then represented as a negative number.
690 See "Label se:bitand" for the behaviour for negative arguments.
692 The library syntax is gbitneg"(x)".
694 bitnegimply"(x,y)"
696 bitwise negated imply of two integers "x" and "y" (or "not" "(x ==>
697 y)"), that is the integer
698 "sum (x_i and not(y_i)) 2^i"
700 See "Label se:bitand" for the behaviour for negative arguments.
702 The library syntax is gbitnegimply"(x,y)".
704 bitor"(x,y)"
706 bitwise (inclusive) "or" of two integers "x" and "y", that is the
707 integer
708 "sum (x_i or y_i) 2^i"
710 See "Label se:bitand" for the behaviour for negative arguments.
712 The library syntax is gbitor"(x,y)".
714 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 The library syntax is bittest"(x,n)", where "n" and the result are
722 "long"s.
723 bitxor"(x,y)"
725 bitwise (exclusive) "or" of two integers "x" and "y", that is the
726 integer
727 "sum (x_i xor y_i) 2^i"
729 See "Label se:bitand" for the behaviour for negative arguments.
731 The library syntax is gbitxor"(x,y)".
733 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 The library syntax is gceil"(x)".
740 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 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 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 The library syntax is changevar"(x,y)".
765 components of a PARI object
767 There are essentially three ways to extract the components from a PARI
768 object.
769 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 The library syntax is compo"(x,n)", where "n" is a "long".
782 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 For greater flexibility, vector or matrix types are also accepted for
794 "x", and the meaning is then identical with that of "compo".
795 Finally note that a scalar type is considered by "polcoeff" as a
797 polynomial of degree zero.
798 The library syntax is truecoeff"(x,n)".
800 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 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 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 The library syntax is gconj"(x)".
819 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 The library syntax is conjvec"(x,prec)".
832 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 denominator( content(x) )
840 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 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 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 The library syntax is denom"(x)".
854 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 The library syntax is gfloor"(x)".
861 frac"(x)"
863 fractional part of "x". Identical to "x-floor(x)". If "x" is real, the
864 result is in "[0,1[".
865 The library syntax is gfrac"(x)".
867 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 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 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 The library syntax is glength"(x)" and the result is a C long.
883 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 ? 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 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 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 The library syntax is gnorm"(x)".
917 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 ? 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 The library syntax is gnorml2"(x)".
937 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 numerator( content(x) )
945 instead.
947 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 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 The library syntax is numer"(x)".
958 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 The library syntax is numtoperm"(n,k)", where "n" is a "long".
965 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 The library syntax is padicprec"(x,p)" and the result is a "long"
973 integer.
974 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 The library syntax is permtonum"(x)".
980 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 For exact types, no change. For "x" a vector or a matrix, the operation
988 is done componentwise.
989 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 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 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 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 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 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 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 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 RANDOM(N) =
1028 { local(n, L);
1029 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 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 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 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 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 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 "truncate((2.4*X^2-1.7)/(X)) = 2.4*X,"
1061 whereas
1063 "round((2.4*X^2-1.7)/(X)) = (2*X^2-2)/(X)."
1065 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 The library syntax is grndtoi"(x,&e)", where "e" is a "long" integer.
1071 Also available is " ground(x)".
1072 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 This function is especially useful before using arithmetic functions,
1081 which expect integer arguments:
1082 ? 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 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 ? type(%1)
1097 %4 = "t_INT"
1098 The library syntax is simplify"(x)".
1100 sizebyte"(x)"
1102 outputs the total number of bytes occupied by the tree representing the
1103 PARI object "x".
1104 The library syntax is taille2"(x)" which returns a "long"; " taille(x)"
1106 returns the number of \emph{words} instead.
1107 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 The library syntax is sizedigit"(x)" which returns a "long".
1114 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 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 The library syntax is gcvtoi"(x,&e)", where "e" is a "long" integer.
1134 Also available is " gtrunc(x)".
1135 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 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 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 The library syntax is ggval"(x,p)", and the result is a "long".
1154 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 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
1168 As a general rule, which of course in some cases may have exceptions,
1169 transcendental functions operate in the following way:
1170 \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 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 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 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 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 \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" (Teichmueller character) and "agm" (arithmetic-
1201 geometric mean) are implemented.
1202 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 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 \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 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 \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 ^
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 The library syntax is gpow"(x,y,prec)".
1242 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 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 I
1254 the complex number " sqrt {-1}".
1255 The library syntax is the global variable "gi" (of type "GEN").
1257 Pi
1259 the constant "Pi" (3.14159...).
1260 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 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 ? 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 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 The library syntax is gabs"(x,prec)".
1284 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 The library syntax is gacos"(x,prec)".
1290 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 The library syntax is gach"(x,prec)".
1297 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 The library syntax is agm"(x,y,prec)".
1306 arg"(x)"
1308 argument of the complex number "x", such that "-Pi < arg(x) <= Pi".
1309 The library syntax is garg"(x,prec)".
1311 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 The library syntax is gasin"(x,prec)".
1318 asinh"(x)"
1320 principal branch of "sinh^{-1}(x)", i.e. such that "Im(asinh(x))
1321 belongs to [-Pi/2,Pi/2]".
1322 The library syntax is gash"(x,prec)".
1324 atan"(x)"
1326 principal branch of "tan^{-1}(x)", i.e. such that "Re(atan(x)) belongs
1327 to ]-Pi/2,Pi/2[".
1328 The library syntax is gatan"(x,prec)".
1330 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 The library syntax is gath"(x,prec)".
1337 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 The library syntax is bernfrac"(x)".
1344 bernreal"(x)"
1346 Bernoulli number "B_x", as "bernfrac", but "B_x" is returned as a real
1347 number (with the current precision).
1348 The library syntax is bernreal"(x,prec)".
1350 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 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 The library syntax is bernvec"(x)".
1363 besselh1"(nu,x)"
1365 "H^1"-Bessel function of index nu and argument "x".
1366 The library syntax is hbessel1"(nu,x,prec)".
1368 besselh2"(nu,x)"
1370 "H^2"-Bessel function of index nu and argument "x".
1371 The library syntax is hbessel2"(nu,x,prec)".
1373 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 The library syntax is ibessel"(nu,x,prec)".
1380 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 The library syntax is jbessel"(nu,x,prec)".
1387 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 The library syntax is jbesselh"(n,x,prec)".
1395 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 The library syntax is kbessel"(nu,x,prec)" and " kbessel2(nu,x,prec)"
1403 respectively.
1404 besseln"(nu,x)"
1406 "N"-Bessel function of index nu and argument "x".
1407 The library syntax is nbessel"(nu,x,prec)".
1409 cos"(x)"
1411 cosine of "x".
1412 The library syntax is gcos"(x,prec)".
1414 cosh"(x)"
1416 hyperbolic cosine of "x".
1417 The library syntax is gch"(x,prec)".
1419 cotan"(x)"
1421 cotangent of "x".
1422 The library syntax is gcotan"(x,prec)".
1424 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 The library syntax is dilog"(x,prec)".
1430 eint1"(x,{n})"
1432 exponential integral "int_x^ oo (e^{-t})/(t)dt" ("x belongs to R")
1433 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 The library syntax is veceint1"(x,n,prec)". Also available is "
1439 eint1(x,prec)".
1440 erfc"(x)"
1442 complementary error function "(2/ sqrt Pi)int_x^ oo e^{-t^2}dt" ("x
1443 belongs to R").
1444 The library syntax is erfc"(x,prec)".
1446 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 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 The library syntax is eta"(x,prec)".
1459 exp"(x)"
1461 exponential of "x". "p"-adic arguments with positive valuation are
1462 accepted.
1463 The library syntax is gexp"(x,prec)".
1465 gammah"(x)"
1467 gamma function evaluated at the argument "x+1/2".
1468 The library syntax is ggamd"(x,prec)".
1470 gamma"(x)"
1472 gamma function of "x".
1473 The library syntax is ggamma"(x,prec)".
1475 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 The library syntax is hyperu"(a,b,x,prec)".
1482 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 The library syntax is incgam"(s,x,prec)" and " incgam0(s,x,y,prec)",
1491 respectively (an omitted "y" is coded as "NULL").
1492 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 The library syntax is incgamc"(s,x,prec)".
1500 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 " log (x) ~ (Pi)/(2agm(1, 4/s)) - m log 2, "
1508 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 "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 The library syntax is glog"(x,prec)".
1519 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 The library syntax is glngamma"(x,prec)".
1527 polylog"(m,x,{flag = 0})"
1529 one of the different polylogarithms, depending on flag:
1530 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 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 If "flag = 1": compute "~ D_m(x)", defined for "|x| <= 1" by
1542 " 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 If "flag = 2": compute D_m(x), defined for "|x| <= 1" by
1547 " Re _m(sum_{k = 0}^{m-1}((- log |x|)^k)/(k!)Li_{m-k}(x) -(1)/(2)((-
1549 log |x|)^m)/(m!))."
1550 If "flag = 3": compute P_m(x), defined for "|x| <= 1" by
1552 " 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 These three functions satisfy the functional equation "f_m(1/x) =
1557 (-1)^{m-1}f_m(x)".
1558 The library syntax is polylog0"(m,x,flag,prec)".
1560 psi"(x)"
1562 the "psi"-function of "x", i.e. the logarithmic derivative
1563 "Gamma'(x)/Gamma(x)".
1564 The library syntax is gpsi"(x,prec)".
1566 sin"(x)"
1568 sine of "x".
1569 The library syntax is gsin"(x,prec)".
1571 sinh"(x)"
1573 hyperbolic sine of "x".
1574 The library syntax is gsh"(x,prec)".
1576 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 ? (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 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 ? 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 (note the difference between %2 and %3 above).
1599 The library syntax is gsqr"(x)".
1601 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 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 The library syntax is gsqrt"(x,prec)".
1616 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 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 ? 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 The following script computes all roots in all possible cases:
1639 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 The library syntax is gsqrtn"(x,n,&z,prec)".
1655 tan"(x)"
1657 tangent of "x".
1658 The library syntax is gtan"(x,prec)".
1660 tanh"(x)"
1662 hyperbolic tangent of "x".
1663 The library syntax is gth"(x,prec)".
1665 teichmuller"(x)"
1667 Teichmueller 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 The library syntax is teich"(x)".
1671 theta"(q,z)"
1673 Jacobi sine theta-function.
1674 The library syntax is theta"(q,z,prec)".
1676 thetanullk"(q,k)"
1678 "k"-th derivative at "z = 0" of "theta(q,z)".
1679 The library syntax is thetanullk"(q,k,prec)", where "k" is a "long".
1681 weber"(x,{flag = 0})"
1683 one of Weber's three "f" functions. If "flag = 0", returns
1684 "f(x) = exp (-iPi/24).eta((x+1)/2)/eta(x) such that j =
1686 (f^{24}-16)^3/f^{24},"
1687 where "j" is the elliptic "j"-invariant (see the function "ellj"). If
1689 "flag = 1", returns
1690 "f_1(x) = eta(x/2)/eta(x) such that j = (f_1^{24}+16)^3/f_1^{24}."
1692 Finally, if "flag = 2", returns
1694 "f_2(x) = sqrt {2}eta(2x)/eta(x) such that j =
1696 (f_2^{24}+16)^3/f_2^{24}."
1697 Note the identities "f^8 = f_1^8+f_2^8" and "ff_1f_2 = sqrt 2".
1699 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 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 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 The library syntax is gzeta"(s,prec)".
1718
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 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 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 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 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 To remove primes from the list use "removeprimes".
1758 The library syntax is addprimes"(x)".
1760 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 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 The library syntax is bestappr0"(x,A,B)". Also available is "
1775 bestappr(x,A)" corresponding to an omitted "B".
1776 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 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 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 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 bigomega"(x)"
1798 number of prime divisors of "|x|" counted with multiplicity. "x" must
1799 be an integer.
1800 The library syntax is bigomega"(x)", the result is a "long".
1802 binomial"(x,y)"
1804 binomial coefficient "\binom{x}{y}". Here "y" must be an integer, but
1805 "x" can be any PARI object.
1806 The library syntax is binomial"(x,y)", where "y" must be a "long".
1808 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 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 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 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 The library syntax is chinese"(x,y)". Also available is
1827 "chinese1""(x)", corresponding to an ommitted "y".
1828 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 ? content(2*x+y)
1836 %1 = 1 \\ = gcd(2,y) over Q[y]
1837 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 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 ? content([ [2], 4*matid(3) ])
1849 %1 = 2
1850 The library syntax is content"(x)".
1852 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 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 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 If "b" is an integer, the command is understood as "contfrac(x,nmax)".
1873 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 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 The library syntax is pnqn"(x)".
1890 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 The library syntax is core0"(n,flag)". Also available are " core(n)" (
1897 = " core0(n,0)") and " core2(n)" ( = " core0(n,1)").
1898 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 The library syntax is coredisc0"(n,flag)". Also available are "
1906 coredisc(n)" ( = " coredisc(n,0)") and " coredisc2(n)" ( = "
1907 coredisc(n,1)").
1908 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 The library syntax is dirdiv"(x,y)".
1915 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 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 ? direuler(p=2, 10, 1/((1-X)*(1-p*X)))
1928 %1 = [1, 3, 4, 7, 6, 12, 8, 15, 13, 18]
1929 The library syntax is direuler"(void *E, GEN (*eval)(GEN,void*), GEN a,
1931 GEN b)"
1932 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 The library syntax is dirmul"(x,y)".
1939 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 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 The library syntax is divisors"(x)".
1950 eulerphi"(x)"
1952 Euler's "phi" (totient) function of "|x|", in other words "|(Z/xZ)^*|".
1953 "x" must be of type integer.
1954 The library syntax is phi"(x)".
1956 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 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 fa = factor(2^2^7 +1)
1972 isprime( fa[,1] )
1973 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 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 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 ? factor(t^2 + 5/2*t + 1)
1997 %1 =
1998 [2*t + 1 1]
1999 [t + 2 1]
2001 ? content(t^2 + 5/2*t + 1)
2003 %2 = 1/2
2004 See also "factornf" and "nffactor".
2006 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 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 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 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 ? 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 [0 16 0]
2038 [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 [[5, [-2, 1]~, 1, 1, [2, 1]~] 1]
2045 [[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 [0 10]
2054 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 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 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 The library syntax is factcantor"(x,p)".
2075 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 The library syntax is factorff"(x,p,a)".
2086 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 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 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 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 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 The library syntax is factorint"(n,flag)".
2119 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 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 fibonacci"(x)"
2135 "x^{th}" Fibonacci number.
2136 The library syntax is fibo"(x)". "x" must be a "long".
2138 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 The library syntax is ffinit"(p,n,v)", where "v" is a variable number.
2146 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 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 The algorithm used is a naive Euclid except for the following inputs:
2162 \item integers: use modified right-shift binary (``plus-minus''
2164 variant).
2165 \item univariate polynomials with coeffients in the same number field
2167 (in particular rational): use modular gcd algorithm.
2168 \item general polynomials: use the subresultant algorithm if
2170 coefficient explosion is likely (exact, non modular, coefficients).
2171 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 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 The library syntax is hil"(x,y,p)".
2185 isfundamental"(x)"
2187 true (1) if "x" is equal to 1 or to the discriminant of a quadratic
2188 field, false (0) otherwise.
2189 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 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 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 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 The library syntax is ispower"(x, k, &n)", the result is a "long".
2208 Omitted "k" or "n" are coded as "NULL".
2209 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 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 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 If "flag = 2", use APRCL.
2235 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 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 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 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 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 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 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 ? 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 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 ? 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 This will \emph{not} work for "t_INTMOD" (use quadratic reciprocity) or
2295 "t_SER" (only check the leading coefficient).
2296 The library syntax is gissquarerem"(x,&n)". Also available is "
2298 gissquare(x)".
2299 issquarefree"(x)"
2301 true (1) if "x" is squarefree, false (0) if not. Here "x" can be an
2302 integer or a polynomial.
2303 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 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 \item "(x|0) = 1" if "|x |= 1" and 0 otherwise.
2317 \item "(x|-1) = 1" if "x >= 0" and "-1" otherwise.
2319 \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 The library syntax is kronecker"(x,y)", the result (0 or "+- 1") is a
2324 "long".
2325 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 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 Note that lcm(v) is quite different from
2340 l = v[1]; for (i = 1, #v, l = lcm(l, v[i]))
2342 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 ? 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 The library syntax is glcm"(x,y)".
2355 moebius"(x)"
2357 Moebius "mu"-function of "|x|". "x" must be of type integer.
2358 The library syntax is mu"(x)", the result (0 or "+- 1") is a "long".
2360 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 The library syntax is nextprime"(x)".
2369 numdiv"(x)"
2371 number of divisors of "|x|". "x" must be of type integer.
2372 The library syntax is numbdiv"(x)".
2374 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 The library syntax is numbpart"(n)".
2382 omega"(x)"
2384 number of distinct prime divisors of "|x|". "x" must be of type
2385 integer.
2386 The library syntax is omega"(x)", the result is a "long".
2388 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 The library syntax is precprime"(x)".
2397 prime"(x)"
2399 the "x^{th}" prime number, which must be among the precalculated
2400 primes.
2401 The library syntax is prime"(x)". "x" must be a "long".
2403 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 The library syntax is primepi"(x)".
2409 primes"(x)"
2411 creates a row vector whose components are the first "x" prime numbers,
2412 which must be among the precalculated primes.
2413 The library syntax is primes"(x)". "x" must be a "long".
2415 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 If "flag = 1", compute the class number using Euler products and the
2426 functional equation. However, it is in "O(|D|^{1/2})".
2427 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 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 QFBclassno(D) =
2446 qfbclassno(D) * if (D < 0 || norm(quadunit(D)) < 0, 1, 2)
2447 Here are a few examples:
2449 ? qfbclassno(400000028)
2451 time = 3,140 ms.
2452 %1 = 1
2453 ? quadclassunit(400000028).no
2454 time = 20 ms. \{ much faster}
2455 %2 = 1
2456 ? qfbclassno(-400000028)
2457 time = 0 ms.
2458 %3 = 7253 \{ correct, and fast enough}
2459 ? quadclassunit(-400000028).no
2460 time = 0 ms.
2461 %4 = 7253
2462 The library syntax is qfbclassno0"(D,flag)". Also available: "
2464 classno(D)" ( = " qfbclassno(D)"), " classno2(D)" ( = "
2465 qfbclassno(D,1)"), and finally we have the function " hclassno(D)"
2466 which computes the class number of an imaginary quadratic field by
2467 counting reduced forms, an "O(|D|)" algorithm. See also "qfbhclassno".
2468 qfbcompraw"(x,y)"
2470 composition of the binary quadratic forms "x" and "y", without
2471 reduction of the result. This is useful e.g. to compute a generating
2472 element of an ideal.
2473 The library syntax is compraw"(x,y)".
2475 qfbhclassno"(x)"
2477 Hurwitz class number of "x", where "x" is non-negative and congruent to
2478 0 or 3 modulo 4. For "x > 5. 10^5", we assume the GRH, and use
2479 "quadclassunit" with default parameters.
2480 The library syntax is hclassno"(x)".
2482 qfbnucomp"(x,y,l)"
2484 composition of the primitive positive definite binary quadratic forms
2485 "x" and "y" (type "t_QFI") using the NUCOMP and NUDUPL algorithms of
2486 Shanks, a la Atkin. "l" is any positive constant, but for optimal
2487 speed, one should take "l = |D|^{1/4}", where "D" is the common
2488 discriminant of "x" and "y". When "x" and "y" do not have the same
2489 discriminant, the result is undefined.
2490 The current implementation is straightforward and in general
2492 \emph{slower} than the generic routine (since the latter take
2493 advantadge of asymptotically fast operations and careful
2494 optimizations).
2495 The library syntax is nucomp"(x,y,l)". The auxiliary function "
2497 nudupl(x,l)" can be used when "x = y".
2498 qfbnupow"(x,n)"
2500 "n"-th power of the primitive positive definite binary quadratic form
2501 "x" using Shanks's NUCOMP and NUDUPL algorithms (see "qfbnucomp", in
2502 particular the final warning).
2503 The library syntax is nupow"(x,n)".
2505 qfbpowraw"(x,n)"
2507 "n"-th power of the binary quadratic form "x", computed without doing
2508 any reduction (i.e. using "qfbcompraw"). Here "n" must be non-negative
2509 and "n < 2^{31}".
2510 The library syntax is powraw"(x,n)" where "n" must be a "long" integer.
2512 qfbprimeform"(x,p)"
2514 prime binary quadratic form of discriminant "x" whose first coefficient
2515 is the prime number "p". By abuse of notation, "p = +- 1" is a valid
2516 special case which returns the unit form. Returns an error if "x" is
2517 not a quadratic residue mod "p". In the case where "x > 0", "p < 0" is
2518 allowed, and the ``distance'' component of the form is set equal to
2519 zero according to the current precision. (Note that negative definite
2520 "t_QFI" are not implemented.)
2521 The library syntax is primeform"(x,p,prec)", where the third variable
2523 "prec" is a "long", but is only taken into account when "x > 0".
2524 qfbred"(x,{flag = 0},{D},{isqrtD},{sqrtD})"
2526 reduces the binary quadratic form "x" (updating Shanks's distance
2527 function if "x" is indefinite). The binary digits of "flag" are toggles
2528 meaning
2529 1: perform a single reduction step
2531 2: don't update Shanks's distance
2533 "D", isqrtD, sqrtD, if present, supply the values of the discriminant,
2535 "\floor{ sqrt {D}}", and " sqrt {D}" respectively (no checking is done
2536 of these facts). If "D < 0" these values are useless, and all
2537 references to Shanks's distance are irrelevant.
2538 The library syntax is qfbred0"(x,flag,D,isqrtD,sqrtD)". Use "NULL" to
2540 omit any of "D", isqrtD, sqrtD.
2541 Also available are
2543 " redimag(x)" ( = " qfbred(x)" where "x" is definite),
2545 and for indefinite forms:
2547 " redreal(x)" ( = " qfbred(x)"),
2549 " rhoreal(x)" ( = " qfbred(x,1)"),
2551 " redrealnod(x,sq)" ( = " qfbred(x,2,,isqrtD)"),
2553 " rhorealnod(x,sq)" ( = " qfbred(x,3,,isqrtD)").
2555 qfbsolve"(Q,p)"
2557 Solve the equation "Q(x,y) = p" over the integers, where "Q" is a
2558 binary quadratic form and "p" a prime number.
2559 Return "[x,y]" as a two-components vector, or zero if there is no
2561 solution. Note that this function returns only one solution and not
2562 all the solutions.
2563 Let "D = \disc Q". The algorithm used runs in probabilistic polynomial
2565 time in "p" (through the computation of a square root of "D" modulo
2566 "p"); it is polynomial time in "D" if "Q" is imaginary, but exponential
2567 time if "Q" is real (through the computation of a full cycle of reduced
2568 forms). In the latter case, note that "bnfisprincipal" provides a
2569 solution in heuristic subexponential time in "D" assuming the GRH.
2570 The library syntax is qfbsolve"(Q,n)".
2572 quadclassunit"(D,{flag = 0},{tech = []})"
2574 Buchmann-McCurley's sub-exponential algorithm for computing the class
2575 group of a quadratic order of discriminant "D".
2576 This function should be used instead of "qfbclassno" or "quadregula"
2578 when "D < -10^{25}", "D > 10^{10}", or when the \emph{structure} is
2579 wanted. It is a special case of "bnfinit", which is slower, but more
2580 robust.
2581 If "flag" is non-zero \emph{and} "D > 0", computes the narrow class
2583 group and regulator, instead of the ordinary (or wide) ones. In the
2584 current version 2.2.0, this does not work at all: use the general
2585 function "bnfnarrow".
2586 Optional parameter tech is a row vector of the form "[c_1, c_2]", where
2588 "c_1 <= c_2" are positive real numbers which control the execution time
2589 and the stack size. For a given "c_1", set "c_2 = c_1" to get maximum
2590 speed. To get a rigorous result under GRH, you must take "c_2 >= 6".
2591 Reasonable values for "c_1" are between 0.1 and 2. More precisely, the
2592 algorithm will \emph{assume} that prime ideals of norm less than "c_2 (
2593 log |D|)^2" generate the class group, but the bulk of the work is done
2594 with prime ideals of norm less than "c_1 ( log |D|)^2". A larger "c_1"
2595 means that relations are easier to find, but more relations are needed
2596 and the linear algebra will be harder. The default is "c_1 = c_2 =
2597 0.2", so the result is \emph{not} rigorously proven.
2598 The result is a vector "v" with 3 components if "D < 0", and 4
2600 otherwise. The correspond respectively to
2601 \item "v[1]": the class number
2603 \item "v[2]": a vector giving the structure of the class group as a
2605 product of cyclic groups;
2606 \item "v[3]": a vector giving generators of those cyclic groups (as
2608 binary quadratic forms).
2609 \item "v[4]": (omitted if "D < 0") the regulator, computed to an
2611 accuracy which is the maximum of an internal accuracy determined by the
2612 program and the current default (note that once the regulator is known
2613 to a small accuracy it is trivial to compute it to very high accuracy,
2614 see the tutorial).
2615 The library syntax is quadclassunit0"(D,flag,tech)". Also available are
2617 " buchimag(D,c_1,c_2)" and " buchreal(D,flag,c_1,c_2)".
2618 quaddisc"(x)"
2620 discriminant of the quadratic field "Q( sqrt {x})", where "x belongs to
2621 Q".
2622 The library syntax is quaddisc"(x)".
2624 quadhilbert"(D,{pq})"
2626 relative equation defining the Hilbert class field of the quadratic
2627 field of discriminant "D".
2628 If "D < 0", uses complex multiplication (Schertz's variant). The
2630 technical component "pq", if supplied, is a vector "[p,q]" where "p",
2631 "q" are the prime numbers needed for the Schertz's method. More
2632 precisely, prime ideals above "p" and "q" should be non-principal and
2633 coprime to all reduced representatives of the class group. In addition,
2634 if one of these ideals has order 2 in the class group, they should have
2635 the same class. Finally, for efficiency, "gcd(24,(p-1)(q-1))" should be
2636 as large as possible. The routine returns 0 if "[p,q]" is not
2637 suitable.
2638 If "D > 0" Stark units are used and (in rare cases) a vector of
2640 extensions may be returned whose compositum is the requested class
2641 field. See "bnrstark" for details.
2642 The library syntax is quadhilbert"(D,pq,prec)".
2644 quadgen"(D)"
2646 creates the quadratic number "omega = (a+ sqrt {D})/2" where "a = 0" if
2647 "x = 0 mod 4", "a = 1" if "D = 1 mod 4", so that "(1,omega)" is an
2648 integral basis for the quadratic order of discriminant "D". "D" must be
2649 an integer congruent to 0 or 1 modulo 4, which is not a square.
2650 The library syntax is quadgen"(x)".
2652 quadpoly"(D,{v = x})"
2654 creates the ``canonical'' quadratic polynomial (in the variable "v")
2655 corresponding to the discriminant "D", i.e. the minimal polynomial of
2656 quadgen(D). "D" must be an integer congruent to 0 or 1 modulo 4, which
2657 is not a square.
2658 The library syntax is quadpoly0"(x,v)".
2660 quadray"(D,f,{lambda})"
2662 relative equation for the ray class field of conductor "f" for the
2663 quadratic field of discriminant "D" using analytic methods. A "bnf" for
2664 "x^2 - D" is also accepted in place of "D".
2665 For "D < 0", uses the "sigma" function. If supplied, lambda is is the
2667 technical element "lambda" of "bnf" necessary for Schertz's method. In
2668 that case, returns 0 if "lambda" is not suitable.
2669 For "D > 0", uses Stark's conjecture, and a vector of relative
2671 equations may be returned. See "bnrstark" for more details.
2672 The library syntax is quadray"(D,f,lambda,prec)", where an omitted
2674 "lambda" is coded as "NULL".
2675 quadregulator"(x)"
2677 regulator of the quadratic field of positive discriminant "x". Returns
2678 an error if "x" is not a discriminant (fundamental or not) or if "x" is
2679 a square. See also "quadclassunit" if "x" is large.
2680 The library syntax is regula"(x,prec)".
2682 quadunit"(D)"
2684 fundamental unit of the real quadratic field "Q( sqrt D)" where "D"
2685 is the positive discriminant of the field. If "D" is not a fundamental
2686 discriminant, this probably gives the fundamental unit of the
2687 corresponding order. "D" must be an integer congruent to 0 or 1 modulo
2688 4, which is not a square; the result is a quadratic number (see "Label
2689 se:quadgen").
2690 The library syntax is fundunit"(x)".
2692 removeprimes"({x = []})"
2694 removes the primes listed in "x" from the prime number table. In
2695 particular "removeprimes(addprimes)" empties the extra prime table. "x"
2696 can also be a single integer. List the current extra primes if "x" is
2697 omitted.
2698 The library syntax is removeprimes"(x)".
2700 sigma"(x,{k = 1})"
2702 sum of the "k^{th}" powers of the positive divisors of "|x|". "x" and
2703 "k" must be of type integer.
2704 The library syntax is sumdiv"(x)" ( = " sigma(x)") or " gsumdivk(x,k)"
2706 ( = " sigma(x,k)"), where "k" is a C long integer.
2707 sqrtint"(x)"
2709 integer square root of "x", which must be a non-negative integer. The
2710 result is non-negative and rounded towards zero.
2711 The library syntax is sqrti"(x)". Also available is "sqrtremi""(x,&r)"
2713 which returns "s" such that "s^2 = x+r", with "0 <= r <= 2s".
2714 zncoppersmith"(P, N, X, {B = N})"
2716 finds all integers "x_0" with "|x_0| <= X" such that
2717 "gcd(N, P(x_0)) >= B."
2719 If "N" is prime or a prime power, "polrootsmod" or "polrootspadic" will
2721 be much faster. "X" must be smaller than " exp ( log ^2 B / ( deg (P)
2722 log N))".
2723 The library syntax is zncoppersmith"(P, N, X, B)", where an omitted "B"
2725 is coded as "NULL".
2726 znlog"(x,g)"
2728 "g" must be a primitive root mod a prime "p", and the result is the
2729 discrete log of "x" in the multiplicative group "(Z/pZ)^*". This
2730 function uses a simple-minded combination of Pohlig-Hellman algorithm
2731 and Shanks baby-step/giant-step which requires "O( sqrt {q})" storage,
2732 where "q" is the largest prime factor of "p-1". Hence it cannot be used
2733 when the largest prime divisor of "p-1" is greater than about
2734 "10^{13}".
2735 The library syntax is znlog"(x,g)".
2737 znorder"(x,{o})"
2739 "x" must be an integer mod "n", and the result is the order of "x" in
2740 the multiplicative group "(Z/nZ)^*". Returns an error if "x" is not
2741 invertible. If optional parameter "o" is given it is assumed to be a
2742 multiple of the order (used to limit the search space).
2743 The library syntax is znorder"(x,o)", where an omitted "o" is coded as
2745 "NULL". Also available is " order(x)".
2746 znprimroot"(n)"
2748 returns a primitive root (generator) of "(Z/nZ)^*", whenever this
2749 latter group is cyclic ("n = 4" or "n = 2p^k" or "n = p^k", where "p"
2750 is an odd prime and "k >= 0").
2751 The library syntax is gener"(x)".
2753 znstar"(n)"
2755 gives the structure of the multiplicative group "(Z/nZ)^*" as a
2756 3-component row vector "v", where "v[1] = phi(n)" is the order of that
2757 group, "v[2]" is a "k"-component row-vector "d" of integers "d[i]" such
2758 that "d[i] > 1" and "d[i] | d[i-1]" for "i >= 2" and "(Z/nZ)^* ~
2759 prod_{i = 1}^k(Z/d[i]Z)", and "v[3]" is a "k"-component row vector
2760 giving generators of the image of the cyclic groups "Z/d[i]Z".
2761 The library syntax is znstar"(n)".
2763
2765 We have implemented a number of functions which are useful for number
2766 theorists working on elliptic curves. We always use Tate's notations.
2767 The functions assume that the curve is given by a general Weierstrass
2768 model
2769 " y^2+a_1xy+a_3y = x^3+a_2x^2+a_4x+a_6, "
2771 where a priori the "a_i" can be of any scalar type. This curve can be
2773 considered as a five-component vector "E = [a1,a2,a3,a4,a6]". Points on
2774 "E" are represented as two-component vectors "[x,y]", except for the
2775 point at infinity, i.e. the identity element of the group law,
2776 represented by the one-component vector "[0]".
2777 It is useful to have at one's disposal more information. This is given
2779 by the function "ellinit" (see there), which initalizes and returns an
2780 ell structure by default. If a specific flag is added, a shortened
2781 sell, for small ell, is returned, which is much faster to compute but
2782 contains less information. The following member functions are available
2783 to deal with the output of "ellinit", both ell and sell: functions"
2784 "a1"--"a6", "b2"--"b8", "c4"--"c6" : coefficients of the elliptic
2786 curve.
2787 "area" : volume of the complex lattice defining "E".
2789 "disc" : discriminant of the curve.
2791 "j" : "j"-invariant of the curve.
2793 "omega" : "[omega_1,omega_2]", periods forming a basis of the
2795 complex lattice defining "E" ("omega_1" is the
2796 real period, and "omega_2/omega_1" belongs to
2798 Poincare's half-plane).
2799 "eta" : quasi-periods "[eta_1, eta_2]", such that
2801 "eta_1omega_2-eta_2omega_1 = iPi".
2802 "roots" : roots of the associated Weierstrass equation.
2804 "tate" : "[u^2,u,v]" in the notation of Tate.
2806 "w" : Mestre's "w" (this is technical).
2808 The member functions "area", "eta" and "omega" are only available for
2810 curves over Q. Conversely, "tate" and "w" are only available for curves
2811 defined over "Q_p". The use of member functions is best described by an
2812 example:
2813 ? E = ellinit([0,0,0,0,1]); \\ The curve y^2 = x^3 + 1
2815 ? E.a6
2816 %2 = 1
2817 ? E.c6
2818 %3 = -864
2819 ? E.disc
2820 %4 = -432
2821 Some functions, in particular those relative to height computations
2823 (see "ellheight") require also that the curve be in minimal Weierstrass
2824 form, which is duly stressed in their description below. This is
2825 achieved by the function "ellminimalmodel". \emph{Using a non-minimal
2826 model in such a routine will yield a wrong result!}
2827 All functions related to elliptic curves share the prefix "ell", and
2829 the precise curve we are interested in is always the first argument, in
2830 either one of the three formats discussed above, unless otherwise
2831 specified. The requirements are given as the \emph{minimal} ones: any
2832 richer structure may replace the ones requested. For instance, in
2833 functions which have no use for the extra information given by an ell
2834 structure, the curve can be given either as a five-component vector, as
2835 an sell, or as an ell; if an sell is requested, an ell may equally be
2836 given.
2837 elladd"(E,z1,z2)"
2839 sum of the points "z1" and "z2" on the elliptic curve corresponding to
2840 "E".
2841 The library syntax is addell"(E,z1,z2)".
2843 ellak"(E,n)"
2845 computes the coefficient "a_n" of the "L"-function of the elliptic
2846 curve "E", i.e. in principle coefficients of a newform of weight 2
2847 assuming Taniyama-Weil conjecture (which is now known to hold in full
2848 generality thanks to the work of Breuil, Conrad, Diamond, Taylor and
2849 Wiles). "E" must be an sell as output by "ellinit". For this function
2850 to work for every "n" and not just those prime to the conductor, "E"
2851 must be a minimal Weierstrass equation. If this is not the case, use
2852 the function "ellminimalmodel" before using "ellak".
2853 The library syntax is akell"(E,n)".
2855 ellan"(E,n)"
2857 computes the vector of the first "n" "a_k" corresponding to the
2858 elliptic curve "E". All comments in "ellak" description remain valid.
2859 The library syntax is anell"(E,n)", where "n" is a C integer.
2861 ellap"(E,p,{flag = 0})"
2863 computes the "a_p" corresponding to the elliptic curve "E" and the
2864 prime number "p". These are defined by the equation "#E(F_p) = p+1 -
2865 a_p", where "#E(F_p)" stands for the number of points of the curve "E"
2866 over the finite field "F_p". When "flag" is 0, this uses the baby-step
2867 giant-step method and a trick due to Mestre. This runs in time
2868 "O(p^{1/4})" and requires "O(p^{1/4})" storage, hence becomes
2869 unreasonable when "p" has about 30 digits.
2870 If "flag" is 1, computes the "a_p" as a sum of Legendre symbols. This
2872 is slower than the previous method as soon as "p" is greater than 100,
2873 say.
2874 No checking is done that "p" is indeed prime. "E" must be an sell as
2876 output by "ellinit", defined over Q, "F_p" or "Q_p". "E" must be given
2877 by a Weierstrass equation minimal at "p".
2878 The library syntax is ellap0"(E,p,flag)". Also available are "
2880 apell(E,p)", corresponding to "flag = 0", and " apell2(E,p)" ("flag =
2881 1").
2882 ellbil"(E,z1,z2)"
2884 if "z1" and "z2" are points on the elliptic curve "E", assumed to be
2885 integral given by a minimal model, this function computes the value of
2886 the canonical bilinear form on "z1", "z2":
2887 " ( h(E,z1+z2) - h(E,z1) - h(E,z2) ) / 2 "
2889 where "+" denotes of course addition on "E". In addition, "z1" or "z2"
2891 (but not both) can be vectors or matrices.
2892 The library syntax is bilhell"(E,z1,z2,prec)".
2894 ellchangecurve"(E,v)"
2896 changes the data for the elliptic curve "E" by changing the coordinates
2897 using the vector "v = [u,r,s,t]", i.e. if "x'" and "y'" are the new
2898 coordinates, then "x = u^2x'+r", "y = u^3y'+su^2x'+t". "E" must be an
2899 sell as output by "ellinit".
2900 The library syntax is coordch"(E,v)".
2902 ellchangepoint"(x,v)"
2904 changes the coordinates of the point or vector of points "x" using the
2905 vector "v = [u,r,s,t]", i.e. if "x'" and "y'" are the new coordinates,
2906 then "x = u^2x'+r", "y = u^3y'+su^2x'+t" (see also "ellchangecurve").
2907 The library syntax is pointch"(x,v)".
2909 ellconvertname"(name)"
2911 converts an elliptic curve name, as found in the "elldata" database,
2912 from a string to a triplet "[conductor, isogeny class, index]". It will
2913 also convert a triplet back to a curve name. Examples:
2914 ? ellconvertname("123b1")
2916 %1 = [123, 1, 1]
2917 ? ellconvertname(%)
2918 %2 = "123b1"
2919 The library syntax is ellconvertname"(name)".
2921 elleisnum"(E,k,{flag = 0})"
2923 "E" being an elliptic curve as output by "ellinit" (or, alternatively,
2924 given by a 2-component vector "[omega_1,omega_2]" representing its
2925 periods), and "k" being an even positive integer, computes the
2926 numerical value of the Eisenstein series of weight "k" at "E", namely
2927 " (2i Pi/omega_2)^k \Big(1 + 2/zeta(1-k) sum_{n >= 0} n^{k-1}q^n /
2929 (1-q^n)\Big), "
2930 where "q = e(omega_1/omega_2)".
2932 When flag is non-zero and "k = 4" or 6, returns the elliptic invariants
2934 "g_2" or "g_3", such that
2935 "y^2 = 4x^3 - g_2 x - g_3"
2937 is a Weierstrass equation for "E".
2939 The library syntax is elleisnum"(E,k,flag)".
2941 elleta"(om)"
2943 returns the two-component row vector "[eta_1,eta_2]" of quasi-periods
2944 associated to "om = [omega_1, omega_2]"
2945 The library syntax is elleta"(om, prec)"
2947 ellgenerators"(E)"
2949 returns a Z-basis of the free part of the Mordell-Weil group associated
2950 to "E". This function depends on the "elldata" database being
2951 installed and referencing the curve, and so is only available for
2952 curves over Z of small conductors.
2953 The library syntax is ellgenerators"(E)".
2955 ellglobalred"(E)"
2957 calculates the arithmetic conductor, the global minimal model of "E"
2958 and the global Tamagawa number "c". "E" must be an sell as output by
2959 "ellinit", \emph{and is supposed to have all its coefficients "a_i" in}
2960 Q. The result is a 3 component vector "[N,v,c]". "N" is the arithmetic
2961 conductor of the curve. "v" gives the coordinate change for "E" over Q
2962 to the minimal integral model (see "ellminimalmodel"). Finally "c" is
2963 the product of the local Tamagawa numbers "c_p", a quantity which
2964 enters in the Birch and Swinnerton-Dyer conjecture. conjecture minimal
2965 model"
2966 The library syntax is ellglobalred"(E)".
2968 ellheight"(E,z,{flag = 2})"
2970 global Neron-Tate height of the point "z" on the elliptic curve "E"
2971 (defined over Q), given by a standard minimal integral model. "E" must
2972 be an "ell" as output by "ellinit". flag selects the algorithm used to
2973 compute the archimedean local height. If "flag = 0", this computation
2974 is done using sigma and theta-functions and a trick due to J.
2975 Silverman. If "flag = 1", use Tate's "4^n" algorithm. If "flag = 2",
2976 use Mestre's AGM algorithm. The latter is much faster than the other
2977 two, both in theory (converges quadratically) and in practice.
2978 The library syntax is ellheight0"(E,z,flag,prec)". Also available are "
2980 ghell(E,z,prec)" ("flag = 0") and " ghell2(E,z,prec)" ("flag = 1").
2981 ellheightmatrix"(E,x)"
2983 "x" being a vector of points, this function outputs the Gram matrix of
2984 "x" with respect to the Neron-Tate height, in other words, the "(i,j)"
2985 component of the matrix is equal to "ellbil(E,x[i],x[j])". The rank of
2986 this matrix, at least in some approximate sense, gives the rank of the
2987 set of points, and if "x" is a basis of the Mordell-Weil group of "E",
2988 its determinant is equal to the regulator of "E". Note that this matrix
2989 should be divided by 2 to be in accordance with certain normalizations.
2990 "E" is assumed to be integral, given by a minimal model.
2991 The library syntax is mathell"(E,x,prec)".
2993 ellidentify"(E)"
2995 look up the elliptic curve "E" (over Z) in the "elldata" database and
2996 return "[[N, M, G], C]" where "N" is the name of the curve in J. E.
2997 Cremona database, "M" the minimal model, "G" a Z-basis of the free part
2998 of the Mordell-Weil group of "E" and "C" the coordinates change (see
2999 "ellchangecurve").
3000 The library syntax is ellidentify"(E)".
3002 ellinit"(E,{flag = 0})"
3004 initialize an "ell" structure, associated to the elliptic curve "E".
3005 "E" is a 5-component vector "[a_1,a_2,a_3,a_4,a_6]" defining the
3006 elliptic curve with Weierstrass equation
3007 " Y^2 + a_1 XY + a_3 Y = X^3 + a_2 X^2 + a_4 X + a_6 "
3009 or a string, in this case the coefficients of the curve with matching
3011 name are looked in the "elldata" database if available. For the time
3012 being, only curves over a prime field "F_p" and over the "p"-adic or
3013 real numbers (including rational numbers) are fully supported. Other
3014 domains are only supported for very basic operations such as point
3015 addition.
3016 The result of "ellinit" is a an ell structure by default, and a shorted
3018 sell if "flag = 1". Both contain the following information in their
3019 components:
3020 " a_1,a_2,a_3,a_4,a_6,b_2,b_4,b_6,b_8,c_4,c_6,Delta,j."
3022 All are accessible via member functions. In particular, the
3024 discriminant is "E.disc", and the "j"-invariant is "E.j".
3025 The other six components are only present if "flag" is 0 or omitted.
3027 Their content depends on whether the curve is defined over R or not:
3028 \item When "E" is defined over R, "E.roots" is a vector whose three
3030 components contain the roots of the right hand side of the associated
3031 Weierstrass equation.
3032 " (y + a_1x/2 + a_3/2)^2 = g(x) "
3034 If the roots are all real, then they are ordered by decreasing value.
3036 If only one is real, it is the first component.
3037 Then "omega_1 = ""E.omega[1]" is the real period of "E" (integral of
3039 "dx/(2y+a_1x+a_3)" over the connected component of the identity element
3040 of the real points of the curve), and "omega_2 = ""E.omega[2]" is a
3041 complex period. In other words, "E.omega" forms a basis of the complex
3042 lattice defining "E", with "tau = (omega_2)/(omega_1)" having positive
3043 imaginary part.
3044 "E.eta" is a row vector containing the corresponding values "eta_1" and
3046 "eta_2" such that "eta_1omega_2-eta_2omega_1 = iPi".
3047 Finally, "E.area" is the volume of the complex lattice defining "E".
3049 \item When "E" is defined over "Q_p", the "p"-adic valuation of "j"
3051 must be negative. Then "E.roots" is the vector with a single component
3052 equal to the "p"-adic root of the associated Weierstrass equation
3053 corresponding to "-1" under the Tate parametrization.
3054 "E.tate" yields the three-component vector "[u^2,u,q]", in the
3056 notations of Tate. If the "u"-component does not belong to "Q_p", it is
3057 set to zero.
3058 "E.w" is Mestre's "w" (this is technical).
3060 For all other base fields or rings, the last six components are
3062 arbitrarily set equal to zero. See also the description of member
3063 functions related to elliptic curves at the beginning of this section.
3064 The library syntax is ellinit0"(E,flag,prec)". Also available are "
3066 initell(E,prec)" ("flag = 0") and " smallinitell(E,prec)" ("flag = 1").
3067 ellisoncurve"(E,z)"
3069 gives 1 (i.e. true) if the point "z" is on the elliptic curve "E", 0
3070 otherwise. If "E" or "z" have imprecise coefficients, an attempt is
3071 made to take this into account, i.e. an imprecise equality is checked,
3072 not a precise one. It is allowed for "z" to be a vector of points in
3073 which case a vector (of the same type) is returned.
3074 The library syntax is ellisoncurve"(E,z)". Also available is "
3076 oncurve(E,z)" which returns a "long" but does not accept vector of
3077 points.
3078 ellj"(x)"
3080 elliptic "j"-invariant. "x" must be a complex number with positive
3081 imaginary part, or convertible into a power series or a "p"-adic number
3082 with positive valuation.
3083 The library syntax is jell"(x,prec)".
3085 elllocalred"(E,p)"
3087 calculates the Kodaira type of the local fiber of the elliptic curve
3088 "E" at the prime "p". "E" must be an sell as output by "ellinit", and
3089 is assumed to have all its coefficients "a_i" in Z. The result is a
3090 4-component vector "[f,kod,v,c]". Here "f" is the exponent of "p" in
3091 the arithmetic conductor of "E", and "kod" is the Kodaira type which is
3092 coded as follows:
3093 1 means good reduction (type I"_0"), 2, 3 and 4 mean types II, III and
3095 IV respectively, "4+nu" with "nu > 0" means type I"_nu"; finally the
3096 opposite values "-1", "-2", etc. refer to the starred types I"_0^*",
3097 II"^*", etc. The third component "v" is itself a vector "[u,r,s,t]"
3098 giving the coordinate changes done during the local reduction.
3099 Normally, this has no use if "u" is 1, that is, if the given equation
3100 was already minimal. Finally, the last component "c" is the local
3101 Tamagawa number "c_p".
3102 The library syntax is elllocalred"(E,p)".
3104 elllseries"(E,s,{A = 1})"
3106 "E" being an sell as output by "ellinit", this computes the value of
3107 the L-series of "E" at "s". It is assumed that "E" is defined over Q,
3108 not necessarily minimal. The optional parameter "A" is a cutoff point
3109 for the integral, which must be chosen close to 1 for best speed. The
3110 result must be independent of "A", so this allows some internal
3111 checking of the function.
3112 Note that if the conductor of the curve is large, say greater than
3114 "10^{12}", this function will take an unreasonable amount of time since
3115 it uses an "O(N^{1/2})" algorithm.
3116 The library syntax is elllseries"(E,s,A,prec)" where "prec" is a "long"
3118 and an omitted "A" is coded as "NULL".
3119 ellminimalmodel"(E,{&v})"
3121 return the standard minimal integral model of the rational elliptic
3122 curve "E". If present, sets "v" to the corresponding change of
3123 variables, which is a vector "[u,r,s,t]" with rational components. The
3124 return value is identical to that of "ellchangecurve(E, v)".
3125 The resulting model has integral coefficients, is everywhere minimal,
3127 "a_1" is 0 or 1, "a_2" is 0, 1 or "-1" and "a_3" is 0 or 1. Such a
3128 model is unique, and the vector "v" is unique if we specify that "u" is
3129 positive, which we do.
3130 The library syntax is ellminimalmodel"(E,&v)", where an omitted "v" is
3132 coded as "NULL".
3133 ellorder"(E,z)"
3135 gives the order of the point "z" on the elliptic curve "E" if it is a
3136 torsion point, zero otherwise. In the present version 2.2.0, this is
3137 implemented only for elliptic curves defined over Q.
3138 The library syntax is orderell"(E,z)".
3140 ellordinate"(E,x)"
3142 gives a 0, 1 or 2-component vector containing the "y"-coordinates of
3143 the points of the curve "E" having "x" as "x"-coordinate.
3144 The library syntax is ordell"(E,x)".
3146 ellpointtoz"(E,z)"
3148 if "E" is an elliptic curve with coefficients in R, this computes a
3149 complex number "t" (modulo the lattice defining "E") corresponding to
3150 the point "z", i.e. such that, in the standard Weierstrass model, " wp
3151 (t) = z[1], wp '(t) = z[2]". In other words, this is the inverse
3152 function of "ellztopoint". More precisely, if "(w1,w2)" are the real
3153 and complex periods of "E", "t" is such that "0 <= Re (t) < w1" and "0
3154 <= Im (t) < Im (w2)".
3155 If "E" has coefficients in "Q_p", then either Tate's "u" is in "Q_p",
3157 in which case the output is a "p"-adic number "t" corresponding to the
3158 point "z" under the Tate parametrization, or only its square is, in
3159 which case the output is "t+1/t". "E" must be an ell as output by
3160 "ellinit".
3161 The library syntax is zell"(E,z,prec)".
3163 ellpow"(E,z,n)"
3165 computes "n" times the point "z" for the group law on the elliptic
3166 curve "E". Here, "n" can be in Z, or "n" can be a complex quadratic
3167 integer if the curve "E" has complex multiplication by "n" (if not, an
3168 error message is issued).
3169 The library syntax is powell"(E,z,n)".
3171 ellrootno"(E,{p = 1})"
3173 "E" being an sell as output by "ellinit", this computes the local (if
3174 "p ! = 1") or global (if "p = 1") root number of the L-series of the
3175 elliptic curve "E". Note that the global root number is the sign of the
3176 functional equation and conjecturally is the parity of the rank of the
3177 Mordell-Weil group. The equation for "E" must have coefficients in Q
3178 but need \emph{not} be minimal.
3179 The library syntax is ellrootno"(E,p)" and the result (equal to "+-1")
3181 is a "long".
3182 ellsigma"(E,z,{flag = 0})"
3184 value of the Weierstrass "sigma" function of the lattice associated to
3185 "E" as given by "ellinit" (alternatively, "E" can be given as a lattice
3186 "[omega_1,omega_2]").
3187 If "flag = 1", computes an (arbitrary) determination of " log
3189 (sigma(z))".
3190 If "flag = 2,3", same using the product expansion instead of theta
3192 series. The library syntax is ellsigma"(E,z,flag)"
3193 ellsearch"(N)"
3195 if "N" is an integer, it is taken as a conductor else if "N" is a
3196 string, it can be a curve name ("11a1"), a isogeny class ("11a") or a
3197 conductor "11". This function finds all curves in the "elldata"
3198 database with the given property.
3199 If "N" is a full curve name, the output format is "[N,
3201 [a_1,a_2,a_3,a_4,a_6], G]" where "[a_1,a_2,a_3,a_4,a_6]" are the
3202 coefficients of the Weierstrass equation of the curve and "G" is a
3203 Z-basis of the free part of the Mordell-Weil group associated to the
3204 curve.
3205 If "N" is not a full-curve name, the output is the list (as a vector)
3207 of all matching curves in the above format.
3208 The library syntax is ellsearch"(N)". Also available is "
3210 ellsearchcurve(N)" that only accept complete curve names.
3211 ellsub"(E,z1,z2)"
3213 difference of the points "z1" and "z2" on the elliptic curve
3214 corresponding to "E".
3215 The library syntax is subell"(E,z1,z2)".
3217 elltaniyama"(E)"
3219 computes the modular parametrization of the elliptic curve "E", where
3220 "E" is an sell as output by "ellinit", in the form of a two-component
3221 vector "[u,v]" of power series, given to the current default series
3222 precision. This vector is characterized by the following two
3223 properties. First the point "(x,y) = (u,v)" satisfies the equation of
3224 the elliptic curve. Second, the differential "du/(2v+a_1u+a_3)" is
3225 equal to "f(z)dz", a differential form on "H/Gamma_0(N)" where "N" is
3226 the conductor of the curve. The variable used in the power series for
3227 "u" and "v" is "x", which is implicitly understood to be equal to " exp
3228 (2iPi z)". It is assumed that the curve is a \emph{strong} Weil curve,
3229 and that the Manin constant is equal to 1. The equation of the curve
3230 "E" must be minimal (use "ellminimalmodel" to get a minimal equation).
3231 The library syntax is elltaniyama"(E, prec)", and the precision of the
3233 result is determined by "prec".
3234 elltors"(E,{flag = 0})"
3236 if "E" is an elliptic curve \emph{defined over Q}, outputs the torsion
3237 subgroup of "E" as a 3-component vector "[t,v1,v2]", where "t" is the
3238 order of the torsion group, "v1" gives the structure of the torsion
3239 group as a product of cyclic groups (sorted by decreasing order), and
3240 "v2" gives generators for these cyclic groups. "E" must be an ell as
3241 output by "ellinit".
3242 ? E = ellinit([0,0,0,-1,0]);
3244 ? elltors(E)
3245 %1 = [4, [2, 2], [[0, 0], [1, 0]]]
3246 Here, the torsion subgroup is isomorphic to "Z/2Z x Z/2Z", with
3248 generators "[0,0]" and "[1,0]".
3249 If "flag = 0", use Doud's algorithm: bound torsion by computing
3251 "#E(F_p)" for small primes of good reduction, then look for torsion
3252 points using Weierstrass parametrization (and Mazur's classification).
3253 If "flag = 1", use Lutz-Nagell (\emph{much} slower), "E" is allowed to
3255 be an sell.
3256 The library syntax is elltors0"(E,flag)".
3258 ellwp"(E,{z = x},{flag = 0})"
3260 Computes the value at "z" of the Weierstrass " wp " function attached
3261 to the elliptic curve "E" as given by "ellinit" (alternatively, "E" can
3262 be given as a lattice "[omega_1,omega_2]").
3263 If "z" is omitted or is a simple variable, computes the \emph{power
3265 series} expansion in "z" (starting "z^{-2}+O(z^2)"). The number of
3266 terms to an \emph{even} power in the expansion is the default
3267 serieslength in "gp", and the second argument (C long integer) in
3268 library mode.
3269 Optional flag is (for now) only taken into account when "z" is numeric,
3271 and means 0: compute only " wp (z)", 1: compute "[ wp (z), wp '(z)]".
3272 The library syntax is ellwp0"(E,z,flag,prec,precdl)". Also available is
3274 " weipell(E,precdl)" for the power series.
3275 ellzeta"(E,z)"
3277 value of the Weierstrass "zeta" function of the lattice associated to
3278 "E" as given by "ellinit" (alternatively, "E" can be given as a lattice
3279 "[omega_1,omega_2]").
3280 The library syntax is ellzeta"(E,z)".
3282 ellztopoint"(E,z)"
3284 "E" being an ell as output by "ellinit", computes the coordinates
3285 "[x,y]" on the curve "E" corresponding to the complex number "z". Hence
3286 this is the inverse function of "ellpointtoz". In other words, if the
3287 curve is put in Weierstrass form, "[x,y]" represents the Weierstrass "
3288 wp "-function and its derivative. If "z" is in the lattice defining "E"
3289 over C, the result is the point at infinity "[0]".
3290 The library syntax is pointell"(E,z,prec)".
3292
3294 In this section can be found functions which are used almost
3295 exclusively for working in general number fields. Other less specific
3296 functions can be found in the next section on polynomials. Functions
3297 related to quadratic number fields are found in section "Label
3298 se:arithmetic" (Arithmetic functions).
3299 Number field structures
3301 Let "K = Q[X] / (T)" a number field, "Z_K" its ring of integers, "T
3302 belongs to Z[X]" is monic. Three basic number field structures can be
3303 associated to "K" in GP:
3304 \item "nf" denotes a number field, i.e. a data structure output by
3306 "nfinit". This contains the basic arithmetic data associated to the
3307 number field: signature, maximal order (given by a basis "nf.zk"),
3308 discriminant, defining polynomial "T", etc.
3309 \item "bnf" denotes a ``Buchmann's number field'', i.e. a data
3311 structure output by "bnfinit". This contains "nf" and the deeper
3312 invariants of the field: units U(K), class group "\Cl(K)", as well as
3313 technical data required to solve the two associated discrete logarithm
3314 problems.
3315 \item "bnr" denotes a ``ray number field'', i.e. a data structure
3317 output by "bnrinit", corresponding to the ray class group structure of
3318 the field, for some modulus "f". It contains a bnf, the modulus "f",
3319 the ray class group "\Cl_f(K)" and data associated to the discrete
3320 logarithm problem therein.
3321 Algebraic numbers and ideals
3323 An algebraic number belonging to "K = Q[X]/(T)" is given as
3324 \item a "t_INT", "t_FRAC" or "t_POL" (implicitly modulo "T"), or
3326 \item a "t_POLMOD" (modulo "T"), or
3328 \item a "t_COL" "v" of dimension "N = [K:Q]", representing the element
3330 in terms of the computed integral basis, as "sum(i = 1, N, v[i] *
3331 nf.zk[i])". Note that a "t_VEC" will not be recognized.
3332 An ideal is given in any of the following ways:
3334 \item an algebraic number in one of the above forms, defining a
3336 principal ideal.
3337 \item a prime ideal, i.e. a 5-component vector in the format output by
3339 "idealprimedec".
3340 \item a "t_MAT", square and in Hermite Normal Form (or at least upper
3342 triangular with non-negative coefficients), whose columns represent a
3343 basis of the ideal.
3344 One may use "idealhnf" to convert an ideal to the last (preferred)
3346 format.
3347 Note. Some routines accept non-square matrices, but using this format
3349 is strongly discouraged. Nevertheless, their behaviour is as follows:
3350 If strictly less than "N = [K:Q]" generators are given, it is assumed
3351 they form a "Z_K"-basis. If "N" or more are given, a Z-basis is
3352 assumed. If exactly "N" are given, it is further assumed the matrix is
3353 in HNF. If any of these assumptions is not correct the behaviour of the
3354 routine is undefined.
3355 \item an idele is a 2-component vector, the first being an ideal as
3357 above, the second being a "R_1+R_2"-component row vector giving
3358 Archimedean information, as complex numbers.
3359 Finite abelian groups
3361 A finite abelian group "G" in user-readable format is given by its
3362 Smith Normal Form as a pair "[h,d]" or triple "[h,d,g]". Here "h" is
3363 the cardinality of "G", "(d_i)" is the vector of elementary divisors,
3364 and "(g_i)" is a vector of generators. In short, "G = oplus _{i <= n}
3365 (Z/d_iZ) g_i", with "d_n | ... | d_2 | d_1" and "prod d_i = h". This
3366 information can also be retrieved as "G.no", "G.cyc" and "G.gen".
3367 \item a character on the abelian group " oplus (Z/d_iZ) g_i" is given
3369 by a row vector "chi = [a_1,...,a_n]" such that "chi(prod g_i^{n_i}) =
3370 exp (2iPisum a_i n_i / d_i)".
3371 \item given such a structure, a subgroup "H" is input as a square
3373 matrix, whose column express generators of "H" on the given generators
3374 "g_i". Note that the absolute value of the determinant of that matrix
3375 is equal to the index "(G:H)".
3376 Relative extensions
3378 When defining a relative extension, the base field "nf" must be defined
3379 by a variable having a lower priority (see "Label se:priority") than
3380 the variable defining the extension. For example, you may use the
3381 variable name "y" to define the base field, and "x" to define the
3382 relative extension.
3383 \item "rnf" denotes a relative number field, i.e. a data structure
3385 output by "rnfinit".
3386 \item A \emph{relative matrix} is a matrix whose entries are elements
3388 of a (fixed) number field "nf", always expressed as column vectors on
3389 the integral basis "nf.zk". Hence it is a matrix of vectors.
3390 \item An ideal list is a row vector of (fractional) ideals of the
3392 number field "nf".
3393 \item A pseudo-matrix is a pair "(A,I)" where "A" is a relative matrix
3395 and "I" an ideal list whose length is the same as the number of columns
3396 of "A". This pair is represented by a 2-component row vector.
3397 \item The projective module generated by a pseudo-matrix "(A,I)" is the
3399 sum "sum_i {a}_j A_j" where the "{a}_j" are the ideals of "I" and "A_j"
3400 is the "j"-th column of "A".
3401 \item A pseudo-matrix "(A,I)" is a pseudo-basis of the module it
3403 generates if "A" is a square matrix with non-zero determinant and all
3404 the ideals of "I" are non-zero. We say that it is in Hermite Normal
3405 Form (HNF) if it is upper triangular and all the elements of the
3406 diagonal are equal to 1.
3407 \item The \emph{determinant} of a pseudo-basis "(A,I)" is the ideal
3409 equal to the product of the determinant of "A" by all the ideals of
3410 "I". The determinant of a pseudo-matrix is the determinant of any
3411 pseudo-basis of the module it generates.
3412 Class field theory
3414 A "modulus", in the sense of class field theory, is a divisor supported
3415 on the non-complex places of "K". In PARI terms, this means either an
3416 ordinary ideal "I" as above (no archimedean component), or a pair
3417 "[I,a]", where "a" is a vector with "r_1" "{0,1}"-components,
3418 corresponding to the infinite part of the divisor. More precisely, the
3419 "i"-th component of "a" corresponds to the real embedding associated to
3420 the "i"-th real root of "K.roots". (That ordering is not canonical, but
3421 well defined once a defining polynomial for "K" is chosen.) For
3422 instance, "[1, [1,1]]" is a modulus for a real quadratic field,
3423 allowing ramification at any of the two places at infinity.
3424 A bid or ``big ideal'' is a structure output by "idealstar" needed to
3426 compute in "(Z_K/I)^*", where "I" is a modulus in the above sense. If
3427 is a finite abelian group as described above, supplemented by technical
3428 data needed to solve discrete log problems.
3429 Finally we explain how to input ray number fields (or bnr), using class
3431 field theory. These are defined by a triple "a1", "a2", "a3", where the
3432 defining set "[a1,a2,a3]" can have any of the following forms: "[bnr]",
3433 "[bnr,subgroup]", "[bnf,module]", "[bnf,module,subgroup]".
3434 \item "bnf" is as output by "bnfinit", where units are mandatory unless
3436 the modulus is trivial; bnr is as output by "bnrinit". This is the
3437 ground field "K".
3438 \item \emph{module} is a modulus "\goth{f}", as described above.
3440 \item \emph{subgroup} a subgroup of the ray class group modulo
3442 "\goth{f}" of "K". As described above, this is input as a square matrix
3443 expressing generators of a subgroup of the ray class group "bnr.clgp"
3444 on the given generators.
3445 The corresponding bnr is the subfield of the ray class field of "K"
3447 modulo "\goth{f}", fixed by the given subgroup.
3448 General use
3450 All the functions which are specific to relative extensions, number
3451 fields, Buchmann's number fields, Buchmann's number rays, share the
3452 prefix "rnf", "nf", "bnf", "bnr" respectively. They take as first
3453 argument a number field of that precise type, respectively output by
3454 "rnfinit", "nfinit", "bnfinit", and "bnrinit".
3455 However, and even though it may not be specified in the descriptions of
3457 the functions below, it is permissible, if the function expects a "nf",
3458 to use a "bnf" instead, which contains much more information. On the
3459 other hand, if the function requires a "bnf", it will \emph{not} launch
3460 "bnfinit" for you, which is a costly operation. Instead, it will give
3461 you a specific error message. In short, the types
3462 " nf <= bnf <= bnr"
3464 are ordered, each function requires a minimal type to work properly,
3466 but you may always substitute a larger type.
3467 The data types corresponding to the structures described above are
3469 rather complicated. Thus, as we already have seen it with elliptic
3470 curves, GP provides ``member functions'' to retrieve data from these
3471 structures (once they have been initialized of course). The relevant
3472 types of number fields are indicated between parentheses:
3473 "bid" (bnr, ) : bid ideal structure.
3475 "bnf" (bnr, bnf ) : Buchmann's number field.
3477 "clgp" (bnr, bnf ) : classgroup. This one admits the following
3479 three subclasses:
3480 "cyc" : cyclic decomposition (SNF).
3482 "gen" : generators.
3484 "no" : number of elements.
3486 "diff" (bnr, bnf, nf ) : the different ideal.
3488 "codiff" (bnr, bnf, nf ) : the codifferent (inverse of the
3490 different in the ideal group).
3491 "disc" (bnr, bnf, nf ) : discriminant.
3493 "fu" (bnr, bnf, nf ) : fundamental units.
3495 "index" (bnr, bnf, nf ) : index of the power order in the ring of
3497 integers.
3498 "nf" (bnr, bnf, nf ) : number field.
3500 "r1" (bnr, bnf, nf ) : the number of real embeddings.
3502 "r2" (bnr, bnf, nf ) : the number of pairs of complex embeddings.
3504 "reg" (bnr, bnf, ) : regulator.
3506 "roots" (bnr, bnf, nf ) : roots of the polynomial generating the
3508 field.
3509 "t2" (bnr, bnf, nf ) : the T2 matrix (see "nfinit").
3511 "tu" (bnr, bnf, ) : a generator for the torsion units.
3513 "tufu" (bnr, bnf, ) : "[w,u_1,...,u_r]", "(u_i)" is a vector of
3515 fundamental units, "w" generates the torsion units.
3516 "zk" (bnr, bnf, nf ) : integral basis, i.e. a Z-basis of the
3518 maximal order.
3519 For instance, assume that "bnf = bnfinit(pol)", for some polynomial.
3521 Then "bnf.clgp" retrieves the class group, and "bnf.clgp.no" the class
3522 number. If we had set "bnf = nfinit(pol)", both would have output an
3523 error message. All these functions are completely recursive, thus for
3524 instance "bnr.bnf.nf.zk" will yield the maximal order of bnr, which you
3525 could get directly with a simple "bnr.zk".
3526 Class group, units, and the GRH
3528 Some of the functions starting with "bnf" are implementations of the
3529 sub-exponential algorithms for finding class and unit groups under GRH,
3530 due to Hafner-McCurley, Buchmann and Cohen-Diaz-Olivier. The general
3531 call to the functions concerning class groups of general number fields
3532 (i.e. excluding "quadclassunit") involves a polynomial "P" and a
3533 technical vector
3534 "tech = [c, c2, nrpid ],"
3536 where the parameters are to be understood as follows:
3538 "P" is the defining polynomial for the number field, which must be in
3540 "Z[X]", irreducible and monic. In fact, if you supply a non-monic
3541 polynomial at this point, "gp" issues a warning, then \emph{transforms
3542 your polynomial} so that it becomes monic. The "nfinit" routine will
3543 return a different result in this case: instead of "res", you get a
3544 vector "[res,Mod(a,Q)]", where "Mod(a,Q) = Mod(X,P)" gives the change
3545 of variables. In all other routines, the variable change is simply
3546 lost.
3547 The numbers "c <= c_2" are positive real numbers which control the
3549 execution time and the stack size. For a given "c", set "c_2 = c" to
3550 get maximum speed. To get a rigorous result under GRH you must take "c2
3551 >= 12" (or "c2 >= 6" in "P" is quadratic). Reasonable values for "c"
3552 are between 0.1 and 2. The default is "c = c_2 = 0.3".
3553 "nrpid" is the maximal number of small norm relations associated to
3555 each ideal in the factor base. Set it to 0 to disable the search for
3556 small norm relations. Otherwise, reasonable values are between 4 and
3557 20. The default is 4.
3558 Warning. Make sure you understand the above! By default, most of the
3560 "bnf" routines depend on the correctness of a heuristic assumption
3561 which is stronger than the GRH. In particular, any of the class number,
3562 class group structure, class group generators, regulator and
3563 fundamental units may be wrong, independently of each other. Any result
3564 computed from such a "bnf" may be wrong. The only guarantee is that the
3565 units given generate a subgroup of finite index in the full unit group.
3566 In practice, very few counter-examples are known, requiring unlucky
3567 random seeds. No counter-example has been reported for "c_2 = 0.5"
3568 (which should be almost as fast as "c_2 = 0.3", and shall very probably
3569 become the default). If you use "c_2 = 12", then everything is correct
3570 assuming the GRH holds. You can use "bnfcertify" to certify the
3571 computations unconditionally.
3572 Remarks.
3574 Apart from the polynomial "P", you do not need to supply the technical
3576 parameters (under the library you still need to send at least an empty
3577 vector, coded as "NULL"). However, should you choose to set some of
3578 them, they \emph{must} be given in the requested order. For example, if
3579 you want to specify a given value of nrpid, you must give some values
3580 as well for "c" and "c_2", and provide a vector "[c,c_2,nrpid]".
3581 Note also that you can use an "nf" instead of "P", which avoids
3583 recomputing the integral basis and analogous quantities.
3584 bnfcertify"(bnf)"
3586 "bnf" being as output by "bnfinit", checks whether the result is
3587 correct, i.e. whether it is possible to remove the assumption of the
3588 Generalized Riemann Hypothesis. It is correct if and only if the answer
3589 is 1. If it is incorrect, the program may output some error message, or
3590 loop indefinitely. You can check its progress by increasing the debug
3591 level.
3592 The library syntax is certifybuchall"(bnf)", and the result is a C
3594 long.
3595 bnfclassunit"(P,{flag = 0},{tech = []})"
3597 \emph{this function is DEPRECATED, use "bnfinit"}.
3598 Buchmann's sub-exponential algorithm for computing the class group, the
3600 regulator and a system of fundamental units of the general algebraic
3601 number field "K" defined by the irreducible polynomial "P" with integer
3602 coefficients.
3603 The result of this function is a vector "v" with many components, which
3605 for ease of presentation is in fact output as a one column matrix. It
3606 is \emph{not} a "bnf", you need "bnfinit" for that. First we describe
3607 the default behaviour ("flag = 0"):
3608 "v[1]" is equal to the polynomial "P".
3610 "v[2]" is the 2-component vector "[r1,r2]", where "r1" and "r2" are as
3612 usual the number of real and half the number of complex embeddings of
3613 the number field "K".
3614 "v[3]" is the 2-component vector containing the field discriminant and
3616 the index.
3617 "v[4]" is an integral basis in Hermite normal form.
3619 "v[5]" ("v.clgp") is a 3-component vector containing the class number
3621 ("v.clgp.no"), the structure of the class group as a product of cyclic
3622 groups of order "n_i" ("v.clgp.cyc"), and the corresponding generators
3623 of the class group of respective orders "n_i" ("v.clgp.gen").
3624 "v[6]" ("v.reg") is the regulator computed to an accuracy which is the
3626 maximum of an internally determined accuracy and of the default.
3627 "v[7]" is deprecated, maintained for backward compatibility and always
3629 equal to 1.
3630 "v[8]" ("v.tu") a vector with 2 components, the first being the number
3632 "w" of roots of unity in "K" and the second a primitive "w"-th root of
3633 unity expressed as a polynomial.
3634 "v[9]" ("v.fu") is a system of fundamental units also expressed as
3636 polynomials.
3637 If "flag = 1", and the precision happens to be insufficient for
3639 obtaining the fundamental units, the internal precision is doubled and
3640 the computation redone, until the exact results are obtained. Be warned
3641 that this can take a very long time when the coefficients of the
3642 fundamental units on the integral basis are very large, for example in
3643 large real quadratic fields. For this case, there are alternate
3644 compact representations for algebraic numbers, implemented in PARI but
3645 currently not available in GP.
3646 If "flag = 2", the fundamental units and roots of unity are not
3648 computed. Hence the result has only 7 components, the first seven
3649 ones.
3650 The library syntax is bnfclassunit0"(P,flag,tech,prec)".
3652 bnfclgp"(P,{tech = []})"
3654 as "bnfinit", but only outputs "bnf.clgp", i.e. the class group.
3655 The library syntax is classgrouponly"(P,tech,prec)", where tech is as
3657 described under "bnfinit".
3658 bnfdecodemodule"(nf,m)"
3660 if "m" is a module as output in the first component of an extension
3661 given by "bnrdisclist", outputs the true module.
3662 The library syntax is decodemodule"(nf,m)".
3664 bnfinit"(P,{flag = 0},{tech = []})"
3666 initializes a bnf structure. Used in programs such as "bnfisprincipal",
3667 "bnfisunit" or "bnfnarrow". By default, the results are conditional on
3668 a heuristic strengthening of the GRH, see se:GRHbnf. The result is a
3669 10-component vector bnf.
3670 This implements Buchmann's sub-exponential algorithm for computing the
3672 class group, the regulator and a system of fundamental units of the
3673 general algebraic number field "K" defined by the irreducible
3674 polynomial "P" with integer coefficients.
3675 If the precision becomes insufficient, "gp" outputs a warning
3677 ("fundamental units too large, not given") and does not strive to
3678 compute the units by default ("flag = 0").
3679 When "flag = 1", we insist on finding the fundamental units exactly. Be
3681 warned that this can take a very long time when the coefficients of the
3682 fundamental units on the integral basis are very large. If the
3683 fundamental units are simply too large to be represented in this form,
3684 an error message is issued. They could be obtained using the so-called
3685 compact representation of algebraic numbers as a formal product of
3686 algebraic integers. The latter is implemented internally but not
3687 publicly accessible yet.
3688 When "flag = 2", on the contrary, it is initially agreed that units are
3690 not computed. Note that the resulting bnf will not be suitable for
3691 "bnrinit", and that this flag provides negligible time savings compared
3692 to the default. In short, it is deprecated.
3693 When "flag = 3", computes a very small version of "bnfinit", a ``small
3695 Buchmann's number field'' (or sbnf for short) which contains enough
3696 information to recover the full "bnf" vector very rapidly, but which is
3697 much smaller and hence easy to store and print. It is supposed to be
3698 used in conjunction with "bnfmake".
3699 "tech" is a technical vector (empty by default, see se:GRHbnf).
3701 Careful use of this parameter may speed up your computations
3702 considerably.
3703 The components of a bnf or sbnf are technical and never used by the
3705 casual user. In fact: \emph{never access a component directly, always
3706 use a proper member function.} However, for the sake of completeness
3707 and internal documentation, their description is as follows. We use the
3708 notations explained in the book by H. Cohen, \emph{A Course in
3709 Computational Algebraic Number Theory}, Graduate Texts in Maths 138,
3710 Springer-Verlag, 1993, Section 6.5, and subsection 6.5.5 in particular.
3711 "bnf[1]" contains the matrix "W", i.e. the matrix in Hermite normal
3713 form giving relations for the class group on prime ideal generators "(
3714 wp _i)_{1 <= i <= r}".
3715 "bnf[2]" contains the matrix "B", i.e. the matrix containing the
3717 expressions of the prime ideal factorbase in terms of the " wp _i". It
3718 is an "r x c" matrix.
3719 "bnf[3]" contains the complex logarithmic embeddings of the system of
3721 fundamental units which has been found. It is an "(r_1+r_2) x
3722 (r_1+r_2-1)" matrix.
3723 "bnf[4]" contains the matrix "M''_C" of Archimedean components of the
3725 relations of the matrix "(W|B)".
3726 "bnf[5]" contains the prime factor base, i.e. the list of prime ideals
3728 used in finding the relations.
3729 "bnf[6]" used to contain a permutation of the prime factor base, but
3731 has been obsoleted. It contains a dummy 0.
3732 "bnf[7]" or "bnf.nf" is equal to the number field data "nf" as would be
3734 given by "nfinit".
3735 "bnf[8]" is a vector containing the classgroup "bnf.clgp" as a finite
3737 abelian group, the regulator "bnf.reg", a 1 (used to contain an
3738 obsolete ``check number''), the number of roots of unity and a
3739 generator "bnf.tu", the fundamental units "bnf.fu".
3740 "bnf[9]" is a 3-element row vector used in "bnfisprincipal" only and
3742 obtained as follows. Let "D = U W V" obtained by applying the Smith
3743 normal form algorithm to the matrix "W" ( = "bnf[1]") and let "U_r" be
3744 the reduction of "U" modulo "D". The first elements of the factorbase
3745 are given (in terms of "bnf.gen") by the columns of "U_r", with
3746 Archimedean component "g_a"; let also "GD_a" be the Archimedean
3747 components of the generators of the (principal) ideals defined by the
3748 "bnf.gen[i]^bnf.cyc[i]". Then "bnf[9] = [U_r, g_a, GD_a]".
3749 "bnf[10]" is by default unused and set equal to 0. This field is used
3751 to store further information about the field as it becomes available,
3752 which is rarely needed, hence would be too expensive to compute during
3753 the initial "bnfinit" call. For instance, the generators of the
3754 principal ideals "bnf.gen[i]^bnf.cyc[i]" (during a call to
3755 "bnrisprincipal"), or those corresponding to the relations in "W" and
3756 "B" (when the "bnf" internal precision needs to be increased).
3757 An sbnf is a 12 component vector "v", as follows. Let "bnf" be the
3759 result of a full "bnfinit", complete with units. Then "v[1]" is the
3760 polynomial "P", "v[2]" is the number of real embeddings "r_1", "v[3]"
3761 is the field discriminant, "v[4]" is the integral basis, "v[5]" is the
3762 list of roots as in the sixth component of "nfinit", "v[6]" is the
3763 matrix "MD" of "nfinit" giving a Z-basis of the different, "v[7]" is
3764 the matrix "W = bnf[1]", "v[8]" is the matrix "matalpha = bnf[2]",
3765 "v[9]" is the prime ideal factor base "bnf[5]" coded in a compact way,
3766 and ordered according to the permutation "bnf[6]", "v[10]" is the
3767 2-component vector giving the number of roots of unity and a generator,
3768 expressed on the integral basis, "v[11]" is the list of fundamental
3769 units, expressed on the integral basis, "v[12]" is a vector containing
3770 the algebraic numbers alpha corresponding to the columns of the matrix
3771 "matalpha", expressed on the integral basis.
3772 Note that all the components are exact (integral or rational), except
3774 for the roots in "v[5]". Note also that member functions will
3775 \emph{not} work on sbnf, you have to use "bnfmake" explicitly first.
3776 The library syntax is bnfinit0"(P,flag,tech,prec)".
3778 bnfisintnorm"(bnf,x)"
3780 computes a complete system of solutions (modulo units of positive norm)
3781 of the absolute norm equation "\Norm(a) = x", where "a" is an integer
3782 in "bnf". If "bnf" has not been certified, the correctness of the
3783 result depends on the validity of GRH.
3784 See also "bnfisnorm".
3786 The library syntax is bnfisintnorm"(bnf,x)".
3788 bnfisnorm"(bnf,x,{flag = 1})"
3790 tries to tell whether the rational number "x" is the norm of some
3791 element y in "bnf". Returns a vector "[a,b]" where "x = Norm(a)*b".
3792 Looks for a solution which is an "S"-unit, with "S" a certain set of
3793 prime ideals containing (among others) all primes dividing "x". If
3794 "bnf" is known to be Galois, set "flag = 0" (in this case, "x" is a
3795 norm iff "b = 1"). If "flag" is non zero the program adds to "S" the
3796 following prime ideals, depending on the sign of "flag". If "flag > 0",
3797 the ideals of norm less than "flag". And if "flag < 0" the ideals
3798 dividing "flag".
3799 Assuming GRH, the answer is guaranteed (i.e. "x" is a norm iff "b =
3801 1"), if "S" contains all primes less than "12 log (\disc(Bnf))^2",
3802 where "Bnf" is the Galois closure of "bnf".
3803 See also "bnfisintnorm".
3805 The library syntax is bnfisnorm"(bnf,x,flag,prec)", where "flag" and
3807 "prec" are "long"s.
3808 bnfissunit"(bnf,sfu,x)"
3810 "bnf" being output by "bnfinit", sfu by "bnfsunit", gives the column
3811 vector of exponents of "x" on the fundamental "S"-units and the roots
3812 of unity. If "x" is not a unit, outputs an empty vector.
3813 The library syntax is bnfissunit"(bnf,sfu,x)".
3815 bnfisprincipal"(bnf,x,{flag = 1})"
3817 "bnf" being the number field data output by "bnfinit", and "x" being
3818 either a Z-basis of an ideal in the number field (not necessarily in
3819 HNF) or a prime ideal in the format output by the function
3820 "idealprimedec", this function tests whether the ideal is principal or
3821 not. The result is more complete than a simple true/false answer: it
3822 gives a row vector "[v_1,v_2]", where
3823 "v_1" is the vector of components "c_i" of the class of the ideal "x"
3825 in the class group, expressed on the generators "g_i" given by
3826 "bnfinit" (specifically "bnf.gen"). The "c_i" are chosen so that "0 <=
3827 c_i < n_i" where "n_i" is the order of "g_i" (the vector of "n_i" being
3828 "bnf.cyc").
3829 "v_2" gives on the integral basis the components of "alpha" such that
3831 "x = alphaprod_ig_i^{c_i}". In particular, "x" is principal if and only
3832 if "v_1" is equal to the zero vector. In the latter case, "x =
3833 alphaZ_K" where "alpha" is given by "v_2". Note that if "alpha" is too
3834 large to be given, a warning message will be printed and "v_2" will be
3835 set equal to the empty vector.
3836 If "flag = 0", outputs only "v_1", which is much easier to compute.
3838 If "flag = 2", does as if "flag" were 0, but doubles the precision
3840 until a result is obtained.
3841 If "flag = 3", as in the default behaviour ("flag = 1"), but doubles
3843 the precision until a result is obtained.
3844 The user is warned that these two last setting may induce \emph{very}
3846 lengthy computations.
3847 The library syntax is isprincipalall"(bnf,x,flag)".
3849 bnfisunit"(bnf,x)"
3851 "bnf" being the number field data output by "bnfinit" and "x" being an
3852 algebraic number (type integer, rational or polmod), this outputs the
3853 decomposition of "x" on the fundamental units and the roots of unity if
3854 "x" is a unit, the empty vector otherwise. More precisely, if
3855 "u_1",...,"u_r" are the fundamental units, and "zeta" is the generator
3856 of the group of roots of unity ("bnf.tu"), the output is a vector
3857 "[x_1,...,x_r,x_{r+1}]" such that "x = u_1^{x_1}...
3858 u_r^{x_r}.zeta^{x_{r+1}}". The "x_i" are integers for "i <= r" and is
3859 an integer modulo the order of "zeta" for "i = r+1".
3860 The library syntax is isunit"(bnf,x)".
3862 bnfmake"(sbnf)"
3864 sbnf being a ``small "bnf"'' as output by "bnfinit""(x,3)", computes
3865 the complete "bnfinit" information. The result is \emph{not} identical
3866 to what "bnfinit" would yield, but is functionally identical. The
3867 execution time is very small compared to a complete "bnfinit". Note
3868 that if the default precision in "gp" (or "prec" in library mode) is
3869 greater than the precision of the roots "sbnf[5]", these are recomputed
3870 so as to get a result with greater accuracy.
3871 Note that the member functions are \emph{not} available for sbnf, you
3873 have to use "bnfmake" explicitly first.
3874 The library syntax is makebigbnf"(sbnf,prec)", where "prec" is a C long
3876 integer.
3877 bnfnarrow"(bnf)"
3879 "bnf" being as output by "bnfinit", computes the narrow class group of
3880 "bnf". The output is a 3-component row vector "v" analogous to the
3881 corresponding class group component "bnf.clgp" ("bnf[8][1]"): the first
3882 component is the narrow class number "v.no", the second component is a
3883 vector containing the SNF cyclic components "v.cyc" of the narrow class
3884 group, and the third is a vector giving the generators of the
3885 corresponding "v.gen" cyclic groups. Note that this function is a
3886 special case of "bnrinit".
3887 The library syntax is buchnarrow"(bnf)".
3889 bnfsignunit"(bnf)"
3891 "bnf" being as output by "bnfinit", this computes an "r_1 x
3892 (r_1+r_2-1)" matrix having "+-1" components, giving the signs of the
3893 real embeddings of the fundamental units. The following functions
3894 compute generators for the totally positive units:
3895 /* exponents of totally positive units generators on bnf.tufu */
3897 tpuexpo(bnf)=
3898 { local(S,d,K);
3899 S = bnfsignunit(bnf); d = matsize(S);
3901 S = matrix(d[1],d[2], i,j, if (S[i,j] < 0, 1,0));
3902 S = concat(vectorv(d[1],i,1), S); \\ add sign(-1)
3903 K = lift(matker(S * Mod(1,2)));
3904 if (K, mathnfmodid(K, 2), 2*matid(d[1]))
3905 }
3906 /* totally positive units */
3908 tpu(bnf)=
3909 { local(vu = bnf.tufu, ex = tpuexpo(bnf));
3910 vector(#ex-1, i, factorback(vu, ex[,i+1])) \\ ex[,1] is 1
3912 }
3913 The library syntax is signunits"(bnf)".
3915 bnfreg"(bnf)"
3917 "bnf" being as output by "bnfinit", computes its regulator.
3918 The library syntax is regulator"(bnf,tech,prec)", where tech is as in
3920 "bnfinit".
3921 bnfsunit"(bnf,S)"
3923 computes the fundamental "S"-units of the number field "bnf" (output by
3924 "bnfinit"), where "S" is a list of prime ideals (output by
3925 "idealprimedec"). The output is a vector "v" with 6 components.
3926 "v[1]" gives a minimal system of (integral) generators of the "S"-unit
3928 group modulo the unit group.
3929 "v[2]" contains technical data needed by "bnfissunit".
3931 "v[3]" is an empty vector (used to give the logarithmic embeddings of
3933 the generators in "v[1]" in version 2.0.16).
3934 "v[4]" is the "S"-regulator (this is the product of the regulator, the
3936 determinant of "v[2]" and the natural logarithms of the norms of the
3937 ideals in "S").
3938 "v[5]" gives the "S"-class group structure, in the usual format (a row
3940 vector whose three components give in order the "S"-class number, the
3941 cyclic components and the generators).
3942 "v[6]" is a copy of "S".
3944 The library syntax is bnfsunit"(bnf,S,prec)".
3946 bnfunit"(bnf)"
3948 "bnf" being as output by "bnfinit", outputs the vector of fundamental
3949 units of the number field.
3950 This function is mostly useless, since it will only succeed if bnf
3952 contains the units, in which case "bnf.fu" is recommanded instead, or
3953 bnf was produced with "bnfinit(,,2)", which is itself deprecated.
3954 The library syntax is buchfu"(bnf)".
3956 bnrL1"(bnr,{subgroup},{flag = 0})"
3958 bnr being the number field data which is output by "bnrinit(,,1)" and
3959 subgroup being a square matrix defining a congruence subgroup of the
3960 ray class group corresponding to bnr (the trivial congruence subgroup
3961 if omitted), returns for each character "chi" of the ray class group
3962 which is trivial on this subgroup, the value at "s = 1" (or "s = 0") of
3963 the abelian "L"-function associated to "chi". For the value at "s = 0",
3964 the function returns in fact for each character "chi" a vector "[r_chi
3965 , c_chi]" where "r_chi" is the order of "L(s, chi)" at "s = 0" and
3966 "c_chi" the first non-zero term in the expansion of "L(s, chi)" at "s =
3967 0"; in other words
3968 "L(s, chi) = c_chi.s^{r_chi} + O(s^{r_chi + 1})"
3970 near 0. flag is optional, default value is 0; its binary digits mean 1:
3972 compute at "s = 1" if set to 1 or "s = 0" if set to 0, 2: compute the
3973 primitive "L"-functions associated to "chi" if set to 0 or the
3974 "L"-function with Euler factors at prime ideals dividing the modulus of
3975 bnr removed if set to 1 (this is the so-called "L_S(s, chi)" function
3976 where "S" is the set of infinite places of the number field together
3977 with the finite prime ideals dividing the modulus of bnr, see the
3978 example below), 3: returns also the character. Example:
3979 bnf = bnfinit(x^2 - 229);
3981 bnr = bnrinit(bnf,1,1);
3982 bnrL1(bnr)
3983 returns the order and the first non-zero term of the abelian
3985 "L"-functions "L(s, chi)" at "s = 0" where "chi" runs through the
3986 characters of the class group of "Q( sqrt {229})". Then
3987 bnr2 = bnrinit(bnf,2,1);
3989 bnrL1(bnr2,,2)
3990 returns the order and the first non-zero terms of the abelian
3992 "L"-functions "L_S(s, chi)" at "s = 0" where "chi" runs through the
3993 characters of the class group of "Q( sqrt {229})" and "S" is the set of
3994 infinite places of "Q( sqrt {229})" together with the finite prime 2.
3995 Note that the ray class group modulo 2 is in fact the class group, so
3996 "bnrL1(bnr2,0)" returns exactly the same answer as "bnrL1(bnr,0)".
3997 The library syntax is bnrL1"(bnr,subgroup,flag,prec)", where an omitted
3999 subgroup is coded as "NULL".
4000 bnrclass"(bnf,ideal,{flag = 0})"
4002 \emph{this function is DEPRECATED, use "bnrinit"}.
4003 "bnf" being as output by "bnfinit" (the units are mandatory unless the
4005 ideal is trivial), and ideal being a modulus, computes the ray class
4006 group of the number field for the modulus ideal, as a finite abelian
4007 group.
4008 The library syntax is bnrclass0"(bnf,ideal,flag)".
4010 bnrclassno"(bnf,I)"
4012 "bnf" being as output by "bnfinit" (units are mandatory unless the
4013 ideal is trivial), and "I" being a modulus, computes the ray class
4014 number of the number field for the modulus "I". This is faster than
4015 "bnrinit" and should be used if only the ray class number is desired.
4016 See "bnrclassnolist" if you need ray class numbers for all moduli less
4017 than some bound.
4018 The library syntax is bnrclassno"(bnf,I)".
4020 bnrclassnolist"(bnf,list)"
4022 "bnf" being as output by "bnfinit", and list being a list of moduli
4023 (with units) as output by "ideallist" or "ideallistarch", outputs the
4024 list of the class numbers of the corresponding ray class groups. To
4025 compute a single class number, "bnrclassno" is more efficient.
4026 ? bnf = bnfinit(x^2 - 2);
4028 ? L = ideallist(bnf, 100, 2);
4029 ? H = bnrclassnolist(bnf, L);
4030 ? H[98]
4031 %4 = [1, 3, 1]
4032 ? l = L[1][98]; ids = vector(#l, i, l[i].mod[1])
4033 %5 = [[98, 88; 0, 1], [14, 0; 0, 7], [98, 10; 0, 1]]
4034 The weird "l[i].mod[1]", is the first component of "l[i].mod", i.e.
4036 the finite part of the conductor. (This is cosmetic: since by
4037 construction the archimedean part is trivial, I do not want to see it).
4038 This tells us that the ray class groups modulo the ideals of norm 98
4039 (printed as %5) have respectively order 1, 3 and 1. Indeed, we may
4040 check directly :
4041 ? bnrclassno(bnf, ids[2])
4043 %6 = 3
4044 The library syntax is bnrclassnolist"(bnf,list)".
4046 bnrconductor"(a_1,{a_2},{a_3}, {flag = 0})"
4048 conductor "f" of the subfield of a ray class field as defined by
4049 "[a_1,a_2,a_3]" (see "bnr" at the beginning of this section).
4050 If "flag = 0", returns "f".
4052 If "flag = 1", returns "[f, Cl_f, H]", where "Cl_f" is the ray class
4054 group modulo "f", as a finite abelian group; finally "H" is the
4055 subgroup of "Cl_f" defining the extension.
4056 If "flag = 2", returns "[f, bnr(f), H]", as above except "Cl_f" is
4058 replaced by a "bnr" structure, as output by "bnrinit(,f,1)".
4059 The library syntax is conductor"(bnr, subgroup, flag)", where an
4061 omitted subgroup (trivial subgroup, i.e. ray class field) is input as
4062 "NULL", and "flag" is a C long.
4063 bnrconductorofchar"(bnr,chi)"
4065 bnr being a big ray number field as output by "bnrinit", and chi being
4066 a row vector representing a character as expressed on the generators of
4067 the ray class group, gives the conductor of this character as a
4068 modulus.
4069 The library syntax is bnrconductorofchar"(bnr,chi)".
4071 bnrdisc"(a1,{a2},{a3},{flag = 0})"
4073 "a1", "a2", "a3" defining a big ray number field "L" over a ground
4074 field "K" (see "bnr" at the beginning of this section for the meaning
4075 of "a1", "a2", "a3"), outputs a 3-component row vector "[N,R_1,D]",
4076 where "N" is the (absolute) degree of "L", "R_1" the number of real
4077 places of "L", and "D" the discriminant of "L/Q", including sign (if
4078 "flag = 0").
4079 If "flag = 1", as above but outputs relative data. "N" is now the
4081 degree of "L/K", "R_1" is the number of real places of "K" unramified
4082 in "L" (so that the number of real places of "L" is equal to "R_1"
4083 times the relative degree "N"), and "D" is the relative discriminant
4084 ideal of "L/K".
4085 If "flag = 2", as the default case, except that if the modulus is not
4087 the exact conductor corresponding to the "L", no data is computed and
4088 the result is 0.
4089 If "flag = 3", as case 2, but output relative data.
4091 The library syntax is bnrdisc0"(a1,a2,a3,flag)".
4093 bnrdisclist"(bnf,bound,{arch})"
4095 "bnf" being as output by "bnfinit" (with units), computes a list of
4096 discriminants of Abelian extensions of the number field by increasing
4097 modulus norm up to bound bound. The ramified Archimedean places are
4098 given by arch; all possible values are taken if arch is omitted.
4099 The alternative syntax "bnrdisclist(bnf,list)" is supported, where list
4101 is as output by "ideallist" or "ideallistarch" (with units), in which
4102 case arch is disregarded.
4103 The output "v" is a vector of vectors, where "v[i][j]" is understood to
4105 be in fact "V[2^{15}(i-1)+j]" of a unique big vector "V". (This akward
4106 scheme allows for larger vectors than could be otherwise represented.)
4107 "V[k]" is itself a vector "W", whose length is the number of ideals of
4109 norm "k". We consider first the case where arch was specified. Each
4110 component of "W" corresponds to an ideal "m" of norm "k", and gives
4111 invariants associated to the ray class field "L" of "bnf" of conductor
4112 "[m, arch]". Namely, each contains a vector "[m,d,r,D]" with the
4113 following meaning: "m" is the prime ideal factorization of the modulus,
4114 "d = [L:Q]" is the absolute degree of "L", "r" is the number of real
4115 places of "L", and "D" is the factorization of its absolute
4116 discriminant. We set "d = r = D = 0" if "m" is not the finite part of a
4117 conductor.
4118 If arch was omitted, all "t = 2^{r_1}" possible values are taken and a
4120 component of "W" has the form "[m, [[d_1,r_1,D_1],...,
4121 [d_t,r_t,D_t]]]", where "m" is the finite part of the conductor as
4122 above, and "[d_i,r_i,D_i]" are the invariants of the ray class field of
4123 conductor "[m,v_i]", where "v_i" is the "i"-th archimedean component,
4124 ordered by inverse lexicographic order; so "v_1 = [0,...,0]", "v_2 =
4125 [1,0...,0]", etc. Again, we set "d_i = r_i = D_i = 0" if "[m,v_i]" is
4126 not a conductor.
4127 Finally, each prime ideal "pr = [p,alpha,e,f,beta]" in the prime
4129 factorization "m" is coded as the integer "p.n^2+(f-1).n+(j-1)", where
4130 "n" is the degree of the base field and "j" is such that
4131 "pr = idealprimedec(nf,p)[j]".
4133 "m" can be decoded using "bnfdecodemodule".
4135 Note that to compute such data for a single field, either "bnrclassno"
4137 or "bnrdisc" is more efficient.
4138 The library syntax is bnrdisclist0"(bnf,bound,arch)".
4140 bnrinit"(bnf,f,{flag = 0})"
4142 "bnf" is as output by "bnfinit", "f" is a modulus, initializes data
4143 linked to the ray class group structure corresponding to this module, a
4144 so-called bnr structure. The following member functions are available
4145 on the result: ".bnf" is the underlying bnf, ".mod" the modulus, ".bid"
4146 the bid structure associated to the modulus; finally, ".clgp", ".no",
4147 ".cyc", "clgp" refer to the ray class group (as a finite abelian
4148 group), its cardinality, its elementary divisors, its generators.
4149 The last group of functions are different from the members of the
4151 underlying bnf, which refer to the class group; use "bnr.bnf.xxx" to
4152 access these, e.g. "bnr.bnf.cyc" to get the cyclic decomposition of the
4153 class group.
4154 They are also different from the members of the underlying bid, which
4156 refer to "(\O_K/f)^*"; use "bnr.bid.xxx" to access these,
4157 e.g. "bnr.bid.no" to get "phi(f)".
4158 If "flag = 0" (default), the generators of the ray class group are not
4160 computed, which saves time. Hence "bnr.gen" would produce an error.
4161 If "flag = 1", as the default, except that generators are computed.
4163 The library syntax is bnrinit0"(bnf,f,flag)".
4165 bnrisconductor"(a1,{a2},{a3})"
4167 "a1", "a2", "a3" represent an extension of the base field, given by
4168 class field theory for some modulus encoded in the parameters. Outputs
4169 1 if this modulus is the conductor, and 0 otherwise. This is slightly
4170 faster than "bnrconductor".
4171 The library syntax is bnrisconductor"(a1,a2,a3)" and the result is a
4173 "long".
4174 bnrisprincipal"(bnr,x,{flag = 1})"
4176 bnr being the number field data which is output by "bnrinit""(,,1)" and
4177 "x" being an ideal in any form, outputs the components of "x" on the
4178 ray class group generators in a way similar to "bnfisprincipal". That
4179 is a 2-component vector "v" where "v[1]" is the vector of components of
4180 "x" on the ray class group generators, "v[2]" gives on the integral
4181 basis an element "alpha" such that "x = alphaprod_ig_i^{x_i}".
4182 If "flag = 0", outputs only "v_1". In that case, bnr need not contain
4184 the ray class group generators, i.e. it may be created with
4185 "bnrinit""(,,0)"
4186 The library syntax is bnrisprincipal"(bnr,x,flag)".
4188 bnrrootnumber"(bnr,chi,{flag = 0})"
4190 if "chi = chi" is a (not necessarily primitive) character over bnr, let
4191 "L(s,chi) = sum_{id} chi(id) N(id)^{-s}" be the associated Artin
4192 L-function. Returns the so-called Artin root number, i.e. the complex
4193 number "W(chi)" of modulus 1 such that
4194 "Lambda(1-s,chi) = W(chi) Lambda(s,\overline{chi})"
4196 where "Lambda(s,chi) = A(chi)^{s/2}gamma_chi(s) L(s,chi)" is the
4198 enlarged L-function associated to "L".
4199 The generators of the ray class group are needed, and you can set "flag
4201 = 1" if the character is known to be primitive. Example:
4202 bnf = bnfinit(x^2 - 145);
4204 bnr = bnrinit(bnf,7,1);
4205 bnrrootnumber(bnr, [5])
4206 returns the root number of the character "chi" of "\Cl_7(Q( sqrt
4208 {145}))" such that "chi(g) = zeta^5", where "g" is the generator of the
4209 ray-class field and "zeta = e^{2iPi/N}" where "N" is the order of "g"
4210 ("N = 12" as "bnr.cyc" readily tells us).
4211 The library syntax is bnrrootnumber"(bnf,chi,flag)"
4213 bnrstark"{(bnr,{subgroup})}"
4215 bnr being as output by "bnrinit(,,1)", finds a relative equation for
4216 the class field corresponding to the modulus in bnr and the given
4217 congruence subgroup (as usual, omit "subgroup" if you want the whole
4218 ray class group).
4219 The routine uses Stark units and needs to find a suitable auxilliary
4221 conductor, which may not exist when the class field is not cyclic over
4222 the base. In this case "bnrstark" is allowed to return a vector of
4223 polynomials defining \emph{independent} relative extensions, whose
4224 compositum is the requested class field. It was decided that it was
4225 more useful to keep the extra information thus made available, hence
4226 the user has to take the compositum herself.
4227 The main variable of bnr must not be "x", and the ground field and the
4229 class field must be totally real. When the base field is Q, the vastly
4230 simpler "galoissubcyclo" is used instead. Here is an example:
4231 bnf = bnfinit(y^2 - 3);
4233 bnr = bnrinit(bnf, 5, 1);
4234 pol = bnrstark(bnr)
4235 returns the ray class field of "Q( sqrt {3})" modulo 5. Usually, one
4237 wants to apply to the result one of
4238 rnfpolredabs(bnf, pol, 16) \\ compute a reduced relative polynomial
4240 rnfpolredabs(bnf, pol, 16 + 2) \\ compute a reduced absolute polynomial
4241 The library syntax is bnrstark"(bnr,subgroup)", where an omitted
4243 subgroup is coded by "NULL".
4244 dirzetak"(nf,b)"
4246 gives as a vector the first "b" coefficients of the Dedekind zeta
4247 function of the number field "nf" considered as a Dirichlet series.
4248 The library syntax is dirzetak"(nf,b)".
4250 factornf"(x,t)"
4252 factorization of the univariate polynomial "x" over the number field
4253 defined by the (univariate) polynomial "t". "x" may have coefficients
4254 in Q or in the number field. The algorithm reduces to factorization
4255 over Q (Trager's trick). The direct approach of "nffactor", which uses
4256 van Hoeij's method in a relative setting, is in general faster.
4257 The main variable of "t" must be of \emph{lower} priority than that of
4259 "x" (see "Label se:priority"). However if non-rational number field
4260 elements occur (as polmods or polynomials) as coefficients of "x", the
4261 variable of these polmods \emph{must} be the same as the main variable
4262 of "t". For example
4263 ? factornf(x^2 + Mod(y, y^2+1), y^2+1);
4265 ? factornf(x^2 + y, y^2+1); \\ these two are OK
4266 ? factornf(x^2 + Mod(z,z^2+1), y^2+1)
4267 *** factornf: inconsistent data in rnf function.
4268 ? factornf(x^2 + z, y^2+1)
4269 *** factornf: incorrect variable in rnf function.
4270 The library syntax is polfnf"(x,t)".
4272 galoisexport"(gal,{flag = 0})"
4274 gal being be a Galois field as output by "galoisinit", export the
4275 underlying permutation group as a string suitable for (no flags or
4276 "flag = 0") GAP or ("flag = 1") Magma. The following example compute
4277 the index of the underlying abstract group in the GAP library:
4278 ? G = galoisinit(x^6+108);
4280 ? s = galoisexport(G)
4281 %2 = "Group((1, 2, 3)(4, 5, 6), (1, 4)(2, 6)(3, 5))"
4282 ? extern("echo \"IdGroup("s");\" | gap -q")
4283 %3 = [6, 1]
4284 ? galoisidentify(G)
4285 %4 = [6, 1]
4286 This command also accepts subgroups returned by "galoissubgroups".
4288 The library syntax is galoisexport"(gal,flag)".
4290 galoisfixedfield"(gal,perm,{flag = 0},{v = y}))"
4292 gal being be a Galois field as output by "galoisinit" and perm an
4293 element of "gal.group" or a vector of such elements, computes the fixed
4294 field of gal by the automorphism defined by the permutations perm of
4295 the roots "gal.roots". "P" is guaranteed to be squarefree modulo
4296 "gal.p".
4297 If no flags or "flag = 0", output format is the same as for
4299 "nfsubfield", returning "[P,x]" such that "P" is a polynomial defining
4300 the fixed field, and "x" is a root of "P" expressed as a polmod in
4301 "gal.pol".
4302 If "flag = 1" return only the polynomial "P".
4304 If "flag = 2" return "[P,x,F]" where "P" and "x" are as above and "F"
4306 is the factorization of "gal.pol" over the field defined by "P", where
4307 variable "v" ("y" by default) stands for a root of "P". The priority of
4308 "v" must be less than the priority of the variable of "gal.pol" (see
4309 "Label se:priority"). Example:
4310 ? G = galoisinit(x^4+1);
4312 ? galoisfixedfield(G,G.group[2],2)
4313 %2 = [x^2 + 2, Mod(x^3 + x, x^4 + 1), [x^2 - y*x - 1, x^2 + y*x - 1]]
4314 computes the factorization "x^4+1 = (x^2- sqrt {-2}x-1)(x^2+ sqrt
4316 {-2}x-1)"
4317 The library syntax is galoisfixedfield"(gal,perm,flag,"v")", where "v"
4319 is a variable number, an omitted "v" being coded by "-1".
4320 galoisidentify"(gal)"
4322 gal being be a Galois field as output by "galoisinit", output the
4323 isomorphism class of the underlying abstract group as a two-components
4324 vector "[o,i]", where "o" is the group order, and "i" is the group
4325 index in the GAP4 Small Group library, by Hans Ulrich Besche, Bettina
4326 Eick and Eamonn O'Brien.
4327 This command also accepts subgroups returned by "galoissubgroups".
4329 The current implementation is limited to degree less or equal to 127.
4331 Some larger ``easy'' orders are also supported.
4332 The output is similar to the output of the function "IdGroup" in GAP4.
4334 Note that GAP4 "IdGroup" handles all groups of order less than 2000
4335 except 1024, so you can use "galoisexport" and GAP4 to identify large
4336 Galois groups.
4337 The library syntax is galoisidentify"(gal)".
4339 galoisinit"(pol,{den})"
4341 computes the Galois group and all necessary information for computing
4342 the fixed fields of the Galois extension "K/Q" where "K" is the number
4343 field defined by "pol" (monic irreducible polynomial in "Z[X]" or a
4344 number field as output by "nfinit"). The extension "K/Q" must be Galois
4345 with Galois group ``weakly'' super-solvable (see "nfgaloisconj")
4346 This is a prerequisite for most of the "galois""xxx" routines. For
4348 instance:
4349 P = x^6 + 108;
4351 G = galoisinit(P);
4352 L = galoissubgroups(G);
4353 vector(#L, i, galoisisabelian(L[i],1))
4354 vector(#L, i, galoisidentify(L[i]))
4355 The output is an 8-component vector gal.
4357 "gal[1]" contains the polynomial pol ("gal.pol").
4359 "gal[2]" is a three-components vector "[p,e,q]" where "p" is a prime
4361 number ("gal.p") such that pol totally split modulo "p" , "e" is an
4362 integer and "q = p^e" ("gal.mod") is the modulus of the roots in
4363 "gal.roots".
4364 "gal[3]" is a vector "L" containing the "p"-adic roots of pol as
4366 integers implicitly modulo "gal.mod". ("gal.roots").
4367 "gal[4]" is the inverse of the Van der Monde matrix of the "p"-adic
4369 roots of pol, multiplied by "gal[5]".
4370 "gal[5]" is a multiple of the least common denominator of the
4372 automorphisms expressed as polynomial in a root of pol.
4373 "gal[6]" is the Galois group "G" expressed as a vector of permutations
4375 of "L" ("gal.group").
4376 "gal[7]" is a generating subset "S = [s_1,...,s_g]" of "G" expressed as
4378 a vector of permutations of "L" ("gal.gen").
4379 "gal[8]" contains the relative orders "[o_1,...,o_g]" of the generators
4381 of "S" ("gal.orders").
4382 Let "H" be the maximal normal supersolvable subgroup of "G", we have
4384 the following properties:
4385 \item if "G/H ~ A_4" then "[o_1,...,o_g]" ends by "[2,2,3]".
4387 \item if "G/H ~ S_4" then "[o_1,...,o_g]" ends by "[2,2,3,2]".
4389 \item else "G" is super-solvable.
4391 \item for "1 <= i <= g" the subgroup of "G" generated by
4393 "[s_1,...,s_g]" is normal, with the exception of "i = g-2" in the
4394 second case and of "i = g-3" in the third.
4395 \item the relative order "o_i" of "s_i" is its order in the quotient
4397 group "G/<s_1,...,s_{i-1}>", with the same exceptions.
4398 \item for any "x belongs to G" there exists a unique family
4400 "[e_1,...,e_g]" such that (no exceptions):
4401 -- for "1 <= i <= g" we have "0 <= e_i < o_i"
4403 -- "x = g_1^{e_1}g_2^{e_2}...g_n^{e_n}"
4405 If present "den" must be a suitable value for "gal[5]".
4407 The library syntax is galoisinit"(gal,den)".
4409 galoisisabelian"(gal,{fl = 0})"
4411 gal being as output by "galoisinit", return 0 if gal is not an abelian
4412 group, and the HNF matrix of gal over "gal.gen" if "fl = 0", 1 if "fl =
4413 1".
4414 This command also accepts subgroups returned by "galoissubgroups".
4416 The library syntax is galoisisabelian"(gal,fl)" where fl is a C long
4418 integer.
4419 galoispermtopol"(gal,perm)"
4421 gal being a Galois field as output by "galoisinit" and perm a element
4422 of "gal.group", return the polynomial defining the Galois automorphism,
4423 as output by "nfgaloisconj", associated with the permutation perm of
4424 the roots "gal.roots". perm can also be a vector or matrix, in this
4425 case, "galoispermtopol" is applied to all components recursively.
4426 Note that
4428 G = galoisinit(pol);
4430 galoispermtopol(G, G[6])~
4431 is equivalent to "nfgaloisconj(pol)", if degree of pol is greater or
4433 equal to 2.
4434 The library syntax is galoispermtopol"(gal,perm)".
4436 galoissubcyclo"(N,H,{fl = 0},{v})"
4438 computes the subextension of "Q(zeta_n)" fixed by the subgroup "H
4439 \subset (Z/nZ)^*". By the Kronecker-Weber theorem, all abelian number
4440 fields can be generated in this way (uniquely if "n" is taken to be
4441 minimal).
4442 The pair "(n, H)" is deduced from the parameters "(N, H)" as follows
4444 \item "N" an integer: then "n = N"; "H" is a generator, i.e. an integer
4446 or an integer modulo "n"; or a vector of generators.
4447 \item "N" the output of znstar(n). "H" as in the first case above, or a
4449 matrix, taken to be a HNF left divisor of the SNF for "(Z/nZ)^*" (of
4450 type "N.cyc"), giving the generators of "H" in terms of "N.gen".
4451 \item "N" the output of "bnrinit(bnfinit(y), m, 1)" where "m" is a
4453 module. "H" as in the first case, or a matrix taken to be a HNF left
4454 divisor of the SNF for the ray class group modulo "m" (of type
4455 "N.cyc"), giving the generators of "H" in terms of "N.gen".
4456 In this last case, beware that "H" is understood relatively to "N"; in
4458 particular, if the infinite place does not divide the module, e.g if
4459 "m" is an integer, then it is not a subgroup of "(Z/nZ)^*", but of its
4460 quotient by "{+- 1}".
4461 If "fl = 0", compute a polynomial (in the variable v) defining the the
4463 subfield of "Q(zeta_n)" fixed by the subgroup H of "(Z/nZ)^*".
4464 If "fl = 1", compute only the conductor of the abelian extension, as a
4466 module.
4467 If "fl = 2", output "[pol, N]", where "pol" is the polynomial as output
4469 when "fl = 0" and "N" the conductor as output when "fl = 1".
4470 The following function can be used to compute all subfields of
4472 "Q(zeta_n)" (of exact degree "d", if "d" is set):
4473 subcyclo(n, d = -1)=
4475 {
4476 local(bnr,L,IndexBound);
4477 IndexBound = if (d < 0, n, [d]);
4478 bnr = bnrinit(bnfinit(y), [n,[1]], 1);
4479 L = subgrouplist(bnr, IndexBound, 1);
4480 vector(#L,i, galoissubcyclo(bnr,L[i]));
4481 }
4482 Setting "L = subgrouplist(bnr, IndexBound)" would produce subfields of
4484 exact conductor "n oo ".
4485 The library syntax is galoissubcyclo"(N,H,fl,v)" where fl is a C long
4487 integer, and v a variable number.
4488 galoissubfields"(G,{fl = 0},{v})"
4490 Output all the subfields of the Galois group G, as a vector. This
4491 works by applying "galoisfixedfield" to all subgroups. The meaning of
4492 the flag fl is the same as for "galoisfixedfield".
4493 The library syntax is galoissubfields"(G,fl,v)", where fl is a long and
4495 v a variable number.
4496 galoissubgroups"(gal)"
4498 Output all the subgroups of the Galois group "gal". A subgroup is a
4499 vector [gen, orders], with the same meaning as for "gal.gen" and
4500 "gal.orders". Hence gen is a vector of permutations generating the
4501 subgroup, and orders is the relatives orders of the generators. The
4502 cardinal of a subgroup is the product of the relative orders. Such
4503 subgroup can be used instead of a Galois group in the following
4504 command: "galoisisabelian", "galoissubgroups", "galoisexport" and
4505 "galoisidentify".
4506 To get the subfield fixed by a subgroup sub of gal, use
4508 galoisfixedfield(gal,sub[1])
4510 The library syntax is galoissubgroups"(gal)".
4512 idealadd"(nf,x,y)"
4514 sum of the two ideals "x" and "y" in the number field "nf". When "x"
4515 and "y" are given by Z-bases, this does not depend on "nf" and can be
4516 used to compute the sum of any two Z-modules. The result is given in
4517 HNF.
4518 The library syntax is idealadd"(nf,x,y)".
4520 idealaddtoone"(nf,x,{y})"
4522 "x" and "y" being two co-prime integral ideals (given in any form),
4523 this gives a two-component row vector "[a,b]" such that "a belongs to
4524 x", "b belongs to y" and "a+b = 1".
4525 The alternative syntax "idealaddtoone(nf,v)", is supported, where "v"
4527 is a "k"-component vector of ideals (given in any form) which sum to
4528 "Z_K". This outputs a "k"-component vector "e" such that "e[i] belongs
4529 to x[i]" for "1 <= i <= k" and "sum_{1 <= i <= k}e[i] = 1".
4530 The library syntax is idealaddtoone0"(nf,x,y)", where an omitted "y" is
4532 coded as "NULL".
4533 idealappr"(nf,x,{flag = 0})"
4535 if "x" is a fractional ideal (given in any form), gives an element
4536 "alpha" in "nf" such that for all prime ideals " wp " such that the
4537 valuation of "x" at " wp " is non-zero, we have "v_{ wp }(alpha) = v_{
4538 wp }(x)", and. "v_{ wp }(alpha) >= 0" for all other "{ wp }".
4539 If "flag" is non-zero, "x" must be given as a prime ideal
4541 factorization, as output by "idealfactor", but possibly with zero or
4542 negative exponents. This yields an element "alpha" such that for all
4543 prime ideals " wp " occurring in "x", "v_{ wp }(alpha)" is equal to the
4544 exponent of " wp " in "x", and for all other prime ideals, "v_{ wp
4545 }(alpha) >= 0". This generalizes "idealappr(nf,x,0)" since zero
4546 exponents are allowed. Note that the algorithm used is slightly
4547 different, so that "idealappr(nf,idealfactor(nf,x))" may not be the
4548 same as "idealappr(nf,x,1)".
4549 The library syntax is idealappr0"(nf,x,flag)".
4551 idealchinese"(nf,x,y)"
4553 "x" being a prime ideal factorization (i.e. a 2 by 2 matrix whose first
4554 column contain prime ideals, and the second column integral exponents),
4555 "y" a vector of elements in "nf" indexed by the ideals in "x", computes
4556 an element "b" such that
4557 "v_ wp (b - y_ wp ) >= v_ wp (x)" for all prime ideals in "x" and "v_
4559 wp (b) >= 0" for all other " wp ".
4560 The library syntax is idealchinese"(nf,x,y)".
4562 idealcoprime"(nf,x,y)"
4564 given two integral ideals "x" and "y" in the number field "nf", finds a
4565 "beta" in the field, expressed on the integral basis "nf[7]", such that
4566 "beta.x" is an integral ideal coprime to "y".
4567 The library syntax is idealcoprime"(nf,x,y)".
4569 idealdiv"(nf,x,y,{flag = 0})"
4571 quotient "x.y^{-1}" of the two ideals "x" and "y" in the number field
4572 "nf". The result is given in HNF.
4573 If "flag" is non-zero, the quotient "x.y^{-1}" is assumed to be an
4575 integral ideal. This can be much faster when the norm of the quotient
4576 is small even though the norms of "x" and "y" are large.
4577 The library syntax is idealdiv0"(nf,x,y,flag)". Also available are "
4579 idealdiv(nf,x,y)" ("flag = 0") and " idealdivexact(nf,x,y)" ("flag =
4580 1").
4581 idealfactor"(nf,x)"
4583 factors into prime ideal powers the ideal "x" in the number field "nf".
4584 The output format is similar to the "factor" function, and the prime
4585 ideals are represented in the form output by the "idealprimedec"
4586 function, i.e. as 5-element vectors.
4587 The library syntax is idealfactor"(nf,x)".
4589 idealhnf"(nf,a,{b})"
4591 gives the Hermite normal form matrix of the ideal "a". The ideal can be
4592 given in any form whatsoever (typically by an algebraic number if it is
4593 principal, by a "Z_K"-system of generators, as a prime ideal as given
4594 by "idealprimedec", or by a Z-basis).
4595 If "b" is not omitted, assume the ideal given was "aZ_K+bZ_K", where
4597 "a" and "b" are elements of "K" given either as vectors on the integral
4598 basis "nf[7]" or as algebraic numbers.
4599 The library syntax is idealhnf0"(nf,a,b)" where an omitted "b" is coded
4601 as "NULL". Also available is " idealhermite(nf,a)" ("b" omitted).
4602 idealintersect"(nf,A,B)"
4604 intersection of the two ideals "A" and "B" in the number field "nf".
4605 The result is given in HNF.
4606 ? nf = nfinit(x^2+1);
4608 ? idealintersect(nf, 2, x+1)
4609 %2 =
4610 [2 0]
4611 [0 2]
4613 This function does not apply to general Z-modules, e.g. orders, since
4615 its arguments are replaced by the ideals they generate. The following
4616 script intersects Z-modules "A" and "B" given by matrices of compatible
4617 dimensions with integer coefficients:
4618 ZM_intersect(A,B) =
4620 { local( Ker = matkerint(concat(A,B)) );
4621 mathnf(A * vecextract(Ker, Str("..", #A), ".."))
4622 }
4623 The library syntax is idealintersect"(nf,A,B)".
4625 idealinv"(nf,x)"
4627 inverse of the ideal "x" in the number field "nf". The result is the
4628 Hermite normal form of the inverse of the ideal, together with the
4629 opposite of the Archimedean information if it is given.
4630 The library syntax is idealinv"(nf,x)".
4632 ideallist"(nf,bound,{flag = 4})"
4634 computes the list of all ideals of norm less or equal to bound in the
4635 number field nf. The result is a row vector with exactly bound
4636 components. Each component is itself a row vector containing the
4637 information about ideals of a given norm, in no specific order,
4638 depending on the value of "flag":
4639 The possible values of "flag" are:
4641 0: give the bid associated to the ideals, without generators.
4643 1: as 0, but include the generators in the bid.
4645 2: in this case, nf must be a bnf with units. Each component is of
4647 the form "[bid,U]", where bid is as case 0 and "U" is a vector of
4648 discrete logarithms of the units. More precisely, it gives the
4649 "ideallog"s with respect to bid of "bnf.tufu". This structure is
4650 technical, and only meant to be used in conjunction with
4651 "bnrclassnolist" or "bnrdisclist".
4652 3: as 2, but include the generators in the bid.
4654 4: give only the HNF of the ideal.
4656 ? nf = nfinit(x^2+1);
4658 ? L = ideallist(nf, 100);
4659 ? L[1]
4660 %3 = [[1, 0; 0, 1]] \\ A single ideal of norm 1
4661 ? #L[65]
4662 %4 = 4 \\ There are 4 ideals of norm 4 in Z[i]
4663 If one wants more information, one could do instead:
4665 ? nf = nfinit(x^2+1);
4667 ? L = ideallist(nf, 100, 0);
4668 ? l = L[25]; vector(#l, i, l[i].clgp)
4669 %3 = [[20, [20]], [16, [4, 4]], [20, [20]]]
4670 ? l[1].mod
4671 %4 = [[25, 18; 0, 1], []]
4672 ? l[2].mod
4673 %5 = [[5, 0; 0, 5], []]
4674 ? l[3].mod
4675 %6 = [[25, 7; 0, 1], []]
4676 where we ask for the structures of the "(Z[i]/I)^*" for all three
4678 ideals of norm 25. In fact, for all moduli with finite part of norm 25
4679 and trivial archimedean part, as the last 3 commands show. See
4680 "ideallistarch" to treat general moduli.
4681 The library syntax is ideallist0"(nf,bound,flag)", where bound must be
4683 a C long integer. Also available is " ideallist(nf,bound)",
4684 corresponding to the case "flag = 4".
4685 ideallistarch"(nf,list,arch)"
4687 list is a vector of vectors of bid's, as output by "ideallist" with
4688 flag 0 to 3. Return a vector of vectors with the same number of
4689 components as the original list. The leaves give information about
4690 moduli whose finite part is as in original list, in the same order, and
4691 archimedean part is now arch (it was originally trivial). The
4692 information contained is of the same kind as was present in the input;
4693 see "ideallist", in particular the meaning of flag.
4694 ? bnf = bnfinit(x^2-2);
4696 ? bnf.sign
4697 %2 = [2, 0] \\ two places at infinity
4698 ? L = ideallist(bnf, 100, 0);
4699 ? l = L[98]; vector(#l, i, l[i].clgp)
4700 %4 = [[42, [42]], [36, [6, 6]], [42, [42]]]
4701 ? La = ideallistarch(bnf, L, [1,1]); \\ add them to the modulus
4702 ? l = La[98]; vector(#l, i, l[i].clgp)
4703 %6 = [[168, [42, 2, 2]], [144, [6, 6, 2, 2]], [168, [42, 2, 2]]]
4704 Of course, the results above are obvious: adding "t" places at infinity
4706 will add "t" copies of "Z/2Z" to the ray class group. The following
4707 application is more typical:
4708 ? L = ideallist(bnf, 100, 2); \\ units are required now
4710 ? La = ideallistarch(bnf, L, [1,1]);
4711 ? H = bnrclassnolist(bnf, La);
4712 ? H[98];
4713 %6 = [2, 12, 2]
4714 The library syntax is ideallistarch"(nf,list,arch)".
4716 ideallog"(nf,x,bid)"
4718 "nf" is a number field, bid a ``big ideal'' as output by "idealstar"
4719 and "x" a non-necessarily integral element of nf which must have
4720 valuation equal to 0 at all prime ideals dividing "I = bid[1]". This
4721 function computes the ``discrete logarithm'' of "x" on the generators
4722 given in "bid[2]". In other words, if "g_i" are these generators, of
4723 orders "d_i" respectively, the result is a column vector of integers
4724 "(x_i)" such that "0 <= x_i < d_i" and
4725 "x = prod_ig_i^{x_i} (mod ^*I) ."
4727 Note that when "I" is a module, this implies also sign conditions on
4729 the embeddings.
4730 The library syntax is zideallog"(nf,x,bid)".
4732 idealmin"(nf,x,{vdir})"
4734 computes a minimum of the ideal "x" in the direction vdir in the number
4735 field nf.
4736 The library syntax is minideal"(nf,x,vdir,prec)", where an omitted vdir
4738 is coded as "NULL".
4739 idealmul"(nf,x,y,{flag = 0})"
4741 ideal multiplication of the ideals "x" and "y" in the number field nf.
4742 The result is a generating set for the ideal product with at most "n"
4743 elements, and is in Hermite normal form if either "x" or "y" is in HNF
4744 or is a prime ideal as output by "idealprimedec", and this is given
4745 together with the sum of the Archimedean information in "x" and "y" if
4746 both are given.
4747 If "flag" is non-zero, reduce the result using "idealred".
4749 The library syntax is idealmul"(nf,x,y)" ("flag = 0") or "
4751 idealmulred(nf,x,y,prec)" ("flag ! = 0"), where as usual, "prec" is a C
4752 long integer representing the precision.
4753 idealnorm"(nf,x)"
4755 computes the norm of the ideal "x" in the number field "nf".
4756 The library syntax is idealnorm"(nf, x)".
4758 idealpow"(nf,x,k,{flag = 0})"
4760 computes the "k"-th power of the ideal "x" in the number field "nf".
4761 "k" can be positive, negative or zero. The result is NOT reduced, it is
4762 really the "k"-th ideal power, and is given in HNF.
4763 If "flag" is non-zero, reduce the result using "idealred". Note however
4765 that this is NOT the same as as "idealpow(nf,x,k)" followed by
4766 reduction, since the reduction is performed throughout the powering
4767 process.
4768 The library syntax corresponding to "flag = 0" is " idealpow(nf,x,k)".
4770 If "k" is a "long", you can use " idealpows(nf,x,k)". Corresponding to
4771 "flag = 1" is " idealpowred(nf,vp,k,prec)", where "prec" is a "long".
4772 idealprimedec"(nf,p)"
4774 computes the prime ideal decomposition of the prime number "p" in the
4775 number field "nf". "p" must be a (positive) prime number. Note that the
4776 fact that "p" is prime is not checked, so if a non-prime "p" is given
4777 the result is undefined.
4778 The result is a vector of pr structures, each representing one of the
4780 prime ideals above "p" in the number field "nf". The representation "P
4781 = [p,a,e,f,b]" of a prime ideal means the following. The prime ideal is
4782 equal to "pZ_K+alphaZ_K" where "Z_K" is the ring of integers of the
4783 field and "alpha = sum_i a_iomega_i" where the "omega_i" form the
4784 integral basis "nf.zk", "e" is the ramification index, "f" is the
4785 residual index, and "b" represents a "beta belongs to Z_K" such that
4786 "P^{-1} = Z_K+beta/pZ_K" which will be useful for computing valuations,
4787 but which the user can ignore. The number "alpha" is guaranteed to have
4788 a valuation equal to 1 at the prime ideal (this is automatic if "e >
4789 1").
4790 The components of "P" should be accessed by member functions: "P.p",
4792 "P.e", "P.f", and "P.gen" (returns the vector "[p,a]").
4793 The library syntax is primedec"(nf,p)".
4795 idealprincipal"(nf,x)"
4797 creates the principal ideal generated by the algebraic number "x"
4798 (which must be of type integer, rational or polmod) in the number field
4799 "nf". The result is a one-column matrix.
4800 The library syntax is principalideal"(nf,x)".
4802 idealred"(nf,I,{vdir = 0})"
4804 LLL reduction of the ideal "I" in the number field nf, along the
4805 direction vdir. If vdir is present, it must be an "r1+r2"-component
4806 vector ("r1" and "r2" number of real and complex places of nf as
4807 usual).
4808 This function finds a ``small'' "a" in "I" (it is an LLL pseudo-minimum
4810 along direction vdir). The result is the Hermite normal form of the
4811 LLL-reduced ideal "r I/a", where "r" is a rational number such that the
4812 resulting ideal is integral and primitive. This is often, but not
4813 always, a reduced ideal in the sense of Buchmann. If "I" is an idele,
4814 the logarithmic embeddings of "a" are subtracted to the Archimedean
4815 part.
4816 More often than not, a principal ideal will yield the identity matrix.
4818 This is a quick and dirty way to check if ideals are principal without
4819 computing a full "bnf" structure, but it's not a necessary condition;
4820 hence, a non-trivial result doesn't prove the ideal is non-trivial in
4821 the class group.
4822 Note that this is \emph{not} the same as the LLL reduction of the
4824 lattice "I" since ideal operations are involved.
4825 The library syntax is ideallllred"(nf,x,vdir,prec)", where an omitted
4827 vdir is coded as "NULL".
4828 idealstar"(nf,I,{flag = 1})"
4830 outputs a bid structure, necessary for computing in the finite abelian
4831 group "G = (Z_K/I)^*". Here, nf is a number field and "I" is a modulus:
4832 either an ideal in any form, or a row vector whose first component is
4833 an ideal and whose second component is a row vector of "r_1" 0 or 1.
4834 This bid is used in "ideallog" to compute discrete logarithms. It also
4836 contains useful information which can be conveniently retrieved as
4837 "bid.mod" (the modulus), "bid.clgp" ("G" as a finite abelian group),
4838 "bid.no" (the cardinality of "G"), "bid.cyc" (elementary divisors) and
4839 "bid.gen" (generators).
4840 If "flag = 1" (default), the result is a bid structure without
4842 generators.
4843 If "flag = 2", as "flag = 1", but including generators, which wastes
4845 some time.
4846 If "flag = 0", \emph{deprecated}. Only outputs "(Z_K/I)^*" as an
4848 abelian group, i.e as a 3-component vector "[h,d,g]": "h" is the order,
4849 "d" is the vector of SNF cyclic components and "g" the corresponding
4850 generators. This flag is deprecated: it is in fact slightly faster to
4851 compute a true bid structure, which contains much more information.
4852 The library syntax is idealstar0"(nf,I,flag)".
4854 idealtwoelt"(nf,x,{a})"
4856 computes a two-element representation of the ideal "x" in the number
4857 field "nf", using a straightforward (exponential time) search. "x" can
4858 be an ideal in any form, (including perhaps an Archimedean part, which
4859 is ignored) and the result is a row vector "[a,alpha]" with two
4860 components such that "x = aZ_K+alphaZ_K" and "a belongs to Z", where
4861 "a" is the one passed as argument if any. If "x" is given by at least
4862 two generators, "a" is chosen to be the positive generator of "x cap
4863 Z".
4864 Note that when an explicit "a" is given, we use an asymptotically
4866 faster method, however in practice it is usually slower.
4867 The library syntax is ideal_two_elt0"(nf,x,a)", where an omitted "a" is
4869 entered as "NULL".
4870 idealval"(nf,x,vp)"
4872 gives the valuation of the ideal "x" at the prime ideal vp in the
4873 number field "nf", where vp must be a 5-component vector as given by
4874 "idealprimedec".
4875 The library syntax is idealval"(nf,x,vp)", and the result is a "long"
4877 integer.
4878 ideleprincipal"(nf,x)"
4880 creates the principal idele generated by the algebraic number "x"
4881 (which must be of type integer, rational or polmod) in the number field
4882 "nf". The result is a two-component vector, the first being a one-
4883 column matrix representing the corresponding principal ideal, and the
4884 second being the vector with "r_1+r_2" components giving the complex
4885 logarithmic embedding of "x".
4886 The library syntax is principalidele"(nf,x)".
4888 matalgtobasis"(nf,x)"
4890 "nf" being a number field in "nfinit" format, and "x" a matrix whose
4891 coefficients are expressed as polmods in "nf", transforms this matrix
4892 into a matrix whose coefficients are expressed on the integral basis of
4893 "nf". This is the same as applying "nfalgtobasis" to each entry, but it
4894 would be dangerous to use the same name.
4895 The library syntax is matalgtobasis"(nf,x)".
4897 matbasistoalg"(nf,x)"
4899 "nf" being a number field in "nfinit" format, and "x" a matrix whose
4900 coefficients are expressed as column vectors on the integral basis of
4901 "nf", transforms this matrix into a matrix whose coefficients are
4902 algebraic numbers expressed as polmods. This is the same as applying
4903 "nfbasistoalg" to each entry, but it would be dangerous to use the same
4904 name.
4905 The library syntax is matbasistoalg"(nf,x)".
4907 modreverse"(a)"
4909 "a" being a polmod A(X) modulo T(X), finds the ``reverse polmod'' B(X)
4910 modulo Q(X), where "Q" is the minimal polynomial of "a", which must be
4911 equal to the degree of "T", and such that if "theta" is a root of "T"
4912 then "theta = B(alpha)" for a certain root "alpha" of "Q".
4913 This is very useful when one changes the generating element in
4915 algebraic extensions.
4916 The library syntax is polmodrecip"(x)".
4918 newtonpoly"(x,p)"
4920 gives the vector of the slopes of the Newton polygon of the polynomial
4921 "x" with respect to the prime number "p". The "n" components of the
4922 vector are in decreasing order, where "n" is equal to the degree of
4923 "x". Vertical slopes occur iff the constant coefficient of "x" is zero
4924 and are denoted by "VERYBIGINT", the biggest single precision integer
4925 representable on the machine ("2^{31}-1" (resp. "2^{63}-1") on 32-bit
4926 (resp. 64-bit) machines), see "Label se:valuation".
4927 The library syntax is newtonpoly"(x,p)".
4929 nfalgtobasis"(nf,x)"
4931 this is the inverse function of "nfbasistoalg". Given an object "x"
4932 whose entries are expressed as algebraic numbers in the number field
4933 "nf", transforms it so that the entries are expressed as a column
4934 vector on the integral basis "nf.zk".
4935 The library syntax is algtobasis"(nf,x)".
4937 nfbasis"(x,{flag = 0},{fa})"
4939 integral basis of the number field defined by the irreducible,
4940 preferably monic, polynomial "x", using a modified version of the round
4941 4 algorithm by default, due to David Ford, Sebastian Pauli and Xavier
4942 Roblot. The binary digits of "flag" have the following meaning:
4943 1: assume that no square of a prime greater than the default
4945 "primelimit" divides the discriminant of "x", i.e. that the index of
4946 "x" has only small prime divisors.
4947 2: use round 2 algorithm. For small degrees and coefficient size, this
4949 is sometimes a little faster. (This program is the translation into C
4950 of a program written by David Ford in Algeb.)
4951 Thus for instance, if "flag = 3", this uses the round 2 algorithm and
4953 outputs an order which will be maximal at all the small primes.
4954 If fa is present, we assume (without checking!) that it is the two-
4956 column matrix of the factorization of the discriminant of the
4957 polynomial "x". Note that it does \emph{not} have to be a complete
4958 factorization. This is especially useful if only a local integral basis
4959 for some small set of places is desired: only factors with exponents
4960 greater or equal to 2 will be considered.
4961 The library syntax is nfbasis0"(x,flag,fa)". An extended version is "
4963 nfbasis(x,&d,flag,fa)", where "d" receives the discriminant of the
4964 number field (\emph{not} of the polynomial "x"), and an omitted fa is
4965 input as "NULL". Also available are " base(x,&d)" ("flag = 0"), "
4966 base2(x,&d)" ("flag = 2") and " factoredbase(x,fa,&d)".
4967 nfbasistoalg"(nf,x)"
4969 this is the inverse function of "nfalgtobasis". Given an object "x"
4970 whose entries are expressed on the integral basis "nf.zk", transforms
4971 it into an object whose entries are algebraic numbers (i.e. polmods).
4972 The library syntax is basistoalg"(nf,x)".
4974 nfdetint"(nf,x)"
4976 given a pseudo-matrix "x", computes a non-zero ideal contained in
4977 (i.e. multiple of) the determinant of "x". This is particularly useful
4978 in conjunction with "nfhnfmod".
4979 The library syntax is nfdetint"(nf,x)".
4981 nfdisc"(x,{flag = 0},{fa})"
4983 field discriminant of the number field defined by the integral,
4984 preferably monic, irreducible polynomial "x". "flag" and "fa" are
4985 exactly as in "nfbasis". That is, "fa" provides the matrix of a partial
4986 factorization of the discriminant of "x", and binary digits of "flag"
4987 are as follows:
4988 1: assume that no square of a prime greater than "primelimit" divides
4990 the discriminant.
4991 2: use the round 2 algorithm, instead of the default round 4. This
4993 should be slower except maybe for polynomials of small degree and
4994 coefficients.
4995 The library syntax is nfdiscf0"(x,flag,fa)" where an omitted "fa" is
4997 input as "NULL". You can also use " discf(x)" ("flag = 0").
4998 nfeltdiv"(nf,x,y)"
5000 given two elements "x" and "y" in nf, computes their quotient "x/y" in
5001 the number field "nf".
5002 The library syntax is element_div"(nf,x,y)".
5004 nfeltdiveuc"(nf,x,y)"
5006 given two elements "x" and "y" in nf, computes an algebraic integer "q"
5007 in the number field "nf" such that the components of "x-qy" are
5008 reasonably small. In fact, this is functionally identical to
5009 "round(nfeltdiv(nf,x,y))".
5010 The library syntax is nfdiveuc"(nf,x,y)".
5012 nfeltdivmodpr"(nf,x,y,pr)"
5014 given two elements "x" and "y" in nf and pr a prime ideal in "modpr"
5015 format (see "nfmodprinit"), computes their quotient "x / y" modulo the
5016 prime ideal pr.
5017 The library syntax is element_divmodpr"(nf,x,y,pr)".
5019 nfeltdivrem"(nf,x,y)"
5021 given two elements "x" and "y" in nf, gives a two-element row vector
5022 "[q,r]" such that "x = qy+r", "q" is an algebraic integer in "nf", and
5023 the components of "r" are reasonably small.
5024 The library syntax is nfdivrem"(nf,x,y)".
5026 nfeltmod"(nf,x,y)"
5028 given two elements "x" and "y" in nf, computes an element "r" of "nf"
5029 of the form "r = x-qy" with "q" and algebraic integer, and such that
5030 "r" is small. This is functionally identical to
5031 "x - nfeltmul(nf,round(nfeltdiv(nf,x,y)),y)."
5033 The library syntax is nfmod"(nf,x,y)".
5035 nfeltmul"(nf,x,y)"
5037 given two elements "x" and "y" in nf, computes their product "x*y" in
5038 the number field "nf".
5039 The library syntax is element_mul"(nf,x,y)".
5041 nfeltmulmodpr"(nf,x,y,pr)"
5043 given two elements "x" and "y" in nf and pr a prime ideal in "modpr"
5044 format (see "nfmodprinit"), computes their product "x*y" modulo the
5045 prime ideal pr.
5046 The library syntax is element_mulmodpr"(nf,x,y,pr)".
5048 nfeltpow"(nf,x,k)"
5050 given an element "x" in nf, and a positive or negative integer "k",
5051 computes "x^k" in the number field "nf".
5052 The library syntax is element_pow"(nf,x,k)".
5054 nfeltpowmodpr"(nf,x,k,pr)"
5056 given an element "x" in nf, an integer "k" and a prime ideal pr in
5057 "modpr" format (see "nfmodprinit"), computes "x^k" modulo the prime
5058 ideal pr.
5059 The library syntax is element_powmodpr"(nf,x,k,pr)".
5061 nfeltreduce"(nf,x,ideal)"
5063 given an ideal in Hermite normal form and an element "x" of the number
5064 field "nf", finds an element "r" in "nf" such that "x-r" belongs to the
5065 ideal and "r" is small.
5066 The library syntax is element_reduce"(nf,x,ideal)".
5068 nfeltreducemodpr"(nf,x,pr)"
5070 given an element "x" of the number field "nf" and a prime ideal pr in
5071 "modpr" format compute a canonical representative for the class of "x"
5072 modulo pr.
5073 The library syntax is nfreducemodpr"(nf,x,pr)".
5075 nfeltval"(nf,x,pr)"
5077 given an element "x" in nf and a prime ideal pr in the format output by
5078 "idealprimedec", computes their the valuation at pr of the element "x".
5079 The same result could be obtained using "idealval(nf,x,pr)" (since "x"
5080 would then be converted to a principal ideal), but it would be less
5081 efficient.
5082 The library syntax is element_val"(nf,x,pr)", and the result is a
5084 "long".
5085 nffactor"(nf,x)"
5087 factorization of the univariate polynomial "x" over the number field
5088 "nf" given by "nfinit". "x" has coefficients in "nf" (i.e. either
5089 scalar, polmod, polynomial or column vector). The main variable of "nf"
5090 must be of \emph{lower} priority than that of "x" (see "Label
5091 se:priority"). However if the polynomial defining the number field
5092 occurs explicitly in the coefficients of "x" (as modulus of a
5093 "t_POLMOD"), its main variable must be \emph{the same} as the main
5094 variable of "x". For example,
5095 ? nf = nfinit(y^2 + 1);
5097 ? nffactor(nf, x^2 + y); \\ OK
5098 ? nffactor(nf, x^2 + Mod(y, y^2+1)); \\ OK
5099 ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ WRONG
5100 The library syntax is nffactor"(nf,x)".
5102 nffactormod"(nf,x,pr)"
5104 factorization of the univariate polynomial "x" modulo the prime ideal
5105 pr in the number field "nf". "x" can have coefficients in the number
5106 field (scalar, polmod, polynomial, column vector) or modulo the prime
5107 ideal (intmod modulo the rational prime under pr, polmod or polynomial
5108 with intmod coefficients, column vector of intmod). The prime ideal pr
5109 \emph{must} be in the format output by "idealprimedec". The main
5110 variable of "nf" must be of lower priority than that of "x" (see "Label
5111 se:priority"). However if the coefficients of the number field occur
5112 explicitly (as polmods) as coefficients of "x", the variable of these
5113 polmods \emph{must} be the same as the main variable of "t" (see
5114 "nffactor").
5115 The library syntax is nffactormod"(nf,x,pr)".
5117 nfgaloisapply"(nf,aut,x)"
5119 "nf" being a number field as output by "nfinit", and aut being a Galois
5120 automorphism of "nf" expressed either as a polynomial or a polmod (such
5121 automorphisms being found using for example one of the variants of
5122 "nfgaloisconj"), computes the action of the automorphism aut on the
5123 object "x" in the number field. "x" can be an element (scalar, polmod,
5124 polynomial or column vector) of the number field, an ideal (either
5125 given by "Z_K"-generators or by a Z-basis), a prime ideal (given as a
5126 5-element row vector) or an idele (given as a 2-element row vector).
5127 Because of possible confusion with elements and ideals, other vector or
5128 matrix arguments are forbidden.
5129 The library syntax is galoisapply"(nf,aut,x)".
5131 nfgaloisconj"(nf,{flag = 0},{d})"
5133 "nf" being a number field as output by "nfinit", computes the
5134 conjugates of a root "r" of the non-constant polynomial "x = nf[1]"
5135 expressed as polynomials in "r". This can be used even if the number
5136 field "nf" is not Galois since some conjugates may lie in the field.
5137 "nf" can simply be a polynomial if "flag ! = 1".
5139 If no flags or "flag = 0", if "nf" is a number field use a combination
5141 of flag 4 and 1 and the result is always complete, else use a
5142 combination of flag 4 and 2 and the result is subject to the
5143 restriction of "flag = 2", but a warning is issued when it is not
5144 proven complete.
5145 If "flag = 1", use "nfroots" (require a number field).
5147 If "flag = 2", use complex approximations to the roots and an integral
5149 LLL. The result is not guaranteed to be complete: some conjugates may
5150 be missing (no warning issued), especially so if the corresponding
5151 polynomial has a huge index. In that case, increasing the default
5152 precision may help.
5153 If "flag = 4", use Allombert's algorithm and permutation testing. If
5155 the field is Galois with ``weakly'' super solvable Galois group, return
5156 the complete list of automorphisms, else only the identity element. If
5157 present, "d" is assumed to be a multiple of the least common
5158 denominator of the conjugates expressed as polynomial in a root of pol.
5159 A group G is ``weakly'' super solvable (WKSS) if it contains a super
5161 solvable normal subgroup "H" such that "G = H" , or "G/H ~ A_4" , or
5162 "G/H ~ S_4". Abelian and nilpotent groups are WKSS. In practice,
5163 almost all groups of small order are WKSS, the exceptions having order
5164 36(1 exception), 48(2), 56(1), 60(1), 72(5), 75(1), 80(1), 96(10) and "
5165 >= 108".
5166 Hence "flag = 4" permits to quickly check whether a polynomial of order
5168 strictly less than 36 is Galois or not. This method is much faster than
5169 "nfroots" and can be applied to polynomials of degree larger than 50.
5170 This routine can only compute Q-automorphisms, but it may be used to
5172 get "K"-automorphism for any base field "K" as follows:
5173 rnfgaloisconj(nfK, R) = \\ K-automorphisms of L = K[X] / (R)
5175 { local(polabs, N, H);
5176 R *= Mod(1, nfK.pol); \\ convert coeffs to polmod elts of K
5177 polabs = rnfequation(nfK, R);
5178 N = nfgaloisconj(polabs) % R; \\ Q-automorphisms of L
5179 H = [];
5180 for(i=1, #N, \\ select the ones that fix K
5181 if (subst(R, variable(R), Mod(N[i],R)) == 0,
5182 H = concat(H,N[i])
5183 )
5184 ); H
5185 }
5186 K = nfinit(y^2 + 7);
5187 polL = x^4 - y*x^3 - 3*x^2 + y*x + 1;
5188 rnfgaloisconj(K, polL) \\ K-automorphisms of L
5189 The library syntax is galoisconj0"(nf,flag,d,prec)". Also available are
5191 " galoisconj(nf)" for "flag = 0", " galoisconj2(nf,n,prec)" for "flag =
5192 2" where "n" is a bound on the number of conjugates, and "
5193 galoisconj4(nf,d)" corresponding to "flag = 4".
5194 nfhilbert"(nf,a,b,{pr})"
5196 if pr is omitted, compute the global Hilbert symbol "(a,b)" in "nf",
5197 that is 1 if "x^2 - a y^2 - b z^2" has a non trivial solution "(x,y,z)"
5198 in "nf", and "-1" otherwise. Otherwise compute the local symbol modulo
5199 the prime ideal pr (as output by "idealprimedec").
5200 The library syntax is nfhilbert"(nf,a,b,pr)", where an omitted pr is
5202 coded as "NULL".
5203 nfhnf"(nf,x)"
5205 given a pseudo-matrix "(A,I)", finds a pseudo-basis in Hermite normal
5206 form of the module it generates.
5207 The library syntax is nfhermite"(nf,x)".
5209 nfhnfmod"(nf,x,detx)"
5211 given a pseudo-matrix "(A,I)" and an ideal detx which is contained in
5212 (read integral multiple of) the determinant of "(A,I)", finds a pseudo-
5213 basis in Hermite normal form of the module generated by "(A,I)". This
5214 avoids coefficient explosion. detx can be computed using the function
5215 "nfdetint".
5216 The library syntax is nfhermitemod"(nf,x,detx)".
5218 nfinit"(pol,{flag = 0})"
5220 pol being a non-constant, preferably monic, irreducible polynomial in
5221 "Z[X]", initializes a \emph{number field} structure ("nf") associated
5222 to the field "K" defined by pol. As such, it's a technical object
5223 passed as the first argument to most "nf"xxx functions, but it contains
5224 some information which may be directly useful. Access to this
5225 information via \emph{member functions} is preferred since the specific
5226 data organization specified below may change in the future. Currently,
5227 "nf" is a row vector with 9 components:
5228 "nf[1]" contains the polynomial pol ("nf.pol").
5230 "nf[2]" contains "[r1,r2]" ("nf.sign", "nf.r1", "nf.r2"), the number of
5232 real and complex places of "K".
5233 "nf[3]" contains the discriminant d(K) ("nf.disc") of "K".
5235 "nf[4]" contains the index of "nf[1]" ("nf.index"), i.e. "[Z_K :
5237 Z[theta]]", where "theta" is any root of "nf[1]".
5238 "nf[5]" is a vector containing 7 matrices "M", "G", "T2", "T", "MD",
5240 "TI", "MDI" useful for certain computations in the number field "K".
5241 \item "M" is the "(r1+r2) x n" matrix whose columns represent the
5243 numerical values of the conjugates of the elements of the integral
5244 basis.
5245 \item "G" is such that "T2 = ^t G G", where "T2" is the quadratic
5247 form "T_2(x) = sum |sigma(x)|^2", "sigma" running over the embeddings
5248 of "K" into C.
5249 \item The "T2" component is deprecated and currently unused.
5251 \item "T" is the "n x n" matrix whose coefficients are
5253 "Tr(omega_iomega_j)" where the "omega_i" are the elements of the
5254 integral basis. Note also that " det (T)" is equal to the discriminant
5255 of the field "K".
5256 \item The columns of "MD" ("nf.diff") express a Z-basis of the
5258 different of "K" on the integral basis.
5259 \item "TI" is equal to "d(K)T^{-1}", which has integral coefficients.
5261 Note that, understood as as ideal, the matrix "T^{-1}" generates the
5262 codifferent ideal.
5263 \item Finally, "MDI" is a two-element representation (for faster
5265 ideal product) of d(K) times the codifferent ideal
5266 ("nf.disc*nf.codiff", which is an integral ideal). "MDI" is only used
5267 in "idealinv".
5268 "nf[6]" is the vector containing the "r1+r2" roots ("nf.roots") of
5270 "nf[1]" corresponding to the "r1+r2" embeddings of the number field
5271 into C (the first "r1" components are real, the next "r2" have positive
5272 imaginary part).
5273 "nf[7]" is an integral basis for "Z_K" ("nf.zk") expressed on the
5275 powers of "theta". Its first element is guaranteed to be 1. This basis
5276 is LLL-reduced with respect to "T_2" (strictly speaking, it is a
5277 permutation of such a basis, due to the condition that the first
5278 element be 1).
5279 "nf[8]" is the "n x n" integral matrix expressing the power basis in
5281 terms of the integral basis, and finally
5282 "nf[9]" is the "n x n^2" matrix giving the multiplication table of the
5284 integral basis.
5285 If a non monic polynomial is input, "nfinit" will transform it into a
5287 monic one, then reduce it (see "flag = 3"). It is allowed, though not
5288 very useful given the existence of "nfnewprec", to input a "nf" or a
5289 "bnf" instead of a polynomial.
5290 ? nf = nfinit(x^3 - 12); \\ initialize number field Q[X] / (X^3 - 12)
5292 ? nf.pol \\ defining polynomial
5293 %2 = x^3 - 12
5294 ? nf.disc \\ field discriminant
5295 %3 = -972
5296 ? nf.index \\ index of power basis order in maximal order
5297 %4 = 2
5298 ? nf.zk \\ integer basis, lifted to Q[X]
5299 %5 = [1, x, 1/2*x^2]
5300 ? nf.sign \\ signature
5301 %6 = [1, 1]
5302 ? factor(abs(nf.disc )) \\ determines ramified primes
5303 %7 =
5304 [2 2]
5305 [3 5]
5307 ? idealfactor(nf, 2)
5308 %8 =
5309 [[2, [0, 0, -1]~, 3, 1, [0, 1, 0]~] 3] \\ \goth{P}_2^3
5310 In case pol has a huge discriminant which is difficult to factor, the
5312 special input format "[pol,B]" is also accepted where pol is a
5313 polynomial as above and "B" is the integer basis, as would be computed
5314 by "nfbasis". This is useful if the integer basis is known in advance,
5315 or was computed conditionnally.
5316 ? pol = polcompositum(x^5 - 101, polcyclo(7))[1];
5318 ? B = nfbasis(pol, 1); \\ faster than nfbasis(pol), but conditional
5319 ? nf = nfinit( [pol, B] );
5320 ? factor( abs(nf.disc) )
5321 [5 18]
5322 [7 25]
5324 [101 24]
5326 "B" is conditional when its discriminant, which is "nf.disc", can't be
5328 factored. In this example, the above factorization proves the
5329 correctness of the computation.
5330 If "flag = 2": pol is changed into another polynomial "P" defining the
5332 same number field, which is as simple as can easily be found using the
5333 "polred" algorithm, and all the subsequent computations are done using
5334 this new polynomial. In particular, the first component of the result
5335 is the modified polynomial.
5336 If "flag = 3", does a "polred" as in case 2, but outputs
5338 "[nf,Mod(a,P)]", where "nf" is as before and "Mod(a,P) = Mod(x,pol)"
5339 gives the change of variables. This is implicit when pol is not monic:
5340 first a linear change of variables is performed, to get a monic
5341 polynomial, then a "polred" reduction.
5342 If "flag = 4", as 2 but uses a partial "polred".
5344 If "flag = 5", as 3 using a partial "polred".
5346 The library syntax is nfinit0"(x,flag,prec)".
5348 nfisideal"(nf,x)"
5350 returns 1 if "x" is an ideal in the number field "nf", 0 otherwise.
5351 The library syntax is isideal"(x)".
5353 nfisincl"(x,y)"
5355 tests whether the number field "K" defined by the polynomial "x" is
5356 conjugate to a subfield of the field "L" defined by "y" (where "x" and
5357 "y" must be in "Q[X]"). If they are not, the output is the number 0. If
5358 they are, the output is a vector of polynomials, each polynomial "a"
5359 representing an embedding of "K" into "L", i.e. being such that "y | x
5360 o a".
5361 If "y" is a number field (nf), a much faster algorithm is used
5363 (factoring "x" over "y" using "nffactor"). Before version 2.0.14, this
5364 wasn't guaranteed to return all the embeddings, hence was triggered by
5365 a special flag. This is no more the case.
5366 The library syntax is nfisincl"(x,y,flag)".
5368 nfisisom"(x,y)"
5370 as "nfisincl", but tests for isomorphism. If either "x" or "y" is a
5371 number field, a much faster algorithm will be used.
5372 The library syntax is nfisisom"(x,y,flag)".
5374 nfnewprec"(nf)"
5376 transforms the number field "nf" into the corresponding data using
5377 current (usually larger) precision. This function works as expected if
5378 "nf" is in fact a "bnf" (update "bnf" to current precision) but may be
5379 quite slow (many generators of principal ideals have to be computed).
5380 The library syntax is nfnewprec"(nf,prec)".
5382 nfkermodpr"(nf,a,pr)"
5384 kernel of the matrix "a" in "Z_K/pr", where pr is in modpr format (see
5385 "nfmodprinit").
5386 The library syntax is nfkermodpr"(nf,a,pr)".
5388 nfmodprinit"(nf,pr)"
5390 transforms the prime ideal pr into "modpr" format necessary for all
5391 operations modulo pr in the number field nf.
5392 The library syntax is nfmodprinit"(nf,pr)".
5394 nfsubfields"(pol,{d = 0})"
5396 finds all subfields of degree "d" of the number field defined by the
5397 (monic, integral) polynomial pol (all subfields if "d" is null or
5398 omitted). The result is a vector of subfields, each being given by
5399 "[g,h]", where "g" is an absolute equation and "h" expresses one of the
5400 roots of "g" in terms of the root "x" of the polynomial defining "nf".
5401 This routine uses J. Klueners's algorithm in the general case, and
5402 B. Allombert's "galoissubfields" when nf is Galois (with weakly
5403 supersolvable Galois group).
5404 The library syntax is subfields"(nf,d)".
5406 nfroots"({nf},x)"
5408 roots of the polynomial "x" in the number field "nf" given by "nfinit"
5409 without multiplicity (in Q if "nf" is omitted). "x" has coefficients in
5410 the number field (scalar, polmod, polynomial, column vector). The main
5411 variable of "nf" must be of lower priority than that of "x" (see "Label
5412 se:priority"). However if the coefficients of the number field occur
5413 explicitly (as polmods) as coefficients of "x", the variable of these
5414 polmods \emph{must} be the same as the main variable of "t" (see
5415 "nffactor").
5416 The library syntax is nfroots"(nf,x)".
5418 nfrootsof1"(nf)"
5420 computes the number of roots of unity "w" and a primitive "w"-th root
5421 of unity (expressed on the integral basis) belonging to the number
5422 field "nf". The result is a two-component vector "[w,z]" where "z" is a
5423 column vector expressing a primitive "w"-th root of unity on the
5424 integral basis "nf.zk".
5425 The library syntax is rootsof1"(nf)".
5427 nfsnf"(nf,x)"
5429 given a torsion module "x" as a 3-component row vector "[A,I,J]" where
5430 "A" is a square invertible "n x n" matrix, "I" and "J" are two ideal
5431 lists, outputs an ideal list "d_1,...,d_n" which is the Smith normal
5432 form of "x". In other words, "x" is isomorphic to "Z_K/d_1 oplus ...
5433 oplus Z_K/d_n" and "d_i" divides "d_{i-1}" for "i >= 2". The link
5434 between "x" and "[A,I,J]" is as follows: if "e_i" is the canonical
5435 basis of "K^n", "I = [b_1,...,b_n]" and "J = [a_1,...,a_n]", then "x"
5436 is isomorphic to
5437 " (b_1e_1 oplus ... oplus b_ne_n) / (a_1A_1 oplus ... oplus a_nA_n)
5439 , "
5440 where the "A_j" are the columns of the matrix "A". Note that every
5442 finitely generated torsion module can be given in this way, and even
5443 with "b_i = Z_K" for all "i".
5444 The library syntax is nfsmith"(nf,x)".
5446 nfsolvemodpr"(nf,a,b,pr)"
5448 solution of "a.x = b" in "Z_K/pr", where "a" is a matrix and "b" a
5449 column vector, and where pr is in modpr format (see "nfmodprinit").
5450 The library syntax is nfsolvemodpr"(nf,a,b,pr)".
5452 polcompositum"(P,Q,{flag = 0})"
5454 "P" and "Q" being squarefree polynomials in "Z[X]" in the same
5455 variable, outputs the simple factors of the etale Q-algebra "A = Q(X,
5456 Y) / (P(X), Q(Y))". The factors are given by a list of polynomials "R"
5457 in "Z[X]", associated to the number field "Q(X)/ (R)", and sorted by
5458 increasing degree (with respect to lexicographic ordering for factors
5459 of equal degrees). Returns an error if one of the polynomials is not
5460 squarefree.
5461 Note that it is more efficient to reduce to the case where "P" and "Q"
5463 are irreducible first. The routine will not perform this for you, since
5464 it may be expensive, and the inputs are irreducible in most
5465 applications anyway. Assuming "P" is irreducible (of smaller degree
5466 than "Q" for efficiency), it is in general \emph{much} faster to
5467 proceed as follows
5468 nf = nfinit(P); L = nffactor(nf, Q)[,1];
5470 vector(#L, i, rnfequation(nf, L[i]))
5471 to obtain the same result. If you are only interested in the degrees of
5473 the simple factors, the "rnfequation" instruction can be replaced by a
5474 trivial "poldegree(P) * poldegree(L[i])".
5475 If "flag = 1", outputs a vector of 4-component vectors "[R,a,b,k]",
5477 where "R" ranges through the list of all possible compositums as above,
5478 and "a" (resp. "b") expresses the root of "P" (resp. "Q") as an element
5479 of "Q(X)/(R)". Finally, "k" is a small integer such that "b + ka = X"
5480 modulo "R".
5481 A compositum is quite often defined by a complicated polynomial, which
5483 it is advisable to reduce before further work. Here is a simple example
5484 involving the field "Q(zeta_5, 5^{1/5})":
5485 ? z = polcompositum(x^5 - 5, polcyclo(5), 1)[1];
5487 ? pol = z[1] \\ pol defines the compositum
5488 %2 = x^20 + 5*x^19 + 15*x^18 + 35*x^17 + 70*x^16 + 141*x^15 + 260*x^14 \
5489 + 355*x^13 + 95*x^12 - 1460*x^11 - 3279*x^10 - 3660*x^9 - 2005*x^8 \
5490 + 705*x^7 + 9210*x^6 + 13506*x^5 + 7145*x^4 - 2740*x^3 + 1040*x^2 \
5491 - 320*x + 256
5492 ? a = z[2]; a^5 - 5 \\ a is a fifth root of 5
5493 %3 = 0
5494 ? z = polredabs(pol, 1); \\ look for a simpler polynomial
5495 ? pol = z[1]
5496 %5 = x^20 + 25*x^10 + 5
5497 ? a = subst(a.pol, x, z[2]) \\ a in the new coordinates
5498 %6 = Mod(-5/22*x^19 + 1/22*x^14 - 123/22*x^9 + 9/11*x^4, x^20 + 25*x^10 + 5)
5499 The library syntax is polcompositum0"(P,Q,flag)".
5501 polgalois"(x)"
5503 Galois group of the non-constant polynomial "x belongs to Q[X]". In the
5504 present version 2.2.0, "x" must be irreducible and the degree of "x"
5505 must be less than or equal to 7. On certain versions for which the data
5506 file of Galois resolvents has been installed (available in the Unix
5507 distribution as a separate package), degrees 8, 9, 10 and 11 are also
5508 implemented.
5509 The output is a 4-component vector "[n,s,k,name]" with the following
5511 meaning: "n" is the cardinality of the group, "s" is its signature ("s
5512 = 1" if the group is a subgroup of the alternating group "A_n", "s =
5513 -1" otherwise) and name is a character string containing name of the
5514 transitive group according to the GAP 4 transitive groups library by
5515 Alexander Hulpke.
5516 "k" is more arbitrary and the choice made up to version 2.2.3 of PARI
5518 is rather unfortunate: for "n > 7", "k" is the numbering of the group
5519 among all transitive subgroups of "S_n", as given in ``The transitive
5520 groups of degree up to eleven'', G. Butler and J. McKay,
5521 \emph{Communications in Algebra}, vol. 11, 1983, pp. 863--911 (group
5522 "k" is denoted "T_k" there). And for "n <= 7", it was ad hoc, so as to
5523 ensure that a given triple would design a unique group. Specifically,
5524 for polynomials of degree " <= 7", the groups are coded as follows,
5525 using standard notations
5526 In degree 1: "S_1 = [1,1,1]".
5528 In degree 2: "S_2 = [2,-1,1]".
5530 In degree 3: "A_3 = C_3 = [3,1,1]", "S_3 = [6,-1,1]".
5532 In degree 4: "C_4 = [4,-1,1]", "V_4 = [4,1,1]", "D_4 = [8,-1,1]", "A_4
5534 = [12,1,1]", "S_4 = [24,-1,1]".
5535 In degree 5: "C_5 = [5,1,1]", "D_5 = [10,1,1]", "M_{20} = [20,-1,1]",
5537 "A_5 = [60,1,1]", "S_5 = [120,-1,1]".
5538 In degree 6: "C_6 = [6,-1,1]", "S_3 = [6,-1,2]", "D_6 = [12,-1,1]",
5540 "A_4 = [12,1,1]", "G_{18} = [18,-1,1]", "S_4^ -= [24,-1,1]", "A_4 x C_2
5541 = [24,-1,2]", "S_4^ += [24,1,1]", "G_{36}^ -= [36,-1,1]", "G_{36}^ +=
5542 [36,1,1]", "S_4 x C_2 = [48,-1,1]", "A_5 = PSL_2(5) = [60,1,1]",
5543 "G_{72} = [72,-1,1]", "S_5 = PGL_2(5) = [120,-1,1]", "A_6 = [360,1,1]",
5544 "S_6 = [720,-1,1]".
5545 In degree 7: "C_7 = [7,1,1]", "D_7 = [14,-1,1]", "M_{21} = [21,1,1]",
5547 "M_{42} = [42,-1,1]", "PSL_2(7) = PSL_3(2) = [168,1,1]", "A_7 =
5548 [2520,1,1]", "S_7 = [5040,-1,1]".
5549 This is deprecated and obsolete, but for reasons of backward
5551 compatibility, we cannot change this behaviour yet. So you can use the
5552 default "new_galois_format" to switch to a consistent naming scheme,
5553 namely "k" is always the standard numbering of the group among all
5554 transitive subgroups of "S_n". If this default is in effect, the above
5555 groups will be coded as:
5556 In degree 1: "S_1 = [1,1,1]".
5558 In degree 2: "S_2 = [2,-1,1]".
5560 In degree 3: "A_3 = C_3 = [3,1,1]", "S_3 = [6,-1,2]".
5562 In degree 4: "C_4 = [4,-1,1]", "V_4 = [4,1,2]", "D_4 = [8,-1,3]", "A_4
5564 = [12,1,4]", "S_4 = [24,-1,5]".
5565 In degree 5: "C_5 = [5,1,1]", "D_5 = [10,1,2]", "M_{20} = [20,-1,3]",
5567 "A_5 = [60,1,4]", "S_5 = [120,-1,5]".
5568 In degree 6: "C_6 = [6,-1,1]", "S_3 = [6,-1,2]", "D_6 = [12,-1,3]",
5570 "A_4 = [12,1,4]", "G_{18} = [18,-1,5]", "A_4 x C_2 = [24,-1,6]", "S_4^
5571 += [24,1,7]", "S_4^ -= [24,-1,8]", "G_{36}^ -= [36,-1,9]", "G_{36}^ +=
5572 [36,1,10]", "S_4 x C_2 = [48,-1,11]", "A_5 = PSL_2(5) = [60,1,12]",
5573 "G_{72} = [72,-1,13]", "S_5 = PGL_2(5) = [120,-1,14]", "A_6 =
5574 [360,1,15]", "S_6 = [720,-1,16]".
5575 In degree 7: "C_7 = [7,1,1]", "D_7 = [14,-1,2]", "M_{21} = [21,1,3]",
5577 "M_{42} = [42,-1,4]", "PSL_2(7) = PSL_3(2) = [168,1,5]", "A_7 =
5578 [2520,1,6]", "S_7 = [5040,-1,7]".
5579 Warning: The method used is that of resolvent polynomials and is
5581 sensitive to the current precision. The precision is updated internally
5582 but, in very rare cases, a wrong result may be returned if the initial
5583 precision was not sufficient.
5584 The library syntax is polgalois"(x,prec)". To enable the new format in
5586 library mode, set the global variable "new_galois_format" to 1.
5587 polred"(x,{flag = 0},{fa})"
5589 finds polynomials with reasonably small coefficients defining subfields
5590 of the number field defined by "x". One of the polynomials always
5591 defines Q (hence is equal to "x-1"), and another always defines the
5592 same number field as "x" if "x" is irreducible. All "x" accepted by
5593 "nfinit" are also allowed here (e.g. non-monic polynomials, "nf",
5594 "bnf", "[x,Z_K_basis]").
5595 The following binary digits of "flag" are significant:
5597 1: possibly use a suborder of the maximal order. The primes dividing
5599 the index of the order chosen are larger than "primelimit" or divide
5600 integers stored in the "addprimes" table.
5601 2: gives also elements. The result is a two-column matrix, the first
5603 column giving the elements defining these subfields, the second giving
5604 the corresponding minimal polynomials.
5605 If "fa" is given, it is assumed that it is the two-column matrix of the
5607 factorization of the discriminant of the polynomial "x".
5608 The library syntax is polred0"(x,flag,fa)", where an omitted "fa" is
5610 coded by "NULL". Also available are " polred(x)" and "
5611 factoredpolred(x,fa)", both corresponding to "flag = 0".
5612 polredabs"(x,{flag = 0})"
5614 finds one of the polynomial defining the same number field as the one
5615 defined by "x", and such that the sum of the squares of the modulus of
5616 the roots (i.e. the "T_2"-norm) is minimal. All "x" accepted by
5617 "nfinit" are also allowed here (e.g. non-monic polynomials, "nf",
5618 "bnf", "[x,Z_K_basis]").
5619 Warning: this routine uses an exponential-time algorithm to enumerate
5621 all potential generators, and may be exceedingly slow when the number
5622 field has many subfields, hence a lot of elements of small "T_2"-norm.
5623 E.g. do not try it on the compositum of many quadratic fields, use
5624 "polred" instead.
5625 The binary digits of "flag" mean
5627 1: outputs a two-component row vector "[P,a]", where "P" is the default
5629 output and "a" is an element expressed on a root of the polynomial "P",
5630 whose minimal polynomial is equal to "x".
5631 4: gives \emph{all} polynomials of minimal "T_2" norm (of the two
5633 polynomials P(x) and "P(-x)", only one is given).
5634 16: possibly use a suborder of the maximal order. The primes dividing
5636 the index of the order chosen are larger than "primelimit" or divide
5637 integers stored in the "addprimes" table. In that case it may happen
5638 that the output polynomial does not have minimal "T_2" norm.
5639 The library syntax is polredabs0"(x,flag)".
5641 polredord"(x)"
5643 finds polynomials with reasonably small coefficients and of the same
5644 degree as that of "x" defining suborders of the order defined by "x".
5645 One of the polynomials always defines Q (hence is equal to "(x-1)^n",
5646 where "n" is the degree), and another always defines the same order as
5647 "x" if "x" is irreducible.
5648 The library syntax is ordred"(x)".
5650 poltschirnhaus"(x)"
5652 applies a random Tschirnhausen transformation to the polynomial "x",
5653 which is assumed to be non-constant and separable, so as to obtain a
5654 new equation for the etale algebra defined by "x". This is for instance
5655 useful when computing resolvents, hence is used by the "polgalois"
5656 function.
5657 The library syntax is tschirnhaus"(x)".
5659 rnfalgtobasis"(rnf,x)"
5661 expresses "x" on the relative integral basis. Here, "rnf" is a relative
5662 number field extension "L/K" as output by "rnfinit", and "x" an element
5663 of "L" in absolute form, i.e. expressed as a polynomial or polmod with
5664 polmod coefficients, \emph{not} on the relative integral basis.
5665 The library syntax is rnfalgtobasis"(rnf,x)".
5667 rnfbasis"(bnf, M)"
5669 let "K" the field represented by bnf, as output by "bnfinit". "M" is a
5670 projective "Z_K"-module given by a pseudo-basis, as output by
5671 "rnfhnfbasis". The routine returns either a true "Z_K"-basis of "M" if
5672 it exists, or an "n+1"-element generating set of "M" if not, where "n"
5673 is the rank of "M" over "K". (Note that "n" is the size of the pseudo-
5674 basis.)
5675 It is allowed to use a polynomial "P" with coefficients in "K" instead
5677 of "M", in which case, "M" is defined as the ring of integers of
5678 "K[X]/(P)" ("P" is assumed irreducible over "K"), viewed as a
5679 "Z_K"-module.
5680 The library syntax is rnfbasis"(bnf,x)".
5682 rnfbasistoalg"(rnf,x)"
5684 computes the representation of "x" as a polmod with polmods
5685 coefficients. Here, "rnf" is a relative number field extension "L/K" as
5686 output by "rnfinit", and "x" an element of "L" expressed on the
5687 relative integral basis.
5688 The library syntax is rnfbasistoalg"(rnf,x)".
5690 rnfcharpoly"(nf,T,a,{v = x})"
5692 characteristic polynomial of "a" over "nf", where "a" belongs to the
5693 algebra defined by "T" over "nf", i.e. "nf[X]/(T)". Returns a
5694 polynomial in variable "v" ("x" by default).
5695 The library syntax is rnfcharpoly"(nf,T,a,v)", where "v" is a variable
5697 number.
5698 rnfconductor"(bnf,pol,{flag = 0})"
5700 given "bnf" as output by "bnfinit", and pol a relative polynomial
5701 defining an Abelian extension, computes the class field theory
5702 conductor of this Abelian extension. The result is a 3-component vector
5703 "[conductor,rayclgp,subgroup]", where conductor is the conductor of the
5704 extension given as a 2-component row vector "[f_0,f_ oo ]", rayclgp is
5705 the full ray class group corresponding to the conductor given as a
5706 3-component vector [h,cyc,gen] as usual for a group, and subgroup is a
5707 matrix in HNF defining the subgroup of the ray class group on the given
5708 generators gen. If "flag" is non-zero, check that pol indeed defines an
5709 Abelian extension, return 0 if it does not.
5710 The library syntax is rnfconductor"(rnf,pol,flag)".
5712 rnfdedekind"(nf,pol,pr)"
5714 given a number field "nf" as output by "nfinit" and a polynomial pol
5715 with coefficients in "nf" defining a relative extension "L" of "nf",
5716 evaluates the relative Dedekind criterion over the order defined by a
5717 root of pol for the prime ideal pr and outputs a 3-component vector as
5718 the result. The first component is a flag equal to 1 if the enlarged
5719 order could be proven to be pr-maximal and to 0 otherwise (it may be
5720 maximal in the latter case if pr is ramified in "L"), the second
5721 component is a pseudo-basis of the enlarged order and the third
5722 component is the valuation at pr of the order discriminant.
5723 The library syntax is rnfdedekind"(nf,pol,pr)".
5725 rnfdet"(nf,M)"
5727 given a pseudo-matrix "M" over the maximal order of "nf", computes its
5728 determinant.
5729 The library syntax is rnfdet"(nf,M)".
5731 rnfdisc"(nf,pol)"
5733 given a number field "nf" as output by "nfinit" and a polynomial pol
5734 with coefficients in "nf" defining a relative extension "L" of "nf",
5735 computes the relative discriminant of "L". This is a two-element row
5736 vector "[D,d]", where "D" is the relative ideal discriminant and "d" is
5737 the relative discriminant considered as an element of "nf^*/{nf^*}^2".
5738 The main variable of "nf" \emph{must} be of lower priority than that of
5739 pol, see "Label se:priority".
5740 The library syntax is rnfdiscf"(bnf,pol)".
5742 rnfeltabstorel"(rnf,x)"
5744 "rnf" being a relative number field extension "L/K" as output by
5745 "rnfinit" and "x" being an element of "L" expressed as a polynomial
5746 modulo the absolute equation "rnf.pol", computes "x" as an element of
5747 the relative extension "L/K" as a polmod with polmod coefficients.
5748 The library syntax is rnfelementabstorel"(rnf,x)".
5750 rnfeltdown"(rnf,x)"
5752 "rnf" being a relative number field extension "L/K" as output by
5753 "rnfinit" and "x" being an element of "L" expressed as a polynomial or
5754 polmod with polmod coefficients, computes "x" as an element of "K" as a
5755 polmod, assuming "x" is in "K" (otherwise an error will occur). If "x"
5756 is given on the relative integral basis, apply "rnfbasistoalg" first,
5757 otherwise PARI will believe you are dealing with a vector.
5758 The library syntax is rnfelementdown"(rnf,x)".
5760 rnfeltreltoabs"(rnf,x)"
5762 "rnf" being a relative number field extension "L/K" as output by
5763 "rnfinit" and "x" being an element of "L" expressed as a polynomial or
5764 polmod with polmod coefficients, computes "x" as an element of the
5765 absolute extension "L/Q" as a polynomial modulo the absolute equation
5766 "rnf.pol". If "x" is given on the relative integral basis, apply
5767 "rnfbasistoalg" first, otherwise PARI will believe you are dealing with
5768 a vector.
5769 The library syntax is rnfelementreltoabs"(rnf,x)".
5771 rnfeltup"(rnf,x)"
5773 "rnf" being a relative number field extension "L/K" as output by
5774 "rnfinit" and "x" being an element of "K" expressed as a polynomial or
5775 polmod, computes "x" as an element of the absolute extension "L/Q" as a
5776 polynomial modulo the absolute equation "rnf.pol". If "x" is given on
5777 the integral basis of "K", apply "nfbasistoalg" first, otherwise PARI
5778 will believe you are dealing with a vector.
5779 The library syntax is rnfelementup"(rnf,x)".
5781 rnfequation"(nf,pol,{flag = 0})"
5783 given a number field "nf" as output by "nfinit" (or simply a
5784 polynomial) and a polynomial pol with coefficients in "nf" defining a
5785 relative extension "L" of "nf", computes the absolute equation of "L"
5786 over Q.
5787 If "flag" is non-zero, outputs a 3-component row vector "[z,a,k]",
5789 where "z" is the absolute equation of "L" over Q, as in the default
5790 behaviour, "a" expresses as an element of "L" a root "alpha" of the
5791 polynomial defining the base field "nf", and "k" is a small integer
5792 such that "theta = beta+kalpha" where "theta" is a root of "z" and
5793 "beta" a root of "pol".
5794 The main variable of "nf" \emph{must} be of lower priority than that of
5796 pol (see "Label se:priority"). Note that for efficiency, this does not
5797 check whether the relative equation is irreducible over "nf", but only
5798 if it is squarefree. If it is reducible but squarefree, the result will
5799 be the absolute equation of the etale algebra defined by pol. If pol is
5800 not squarefree, an error message will be issued.
5801 The library syntax is rnfequation0"(nf,pol,flag)".
5803 rnfhnfbasis"(bnf,x)"
5805 given "bnf" as output by "bnfinit", and either a polynomial "x" with
5806 coefficients in "bnf" defining a relative extension "L" of "bnf", or a
5807 pseudo-basis "x" of such an extension, gives either a true "bnf"-basis
5808 of "L" in upper triangular Hermite normal form, if it exists, and
5809 returns 0 otherwise.
5810 The library syntax is rnfhnfbasis"(nf,x)".
5812 rnfidealabstorel"(rnf,x)"
5814 let "rnf" be a relative number field extension "L/K" as output by
5815 "rnfinit", and "x" an ideal of the absolute extension "L/Q" given by a
5816 Z-basis of elements of "L". Returns the relative pseudo-matrix in HNF
5817 giving the ideal "x" considered as an ideal of the relative extension
5818 "L/K".
5819 If "x" is an ideal in HNF form, associated to an nf structure, for
5821 instance as output by "idealhnf(nf,...)", use "rnfidealabstorel(rnf,
5822 nf.zk * x)" to convert it to a relative ideal.
5823 The library syntax is rnfidealabstorel"(rnf,x)".
5825 rnfidealdown"(rnf,x)"
5827 let "rnf" be a relative number field extension "L/K" as output by
5828 "rnfinit", and "x" an ideal of "L", given either in relative form or by
5829 a Z-basis of elements of "L" (see "Label se:rnfidealabstorel"), returns
5830 the ideal of "K" below "x", i.e. the intersection of "x" with "K".
5831 The library syntax is rnfidealdown"(rnf,x)".
5833 rnfidealhnf"(rnf,x)"
5835 "rnf" being a relative number field extension "L/K" as output by
5836 "rnfinit" and "x" being a relative ideal (which can be, as in the
5837 absolute case, of many different types, including of course elements),
5838 computes the HNF pseudo-matrix associated to "x", viewed as a
5839 "Z_K"-module.
5840 The library syntax is rnfidealhermite"(rnf,x)".
5842 rnfidealmul"(rnf,x,y)"
5844 "rnf" being a relative number field extension "L/K" as output by
5845 "rnfinit" and "x" and "y" being ideals of the relative extension "L/K"
5846 given by pseudo-matrices, outputs the ideal product, again as a
5847 relative ideal.
5848 The library syntax is rnfidealmul"(rnf,x,y)".
5850 rnfidealnormabs"(rnf,x)"
5852 "rnf" being a relative number field extension "L/K" as output by
5853 "rnfinit" and "x" being a relative ideal (which can be, as in the
5854 absolute case, of many different types, including of course elements),
5855 computes the norm of the ideal "x" considered as an ideal of the
5856 absolute extension "L/Q". This is identical to
5857 "idealnorm(rnfidealnormrel(rnf,x))", but faster.
5858 The library syntax is rnfidealnormabs"(rnf,x)".
5860 rnfidealnormrel"(rnf,x)"
5862 "rnf" being a relative number field extension "L/K" as output by
5863 "rnfinit" and "x" being a relative ideal (which can be, as in the
5864 absolute case, of many different types, including of course elements),
5865 computes the relative norm of "x" as a ideal of "K" in HNF.
5866 The library syntax is rnfidealnormrel"(rnf,x)".
5868 rnfidealreltoabs"(rnf,x)"
5870 "rnf" being a relative number field extension "L/K" as output by
5871 "rnfinit" and "x" being a relative ideal, gives the ideal "xZ_L" as an
5872 absolute ideal of "L/Q", in the form of a Z-basis, given by a vector of
5873 polynomials (modulo "rnf.pol"). The following routine might be useful:
5874 \\ return y = rnfidealreltoabs(rnf,...) as an ideal in HNF form
5876 \\ associated to nf = nfinit( rnf.pol );
5877 idealgentoHNF(nf, y) = mathnf( Mat( nfalgtobasis(nf, y) ) );
5878 The library syntax is rnfidealreltoabs"(rnf,x)".
5880 rnfidealtwoelt"(rnf,x)"
5882 "rnf" being a relative number field extension "L/K" as output by
5883 "rnfinit" and "x" being an ideal of the relative extension "L/K" given
5884 by a pseudo-matrix, gives a vector of two generators of "x" over "Z_L"
5885 expressed as polmods with polmod coefficients.
5886 The library syntax is rnfidealtwoelement"(rnf,x)".
5888 rnfidealup"(rnf,x)"
5890 "rnf" being a relative number field extension "L/K" as output by
5891 "rnfinit" and "x" being an ideal of "K", gives the ideal "xZ_L" as an
5892 absolute ideal of "L/Q", in the form of a Z-basis, given by a vector of
5893 polynomials (modulo "rnf.pol"). The following routine might be useful:
5894 \\ return y = rnfidealup(rnf,...) as an ideal in HNF form
5896 \\ associated to nf = nfinit( rnf.pol );
5897 idealgentoHNF(nf, y) = mathnf( Mat( nfalgtobasis(nf, y) ) );
5898 The library syntax is rnfidealup"(rnf,x)".
5900 rnfinit"(nf,pol)"
5902 "nf" being a number field in "nfinit" format considered as base field,
5903 and pol a polynomial defining a relative extension over "nf", this
5904 computes all the necessary data to work in the relative extension. The
5905 main variable of pol must be of higher priority (see "Label
5906 se:priority") than that of "nf", and the coefficients of pol must be in
5907 "nf".
5908 The result is a row vector, whose components are technical. In the
5910 following description, we let "K" be the base field defined by "nf",
5911 "m" the degree of the base field, "n" the relative degree, "L" the
5912 large field (of relative degree "n" or absolute degree "nm"), "r_1" and
5913 "r_2" the number of real and complex places of "K".
5914 "rnf[1]" contains the relative polynomial pol.
5916 "rnf[2]" is currently unused.
5918 "rnf[3]" is a two-component row vector "[\goth{d}(L/K),s]" where
5920 "\goth{d}(L/K)" is the relative ideal discriminant of "L/K" and "s" is
5921 the discriminant of "L/K" viewed as an element of "K^*/(K^*)^2", in
5922 other words it is the output of "rnfdisc".
5923 "rnf[4]" is the ideal index "\goth{f}", i.e. such that "d(pol)Z_K =
5925 \goth{f}^2\goth{d}(L/K)".
5926 "rnf[5]" is currently unused.
5928 "rnf[6]" is currently unused.
5930 "rnf[7]" is a two-component row vector, where the first component is
5932 the relative integral pseudo basis expressed as polynomials (in the
5933 variable of "pol") with polmod coefficients in "nf", and the second
5934 component is the ideal list of the pseudobasis in HNF.
5935 "rnf[8]" is the inverse matrix of the integral basis matrix, with
5937 coefficients polmods in "nf".
5938 "rnf[9]" is currently unused.
5940 "rnf[10]" is "nf".
5942 "rnf[11]" is the output of "rnfequation(nf, pol, 1)". Namely, a vector
5944 vabs with 3 entries describing the \emph{absolute} extension "L/Q".
5945 "vabs[1]" is an absolute equation, more conveniently obtained as
5946 "rnf.pol". "vabs[2]" expresses the generator "alpha" of the number
5947 field "nf" as a polynomial modulo the absolute equation "vabs[1]".
5948 "vabs[3]" is a small integer "k" such that, if "beta" is an abstract
5949 root of pol and "alpha" the generator of "nf", the generator whose root
5950 is vabs will be "beta + k alpha". Note that one must be very careful if
5951 "k ! = 0" when dealing simultaneously with absolute and relative
5952 quantities since the generator chosen for the absolute extension is not
5953 the same as for the relative one. If this happens, one can of course go
5954 on working, but we strongly advise to change the relative polynomial so
5955 that its root will be "beta + k alpha". Typically, the GP instruction
5956 would be
5957 "pol = subst(pol, x, x - k*Mod(y,nf.pol))"
5959 "rnf[12]" is by default unused and set equal to 0. This field is used
5961 to store further information about the field as it becomes available
5962 (which is rarely needed, hence would be too expensive to compute during
5963 the initial "rnfinit" call).
5964 The library syntax is rnfinitalg"(nf,pol,prec)".
5966 rnfisfree"(bnf,x)"
5968 given "bnf" as output by "bnfinit", and either a polynomial "x" with
5969 coefficients in "bnf" defining a relative extension "L" of "bnf", or a
5970 pseudo-basis "x" of such an extension, returns true (1) if "L/bnf" is
5971 free, false (0) if not.
5972 The library syntax is rnfisfree"(bnf,x)", and the result is a "long".
5974 rnfisnorm"(T,a,{flag = 0})"
5976 similar to "bnfisnorm" but in the relative case. "T" is as output by
5977 "rnfisnorminit" applied to the extension "L/K". This tries to decide
5978 whether the element "a" in "K" is the norm of some "x" in the extension
5979 "L/K".
5980 The output is a vector "[x,q]", where "a = \Norm(x)*q". The algorithm
5982 looks for a solution "x" which is an "S"-integer, with "S" a list of
5983 places of "K" containing at least the ramified primes, the generators
5984 of the class group of "L", as well as those primes dividing "a". If
5985 "L/K" is Galois, then this is enough; otherwise, "flag" is used to add
5986 more primes to "S": all the places above the primes "p <= flag"
5987 (resp. "p|flag") if "flag > 0" (resp. "flag < 0").
5988 The answer is guaranteed (i.e. "a" is a norm iff "q = 1") if the field
5990 is Galois, or, under GRH, if "S" contains all primes less than "12 log
5991 ^2|\disc(M)|", where "M" is the normal closure of "L/K".
5992 If "rnfisnorminit" has determined (or was told) that "L/K" is Galois,
5994 and "flag ! = 0", a Warning is issued (so that you can set "flag = 1"
5995 to check whether "L/K" is known to be Galois, according to "T").
5996 Example:
5997 bnf = bnfinit(y^3 + y^2 - 2*y - 1);
5999 p = x^2 + Mod(y^2 + 2*y + 1, bnf.pol);
6000 T = rnfisnorminit(bnf, p);
6001 rnfisnorm(T, 17)
6002 checks whether 17 is a norm in the Galois extension "Q(beta) /
6004 Q(alpha)", where "alpha^3 + alpha^2 - 2alpha - 1 = 0" and "beta^2 +
6005 alpha^2 + 2alpha + 1 = 0" (it is).
6006 The library syntax is rnfisnorm"(T,x,flag)".
6008 rnfisnorminit"(pol,polrel,{flag = 2})"
6010 let "K" be defined by a root of pol, and "L/K" the extension defined by
6011 the polynomial polrel. As usual, pol can in fact be an nf, or bnf, etc;
6012 if pol has degree 1 (the base field is Q), polrel is also allowed to be
6013 an nf, etc. Computes technical data needed by "rnfisnorm" to solve norm
6014 equations "Nx = a", for "x" in "L", and "a" in "K".
6015 If "flag = 0", do not care whether "L/K" is Galois or not.
6017 If "flag = 1", "L/K" is assumed to be Galois (unchecked), which speeds
6019 up "rnfisnorm".
6020 If "flag = 2", let the routine determine whether "L/K" is Galois.
6022 The library syntax is rnfisnorminit"(pol,polrel,flag)".
6024 rnfkummer"(bnr,{subgroup},{deg = 0})"
6026 bnr being as output by "bnrinit", finds a relative equation for the
6027 class field corresponding to the module in bnr and the given congruence
6028 subgroup (the full ray class field if subgroup is omitted). If deg is
6029 positive, outputs the list of all relative equations of degree deg
6030 contained in the ray class field defined by bnr, with the \emph{same}
6031 conductor as "(bnr, subgroup)".
6032 Warning: this routine only works for subgroups of prime index. It uses
6034 Kummer theory, adjoining necessary roots of unity (it needs to compute
6035 a tough "bnfinit" here), and finds a generator via Hecke's
6036 characterization of ramification in Kummer extensions of prime degree.
6037 If your extension does not have prime degree, for the time being, you
6038 have to split it by hand as a tower / compositum of such extensions.
6039 The library syntax is rnfkummer"(bnr,subgroup,deg,prec)", where deg is
6041 a "long" and an omitted subgroup is coded as "NULL"
6042 rnflllgram"(nf,pol,order)"
6044 given a polynomial pol with coefficients in nf defining a relative
6045 extension "L" and a suborder order of "L" (of maximal rank), as output
6046 by "rnfpseudobasis""(nf,pol)" or similar, gives "[[neworder],U]", where
6047 neworder is a reduced order and "U" is the unimodular transformation
6048 matrix.
6049 The library syntax is rnflllgram"(nf,pol,order,prec)".
6051 rnfnormgroup"(bnr,pol)"
6053 bnr being a big ray class field as output by "bnrinit" and pol a
6054 relative polynomial defining an Abelian extension, computes the norm
6055 group (alias Artin or Takagi group) corresponding to the Abelian
6056 extension of "bnf = bnr[1]" defined by pol, where the module
6057 corresponding to bnr is assumed to be a multiple of the conductor
6058 (i.e. pol defines a subextension of bnr). The result is the HNF
6059 defining the norm group on the given generators of "bnr[5][3]". Note
6060 that neither the fact that pol defines an Abelian extension nor the
6061 fact that the module is a multiple of the conductor is checked. The
6062 result is undefined if the assumption is not correct.
6063 The library syntax is rnfnormgroup"(bnr,pol)".
6065 rnfpolred"(nf,pol)"
6067 relative version of "polred". Given a monic polynomial pol with
6068 coefficients in "nf", finds a list of relative polynomials defining
6069 some subfields, hopefully simpler and containing the original field. In
6070 the present version 2.2.0, this is slower and less efficient than
6071 "rnfpolredabs".
6072 The library syntax is rnfpolred"(nf,pol,prec)".
6074 rnfpolredabs"(nf,pol,{flag = 0})"
6076 relative version of "polredabs". Given a monic polynomial pol with
6077 coefficients in "nf", finds a simpler relative polynomial defining the
6078 same field. The binary digits of "flag" mean
6079 1: returns "[P,a]" where "P" is the default output and "a" is an
6081 element expressed on a root of "P" whose characteristic polynomial is
6082 pol
6083 2: returns an absolute polynomial (same as
6085 "rnfequation(nf,rnfpolredabs(nf,pol))" but faster).
6086 16: possibly use a suborder of the maximal order. This is slower than
6088 the default when the relative discriminant is smooth, and much faster
6089 otherwise. See "Label se:polredabs".
6090 Remark. In the present implementation, this is both faster and much
6092 more efficient than "rnfpolred", the difference being more dramatic
6093 than in the absolute case. This is because the implementation of
6094 "rnfpolred" is based on (a partial implementation of) an incomplete
6095 reduction theory of lattices over number fields, the function
6096 "rnflllgram", which deserves to be improved.
6097 The library syntax is rnfpolredabs"(nf,pol,flag,prec)".
6099 rnfpseudobasis"(nf,pol)"
6101 given a number field "nf" as output by "nfinit" and a polynomial pol
6102 with coefficients in "nf" defining a relative extension "L" of "nf",
6103 computes a pseudo-basis "(A,I)" for the maximal order "Z_L" viewed as a
6104 "Z_K"-module, and the relative discriminant of "L". This is output as a
6105 four-element row vector "[A,I,D,d]", where "D" is the relative ideal
6106 discriminant and "d" is the relative discriminant considered as an
6107 element of "nf^*/{nf^*}^2".
6108 The library syntax is rnfpseudobasis"(nf,pol)".
6110 rnfsteinitz"(nf,x)"
6112 given a number field "nf" as output by "nfinit" and either a polynomial
6113 "x" with coefficients in "nf" defining a relative extension "L" of
6114 "nf", or a pseudo-basis "x" of such an extension as output for example
6115 by "rnfpseudobasis", computes another pseudo-basis "(A,I)" (not in HNF
6116 in general) such that all the ideals of "I" except perhaps the last one
6117 are equal to the ring of integers of "nf", and outputs the four-
6118 component row vector "[A,I,D,d]" as in "rnfpseudobasis". The name of
6119 this function comes from the fact that the ideal class of the last
6120 ideal of "I", which is well defined, is the Steinitz class of the
6121 "Z_K"-module "Z_L" (its image in "SK_0(Z_K)").
6122 The library syntax is rnfsteinitz"(nf,x)".
6124 subgrouplist"(bnr,{bound},{flag = 0})"
6126 bnr being as output by "bnrinit" or a list of cyclic components of a
6127 finite Abelian group "G", outputs the list of subgroups of "G".
6128 Subgroups are given as HNF left divisors of the SNF matrix
6129 corresponding to "G".
6130 Warning: the present implementation cannot treat a group "G" where any
6132 cyclic factor has more than "2^{31}", resp. "2^{63}" elements on a
6133 32-bit, resp. 64-bit architecture. "forsubgroup" is a bit more general
6134 and can handle "G" if all "p"-Sylow subgroups of "G" satisfy the
6135 condition above.
6136 If "flag = 0" (default) and bnr is as output by "bnrinit", gives only
6138 the subgroups whose modulus is the conductor. Otherwise, the modulus is
6139 not taken into account.
6140 If bound is present, and is a positive integer, restrict the output to
6142 subgroups of index less than bound. If bound is a vector containing a
6143 single positive integer "B", then only subgroups of index exactly equal
6144 to "B" are computed. For instance
6145 ? subgrouplist([6,2])
6147 %1 = [[6, 0; 0, 2], [2, 0; 0, 2], [6, 3; 0, 1], [2, 1; 0, 1], [3, 0; 0, 2],
6148 [1, 0; 0, 2], [6, 0; 0, 1], [2, 0; 0, 1], [3, 0; 0, 1], [1, 0; 0, 1]]
6149 ? subgrouplist([6,2],3) \\ index less than 3
6150 %2 = [[2, 1; 0, 1], [1, 0; 0, 2], [2, 0; 0, 1], [3, 0; 0, 1], [1, 0; 0, 1]]
6151 ? subgrouplist([6,2],[3]) \\ index 3
6152 %3 = [[3, 0; 0, 1]]
6153 ? bnr = bnrinit(bnfinit(x), [120,[1]], 1);
6154 ? L = subgrouplist(bnr, [8]);
6155 In the last example, "L" corresponds to the 24 subfields of
6157 "Q(zeta_{120})", of degree 8 and conductor "120 oo " (by setting flag,
6158 we see there are a total of 43 subgroups of degree 8).
6159 ? vector(#L, i, galoissubcyclo(bnr, L[i]))
6161 will produce their equations. (For a general base field, you would have
6163 to rely on "bnrstark", or "rnfkummer".)
6164 The library syntax is subgrouplist0"(bnr,bound,flag)", where "flag" is
6166 a long integer, and an omitted bound is coded by "NULL".
6167 zetak"(znf,x,{flag = 0})"
6169 znf being a number field initialized by "zetakinit" (\emph{not} by
6170 "nfinit"), computes the value of the Dedekind zeta function of the
6171 number field at the complex number "x". If "flag = 1" computes Dedekind
6172 "Lambda" function instead (i.e. the product of the Dedekind zeta
6173 function by its gamma and exponential factors).
6174 CAVEAT. This implementation is not satisfactory and must be rewritten.
6176 In particular
6177 "*" The accuracy of the result depends in an essential way on the
6179 accuracy of both the "zetakinit" program and the current accuracy. Be
6180 wary in particular that "x" of large imaginary part or, on the
6181 contrary, very close to an ordinary integer will suffer from precision
6182 loss, yielding fewer significant digits than expected. Computing with
6183 28 eight digits of relative accuracy, we have
6184 ? zeta(3)
6186 %1 = 1.202056903159594285399738161
6187 ? zeta(3-1e-20)
6188 %2 = 1.202056903159594285401719424
6189 ? zetak(zetakinit(x), 3-1e-20)
6190 %3 = 1.2020569031595952919 \\ 5 digits are wrong
6191 ? zetak(zetakinit(x), 3-1e-28)
6192 %4 = -25.33411749 \\ junk
6193 "*" As the precision increases, results become unexpectedly completely
6195 wrong:
6196 ? \p100
6198 ? zetak(zetakinit(x^2-5), -1) - 1/30
6199 %1 = 7.26691813 E-108 \\ perfect
6200 ? \p150
6201 ? zetak(zetakinit(x^2-5), -1) - 1/30
6202 %2 = -2.486113578 E-156 \\ perfect
6203 ? \p200
6204 ? zetak(zetakinit(x^2-5), -1) - 1/30
6205 %3 = 4.47... E-75 \\ more than half of the digits are wrong
6206 ? \p250
6207 ? zetak(zetakinit(x^2-5), -1) - 1/30
6208 %4 = 1.6 E43 \\ junk
6209 The library syntax is glambdak"(znf,x,prec)" or " gzetak(znf,x,prec)".
6211 zetakinit"(x)"
6213 computes a number of initialization data concerning the number field
6214 defined by the polynomial "x" so as to be able to compute the Dedekind
6215 zeta and lambda functions (respectively zetak(x) and "zetak(x,1)").
6216 This function calls in particular the "bnfinit" program. The result is
6217 a 9-component vector "v" whose components are very technical and cannot
6218 really be used by the user except through the "zetak" function. The
6219 only component which can be used if it has not been computed already is
6220 "v[1][4]" which is the result of the "bnfinit" call.
6221 This function is very inefficient and should be rewritten. It needs to
6223 computes millions of coefficients of the corresponding Dirichlet series
6224 if the precision is big. Unless the discriminant is small it will not
6225 be able to handle more than 9 digits of relative precision. For
6226 instance, "zetakinit(x^8 - 2)" needs 440MB of memory at default
6227 precision.
6228 The library syntax is initzeta"(x)".
6230
6232 We group here all functions which are specific to polynomials or power
6233 series. Many other functions which can be applied on these objects are
6234 described in the other sections. Also, some of the functions described
6235 here can be applied to other types.
6236 O"(p^e)"
6238 if "p" is an integer greater than 2, returns a "p"-adic 0 of precision
6239 "e". In all other cases, returns a power series zero with precision
6240 given by "e v", where "v" is the "X"-adic valuation of "p" with respect
6241 to its main variable.
6242 The library syntax is zeropadic"(p,e)" for a "p"-adic and "
6244 zeroser(v,e)" for a power series zero in variable "v", which is a
6245 "long". The precision "e" is a "long".
6246 deriv"(x,{v})"
6248 derivative of "x" with respect to the main variable if "v" is omitted,
6249 and with respect to "v" otherwise. The derivative of a scalar type is
6250 zero, and the derivative of a vector or matrix is done componentwise.
6251 One can use "x'" as a shortcut if the derivative is with respect to the
6252 main variable of "x".
6253 By definition, the main variable of a "t_POLMOD" is the main variable
6255 among the coefficients from its two polynomial components
6256 (representative and modulus); in other words, assuming a polmod
6257 represents an element of "R[X]/(T(X))", the variable "X" is a mute
6258 variable and the derivative is taken with respect to the main variable
6259 used in the base ring "R".
6260 The library syntax is deriv"(x,v)", where "v" is a "long", and an
6262 omitted "v" is coded as "-1". When "x" is a "t_POL", derivpol(x) is a
6263 shortcut for "deriv(x, -1)".
6264 eval"(x)"
6266 replaces in "x" the formal variables by the values that have been
6267 assigned to them after the creation of "x". This is mainly useful in
6268 GP, and not in library mode. Do not confuse this with substitution (see
6269 "subst").
6270 If "x" is a character string, eval(x) executes "x" as a GP command, as
6272 if directly input from the keyboard, and returns its output. For
6273 convenience, "x" is evaluated as if "strictmatch" was off. In
6274 particular, unused characters at the end of "x" do not prevent its
6275 evaluation:
6276 ? eval("1a")
6278 % 1 = 1
6279 The library syntax is geval"(x)". The more basic functions "
6281 poleval(q,x)", " qfeval(q,x)", and " hqfeval(q,x)" evaluate "q" at "x",
6282 where "q" is respectively assumed to be a polynomial, a quadratic form
6283 (a symmetric matrix), or an Hermitian form (an Hermitian complex
6284 matrix).
6285 factorpadic"(pol,p,r,{flag = 0})"
6287 "p"-adic factorization of the polynomial pol to precision "r", the
6288 result being a two-column matrix as in "factor". The factors are
6289 normalized so that their leading coefficient is a power of "p". "r"
6290 must be strictly larger than the "p"-adic valuation of the discriminant
6291 of pol for the result to make any sense. The method used is a modified
6292 version of the round 4 algorithm of Zassenhaus.
6293 If "flag = 1", use an algorithm due to Buchmann and Lenstra, which is
6295 usually less efficient.
6296 The library syntax is factorpadic4"(pol,p,r)", where "r" is a "long"
6298 integer.
6299 intformal"(x,{v})"
6301 formal integration of "x" with respect to the main variable if "v" is
6302 omitted, with respect to the variable "v" otherwise. Since PARI does
6303 not know about ``abstract'' logarithms (they are immediately evaluated,
6304 if only to a power series), logarithmic terms in the result will yield
6305 an error. "x" can be of any type. When "x" is a rational function, it
6306 is assumed that the base ring is an integral domain of characteristic
6307 zero.
6308 The library syntax is integ"(x,v)", where "v" is a "long" and an
6310 omitted "v" is coded as "-1".
6311 padicappr"(pol,a)"
6313 vector of "p"-adic roots of the polynomial "pol" congruent to the
6314 "p"-adic number "a" modulo "p", and with the same "p"-adic precision as
6315 "a". The number "a" can be an ordinary "p"-adic number (type "t_PADIC",
6316 i.e. an element of "Z_p") or can be an integral element of a finite
6317 extension of "Q_p", given as a "t_POLMOD" at least one of whose
6318 coefficients is a "t_PADIC". In this case, the result is the vector of
6319 roots belonging to the same extension of "Q_p" as "a".
6320 The library syntax is padicappr"(pol,a)".
6322 polcoeff"(x,s,{v})"
6324 coefficient of degree "s" of the polynomial "x", with respect to the
6325 main variable if "v" is omitted, with respect to "v" otherwise. Also
6326 applies to power series, scalars (polynomial of degree 0), and to
6327 rational functions provided the denominator is a monomial.
6328 The library syntax is polcoeff0"(x,s,v)", where "v" is a "long" and an
6330 omitted "v" is coded as "-1". Also available is " truecoeff(x,v)".
6331 poldegree"(x,{v})"
6333 degree of the polynomial "x" in the main variable if "v" is omitted, in
6334 the variable "v" otherwise.
6335 The degree of 0 is a fixed negative number, whose exact value should
6337 not be used. The degree of a non-zero scalar is 0. Finally, when "x" is
6338 a non-zero polynomial or rational function, returns the ordinary degree
6339 of "x". Raise an error otherwise.
6340 The library syntax is poldegree"(x,v)", where "v" and the result are
6342 "long"s (and an omitted "v" is coded as "-1"). Also available is "
6343 degree(x)", which is equivalent to "poldegree(x,-1)".
6344 polcyclo"(n,{v = x})"
6346 "n"-th cyclotomic polynomial, in variable "v" ("x" by default). The
6347 integer "n" must be positive.
6348 The library syntax is cyclo"(n,v)", where "n" and "v" are "long"
6350 integers ("v" is a variable number, usually obtained through "varn").
6351 poldisc"(pol,{v})"
6353 discriminant of the polynomial pol in the main variable is "v" is
6354 omitted, in "v" otherwise. The algorithm used is the subresultant
6355 algorithm.
6356 The library syntax is poldisc0"(x,v)". Also available is " discsr(x)",
6358 equivalent to "poldisc0(x,-1)".
6359 poldiscreduced"(f)"
6361 reduced discriminant vector of the (integral, monic) polynomial "f".
6362 This is the vector of elementary divisors of
6363 "Z[alpha]/f'(alpha)Z[alpha]", where "alpha" is a root of the polynomial
6364 "f". The components of the result are all positive, and their product
6365 is equal to the absolute value of the discriminant of "f".
6366 The library syntax is reduceddiscsmith"(x)".
6368 polhensellift"(x, y, p, e)"
6370 given a prime "p", an integral polynomial "x" whose leading coefficient
6371 is a "p"-unit, a vector "y" of integral polynomials that are pairwise
6372 relatively prime modulo "p", and whose product is congruent to "x"
6373 modulo "p", lift the elements of "y" to polynomials whose product is
6374 congruent to "x" modulo "p^e".
6375 The library syntax is polhensellift"(x,y,p,e)" where "e" must be a
6377 "long".
6378 polinterpolate"(xa,{ya},{v = x},{&e})"
6380 given the data vectors "xa" and "ya" of the same length "n" ("xa"
6381 containing the "x"-coordinates, and "ya" the corresponding
6382 "y"-coordinates), this function finds the interpolating polynomial
6383 passing through these points and evaluates it at "v". If "ya" is
6384 omitted, return the polynomial interpolating the "(i,xa[i])". If
6385 present, "e" will contain an error estimate on the returned value.
6386 The library syntax is polint"(xa,ya,v,&e)", where "e" will contain an
6388 error estimate on the returned value.
6389 polisirreducible"(pol)"
6391 pol being a polynomial (univariate in the present version 2.2.0),
6392 returns 1 if pol is non-constant and irreducible, 0 otherwise.
6393 Irreducibility is checked over the smallest base field over which pol
6394 seems to be defined.
6395 The library syntax is gisirreducible"(pol)".
6397 pollead"(x,{v})"
6399 leading coefficient of the polynomial or power series "x". This is
6400 computed with respect to the main variable of "x" if "v" is omitted,
6401 with respect to the variable "v" otherwise.
6402 The library syntax is pollead"(x,v)", where "v" is a "long" and an
6404 omitted "v" is coded as "-1". Also available is " leading_term(x)".
6405 pollegendre"(n,{v = x})"
6407 creates the "n^{th}" Legendre polynomial, in variable "v".
6408 The library syntax is legendre"(n)", where "x" is a "long".
6410 polrecip"(pol)"
6412 reciprocal polynomial of pol, i.e. the coefficients are in reverse
6413 order. pol must be a polynomial.
6414 The library syntax is polrecip"(x)".
6416 polresultant"(x,y,{v},{flag = 0})"
6418 resultant of the two polynomials "x" and "y" with exact entries, with
6419 respect to the main variables of "x" and "y" if "v" is omitted, with
6420 respect to the variable "v" otherwise. The algorithm assumes the base
6421 ring is a domain.
6422 If "flag = 0", uses the subresultant algorithm.
6424 If "flag = 1", uses the determinant of Sylvester's matrix instead (here
6426 "x" and "y" may have non-exact coefficients).
6427 If "flag = 2", uses Ducos's modified subresultant algorithm. It should
6429 be much faster than the default if the coefficient ring is complicated
6430 (e.g multivariate polynomials or huge coefficients), and slightly
6431 slower otherwise.
6432 The library syntax is polresultant0"(x,y,v,flag)", where "v" is a
6434 "long" and an omitted "v" is coded as "-1". Also available are "
6435 subres(x,y)" ("flag = 0") and " resultant2(x,y)" ("flag = 1").
6436 polroots"(pol,{flag = 0})"
6438 complex roots of the polynomial pol, given as a column vector where
6439 each root is repeated according to its multiplicity. The precision is
6440 given as for transcendental functions: in GP it is kept in the variable
6441 "realprecision" and is transparent to the user, but it must be
6442 explicitly given as a second argument in library mode.
6443 The algorithm used is a modification of A. Schoenhage's root-finding
6445 algorithm, due to and implemented by X. Gourdon. Barring bugs, it is
6446 guaranteed to converge and to give the roots to the required accuracy.
6447 If "flag = 1", use a variant of the Newton-Raphson method, which is
6449 \emph{not} guaranteed to converge, but is rather fast. If you get the
6450 messages ``too many iterations in roots'' or ``INTERNAL ERROR:
6451 incorrect result in roots'', use the default algorithm. This used to be
6452 the default root-finding function in PARI until version 1.39.06.
6453 The library syntax is roots"(pol,prec)" or " rootsold(pol,prec)".
6455 polrootsmod"(pol,p,{flag = 0})"
6457 row vector of roots modulo "p" of the polynomial pol. The particular
6458 non-prime value "p = 4" is accepted, mainly for 2-adic computations.
6459 Multiple roots are \emph{not} repeated.
6460 If "p" is very small, you may try setting "flag = 1", which uses a
6462 naive search.
6463 The library syntax is rootmod"(pol,p)" ("flag = 0") or "
6465 rootmod2(pol,p)" ("flag = 1").
6466 polrootspadic"(pol,p,r)"
6468 row vector of "p"-adic roots of the polynomial pol, given to "p"-adic
6469 precision "r". Multiple roots are \emph{not} repeated. "p" is assumed
6470 to be a prime, and pol to be non-zero modulo "p". Note that this is not
6471 the same as the roots in "Z/p^rZ", rather it gives approximations in
6472 "Z/p^rZ" of the true roots living in "Q_p".
6473 If pol has inexact "t_PADIC" coefficients, this is not always well-
6475 defined; in this case, the equation is first made integral, then lifted
6476 to Z. Hence the roots given are approximations of the roots of a
6477 polynomial which is "p"-adically close to the input.
6478 The library syntax is rootpadic"(pol,p,r)", where "r" is a "long".
6480 polsturm"(pol,{a},{b})"
6482 number of real roots of the real polynomial pol in the interval
6483 "]a,b]", using Sturm's algorithm. "a" (resp. "b") is taken to be "- oo
6484 " (resp. "+ oo ") if omitted.
6485 The library syntax is sturmpart"(pol,a,b)". Use "NULL" to omit an
6487 argument. " sturm(pol)" is equivalent to " sturmpart(pol,NULL,NULL)".
6488 The result is a "long".
6489 polsubcyclo"(n,d,{v = x})"
6491 gives polynomials (in variable "v") defining the sub-Abelian extensions
6492 of degree "d" of the cyclotomic field "Q(zeta_n)", where "d | phi(n)".
6493 If there is exactly one such extension the output is a polynomial, else
6495 it is a vector of polynomials, eventually empty.
6496 To be sure to get a vector, you can use "concat([],polsubcyclo(n,d))"
6498 The function "galoissubcyclo" allows to specify more closely which sub-
6500 Abelian extension should be computed.
6501 The library syntax is polsubcyclo"(n,d,v)", where "n", "d" and "v" are
6503 "long" and "v" is a variable number. When "(Z/nZ)^*" is cyclic, you can
6504 use " subcyclo(n,d,v)", where "n", "d" and "v" are "long" and "v" is a
6505 variable number.
6506 polsylvestermatrix"(x,y)"
6508 forms the Sylvester matrix corresponding to the two polynomials "x" and
6509 "y", where the coefficients of the polynomials are put in the columns
6510 of the matrix (which is the natural direction for solving equations
6511 afterwards). The use of this matrix can be essential when dealing with
6512 polynomials with inexact entries, since polynomial Euclidean division
6513 doesn't make much sense in this case.
6514 The library syntax is sylvestermatrix"(x,y)".
6516 polsym"(x,n)"
6518 creates the vector of the symmetric powers of the roots of the
6519 polynomial "x" up to power "n", using Newton's formula.
6520 The library syntax is polsym"(x)".
6522 poltchebi"(n,{v = x})"
6524 creates the "n^{th}" Chebyshev polynomial "T_n" of the first kind in
6525 variable "v".
6526 The library syntax is tchebi"(n,v)", where "n" and "v" are "long"
6528 integers ("v" is a variable number).
6529 polzagier"(n,m)"
6531 creates Zagier's polynomial "P_n^{(m)}" used in the functions "sumalt"
6532 and "sumpos" (with "flag = 1"). One must have "m <= n". The exact
6533 definition can be found in ``Convergence acceleration of alternating
6534 series'', Cohen et al., Experiment. Math., vol. 9, 2000, pp. 3--12.
6535 The library syntax is polzagreel"(n,m,prec)" if the result is only
6537 wanted as a polynomial with real coefficients to the precision "prec",
6538 or " polzag(n,m)" if the result is wanted exactly, where "n" and "m"
6539 are "long"s.
6540 serconvol"(x,y)"
6542 convolution (or Hadamard product) of the two power series "x" and "y";
6543 in other words if "x = sum a_k*X^k" and "y = sum b_k*X^k" then
6544 "serconvol(x,y) = sum a_k*b_k*X^k".
6545 The library syntax is convol"(x,y)".
6547 serlaplace"(x)"
6549 "x" must be a power series with non-negative exponents. If "x = sum
6550 (a_k/k!)*X^k" then the result is "sum a_k*X^k".
6551 The library syntax is laplace"(x)".
6553 serreverse"(x)"
6555 reverse power series (i.e. "x^{-1}", not "1/x") of "x". "x" must be a
6556 power series whose valuation is exactly equal to one.
6557 The library syntax is recip"(x)".
6559 subst"(x,y,z)"
6561 replace the simple variable "y" by the argument "z" in the
6562 ``polynomial'' expression "x". Every type is allowed for "x", but if it
6563 is not a genuine polynomial (or power series, or rational function),
6564 the substitution will be done as if the scalar components were
6565 polynomials of degree zero. In particular, beware that:
6566 ? subst(1, x, [1,2; 3,4])
6568 %1 =
6569 [1 0]
6570 [0 1]
6572 ? subst(1, x, Mat([0,1]))
6574 *** forbidden substitution by a non square matrix
6575 If "x" is a power series, "z" must be either a polynomial, a power
6577 series, or a rational function.
6578 The library syntax is gsubst"(x,y,z)", where "y" is the variable
6580 number.
6581 substpol"(x,y,z)"
6583 replace the ``variable'' "y" by the argument "z" in the ``polynomial''
6584 expression "x". Every type is allowed for "x", but the same behaviour
6585 as "subst" above apply.
6586 The difference with "subst" is that "y" is allowed to be any polynomial
6588 here. The substitution is done as per the following script:
6589 subst_poly(pol, from, to) =
6591 { local(t = 'subst_poly_t, M = from - t);
6592 subst(lift(Mod(pol,M), variable(M)), t, to)
6594 }
6595 For instance
6597 ? substpol(x^4 + x^2 + 1, x^2, y)
6599 %1 = y^2 + y + 1
6600 ? substpol(x^4 + x^2 + 1, x^3, y)
6601 %2 = x^2 + y*x + 1
6602 ? substpol(x^4 + x^2 + 1, (x+1)^2, y)
6603 %3 = (-4*y - 6)*x + (y^2 + 3*y - 3)
6604 The library syntax is gsubstpol"(x,y,z)".
6606 substvec"(x,v,w)"
6608 "v" being a vector of monomials (variables), "w" a vector of
6609 expressions of the same length, replace in the expression "x" all
6610 occurences of "v_i" by "w_i". The substitutions are done
6611 simultaneously; more precisely, the "v_i" are first replaced by new
6612 variables in "x", then these are replaced by the "w_i":
6613 ? substvec([x,y], [x,y], [y,x])
6615 %1 = [y, x]
6616 ? substvec([x,y], [x,y], [y,x+y])
6617 %2 = [y, x + y] \\ not [y, 2*y]
6618 The library syntax is gsubstvec"(x,v,w)".
6620 taylor"(x,y)"
6622 Taylor expansion around 0 of "x" with respect to the simple variable
6623 "y". "x" can be of any reasonable type, for example a rational
6624 function. The number of terms of the expansion is transparent to the
6625 user in GP, but must be given as a second argument in library mode.
6626 The library syntax is tayl"(x,y,n)", where the "long" integer "n" is
6628 the desired number of terms in the expansion.
6629 thue"(tnf,a,{sol})"
6631 solves the equation "P(x,y) = a" in integers "x" and "y", where tnf was
6632 created with thueinit(P). sol, if present, contains the solutions of
6633 "\Norm(x) = a" modulo units of positive norm in the number field
6634 defined by "P" (as computed by "bnfisintnorm"). If the result is
6635 conditional (on the GRH or some heuristic strenghtening), a Warning is
6636 printed. Otherwise, the result is unconditional, barring bugs. For
6637 instance, here's how to solve the Thue equation "x^{13} - 5y^{13} = -
6638 4":
6639 ? tnf = thueinit(x^13 - 5);
6641 ? thue(tnf, -4)
6642 %1 = [[1, 1]]
6643 Hence, the only solution is "x = 1", "y = 1" and the result is
6645 unconditional. On the other hand:
6646 ? tnf = thueinit(x^3-2*x^2+3*x-17);
6648 ? thue(tnf, -15)
6649 *** thue: Warning: Non trivial conditional class group.
6650 *** May miss solutions of the norm equation.
6651 %2 = [[1, 1]]
6652 This time the result is conditional. All results computed using this
6654 tnf are likewise conditional, \emph{except} for a right-hand side of
6655 "+- 1".
6656 The library syntax is thue"(tnf,a,sol)", where an omitted sol is coded
6658 as "NULL".
6659 thueinit"(P,{flag = 0})"
6661 initializes the tnf corresponding to "P". It is meant to be used in
6662 conjunction with "thue" to solve Thue equations "P(x,y) = a", where "a"
6663 is an integer. If "flag" is non-zero, certify the result
6664 unconditionnally. Otherwise, assume GRH, this being much faster of
6665 course.
6666 \emph{If} the conditional computed class group is trivial \emph{or} you
6668 are only interested in the case "a = +-1", then results are
6669 unconditional anyway. So one should only use the flag is "thue" prints
6670 a Warning (see the example there).
6671 The library syntax is thueinit"(P,flag,prec)".
6673
6675 Note that most linear algebra functions operating on subspaces defined
6676 by generating sets (such as "mathnf", "qflll", etc.) take matrices as
6677 arguments. As usual, the generating vectors are taken to be the
6678 \emph{columns} of the given matrix.
6679 Since PARI does not have a strong typing system, scalars live in
6681 unspecified commutative base rings. It is very difficult to write
6682 robust linear algebra routines in such a general setting. The
6683 developpers's choice has been to assume the base ring is a domain and
6684 work over its field of fractions. If the base ring is \emph{not} a
6685 domain, one gets an error as soon as a non-zero pivot turns out to be
6686 non-invertible. Some functions, e.g. "mathnf" or "mathnfmod",
6687 specifically assume the base ring is Z.
6688 algdep"(x,k,{flag = 0})"
6690 "x" being real/complex, or "p"-adic, finds a polynomial of degree at
6691 most "k" with integer coefficients having "x" as approximate root.
6692 Note that the polynomial which is obtained is not necessarily the
6693 ``correct'' one. In fact it is not even guaranteed to be irreducible.
6694 One can check the closeness either by a polynomial evaluation (use
6695 "subst"), or by computing the roots of the polynomial given by "algdep"
6696 (use "polroots").
6697 Internally, "lindep""([1,x,...,x^k], flag)" is used. If "lindep" is not
6699 able to find a relation and returns a lower bound for the sup norm of
6700 the smallest relation, "algdep" returns that bound instead. A suitable
6701 non-zero value of "flag" may improve on the default behaviour:
6702 \\\\\\\\\ LLL
6704 ? \p200
6705 ? algdep(2^(1/6)+3^(1/5), 30); \\ wrong in 3.8s
6706 ? algdep(2^(1/6)+3^(1/5), 30, 100); \\ wrong in 1s
6707 ? algdep(2^(1/6)+3^(1/5), 30, 170); \\ right in 3.3s
6708 ? algdep(2^(1/6)+3^(1/5), 30, 200); \\ wrong in 2.9s
6709 ? \p250
6710 ? algdep(2^(1/6)+3^(1/5), 30); \\ right in 2.8s
6711 ? algdep(2^(1/6)+3^(1/5), 30, 200); \\ right in 3.4s
6712 \\\\\\\\\ PSLQ
6713 ? \p200
6714 ? algdep(2^(1/6)+3^(1/5), 30, -3); \\ failure in 14s.
6715 ? \p250
6716 ? algdep(2^(1/6)+3^(1/5), 30, -3); \\ right in 18s
6717 Proceeding by increments of 5 digits of accuracy, "algdep" with default
6719 flag produces its first correct result at 205 digits, and from then on
6720 a steady stream of correct results. Interestingly enough, our PSLQ also
6721 reliably succeeds from 205 digits on (and is 5 times slower at that
6722 accuracy).
6723 The above example is the testcase studied in a 2000 paper by Borwein
6725 and Lisonek, Applications of integer relation algorithms,
6726 \emph{Discrete Math.}, 217, p. 65--82. The paper conludes in the
6727 superiority of the PSLQ algorithm, which either shows that PARI's
6728 implementation of PSLQ is lacking, or that its LLL is extremely good.
6729 The version of PARI tested there was 1.39, which succeeded reliably
6730 from precision 265 on, in about 60 as much time as the current version.
6731 The library syntax is algdep0"(x,k,flag,prec)", where "k" and "flag"
6733 are "long"s. Also available is " algdep(x,k,prec)" ("flag = 0").
6734 charpoly"(A,{v = x},{flag = 0})"
6736 characteristic polynomial of "A" with respect to the variable "v",
6737 i.e. determinant of "v*I-A" if "A" is a square matrix. If "A" is not a
6738 square matrix, it returns the characteristic polynomial of the map
6739 ``multiplication by "A"'' if "A" is a scalar, in particular a polmod.
6740 E.g. "charpoly(I) = x^2+1".
6741 The value of "flag" is only significant for matrices.
6743 If "flag = 0", the method used is essentially the same as for computing
6745 the adjoint matrix, i.e. computing the traces of the powers of "A".
6746 If "flag = 1", uses Lagrange interpolation which is almost always
6748 slower.
6749 If "flag = 2", uses the Hessenberg form. This is faster than the
6751 default when the coefficients are intmod a prime or real numbers, but
6752 is usually slower in other base rings.
6753 The library syntax is charpoly0"(A,v,flag)", where "v" is the variable
6755 number. Also available are the functions " caract(A,v)" ("flag = 1"), "
6756 carhess(A,v)" ("flag = 2"), and " caradj(A,v,pt)" where, in this last
6757 case, pt is a "GEN*" which, if not equal to "NULL", will receive the
6758 address of the adjoint matrix of "A" (see "matadjoint"), so both can be
6759 obtained at once.
6760 concat"(x,{y})"
6762 concatenation of "x" and "y". If "x" or "y" is not a vector or matrix,
6763 it is considered as a one-dimensional vector. All types are allowed for
6764 "x" and "y", but the sizes must be compatible. Note that matrices are
6765 concatenated horizontally, i.e. the number of rows stays the same.
6766 Using transpositions, it is easy to concatenate them vertically.
6767 To concatenate vectors sideways (i.e. to obtain a two-row or two-column
6769 matrix), use "Mat" instead (see the example there). Concatenating a row
6770 vector to a matrix having the same number of columns will add the row
6771 to the matrix (top row if the vector is "x", i.e. comes first, and
6772 bottom row otherwise).
6773 The empty matrix "[;]" is considered to have a number of rows
6775 compatible with any operation, in particular concatenation. (Note that
6776 this is definitely \emph{not} the case for empty vectors "[ ]" or
6777 "[ ]~".)
6778 If "y" is omitted, "x" has to be a row vector or a list, in which case
6780 its elements are concatenated, from left to right, using the above
6781 rules.
6782 ? concat([1,2], [3,4])
6784 %1 = [1, 2, 3, 4]
6785 ? a = [[1,2]~, [3,4]~]; concat(a)
6786 %2 =
6787 [1 3]
6788 [2 4]
6790 ? concat([1,2; 3,4], [5,6]~)
6792 %3 =
6793 [1 2 5]
6794 [3 4 6]
6796 ? concat([%, [7,8]~, [1,2,3,4]])
6797 %5 =
6798 [1 2 5 7]
6799 [3 4 6 8]
6801 [1 2 3 4]
6803 The library syntax is concat"(x,y)".
6805 lindep"(x,{flag = 0})"
6807 "x" being a vector with "p"-adic or real/complex coefficients, finds a
6808 small integral linear combination among these coefficients.
6809 If "x" is "p"-adic, "flag" is meaningless and the algorithm LLL-reduces
6811 a suitable (dual) lattice.
6812 Otherwise, the value of "flag" determines the algorithm used; in the
6814 current version of PARI, we suggest to use \emph{non-negative} values,
6815 since it is by far the fastest and most robust implementation. See the
6816 detailed example in "Label se:algdep" ("algdep").
6817 If "flag >= 0", uses a floating point (variable precision) LLL
6819 algorithm. This is in general much faster than the other variants. If
6820 "flag = 0" the accuracy is chosen internally using a crude heuristic.
6821 If "flag > 0" the computation is done with an accuracy of "flag"
6822 decimal digits. In that case, the parameter "flag" should be between
6823 0.6 and 0.9 times the number of correct decimal digits in the input.
6824 If "flag = -1", uses a variant of the LLL algorithm due to Hastad,
6826 Lagarias and Schnorr (STACS 1986). If the precision is too low, the
6827 routine may enter an infinite loop.
6828 If "flag = -2", "x" is allowed to be (and in any case interpreted as) a
6830 matrix. Returns a non trivial element of the kernel of "x", or 0 if
6831 "x" has trivial kernel. The element is defined over the field of
6832 coefficients of "x", and is in general not integral.
6833 If "flag = -3", uses the PSLQ algorithm. This may return a real number
6835 "B", indicating that the input accuracy was exhausted and that no
6836 relation exist whose sup norm is less than "B".
6837 If "flag = -4", uses an experimental 2-level PSLQ, which does not work
6839 at all. (Should be rewritten.)
6840 The library syntax is lindep0"(x,flag,prec)". Also available is "
6842 lindep(x,prec)" ("flag = 0").
6843 listcreate"(n)"
6845 creates an empty list of maximal length "n".
6846 This function is useless in library mode.
6848 listinsert"(list,x,n)"
6850 inserts the object "x" at position "n" in list (which must be of type
6851 "t_LIST"). All the remaining elements of list (from position "n+1"
6852 onwards) are shifted to the right. This and "listput" are the only
6853 commands which enable you to increase a list's effective length (as
6854 long as it remains under the maximal length specified at the time of
6855 the "listcreate").
6856 This function is useless in library mode.
6858 listkill"(list)"
6860 kill list. This deletes all elements from list and sets its effective
6861 length to 0. The maximal length is not affected.
6862 This function is useless in library mode.
6864 listput"(list,x,{n})"
6866 sets the "n"-th element of the list list (which must be of type
6867 "t_LIST") equal to "x". If "n" is omitted, or greater than the list
6868 current effective length, just appends "x". This and "listinsert" are
6869 the only commands which enable you to increase a list's effective
6870 length (as long as it remains under the maximal length specified at the
6871 time of the "listcreate").
6872 If you want to put an element into an occupied cell, i.e. if you don't
6874 want to change the effective length, you can consider the list as a
6875 vector and use the usual "list[n] = x" construct.
6876 This function is useless in library mode.
6878 listsort"(list,{flag = 0})"
6880 sorts list (which must be of type "t_LIST") in place. If "flag" is non-
6881 zero, suppresses all repeated coefficients. This is much faster than
6882 the "vecsort" command since no copy has to be made.
6883 This function is useless in library mode.
6885 matadjoint"(x)"
6887 adjoint matrix of "x", i.e. the matrix "y" of cofactors of "x",
6888 satisfying "x*y = det (x)*\Id". "x" must be a (non-necessarily
6889 invertible) square matrix.
6890 The library syntax is adj"(x)".
6892 matcompanion"(x)"
6894 the left companion matrix to the polynomial "x".
6895 The library syntax is assmat"(x)".
6897 matdet"(x,{flag = 0})"
6899 determinant of "x". "x" must be a square matrix.
6900 If "flag = 0", uses Gauss-Bareiss.
6902 If "flag = 1", uses classical Gaussian elimination, which is better
6904 when the entries of the matrix are reals or integers for example, but
6905 usually much worse for more complicated entries like multivariate
6906 polynomials.
6907 The library syntax is det"(x)" ("flag = 0") and " det2(x)" ("flag =
6909 1").
6910 matdetint"(x)"
6912 "x" being an "m x n" matrix with integer coefficients, this function
6913 computes a \emph{multiple} of the determinant of the lattice generated
6914 by the columns of "x" if it is of rank "m", and returns zero otherwise.
6915 This function can be useful in conjunction with the function
6916 "mathnfmod" which needs to know such a multiple. To obtain the exact
6917 determinant (assuming the rank is maximal), you can compute
6918 "matdet(mathnfmod(x, matdetint(x)))".
6919 Note that as soon as one of the dimensions gets large ("m" or "n" is
6921 larger than 20, say), it will often be much faster to use "mathnf(x,
6922 1)" or "mathnf(x, 4)" directly.
6923 The library syntax is detint"(x)".
6925 matdiagonal"(x)"
6927 "x" being a vector, creates the diagonal matrix whose diagonal entries
6928 are those of "x".
6929 The library syntax is diagonal"(x)".
6931 mateigen"(x)"
6933 gives the eigenvectors of "x" as columns of a matrix.
6934 The library syntax is eigen"(x)".
6936 matfrobenius"(M,{flag = 0},{v = x})"
6938 returns the Frobenius form of the square matrix "M". If "flag = 1",
6939 returns only the elementary divisors as a vectr of polynomials in the
6940 variable "v". If "flag = 2", returns a two-components vector [F,B]
6941 where "F" is the Frobenius form and "B" is the basis change so that "M
6942 = B^{-1}FB".
6943 The library syntax is matfrobenius"(M,flag,v)", where "v" is the
6945 variable number.
6946 mathess"(x)"
6948 Hessenberg form of the square matrix "x".
6949 The library syntax is hess"(x)".
6951 mathilbert"(x)"
6953 "x" being a "long", creates the Hilbert matrixof order "x", i.e. the
6954 matrix whose coefficient ("i","j") is "1/ (i+j-1)".
6955 The library syntax is mathilbert"(x)".
6957 mathnf"(x,{flag = 0})"
6959 if "x" is a (not necessarily square) matrix with integer entries, finds
6960 the \emph{upper triangular} Hermite normal form of "x". If the rank of
6961 "x" is equal to its number of rows, the result is a square matrix. In
6962 general, the columns of the result form a basis of the lattice spanned
6963 by the columns of "x".
6964 If "flag = 0", uses the naive algorithm. This should never be used if
6966 the dimension is at all large (larger than 10, say). It is recommanded
6967 to use either "mathnfmod(x, matdetint(x))" (when "x" has maximal rank)
6968 or "mathnf(x, 1)". Note that the latter is in general faster than
6969 "mathnfmod", and also provides a base change matrix.
6970 If "flag = 1", uses Batut's algorithm, which is much faster than the
6972 default. Outputs a two-component row vector "[H,U]", where "H" is the
6973 \emph{upper triangular} Hermite normal form of "x" defined as above,
6974 and "U" is the unimodular transformation matrix such that "xU = [0|H]".
6975 "U" has in general huge coefficients, in particular when the kernel is
6976 large.
6977 If "flag = 3", uses Batut's algorithm, but outputs "[H,U,P]", such that
6979 "H" and "U" are as before and "P" is a permutation of the rows such
6980 that "P" applied to "xU" gives "H". The matrix "U" is smaller than with
6981 "flag = 1", but may still be large.
6982 If "flag = 4", as in case 1 above, but uses a heuristic variant of LLL
6984 reduction along the way. The matrix "U" is in general close to optimal
6985 (in terms of smallest "L_2" norm), but the reduction is slower than in
6986 case 1.
6987 The library syntax is mathnf0"(x,flag)". Also available are " hnf(x)"
6989 ("flag = 0") and " hnfall(x)" ("flag = 1"). To reduce \emph{huge} (say
6990 "400 x 400" and more) relation matrices (sparse with small entries),
6991 you can use the pair "hnfspec" / "hnfadd". Since this is rather
6992 technical and the calling interface may change, they are not documented
6993 yet. Look at the code in "basemath/alglin1.c".
6994 mathnfmod"(x,d)"
6996 if "x" is a (not necessarily square) matrix of maximal rank with
6997 integer entries, and "d" is a multiple of the (non-zero) determinant of
6998 the lattice spanned by the columns of "x", finds the \emph{upper
6999 triangular} Hermite normal form of "x".
7000 If the rank of "x" is equal to its number of rows, the result is a
7002 square matrix. In general, the columns of the result form a basis of
7003 the lattice spanned by the columns of "x". This is much faster than
7004 "mathnf" when "d" is known.
7005 The library syntax is hnfmod"(x,d)".
7007 mathnfmodid"(x,d)"
7009 outputs the (upper triangular) Hermite normal form of "x" concatenated
7010 with "d" times the identity matrix. Assumes that "x" has integer
7011 entries.
7012 The library syntax is hnfmodid"(x,d)".
7014 matid"(n)"
7016 creates the "n x n" identity matrix.
7017 The library syntax is matid"(n)" where "n" is a "long".
7019 Related functions are " gscalmat(x,n)", which creates "x" times the
7021 identity matrix ("x" being a "GEN" and "n" a "long"), and "
7022 gscalsmat(x,n)" which is the same when "x" is a "long".
7023 matimage"(x,{flag = 0})"
7025 gives a basis for the image of the matrix "x" as columns of a matrix. A
7026 priori the matrix can have entries of any type. If "flag = 0", use
7027 standard Gauss pivot. If "flag = 1", use "matsupplement".
7028 The library syntax is matimage0"(x,flag)". Also available is "
7030 image(x)" ("flag = 0").
7031 matimagecompl"(x)"
7033 gives the vector of the column indices which are not extracted by the
7034 function "matimage". Hence the number of components of matimagecompl(x)
7035 plus the number of columns of matimage(x) is equal to the number of
7036 columns of the matrix "x".
7037 The library syntax is imagecompl"(x)".
7039 matindexrank"(x)"
7041 "x" being a matrix of rank "r", gives two vectors "y" and "z" of length
7042 "r" giving a list of rows and columns respectively (starting from 1)
7043 such that the extracted matrix obtained from these two vectors using
7044 "vecextract(x,y,z)" is invertible.
7045 The library syntax is indexrank"(x)".
7047 matintersect"(x,y)"
7049 "x" and "y" being two matrices with the same number of rows each of
7050 whose columns are independent, finds a basis of the Q-vector space
7051 equal to the intersection of the spaces spanned by the columns of "x"
7052 and "y" respectively. See also the function "idealintersect", which
7053 does the same for free Z-modules.
7054 The library syntax is intersect"(x,y)".
7056 matinverseimage"(M,y)"
7058 gives a column vector belonging to the inverse image "z" of the column
7059 vector or matrix "y" by the matrix "M" if one exists (i.e such that "Mz
7060 = y"), the empty vector otherwise. To get the complete inverse image,
7061 it suffices to add to the result any element of the kernel of "x"
7062 obtained for example by "matker".
7063 The library syntax is inverseimage"(x,y)".
7065 matisdiagonal"(x)"
7067 returns true (1) if "x" is a diagonal matrix, false (0) if not.
7068 The library syntax is isdiagonal"(x)", and this returns a "long"
7070 integer.
7071 matker"(x,{flag = 0})"
7073 gives a basis for the kernel of the matrix "x" as columns of a matrix.
7074 A priori the matrix can have entries of any type.
7075 If "x" is known to have integral entries, set "flag = 1".
7077 Note: The library function "FpM_ker(x, p)", where "x" has integer
7079 entries \emph{reduced mod p} and "p" is prime, is equivalent to, but
7080 orders of magnitude faster than, "matker(x*Mod(1,p))" and needs much
7081 less stack space. To use it under "gp", type "install(FpM_ker, GG)"
7082 first.
7083 The library syntax is matker0"(x,flag)". Also available are " ker(x)"
7085 ("flag = 0"), " keri(x)" ("flag = 1").
7086 matkerint"(x,{flag = 0})"
7088 gives an LLL-reduced Z-basis for the lattice equal to the kernel of the
7089 matrix "x" as columns of the matrix "x" with integer entries (rational
7090 entries are not permitted).
7091 If "flag = 0", uses a modified integer LLL algorithm.
7093 If "flag = 1", uses "matrixqz(x,-2)". If LLL reduction of the final
7095 result is not desired, you can save time using "matrixqz(matker(x),-2)"
7096 instead.
7097 The library syntax is matkerint0"(x,flag)". Also available is "
7099 kerint(x)" ("flag = 0").
7100 matmuldiagonal"(x,d)"
7102 product of the matrix "x" by the diagonal matrix whose diagonal entries
7103 are those of the vector "d". Equivalent to, but much faster than
7104 "x*matdiagonal(d)".
7105 The library syntax is matmuldiagonal"(x,d)".
7107 matmultodiagonal"(x,y)"
7109 product of the matrices "x" and "y" assuming that the result is a
7110 diagonal matrix. Much faster than "x*y" in that case. The result is
7111 undefined if "x*y" is not diagonal.
7112 The library syntax is matmultodiagonal"(x,y)".
7114 matpascal"(x,{q})"
7116 creates as a matrix the lower triangular Pascal triangle of order "x+1"
7117 (i.e. with binomial coefficients up to "x"). If "q" is given, compute
7118 the "q"-Pascal triangle (i.e. using "q"-binomial coefficients).
7119 The library syntax is matqpascal"(x,q)", where "x" is a "long" and "q =
7121 NULL" is used to omit "q". Also available is " matpascal(x)".
7122 matrank"(x)"
7124 rank of the matrix "x".
7125 The library syntax is rank"(x)", and the result is a "long".
7127 matrix"(m,n,{X},{Y},{expr = 0})"
7129 creation of the "m x n" matrix whose coefficients are given by the
7130 expression expr. There are two formal parameters in expr, the first one
7131 ("X") corresponding to the rows, the second ("Y") to the columns, and
7132 "X" goes from 1 to "m", "Y" goes from 1 to "n". If one of the last 3
7133 parameters is omitted, fill the matrix with zeroes.
7134 The library syntax is matrice"(GEN nlig,GEN ncol,entree *e1,entree
7136 *e2,char *expr)".
7137 matrixqz"(x,p)"
7139 "x" being an "m x n" matrix with "m >= n" with rational or integer
7140 entries, this function has varying behaviour depending on the sign of
7141 "p":
7142 If "p >= 0", "x" is assumed to be of maximal rank. This function
7144 returns a matrix having only integral entries, having the same image as
7145 "x", such that the GCD of all its "n x n" subdeterminants is equal to 1
7146 when "p" is equal to 0, or not divisible by "p" otherwise. Here "p"
7147 must be a prime number (when it is non-zero). However, if the function
7148 is used when "p" has no small prime factors, it will either work or
7149 give the message ``impossible inverse modulo'' and a non-trivial
7150 divisor of "p".
7151 If "p = -1", this function returns a matrix whose columns form a basis
7153 of the lattice equal to "Z^n" intersected with the lattice generated by
7154 the columns of "x".
7155 If "p = -2", returns a matrix whose columns form a basis of the lattice
7157 equal to "Z^n" intersected with the Q-vector space generated by the
7158 columns of "x".
7159 The library syntax is matrixqz0"(x,p)".
7161 matsize"(x)"
7163 "x" being a vector or matrix, returns a row vector with two components,
7164 the first being the number of rows (1 for a row vector), the second the
7165 number of columns (1 for a column vector).
7166 The library syntax is matsize"(x)".
7168 matsnf"(X,{flag = 0})"
7170 if "X" is a (singular or non-singular) matrix outputs the vector of
7171 elementary divisors of "X" (i.e. the diagonal of the Smith normal form
7172 of "X").
7173 The binary digits of flag mean:
7175 1 (complete output): if set, outputs "[U,V,D]", where "U" and "V" are
7177 two unimodular matrices such that "UXV" is the diagonal matrix "D".
7178 Otherwise output only the diagonal of "D".
7179 2 (generic input): if set, allows polynomial entries, in which case the
7181 input matrix must be square. Otherwise, assume that "X" has integer
7182 coefficients with arbitrary shape.
7183 4 (cleanup): if set, cleans up the output. This means that elementary
7185 divisors equal to 1 will be deleted, i.e. outputs a shortened vector
7186 "D'" instead of "D". If complete output was required, returns
7187 "[U',V',D']" so that "U'XV' = D'" holds. If this flag is set, "X" is
7188 allowed to be of the form "D" or "[U,V,D]" as would normally be output
7189 with the cleanup flag unset.
7190 The library syntax is matsnf0"(X,flag)". Also available is " smith(X)"
7192 ("flag = 0").
7193 matsolve"(x,y)"
7195 "x" being an invertible matrix and "y" a column vector, finds the
7196 solution "u" of "x*u = y", using Gaussian elimination. This has the
7197 same effect as, but is a bit faster, than "x^{-1}*y".
7198 The library syntax is gauss"(x,y)".
7200 matsolvemod"(m,d,y,{flag = 0})"
7202 "m" being any integral matrix, "d" a vector of positive integer moduli,
7203 and "y" an integral column vector, gives a small integer solution to
7204 the system of congruences "sum_i m_{i,j}x_j = y_i (mod d_i)" if one
7205 exists, otherwise returns zero. Shorthand notation: "y" (resp. "d") can
7206 be given as a single integer, in which case all the "y_i" (resp. "d_i")
7207 above are taken to be equal to "y" (resp. "d").
7208 ? m = [1,2;3,4];
7210 ? matsolvemod(m, [3,4], [1,2]~)
7211 %2 = [-2, 0]~
7212 ? matsolvemod(m, 3, 1) \\ m X = [1,1]~ over F_3
7213 %3 = [-1, 1]~
7214 If "flag = 1", all solutions are returned in the form of a two-
7216 component row vector "[x,u]", where "x" is a small integer solution to
7217 the system of congruences and "u" is a matrix whose columns give a
7218 basis of the homogeneous system (so that all solutions can be obtained
7219 by adding "x" to any linear combination of columns of "u"). If no
7220 solution exists, returns zero.
7221 The library syntax is matsolvemod0"(m,d,y,flag)". Also available are "
7223 gaussmodulo(m,d,y)" ("flag = 0") and " gaussmodulo2(m,d,y)" ("flag =
7224 1").
7225 matsupplement"(x)"
7227 assuming that the columns of the matrix "x" are linearly independent
7228 (if they are not, an error message is issued), finds a square
7229 invertible matrix whose first columns are the columns of "x",
7230 i.e. supplement the columns of "x" to a basis of the whole space.
7231 The library syntax is suppl"(x)".
7233 mattranspose"(x)" or "x~"
7235 transpose of "x". This has an effect only on vectors and matrices.
7236 The library syntax is gtrans"(x)".
7238 minpoly"(A,{v = x},{flag = 0})"
7240 minimal polynomial of "A" with respect to the variable "v"., i.e. the
7241 monic polynomial "P" of minimal degree (in the variable "v") such that
7242 "P(A) = 0".
7243 The library syntax is minpoly"(A,v)", where "v" is the variable number.
7245 qfgaussred"(q)"
7247 decomposition into squares of the quadratic form represented by the
7248 symmetric matrix "q". The result is a matrix whose diagonal entries are
7249 the coefficients of the squares, and the non-diagonal entries represent
7250 the bilinear forms. More precisely, if "(a_{ij})" denotes the output,
7251 one has
7252 " q(x) = sum_i a_{ii} (x_i + sum_{j > i} a_{ij} x_j)^2 "
7254 The library syntax is sqred"(x)".
7256 qfjacobi"(x)"
7258 "x" being a real symmetric matrix, this gives a vector having two
7259 components: the first one is the vector of eigenvalues of "x", the
7260 second is the corresponding orthogonal matrix of eigenvectors of "x".
7261 The method used is Jacobi's method for symmetric matrices.
7262 The library syntax is jacobi"(x)".
7264 qflll"(x,{flag = 0})"
7266 LLL algorithm applied to the \emph{columns} of the matrix "x". The
7267 columns of "x" must be linearly independent, unless specified otherwise
7268 below. The result is a unimodular transformation matrix "T" such that
7269 "x.T" is an LLL-reduced basis of the lattice generated by the column
7270 vectors of "x".
7271 If "flag = 0" (default), the computations are done with floating point
7273 numbers, using Householder matrices for orthogonalization. If "x" has
7274 integral entries, then computations are nonetheless approximate, with
7275 precision varying as needed (Lehmer's trick, as generalized by
7276 Schnorr).
7277 If "flag = 1", it is assumed that "x" is integral. The computation is
7279 done entirely with integers. In this case, "x" needs not be of maximal
7280 rank, but if it is not, "T" will not be square. This is slower and no
7281 more accurate than "flag = 0" above if "x" has small dimension (say 100
7282 or less).
7283 If "flag = 2", "x" should be an integer matrix whose columns are
7285 linearly independent. Returns a partially reduced basis for "x", using
7286 an unpublished algorithm by Peter Montgomery: a basis is said to be
7287 \emph{partially reduced} if "|v_i +- v_j| >= |v_i|" for any two
7288 distinct basis vectors "v_i, v_j".
7289 This is significantly faster than "flag = 1", esp. when one row is huge
7291 compared to the other rows. Note that the resulting basis is \emph{not}
7292 LLL-reduced in general.
7293 If "flag = 4", "x" is assumed to have integral entries, but needs not
7295 be of maximal rank. The result is a two-component vector of matrices:
7296 the columns of the first matrix represent a basis of the integer kernel
7297 of "x" (not necessarily LLL-reduced) and the second matrix is the
7298 transformation matrix "T" such that "x.T" is an LLL-reduced Z-basis of
7299 the image of the matrix "x".
7300 If "flag = 5", case as case 4, but "x" may have polynomial
7302 coefficients.
7303 If "flag = 8", same as case 0, but "x" may have polynomial
7305 coefficients.
7306 The library syntax is qflll0"(x,flag,prec)". Also available are "
7308 lll(x,prec)" ("flag = 0"), " lllint(x)" ("flag = 1"), and "
7309 lllkerim(x)" ("flag = 4").
7310 qflllgram"(G,{flag = 0})"
7312 same as "qflll", except that the matrix "G = x~ * x" is the Gram matrix
7313 of some lattice vectors "x", and not the coordinates of the vectors
7314 themselves. In particular, "G" must now be a square symmetric real
7315 matrix, corresponding to a positive definite quadratic form. The result
7316 is a unimodular transformation matrix "T" such that "x.T" is an LLL-
7317 reduced basis of the lattice generated by the column vectors of "x".
7318 If "flag = 0" (default): the computations are done with floating point
7320 numbers, using Householder matrices for orthogonalization. If "G" has
7321 integral entries, then computations are nonetheless approximate, with
7322 precision varying as needed (Lehmer's trick, as generalized by
7323 Schnorr).
7324 If "flag = 1": "G" has integer entries, still positive but not
7326 necessarily definite (i.e "x" needs not have maximal rank). The
7327 computations are all done in integers and should be slower than the
7328 default, unless the latter triggers accuracy problems.
7329 "flag = 4": "G" has integer entries, gives the kernel and reduced image
7331 of "x".
7332 "flag = 5": same as case 4, but "G" may have polynomial coefficients.
7334 The library syntax is qflllgram0"(G,flag,prec)". Also available are "
7336 lllgram(G,prec)" ("flag = 0"), " lllgramint(G)" ("flag = 1"), and "
7337 lllgramkerim(G)" ("flag = 4").
7338 qfminim"(x,{b},{m},{flag = 0})"
7340 "x" being a square and symmetric matrix representing a positive
7341 definite quadratic form, this function deals with the vectors of "x"
7342 whose norm is less than or equal to "b", enumerated using the Fincke-
7343 Pohst algorithm. The function searches for the minimal non-zero vectors
7344 if "b" is omitted. The precise behaviour depends on "flag".
7345 If "flag = 0" (default), seeks at most "2m" vectors. The result is a
7347 three-component vector, the first component being the number of vectors
7348 found, the second being the maximum norm found, and the last vector is
7349 a matrix whose columns are the vectors found, only one being given for
7350 each pair "+- v" (at most "m" such pairs). The vectors are returned in
7351 no particular order. In this variant, an explicit "m" must be provided.
7352 If "flag = 1", ignores "m" and returns the first vector whose norm is
7354 less than "b". In this variant, an explicit "b" must be provided.
7355 In both these cases, "x" is assumed to have integral entries. The
7357 implementation uses low precision floating point computations for
7358 maximal speed, which gives incorrect result when "x" has large entries.
7359 (The condition is checked in the code and the routine will raise an
7360 error if large rounding errors occur.) A more robust, but much slower,
7361 implementation is chosen if the following flag is used:
7362 If "flag = 2", "x" can have non integral real entries. In this case, if
7364 "b" is omitted, the ``minimal'' vectors only have approximately the
7365 same norm. If "b" is omitted, "m" is an upper bound for the number of
7366 vectors that will be stored and returned, but all minimal vectors are
7367 nevertheless enumerated. If "m" is omitted, all vectors found are
7368 stored and returned; note that this may be a huge vector!
7369 The library syntax is qfminim0"(x,b,m,flag,prec)", also available are "
7371 minim(x,b,m)" ("flag = 0"), " minim2(x,b,m)" ("flag = 1"). In all
7372 cases, an omitted "b" or "m" is coded as "NULL".
7373 qfperfection"(x)"
7375 "x" being a square and symmetric matrix with integer entries
7376 representing a positive definite quadratic form, outputs the perfection
7377 rank of the form. That is, gives the rank of the family of the "s"
7378 symmetric matrices "v_iv_i^t", where "s" is half the number of minimal
7379 vectors and the "v_i" ("1 <= i <= s") are the minimal vectors.
7380 As a side note to old-timers, this used to fail bluntly when "x" had
7382 more than 5000 minimal vectors. Beware that the computations can now be
7383 very lengthy when "x" has many minimal vectors.
7384 The library syntax is perf"(x)".
7386 qfrep"(q, B, {flag = 0})"
7388 "q" being a square and symmetric matrix with integer entries
7389 representing a positive definite quadratic form, outputs the vector
7390 whose "i"-th entry, "1 <= i <= B" is half the number of vectors "v"
7391 such that "q(v) = i". This routine uses a naive algorithm based on
7392 "qfminim", and will fail if any entry becomes larger than "2^{31}".
7393 The binary digits of flag mean:
7395 \item 1: count vectors of even norm from 1 to "2B".
7397 \item 2: return a "t_VECSMALL" instead of a "t_GEN"
7399 The library syntax is qfrep0"(q, B, flag)".
7401 qfsign"(x)"
7403 signature of the quadratic form represented by the symmetric matrix
7404 "x". The result is a two-component vector.
7405 The library syntax is signat"(x)".
7407 setintersect"(x,y)"
7409 intersection of the two sets "x" and "y".
7410 The library syntax is setintersect"(x,y)".
7412 setisset"(x)"
7414 returns true (1) if "x" is a set, false (0) if not. In PARI, a set is
7415 simply a row vector whose entries are strictly increasing. To convert
7416 any vector (and other objects) into a set, use the function "Set".
7417 The library syntax is setisset"(x)", and this returns a "long".
7419 setminus"(x,y)"
7421 difference of the two sets "x" and "y", i.e. set of elements of "x"
7422 which do not belong to "y".
7423 The library syntax is setminus"(x,y)".
7425 setsearch"(x,y,{flag = 0})"
7427 searches if "y" belongs to the set "x". If it does and "flag" is zero
7428 or omitted, returns the index "j" such that "x[j] = y", otherwise
7429 returns 0. If "flag" is non-zero returns the index "j" where "y" should
7430 be inserted, and 0 if it already belongs to "x" (this is meant to be
7431 used in conjunction with "listinsert").
7432 This function works also if "x" is a \emph{sorted} list (see
7434 "listsort").
7435 The library syntax is setsearch"(x,y,flag)" which returns a "long"
7437 integer.
7438 setunion"(x,y)"
7440 union of the two sets "x" and "y".
7441 The library syntax is setunion"(x,y)".
7443 trace"(x)"
7445 this applies to quite general "x". If "x" is not a matrix, it is equal
7446 to the sum of "x" and its conjugate, except for polmods where it is the
7447 trace as an algebraic number.
7448 For "x" a square matrix, it is the ordinary trace. If "x" is a non-
7450 square matrix (but not a vector), an error occurs.
7451 The library syntax is gtrace"(x)".
7453 vecextract"(x,y,{z})"
7455 extraction of components of the vector or matrix "x" according to "y".
7456 In case "x" is a matrix, its components are as usual the \emph{columns}
7457 of "x". The parameter "y" is a component specifier, which is either an
7458 integer, a string describing a range, or a vector.
7459 If "y" is an integer, it is considered as a mask: the binary bits of
7461 "y" are read from right to left, but correspond to taking the
7462 components from left to right. For example, if "y = 13 = (1101)_2" then
7463 the components 1,3 and 4 are extracted.
7464 If "y" is a vector, which must have integer entries, these entries
7466 correspond to the component numbers to be extracted, in the order
7467 specified.
7468 If "y" is a string, it can be
7470 \item a single (non-zero) index giving a component number (a negative
7472 index means we start counting from the end).
7473 \item a range of the form "a..b", where "a" and "b" are indexes as
7475 above. Any of "a" and "b" can be omitted; in this case, we take as
7476 default values "a = 1" and "b = -1", i.e. the first and last components
7477 respectively. We then extract all components in the interval "[a,b]",
7478 in reverse order if "b < a".
7479 In addition, if the first character in the string is "^", the
7481 complement of the given set of indices is taken.
7482 If "z" is not omitted, "x" must be a matrix. "y" is then the
7484 \emph{line} specifier, and "z" the \emph{column} specifier, where the
7485 component specifier is as explained above.
7486 ? v = [a, b, c, d, e];
7488 ? vecextract(v, 5) \\ mask
7489 %1 = [a, c]
7490 ? vecextract(v, [4, 2, 1]) \\ component list
7491 %2 = [d, b, a]
7492 ? vecextract(v, "2..4") \\ interval
7493 %3 = [b, c, d]
7494 ? vecextract(v, "-1..-3") \\ interval + reverse order
7495 %4 = [e, d, c]
7496 ? vecextract(v, "^2") \\ complement
7497 %5 = [a, c, d, e]
7498 ? vecextract(matid(3), "2..", "..")
7499 %6 =
7500 [0 1 0]
7501 [0 0 1]
7503 The library syntax is extract"(x,y)" or " matextract(x,y,z)".
7505 vecsort"(x,{k},{flag = 0})"
7507 sorts the vector "x" in ascending order, using a mergesort method. "x"
7508 must be a vector, and its components integers, reals, or fractions.
7509 If "k" is present and is an integer, sorts according to the value of
7511 the "k"-th subcomponents of the components of "x". Note that mergesort
7512 is stable, hence is the initial ordering of "equal" entries (with
7513 respect to the sorting criterion) is not changed.
7514 "k" can also be a vector, in which case the sorting is done
7516 lexicographically according to the components listed in the vector "k".
7517 For example, if "k = [2,1,3]", sorting will be done with respect to the
7518 second component, and when these are equal, with respect to the first,
7519 and when these are equal, with respect to the third.
7520 The binary digits of flag mean:
7522 \item 1: indirect sorting of the vector "x", i.e. if "x" is an
7524 "n"-component vector, returns a permutation of "[1,2,...,n]" which
7525 applied to the components of "x" sorts "x" in increasing order. For
7526 example, "vecextract(x, vecsort(x,,1))" is equivalent to vecsort(x).
7527 \item 2: sorts "x" by ascending lexicographic order (as per the "lex"
7529 comparison function).
7530 \item 4: use descending instead of ascending order.
7532 The library syntax is vecsort0"(x,k,flag)". To omit "k", use "NULL"
7534 instead. You can also use the simpler functions
7535 " sort(x)" ( = " vecsort0(x,NULL,0)").
7537 " indexsort(x)" ( = " vecsort0(x,NULL,1)").
7539 " lexsort(x)" ( = " vecsort0(x,NULL,2)").
7541 Also available are " sindexsort(x)" and " sindexlexsort(x)" which
7543 return a "t_VECSMALL" "v", where "v[1]...v[n]" contain the indices.
7544 vector"(n,{X},{expr = 0})"
7546 creates a row vector (type "t_VEC") with "n" components whose
7547 components are the expression expr evaluated at the integer points
7548 between 1 and "n". If one of the last two arguments is omitted, fill
7549 the vector with zeroes.
7550 Avoid modifying "X" within expr; if you do, the formal variable still
7552 runs from 1 to "n". In particular, "vector(n,i,expr)" is not equivalent
7553 to
7554 v = vector(n)
7556 for (i = 1, n, v[i] = expr)
7557 as the following example shows:
7559 n = 3
7561 v = vector(n); vector(n, i, i++) ----> [2, 3, 4]
7562 v = vector(n); for (i = 1, n, v[i] = i++) ----> [2, 0, 4]
7563 The library syntax is vecteur"(GEN nmax, entree *ep, char *expr)".
7565 vectorsmall"(n,{X},{expr = 0})"
7567 creates a row vector of small integers (type "t_VECSMALL") with "n"
7568 components whose components are the expression expr evaluated at the
7569 integer points between 1 and "n". If one of the last two arguments is
7570 omitted, fill the vector with zeroes.
7571 The library syntax is vecteursmall"(GEN nmax, entree *ep, char *expr)".
7573 vectorv"(n,X,expr)"
7575 as "vector", but returns a column vector (type "t_COL").
7576 The library syntax is vvecteur"(GEN nmax, entree *ep, char *expr)".
7578
7580 Although the "gp" calculator is programmable, it is useful to have
7581 preprogrammed a number of loops, including sums, products, and a
7582 certain number of recursions. Also, a number of functions from
7583 numerical analysis like numerical integration and summation of series
7584 will be described here.
7585 One of the parameters in these loops must be the control variable,
7587 hence a simple variable name. In the descriptions, the letter "X" will
7588 always denote any simple variable name, and represents the formal
7589 parameter used in the function. The expression to be summed,
7590 integrated, etc. is any legal PARI expression, including of course
7591 expressions using loops.
7592 Library mode. Since it is easier to program directly the loops in
7594 library mode, these functions are mainly useful for GP programming.
7595 Using them in library mode is tricky and we will not give any details,
7596 although the reader can try and figure it out by himself by checking
7597 the example given for "sum".
7598 On the other hand, numerical routines code a function (to be
7600 integrated, summed, etc.) with two parameters named
7601 GEN (*eval)(GEN,void*)
7603 void *E;
7604 The second is meant to contain all auxilliary data needed by your
7606 function. The first is such that "eval(x, E)" returns your function
7607 evaluated at "x". For instance, one may code the family of functions
7608 "f_t: x \to (x+t)^2" via
7609 GEN f(GEN x, void *t) { return gsqr(gadd(x, (GEN)t)); }
7611 One can then integrate "f_1" between "a" and "b" with the call
7613 intnum((void*)stoi(1), &fun, a, b, NULL, prec);
7615 Since you can set "E" to a pointer to any "struct" (typecast to
7617 "void*") the above mechanism handles arbitrary functions. For simple
7618 functions without extra parameters, you may set "E = NULL" and ignore
7619 that argument in your function definition.
7620 Numerical integration. Starting with version 2.2.9 the powerful
7622 ``double exponential'' univariate integration method is implemented in
7623 "intnum" and its variants. Romberg integration is still available under
7624 the name "intnumromb", but superseded. It is possible to compute
7625 numerically integrals to thousands of decimal places in reasonable
7626 time, as long as the integrand is regular. It is also reasonable to
7627 compute numerically integrals in several variables, although more than
7628 two becomes lengthy. The integration domain may be non-compact, and the
7629 integrand may have reasonable singularities at endpoints. To use
7630 "intnum", the user must split the integral into a sum of subintegrals
7631 where the function has (possible) singularities only at the endpoints.
7632 Polynomials in logarithms are not considered singular, and neglecting
7633 these logs, singularities are assumed to be algebraic (in other words
7634 asymptotic to "C(x-a)^{-alpha}" for some "alpha" such that "alpha > -1"
7635 when "x" is close to "a"), or to correspond to simple discontinuities
7636 of some (higher) derivative of the function. For instance, the point 0
7637 is a singularity of abs(x).
7638 See also the discrete summation methods below (sharing the prefix
7640 "sum").
7641 intcirc"(X = a,R,expr, {tab})"
7643 numerical integration of expr with respect to "X" on the circle "|X-a
7644 |= R", divided by "2iPi". In other words, when expr is a meromorphic
7645 function, sum of the residues in the corresponding disk. tab is as in
7646 "intnum", except that if computed with "intnuminit" it should be with
7647 the endpoints "[-1, 1]".
7648 ? \p105
7650 ? intcirc(s=1, 0.5, zeta(s)) - 1
7651 time = 3,460 ms.
7652 %1 = -2.40... E-104 - 2.7... E-106*I
7653 The library syntax is intcirc"(void *E, GEN (*eval)(GEN,void*), GEN
7655 a,GEN R,GEN tab, long prec)".
7656 intfouriercos"(X = a,b,z,expr,{tab})"
7658 numerical integration of "expr(X) cos (2Pi zX)" from "a" to "b", in
7659 other words Fourier cosine transform (from "a" to "b") of the function
7660 represented by expr. "a" and "b" are coded as in "intnum", and are not
7661 necessarily at infinity, but if they are, oscillations (i.e.
7662 "[[+-1],alpha I]") are forbidden.
7663 The library syntax is intfouriercos"(void *E, GEN (*eval)(GEN,void*),
7665 GEN a, GEN b, GEN z, GEN tab, long prec)".
7666 intfourierexp"(X = a,b,z,expr,{tab})"
7668 numerical integration of "expr(X) exp (-2Pi zX)" from "a" to "b", in
7669 other words Fourier transform (from "a" to "b") of the function
7670 represented by expr. Note the minus sign. "a" and "b" are coded as in
7671 "intnum", and are not necessarily at infinity but if they are,
7672 oscillations (i.e. "[[+-1],alpha I]") are forbidden.
7673 The library syntax is intfourierexp"(void *E, GEN (*eval)(GEN,void*),
7675 GEN a, GEN b, GEN z, GEN tab, long prec)".
7676 intfouriersin"(X = a,b,z,expr,{tab})"
7678 numerical integration of "expr(X) sin (2Pi zX)" from "a" to "b", in
7679 other words Fourier sine transform (from "a" to "b") of the function
7680 represented by expr. "a" and "b" are coded as in "intnum", and are not
7681 necessarily at infinity but if they are, oscillations (i.e.
7682 "[[+-1],alpha I]") are forbidden.
7683 The library syntax is intfouriersin"(void *E, GEN (*eval)(GEN,void*),
7685 GEN a, GEN b, GEN z, GEN tab, long prec)".
7686 intfuncinit"(X = a,b,expr,{flag = 0},{m = 0})"
7688 initalize tables for use with integral transforms such as
7689 "intmellininv", etc., where "a" and "b" are coded as in "intnum",
7690 "expr" is the function s(X) to which the integral transform is to be
7691 applied (which will multiply the weights of integration) and "m" is as
7692 in "intnuminit". If "flag" is nonzero, assumes that "s(-X) =
7693 \overline{s(X)}", which makes the computation twice as fast. See
7694 "intmellininvshort" for examples of the use of this function, which is
7695 particularly useful when the function s(X) is lengthy to compute, such
7696 as a gamma product.
7697 The library syntax is intfuncinit"(void *E, GEN (*eval)(GEN,void*), GEN
7699 a,GEN b,long m, long flag, long prec)". Note that the order of "m" and
7700 "flag" are reversed compared to the "GP" syntax.
7701 intlaplaceinv"(X = sig,z,expr,{tab})"
7703 numerical integration of "expr(X)e^{Xz}" with respect to "X" on the
7704 line " Re (X) = sig", divided by "2iPi", in other words, inverse
7705 Laplace transform of the function corresponding to expr at the value
7706 "z".
7707 "sig" is coded as follows. Either it is a real number "sigma", equal to
7709 the abcissa of integration, and then the function to be integrated is
7710 assumed to be slowly decreasing when the imaginary part of the variable
7711 tends to "+- oo ". Or it is a two component vector "[sigma,alpha]",
7712 where "sigma" is as before, and either "alpha = 0" for slowly
7713 decreasing functions, or "alpha > 0" for functions decreasing like "
7714 exp (-alpha t)". Note that it is not necessary to choose the exact
7715 value of "alpha". tab is as in "intnum".
7716 It is often a good idea to use this function with a value of "m" one or
7718 two higher than the one chosen by default (which can be viewed thanks
7719 to the function "intnumstep"), or to increase the abcissa of
7720 integration "sigma". For example:
7721 ? \p 105
7723 ? intlaplaceinv(x=2, 1, 1/x) - 1
7724 time = 350 ms.
7725 %1 = 7.37... E-55 + 1.72... E-54*I \\ not so good
7726 ? m = intnumstep()
7727 %2 = 7
7728 ? intlaplaceinv(x=2, 1, 1/x, m+1) - 1
7729 time = 700 ms.
7730 %3 = 3.95... E-97 + 4.76... E-98*I \\ better
7731 ? intlaplaceinv(x=2, 1, 1/x, m+2) - 1
7732 time = 1400 ms.
7733 %4 = 0.E-105 + 0.E-106*I \\ perfect but slow.
7734 ? intlaplaceinv(x=5, 1, 1/x) - 1
7735 time = 340 ms.
7736 %5 = -5.98... E-85 + 8.08... E-85*I \\ better than %1
7737 ? intlaplaceinv(x=5, 1, 1/x, m+1) - 1
7738 time = 680 ms.
7739 %6 = -1.09... E-106 + 0.E-104*I \\ perfect, fast.
7740 ? intlaplaceinv(x=10, 1, 1/x) - 1
7741 time = 340 ms.
7742 %7 = -4.36... E-106 + 0.E-102*I \\ perfect, fastest, but why sig = 10?
7743 ? intlaplaceinv(x=100, 1, 1/x) - 1
7744 time = 330 ms.
7745 %7 = 1.07... E-72 + 3.2... E-72*I \\ too far now...
7746 The library syntax is intlaplaceinv"(void *E, GEN (*eval)(GEN,void*),
7748 GEN sig,GEN z, GEN tab, long prec)".
7749 intmellininv"(X = sig,z,expr,{tab})"
7751 numerical integration of "expr(X)z^{-X}" with respect to "X" on the
7752 line " Re (X) = sig", divided by "2iPi", in other words, inverse Mellin
7753 transform of the function corresponding to expr at the value "z".
7754 "sig" is coded as follows. Either it is a real number "sigma", equal to
7756 the abcissa of integration, and then the function to be integrated is
7757 assumed to decrease exponentially fast, of the order of " exp (-t)"
7758 when the imaginary part of the variable tends to "+- oo ". Or it is a
7759 two component vector "[sigma,alpha]", where "sigma" is as before, and
7760 either "alpha = 0" for slowly decreasing functions, or "alpha > 0" for
7761 functions decreasing like " exp (-alpha t)", such as gamma products.
7762 Note that it is not necessary to choose the exact value of "alpha", and
7763 that "alpha = 1" (equivalent to "sig" alone) is usually sufficient. tab
7764 is as in "intnum".
7765 As all similar functions, this function is provided for the convenience
7767 of the user, who could use "intnum" directly. However it is in general
7768 better to use "intmellininvshort".
7769 ? \p 105
7771 ? intmellininv(s=2,4, gamma(s)^3);
7772 time = 1,190 ms. \\ reasonable.
7773 ? \p 308
7774 ? intmellininv(s=2,4, gamma(s)^3);
7775 time = 51,300 ms. \\ slow because of Gamma(s)^3.
7776 The library syntax is intmellininv"(void *E, GEN (*eval)(GEN,void*),
7778 GEN sig, GEN z, GEN tab, long prec)".
7779 intmellininvshort"(sig,z,tab)"
7781 numerical integration of "s(X)z^{-X}" with respect to "X" on the line "
7782 Re (X) = sig", divided by "2iPi", in other words, inverse Mellin
7783 transform of s(X) at the value "z". Here s(X) is implicitly contained
7784 in tab in "intfuncinit" format, typically
7785 tab = intfuncinit(T = [-1], [1], s(sig + I*T))
7787 or similar commands. Take the example of the inverse Mellin transform
7789 of "Gamma(s)^3" given in "intmellininv":
7790 ? \p 105
7792 ? oo = [1]; \\ for clarity
7793 ? A = intmellininv(s=2,4, gamma(s)^3);
7794 time = 2,500 ms. \\ not too fast because of Gamma(s)^3.
7795 \\ function of real type, decreasing as exp(-3Pi/2.|t|)
7796 ? tab = intfuncinit(t=[-oo, 3*Pi/2],[oo, 3*Pi/2], gamma(2+I*t)^3, 1);
7797 time = 1,370 ms.
7798 ? intmellininvshort(2,4, tab) - A
7799 time = 50 ms.
7800 %4 = -1.26... - 3.25...E-109*I \\ 50 times faster than A and perfect.
7801 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7802 ? intmellininvshort(2,4, tab2)
7803 %6 = -1.2...E-42 - 3.2...E-109*I \\ 63 digits lost
7804 In the computation of tab, it was not essential to include the
7806 \emph{exact} exponential decrease of "Gamma(2+it)^3". But as the last
7807 example shows, a rough indication \emph{must} be given, otherwise slow
7808 decrease is assumed, resulting in catastrophic loss of accuracy.
7809 The library syntax is intmellininvshort"(GEN sig, GEN z, GEN tab, long
7811 prec)".
7812 intnum"(X = a,b,expr,{tab})"
7814 numerical integration of expr on "[a,b]" (possibly infinite interval)
7815 with respect to "X", where "a" and "b" are coded as explained below.
7816 The integrand may have values belonging to a vector space over the real
7817 numbers; in particular, it can be complex-valued or vector-valued.
7818 If tab is omitted, necessary integration tables are computed using
7820 "intnuminit" according to the current precision. It may be a positive
7821 integer "m", and tables are computed assuming the integration step is
7822 "1/2^m". Finally tab can be a table output by "intnuminit", in which
7823 case it is used directly. This is important if several integrations of
7824 the same type are performed (on the same kind of interval and
7825 functions, and the same accuracy), since it saves expensive
7826 precomputations.
7827 If tab is omitted the algorithm guesses a reasonable value for "m"
7829 depending on the current precision. That value may be obtained as
7830 intnumstep()
7832 However this value may be off from the optimal one, and this is
7834 important since the integration time is roughly proportional to "2^m".
7835 One may try consecutive values of "m" until they give the same value up
7836 to an accepted error.
7837 The endpoints "a" and "b" are coded as follows. If "a" is not at "+- oo
7839 ", it is either coded as a scalar (real or complex), or as a two
7840 component vector "[a,alpha]", where the function is assumed to have a
7841 singularity of the form "(x-a)^{alpha+\epsilon}" at "a", where
7842 "\epsilon" indicates that powers of logarithms are neglected. In
7843 particular, "[a,alpha]" with "alpha >= 0" is equivalent to "a". If a
7844 wrong singularity exponent is used, the result will lose a catastrophic
7845 number of decimals, for instance approximately half the number of
7846 digits will be correct if "alpha = -1/2" is omitted.
7847 The endpoints of integration can be "+- oo ", which is coded as "[+-
7849 1]" or as "[[+-1],alpha]". Here "alpha" codes the behaviour of the
7850 function at "+- oo " as follows.
7851 \item "alpha = 0" (or no "alpha" at all, i.e. simply "[+-1]") assumes
7853 that the function to be integrated tends to zero, but not exponentially
7854 fast, and not oscillating such as " sin (x)/x".
7855 \item "alpha > 0" assumes that the function tends to zero exponentially
7857 fast approximately as " exp (-alpha x)", including reasonably
7858 oscillating functions such as " exp (-x) sin (x)". The precise choice
7859 of "alpha", while useful in extreme cases, is not critical, and may be
7860 off by a \emph{factor} of 10 or more from the correct value.
7861 \item "alpha < -1" assumes that the function tends to 0 slowly, like
7863 "x^{alpha}". Here it is essential to give the correct "alpha", if
7864 possible, but on the other hand "alpha <= -2" is equivalent to "alpha =
7865 0", in other words to no "alpha" at all.
7866 The last two codes are reserved for oscillating functions. Let "k > 0"
7868 real, and g(x) a nonoscillating function tending to 0, then
7869 \item "alpha = k I" assumes that the function behaves like " cos
7871 (kx)g(x)".
7872 \item "alpha = -kI" assumes that the function behaves like " sin
7874 (kx)g(x)".
7875 Here it is critical to give the exact value of "k". If the oscillating
7877 part is not a pure sine or cosine, one must expand it into a Fourier
7878 series, use the above codings, and sum the resulting contributions.
7879 Otherwise you will get nonsense. Note that " cos (kx)" (and similarly "
7880 sin (kx)") means that very function, and not a translated version such
7881 as " cos (kx+a)".
7882 If for instance "f(x) = cos (kx)g(x)" where g(x) tends to zero
7884 exponentially fast as " exp (-alpha x)", it is up to the user to choose
7885 between "[[+-1],alpha]" and "[[+-1],kI]", but a good rule of thumb is
7886 that if the oscillations are much weaker than the exponential decrease,
7887 choose "[[+-1],alpha]", otherwise choose "[[+-1],kI]", although the
7888 latter can reasonably be used in all cases, while the former cannot. To
7889 take a specific example, in the inverse Mellin transform, the function
7890 to be integrated is almost always exponentially decreasing times
7891 oscillating. If we choose the oscillating type of integral we perhaps
7892 obtain the best results, at the expense of having to recompute our
7893 functions for a different value of the variable "z" giving the
7894 transform, preventing us to use a function such as "intmellininvshort".
7895 On the other hand using the exponential type of integral, we obtain
7896 less accurate results, but we skip expensive recomputations. See
7897 "intmellininvshort" and "intfuncinit" for more explanations.
7898 Note. If you do not like the code "[+-1]" for "+- oo ", you are welcome
7900 to set, e.g "oo = [1]" or "INFINITY = [1]", then using "+oo", "-oo",
7901 "-INFINITY", etc. will have the expected behaviour.
7902 We shall now see many examples to get a feeling for what the various
7904 parameters achieve. All examples below assume precision is set to 105
7905 decimal digits. We first type
7906 ? \p 105
7908 ? oo = [1] \\ for clarity
7909 Apparent singularities. Even if the function f(x) represented by expr
7911 has no singularities, it may be important to define the function
7912 differently near special points. For instance, if "f(x) = 1 /( exp
7913 (x)-1) - exp (-x)/x", then "int_0^ oo f(x)dx = gamma", Euler's
7914 constant "Euler". But
7915 ? f(x) = 1/(exp(x)-1) - exp(-x)/x
7917 ? intnum(x = 0, [oo,1], f(x)) - Euler
7918 %1 = 6.00... E-67
7919 thus only correct to 76 decimal digits. This is because close to 0 the
7921 function "f" is computed with an enormous loss of accuracy. A better
7922 solution is
7923 ? f(x) = 1/(exp(x)-1)-exp(-x)/x
7925 ? F = truncate( f(t + O(t^7)) ); \\ expansion around t = 0
7926 ? g(x) = if (x > 1e-18, f(x), subst(F,t,x)) \\ note that 6.18 > 105
7927 ? intnum(x = 0, [oo,1], g(x)) - Euler
7928 %2 = 0.E-106 \\ perfect
7929 It is up to the user to determine constants such as the "10^{-18}" and
7931 7 used above.
7932 True singularities. With true singularities the result is much worse.
7934 For instance
7935 ? intnum(x = 0, 1, 1/sqrt(x)) - 2
7937 %1 = -1.92... E-59 \\ only 59 correct decimals
7938 ? intnum(x = [0,-1/2], 1, 1/sqrt(x)) - 2
7940 %2 = 0.E-105 \\ better
7941 Oscillating functions.
7943 ? intnum(x = 0, oo, sin(x) / x) - Pi/2
7945 %1 = 20.78.. \\ nonsense
7946 ? intnum(x = 0, [oo,1], sin(x)/x) - Pi/2
7947 %2 = 0.004.. \\ bad
7948 ? intnum(x = 0, [oo,-I], sin(x)/x) - Pi/2
7949 %3 = 0.E-105 \\ perfect
7950 ? intnum(x = 0, [oo,-I], sin(2*x)/x) - Pi/2 \\ oops, wrong k
7951 %4 = 0.07...
7952 ? intnum(x = 0, [oo,-2*I], sin(2*x)/x) - Pi/2
7953 %5 = 0.E-105 \\ perfect
7954 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7956 %6 = 0.0092... \\ bad
7957 ? sin(x)^3 - (3*sin(x)-sin(3*x))/4
7958 %7 = O(x^17)
7959 We may use the above linearization and compute two oscillating
7961 integrals with ``infinite endpoints'' "[oo, -I]" and "[oo, -3*I]"
7962 respectively, or notice the obvious change of variable, and reduce to
7963 the single integral "(1/2)int_0^ oo sin (x)/xdx". We finish with some
7964 more complicated examples:
7965 ? intnum(x = 0, [oo,-I], (1-cos(x))/x^2) - Pi/2
7967 %1 = -0.0004... \\ bad
7968 ? intnum(x = 0, 1, (1-cos(x))/x^2) \
7969 + intnum(x = 1, oo, 1/x^2) - intnum(x = 1, [oo,I], cos(x)/x^2) - Pi/2
7970 %2 = -2.18... E-106 \\ OK
7971 ? intnum(x = 0, [oo, 1], sin(x)^3*exp(-x)) - 0.3
7973 %3 = 5.45... E-107 \\ OK
7974 ? intnum(x = 0, [oo,-I], sin(x)^3*exp(-x)) - 0.3
7975 %4 = -1.33... E-89 \\ lost 16 decimals. Try higher m:
7976 ? m = intnumstep()
7977 %5 = 7 \\ the value of m actually used above.
7978 ? tab = intnuminit(0,[oo,-I], m+1); \\ try m one higher.
7979 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7980 %6 = 5.45... E-107 \\ OK this time.
7981 Warning. Like "sumalt", "intnum" often assigns a reasonable value to
7983 diverging integrals. Use these values at your own risk! For example:
7984 ? intnum(x = 0, [oo, -I], x^2*sin(x))
7986 %1 = -2.0000000000...
7987 Note the formula
7989 " int_0^ oo sin (x)/x^sdx = cos (Pi s/2) Gamma(1-s) , "
7991 a priori valid only for "0 < Re (s) < 2", but the right hand side
7993 provides an analytic continuation which may be evaluated at "s = -2"...
7994 Multivariate integration. Using successive univariate integration with
7996 respect to different formal parameters, it is immediate to do naive
7997 multivariate integration. But it is important to use a suitable
7998 "intnuminit" to precompute data for the \emph{internal} integrations at
7999 least!
8000 For example, to compute the double integral on the unit disc "x^2+y^2
8002 <= 1" of the function "x^2+y^2", we can write
8003 ? tab = intnuminit(-1,1);
8005 ? intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2, tab), tab)
8006 The first tab is essential, the second optional. Compare:
8008 ? tab = intnuminit(-1,1);
8010 time = 30 ms.
8011 ? intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2));
8012 time = 54,410 ms. \\ slow
8013 ? intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2, tab), tab);
8014 time = 7,210 ms. \\ faster
8015 However, the "intnuminit" program is usually pessimistic when it comes
8017 to choosing the integration step "2^{-m}". It is often possible to
8018 improve the speed by trial and error. Continuing the above example:
8019 ? test(M) =
8021 {
8022 tab = intnuminit(-1,1, M);
8023 intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2,tab), tab) - Pi/2
8024 }
8025 ? m = intnumstep() \\ what value of m did it take ?
8026 %1 = 7
8027 ? test(m - 1)
8028 time = 1,790 ms.
8029 %2 = -2.05... E-104 \\ 4 = 2^2 times faster and still OK.
8030 ? test(m - 2)
8031 time = 430 ms.
8032 %3 = -1.11... E-104 \\ 16 = 2^4 times faster and still OK.
8033 ? test(m - 3)
8034 time = 120 ms.
8035 %3 = -7.23... E-60 \\ 64 = 2^6 times faster, lost 45 decimals.
8036 The library syntax is intnum"(void *E, GEN (*eval)(GEN,void*), GEN
8038 a,GEN b,GEN tab, long prec)", where an omitted tab is coded as "NULL".
8039 intnuminit"(a,b,{m = 0})"
8041 initialize tables for integration from "a" to "b", where "a" and "b"
8042 are coded as in "intnum". Only the compactness, the possible existence
8043 of singularities, the speed of decrease or the oscillations at infinity
8044 are taken into account, and not the values. For instance
8045 "intnuminit(-1,1)" is equivalent to "intnuminit(0,Pi)", and
8046 "intnuminit([0,-1/2],[1])" is equivalent to "
8047 intnuminit([-1],[-1,-1/2])". If "m" is not given, it is computed
8048 according to the current precision. Otherwise the integration step is
8049 "1/2^m". Reasonable values of "m" are "m = 6" or "m = 7" for 100
8050 decimal digits, and "m = 9" for 1000 decimal digits.
8051 The result is technical, but in some cases it is useful to know the
8053 output. Let "x = phi(t)" be the change of variable which is used.
8054 tab[1] contains the integer "m" as above, either given by the user or
8055 computed from the default precision, and can be recomputed directly
8056 using the function "intnumstep". tab[2] and tab[3] contain
8057 respectively the abcissa and weight corresponding to "t = 0" ("phi(0)"
8058 and "phi'(0)"). tab[4] and tab[5] contain the abcissas and weights
8059 corresponding to positive "t = nh" for "1 <= n <= N" and "h = 1/2^m"
8060 ("phi(nh)" and "phi'(nh)"). Finally tab[6] and tab[7] contain either
8061 the abcissas and weights corresponding to negative "t = nh" for "-N <=
8062 n <= -1", or may be empty (but not always) if "phi(t)" is an odd
8063 function (implicitly we would have "tab[6] = -tab[4]" and "tab[7] =
8064 tab[5]").
8065 The library syntax is intnuminit"(GEN a, GEN b, long m, long prec)".
8067 intnumromb"(X = a,b,expr,{flag = 0})"
8069 numerical integration of expr (smooth in "]a,b["), with respect to "X".
8070 This function is deprecated, use "intnum" instead.
8071 Set "flag = 0" (or omit it altogether) when "a" and "b" are not too
8073 large, the function is smooth, and can be evaluated exactly everywhere
8074 on the interval "[a,b]".
8075 If "flag = 1", uses a general driver routine for doing numerical
8077 integration, making no particular assumption (slow).
8078 "flag = 2" is tailored for being used when "a" or "b" are infinite. One
8080 \emph{must} have "ab > 0", and in fact if for example "b = + oo ", then
8081 it is preferable to have "a" as large as possible, at least "a >= 1".
8082 If "flag = 3", the function is allowed to be undefined (but continuous)
8084 at "a" or "b", for example the function " sin (x)/x" at "x = 0".
8085 The user should not require too much accuracy: 18 or 28 decimal digits
8087 is OK, but not much more. In addition, analytical cleanup of the
8088 integral must have been done: there must be no singularities in the
8089 interval or at the boundaries. In practice this can be accomplished
8090 with a simple change of variable. Furthermore, for improper integrals,
8091 where one or both of the limits of integration are plus or minus
8092 infinity, the function must decrease sufficiently rapidly at infinity.
8093 This can often be accomplished through integration by parts. Finally,
8094 the function to be integrated should not be very small (compared to the
8095 current precision) on the entire interval. This can of course be
8096 accomplished by just multiplying by an appropriate constant.
8097 Note that infinity can be represented with essentially no loss of
8099 accuracy by 1e1000. However beware of real underflow when dealing with
8100 rapidly decreasing functions. For example, if one wants to compute the
8101 "int_0^ oo e^{-x^2}dx" to 28 decimal digits, then one should set
8102 infinity equal to 10 for example, and certainly not to 1e1000.
8103 The library syntax is intnumromb"(void *E, GEN (*eval)(GEN,void*), GEN
8105 a, GEN b, long flag, long prec)", where "eval(x, E)" returns the value
8106 of the function at "x". You may store any additional information
8107 required by "eval" in "E", or set it to "NULL".
8108 intnumstep"()"
8110 give the value of "m" used in all the "intnum" and "sumnum" programs,
8111 hence such that the integration step is equal to "1/2^m".
8112 The library syntax is intnumstep"(long prec)".
8114 prod"(X = a,b,expr,{x = 1})"
8116 product of expression expr, initialized at "x", the formal parameter
8117 "X" going from "a" to "b". As for "sum", the main purpose of the
8118 initialization parameter "x" is to force the type of the operations
8119 being performed. For example if it is set equal to the integer 1,
8120 operations will start being done exactly. If it is set equal to the
8121 real 1., they will be done using real numbers having the default
8122 precision. If it is set equal to the power series "1+O(X^k)" for a
8123 certain "k", they will be done using power series of precision at most
8124 "k". These are the three most common initializations.
8125 As an extreme example, compare
8127 ? prod(i=1, 100, 1 - X^i); \\ this has degree 5050 !!
8129 time = 3,335 ms.
8130 ? prod(i=1, 100, 1 - X^i, 1 + O(X^101))
8131 time = 43 ms.
8132 %2 = 1 - X - X^2 + X^5 + X^7 - X^12 - X^15 + X^22 + X^26 - X^35 - X^40 + \
8133 X^51 + X^57 - X^70 - X^77 + X^92 + X^100 + O(X^101)
8134 The library syntax is produit"(entree *ep, GEN a, GEN b, char *expr,
8136 GEN x)".
8137 prodeuler"(X = a,b,expr)"
8139 product of expression expr, initialized at 1. (i.e. to a \emph{real}
8140 number equal to 1 to the current "realprecision"), the formal parameter
8141 "X" ranging over the prime numbers between "a" and "b".
8142 The library syntax is prodeuler"(void *E, GEN (*eval)(GEN,void*), GEN
8144 a,GEN b, long prec)".
8145 prodinf"(X = a,expr,{flag = 0})"
8147 infinite product of expression expr, the formal parameter "X" starting
8148 at "a". The evaluation stops when the relative error of the expression
8149 minus 1 is less than the default precision. The expressions must always
8150 evaluate to an element of C.
8151 If "flag = 1", do the product of the ("1+expr") instead.
8153 The library syntax is prodinf"(void *E, GEN (*eval)(GEN, void*), GEN a,
8155 long prec)" ("flag = 0"), or prodinf1 with the same arguments ("flag =
8156 1").
8157 solve"(X = a,b,expr)"
8159 find a real root of expression expr between "a" and "b", under the
8160 condition "expr(X = a) * expr(X = b) <= 0". This routine uses Brent's
8161 method and can fail miserably if expr is not defined in the whole of
8162 "[a,b]" (try "solve(x = 1, 2, tan(x)").
8163 The library syntax is zbrent"(void *E,GEN (*eval)(GEN,void*),GEN a,GEN
8165 b,long prec)".
8166 sum"(X = a,b,expr,{x = 0})"
8168 sum of expression expr, initialized at "x", the formal parameter going
8169 from "a" to "b". As for "prod", the initialization parameter "x" may be
8170 given to force the type of the operations being performed.
8171 As an extreme example, compare
8173 ? sum(i=1, 5000, 1/i); \\ rational number: denominator has 2166 digits.
8175 time = 1,241 ms.
8176 ? sum(i=1, 5000, 1/i, 0.)
8177 time = 158 ms.
8178 %2 = 9.094508852984436967261245533
8179 The library syntax is somme"(entree *ep, GEN a, GEN b, char *expr, GEN
8181 x)". This is to be used as follows: "ep" represents the dummy variable
8182 used in the expression "expr"
8183 /* compute a^2 + ... + b^2 */
8185 {
8186 /* define the dummy variable "i" */
8187 entree *ep = is_entry("i");
8188 /* sum for a <= i <= b */
8189 return somme(ep, a, b, "i^2", gen_0);
8190 }
8191 sumalt"(X = a,expr,{flag = 0})"
8193 numerical summation of the series expr, which should be an alternating
8194 series, the formal variable "X" starting at "a". Use an algorithm of
8195 F. Villegas as modified by D. Zagier (improves on Euler-Van Wijngaarden
8196 method).
8197 If "flag = 1", use a variant with slightly different polynomials.
8199 Sometimes faster.
8200 Divergent alternating series can sometimes be summed by this method, as
8202 well as series which are not exactly alternating (see for example
8203 "Label se:user_defined"). If the series already converges
8204 geometrically, "suminf" is often a better choice:
8205 ? \p28
8207 ? sumalt(i = 1, -(-1)^i / i) - log(2)
8208 time = 0 ms.
8209 %1 = -2.524354897 E-29
8210 ? suminf(i = 1, -(-1)^i / i)
8211 *** suminf: user interrupt after 10min, 20,100 ms.
8212 ? \p1000
8213 ? sumalt(i = 1, -(-1)^i / i) - log(2)
8214 time = 90 ms.
8215 %2 = 4.459597722 E-1002
8216 ? sumalt(i = 0, (-1)^i / i!) - exp(-1)
8218 time = 670 ms.
8219 %3 = -4.03698781490633483156497361352190615794353338591897830587 E-944
8220 ? suminf(i = 0, (-1)^i / i!) - exp(-1)
8221 time = 110 ms.
8222 %4 = -8.39147638 E-1000 \\ faster and more accurate
8223 The library syntax is sumalt"(void *E, GEN (*eval)(GEN,void*),GEN
8225 a,long prec)". Also available is "sumalt2" with the same arguments
8226 ("flag = 1").
8227 sumdiv"(n,X,expr)"
8229 sum of expression expr over the positive divisors of "n".
8230 Arithmetic functions like "sigma" use the multiplicativity of the
8232 underlying expression to speed up the computation. In the present
8233 version 2.2.0, there is no way to indicate that expr is multiplicative
8234 in "n", hence specialized functions should be preferred whenever
8235 possible.
8236 The library syntax is divsum"(entree *ep, GEN num, char *expr)".
8238 suminf"(X = a,expr)"
8240 infinite sum of expression expr, the formal parameter "X" starting at
8241 "a". The evaluation stops when the relative error of the expression is
8242 less than the default precision for 3 consecutive evaluations. The
8243 expressions must always evaluate to a complex number.
8244 If the series converges slowly, make sure "realprecision" is low (even
8246 28 digits may be too much). In this case, if the series is alternating
8247 or the terms have a constant sign, "sumalt" and "sumpos" should be used
8248 instead.
8249 ? \p28
8251 ? suminf(i = 1, -(-1)^i / i)
8252 *** suminf: user interrupt after 10min, 20,100 ms.
8253 ? sumalt(i = 1, -(-1)^i / i) - log(2)
8254 time = 0 ms.
8255 %1 = -2.524354897 E-29
8256 The library syntax is suminf"(void *E, GEN (*eval)(GEN,void*), GEN a,
8258 long prec)".
8259 sumnum"(X = a,sig,expr,{tab}),{flag = 0}"
8261 numerical summation of expr, the variable "X" taking integer values
8262 from ceiling of "a" to "+ oo ", where expr is assumed to be a
8263 holomorphic function f(X) for " Re (X) >= sigma".
8264 The parameter "sigma belongs to R" is coded in the argument "sig" as
8266 follows: it is either
8267 \item a real number "sigma". Then the function "f" is assumed to
8269 decrease at least as "1/X^2" at infinity, but not exponentially;
8270 \item a two-component vector "[sigma,alpha]", where "sigma" is as
8272 before, "alpha < -1". The function "f" is assumed to decrease like
8273 "X^{alpha}". In particular, "alpha <= -2" is equivalent to no "alpha"
8274 at all.
8275 \item a two-component vector "[sigma,alpha]", where "sigma" is as
8277 before, "alpha > 0". The function "f" is assumed to decrease like " exp
8278 (-alpha X)". In this case it is essential that "alpha" be exactly the
8279 rate of exponential decrease, and it is usually a good idea to increase
8280 the default value of "m" used for the integration step. In practice, if
8281 the function is exponentially decreasing "sumnum" is slower and less
8282 accurate than "sumpos" or "suminf", so should not be used.
8283 The function uses the "intnum" routines and integration on the line "
8285 Re (s) = sigma". The optional argument tab is as in intnum, except it
8286 must be initialized with "sumnuminit" instead of "intnuminit".
8287 When tab is not precomputed, "sumnum" can be slower than "sumpos", when
8289 the latter is applicable. It is in general faster for slowly decreasing
8290 functions.
8291 Finally, if "flag" is nonzero, we assume that the function "f" to be
8293 summed is of real type, i.e. satisfies "\overline{f(z)} =
8294 f(\overline{z})", which speeds up the computation.
8295 ? \p 308
8297 ? a = sumpos(n=1, 1/(n^3+n+1));
8298 time = 1,410 ms.
8299 ? tab = sumnuminit(2);
8300 time = 1,620 ms. \\ slower but done once and for all.
8301 ? b = sumnum(n=1, 2, 1/(n^3+n+1), tab);
8302 time = 460 ms. \\ 3 times as fast as sumpos
8303 ? a - b
8304 %4 = -1.0... E-306 + 0.E-320*I \\ perfect.
8305 ? sumnum(n=1, 2, 1/(n^3+n+1), tab, 1) - a; \\ function of real type
8306 time = 240 ms.
8307 %2 = -1.0... E-306 \\ twice as fast, no imaginary part.
8308 ? c = sumnum(n=1, 2, 1/(n^2+1), tab, 1);
8309 time = 170 ms. \\ fast
8310 ? d = sumpos(n=1, 1 / (n^2+1));
8311 time = 2,700 ms. \\ slow.
8312 ? d - c
8313 time = 0 ms.
8314 %5 = 1.97... E-306 \\ perfect.
8315 For slowly decreasing function, we must indicate singularities:
8317 ? \p 308
8319 ? a = sumnum(n=1, 2, n^(-4/3));
8320 time = 9,930 ms. \\ slow because of the computation of n^{-4/3}.
8321 ? a - zeta(4/3)
8322 time = 110 ms.
8323 %1 = -2.42... E-107 \\ lost 200 decimals because of singularity at oo
8324 ? b = sumnum(n=1, [2,-4/3], n^(-4/3), /*omitted*/, 1); \\ of real type
8325 time = 12,210 ms.
8326 ? b - zeta(4/3)
8327 %3 = 1.05... E-300 \\ better
8328 Since the \emph{complex} values of the function are used, beware of
8330 determination problems. For instance:
8331 ? \p 308
8333 ? tab = sumnuminit([2,-3/2]);
8334 time = 1,870 ms.
8335 ? sumnum(n=1,[2,-3/2], 1/(n*sqrt(n)), tab,1) - zeta(3/2)
8336 time = 690 ms.
8337 %1 = -1.19... E-305 \\ fast and correct
8338 ? sumnum(n=1,[2,-3/2], 1/sqrt(n^3), tab,1) - zeta(3/2)
8339 time = 730 ms.
8340 %2 = -1.55... \\ nonsense. However
8341 ? sumnum(n=1,[2,-3/2], 1/n^(3/2), tab,1) - zeta(3/2)
8342 time = 8,990 ms.
8343 %3 = -1.19... E-305 \\ perfect, as 1/(n*sqrt{n}) above but much slower
8344 For exponentially decreasing functions, "sumnum" is given for
8346 completeness, but one of "suminf" or "sumpos" should always be
8347 preferred. If you experiment with such functions and "sumnum" anyway,
8348 indicate the exact rate of decrease and increase "m" by 1 or 2:
8349 ? suminf(n=1, 2^(-n)) - 1
8351 time = 10 ms.
8352 %1 = -1.11... E-308 \\ fast and perfect
8353 ? sumpos(n=1, 2^(-n)) - 1
8354 time = 10 ms.
8355 %2 = -2.78... E-308 \\ also fast and perfect
8356 ? sumnum(n=1,2, 2^(-n)) - 1
8357 *** sumnum: precision too low in mpsc1 \\ nonsense
8358 ? sumnum(n=1, [2,log(2)], 2^(-n), /*omitted*/, 1) - 1 \\ of real type
8359 time = 5,860 ms.
8360 %3 = -1.5... E-236 \\ slow and lost 70 decimals
8361 ? m = intnumstep()
8362 %4 = 9
8363 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8364 time = 11,770 ms.
8365 %5 = -1.9... E-305 \\ now perfect, but slow.
8366 The library syntax is sumnum"(void *E, GEN (*eval)(GEN,void*), GEN
8368 a,GEN sig,GEN tab,long flag, long prec)".
8369 sumnumalt"(X = a,sig,expr,{tab},{flag = 0})"
8371 numerical summation of "(-1)^Xexpr(X)", the variable "X" taking integer
8372 values from ceiling of "a" to "+ oo ", where expr is assumed to be a
8373 holomorphic function for " Re (X) >= sig" (or "sig[1]").
8374 Warning. This function uses the "intnum" routines and is orders of
8376 magnitude slower than "sumalt". It is only given for completeness and
8377 should not be used in practice.
8378 Warning2. The expression expr must \emph{not} include the "(-1)^X"
8380 coefficient. Thus "sumalt(n = a,(-1)^nf(n))" is (approximately) equal
8381 to "sumnumalt(n = a,sig,f(n))".
8382 "sig" is coded as in "sumnum". However for slowly decreasing functions
8384 (where "sig" is coded as "[sigma,alpha]" with "alpha < -1"), it is not
8385 really important to indicate "alpha". In fact, as for "sumalt", the
8386 program will often give meaningful results (usually analytic
8387 continuations) even for divergent series. On the other hand the
8388 exponential decrease must be indicated.
8389 tab is as in "intnum", but if used must be initialized with
8391 "sumnuminit". If "flag" is nonzero, assumes that the function "f" to be
8392 summed is of real type, i.e. satisfies "\overline{f(z)} =
8393 f(\overline{z})", and then twice faster when tab is precomputed.
8394 ? \p 308
8396 ? tab = sumnuminit(2, /*omitted*/, -1); \\ abcissa sigma = 2, alternating sums.
8397 time = 1,620 ms. \\ slow, but done once and for all.
8398 ? a = sumnumalt(n=1, 2, 1/(n^3+n+1), tab, 1);
8399 time = 230 ms. \\ similar speed to sumnum
8400 ? b = sumalt(n=1, (-1)^n/(n^3+n+1));
8401 time = 0 ms. \\ infinitely faster!
8402 ? a - b
8403 time = 0 ms.
8404 %1 = -1.66... E-308 \\ perfect
8405 The library syntax is sumnumalt"(void *E, GEN (*eval)(GEN,void*), GEN
8407 a, GEN sig, GEN tab, long flag, long prec)".
8408 sumnuminit"(sig,{m = 0},{sgn = 1})"
8410 initialize tables for numerical summation using "sumnum" (with "sgn =
8411 1") or "sumnumalt" (with "sgn = -1"), "sig" is the abcissa of
8412 integration coded as in "sumnum", and "m" is as in "intnuminit".
8413 The library syntax is sumnuminit"(GEN sig, long m, long sgn, long
8415 prec)".
8416 sumpos"(X = a,expr,{flag = 0})"
8418 numerical summation of the series expr, which must be a series of terms
8419 having the same sign, the formal variable "X" starting at "a". The
8420 algorithm used is Van Wijngaarden's trick for converting such a series
8421 into an alternating one, and is quite slow. For regular functions, the
8422 function "sumnum" is in general much faster once the initializations
8423 have been made using "sumnuminit".
8424 If "flag = 1", use slightly different polynomials. Sometimes faster.
8426 The library syntax is sumpos"(void *E, GEN (*eval)(GEN,void*),GEN
8428 a,long prec)". Also available is "sumpos2" with the same arguments
8429 ("flag = 1").
8430
8432 Although plotting is not even a side purpose of PARI, a number of
8433 plotting functions are provided. Moreover, a lot of people suggested
8434 ideas or submitted patches for this section of the code. Among these,
8435 special thanks go to Klaus-Peter Nischke who suggested the recursive
8436 plotting and the forking/resizing stuff under X11, and Ilya Zakharevich
8437 who undertook a complete rewrite of the graphic code, so that most of
8438 it is now platform-independent and should be easy to port or expand.
8439 There are three types of graphic functions.
8440 High-level plotting functions
8442 (all the functions starting with "ploth") in which the user has little
8443 to do but explain what type of plot he wants, and whose syntax is
8444 similar to the one used in the preceding section.
8445 Low-level plotting functions
8447 (called rectplot functions, sharing the prefix "plot"), where every
8448 drawing primitive (point, line, box, etc.) is specified by the user.
8449 These low-level functions work as follows. You have at your disposal 16
8450 virtual windows which are filled independently, and can then be
8451 physically ORed on a single window at user-defined positions. These
8452 windows are numbered from 0 to 15, and must be initialized before being
8453 used by the function "plotinit", which specifies the height and width
8454 of the virtual window (called a rectwindow in the sequel). At all
8455 times, a virtual cursor (initialized at "[0,0]") is associated to the
8456 window, and its current value can be obtained using the function
8457 "plotcursor".
8458 A number of primitive graphic objects (called rect objects) can then be
8460 drawn in these windows, using a default color associated to that window
8461 (which can be changed under X11, using the "plotcolor" function, black
8462 otherwise) and only the part of the object which is inside the window
8463 will be drawn, with the exception of polygons and strings which are
8464 drawn entirely. The ones sharing the prefix "plotr" draw relatively to
8465 the current position of the virtual cursor, the others use absolute
8466 coordinates. Those having the prefix "plotrecth" put in the rectwindow
8467 a large batch of rect objects corresponding to the output of the
8468 related "ploth" function.
8469 Finally, the actual physical drawing is done using the function
8471 "plotdraw". The rectwindows are preserved so that further drawings
8472 using the same windows at different positions or different windows can
8473 be done without extra work. To erase a window (and free the
8474 corresponding memory), use the function "plotkill". It is not possible
8475 to partially erase a window. Erase it completely, initialize it again
8476 and then fill it with the graphic objects that you want to keep.
8477 In addition to initializing the window, you may use a scaled window to
8479 avoid unnecessary conversions. For this, use the function "plotscale"
8480 below. As long as this function is not called, the scaling is simply
8481 the number of pixels, the origin being at the upper left and the
8482 "y"-coordinates going downwards.
8483 Note that in the present version 2.2.0 all plotting functions (both low
8485 and high level) are written for the X11-window system (hence also for
8486 GUI's based on X11 such as Openwindows and Motif) only, though little
8487 code remains which is actually platform-dependent. It is also possible
8488 to compile "gp" with either of the Qt or FLTK graphical libraries. A
8489 Suntools/Sunview, Macintosh, and an Atari/Gem port were provided for
8490 previous versions, but are now obsolete.
8491 Under X11, the physical window (opened by "plotdraw" or any of the
8493 "ploth*" functions) is completely separated from "gp" (technically, a
8494 "fork" is done, and the non-graphical memory is immediately freed in
8495 the child process), which means you can go on working in the current
8496 "gp" session, without having to kill the window first. Under X11, this
8497 window can be closed, enlarged or reduced using the standard window
8498 manager functions. No zooming procedure is implemented though (yet).
8499 Functions for PostScript output:
8501 in the same way that "printtex" allows you to have a TeX output
8502 corresponding to printed results, the functions starting with "ps"
8503 allow you to have "PostScript" output of the plots. This will not be
8504 absolutely identical with the screen output, but will be sufficiently
8505 close. Note that you can use PostScript output even if you do not have
8506 the plotting routines enabled. The PostScript output is written in a
8507 file whose name is derived from the "psfile" default ("./pari.ps" if
8508 you did not tamper with it). Each time a new PostScript output is asked
8509 for, the PostScript output is appended to that file. Hence you probably
8510 want to remove this file, or change the value of "psfile", in between
8511 plots. On the other hand, in this manner, as many plots as desired can
8512 be kept in a single file.
8513 And library mode ?
8515 \emph{None of the graphic functions are available within the PARI
8516 library, you must be under "gp" to use them}. The reason for that is
8517 that you really should not use PARI for heavy-duty graphical work,
8518 there are better specialized alternatives around. This whole set of
8519 routines was only meant as a convenient, but simple-minded, visual aid.
8520 If you really insist on using these in your program (we warned you),
8521 the source ("plot*.c") should be readable enough for you to achieve
8522 something.
8523 plot"(X = a,b,expr,{Ymin},{Ymax})"
8525 crude ASCII plot of the function represented by expression expr from
8526 "a" to "b", with Y ranging from Ymin to Ymax. If Ymin (resp. Ymax) is
8527 not given, the minima (resp. the maxima) of the computed values of the
8528 expression is used instead.
8529 plotbox"(w,x2,y2)"
8531 let "(x1,y1)" be the current position of the virtual cursor. Draw in
8532 the rectwindow "w" the outline of the rectangle which is such that the
8533 points "(x1,y1)" and "(x2,y2)" are opposite corners. Only the part of
8534 the rectangle which is in "w" is drawn. The virtual cursor does
8535 \emph{not} move.
8536 plotclip"(w)"
8538 `clips' the content of rectwindow "w", i.e remove all parts of the
8539 drawing that would not be visible on the screen. Together with
8540 "plotcopy" this function enables you to draw on a scratchpad before
8541 commiting the part you're interested in to the final picture.
8542 plotcolor"(w,c)"
8544 set default color to "c" in rectwindow "w". In present version 2.2.0,
8545 this is only implemented for the X11 window system, and you only have
8546 the following palette to choose from:
8547 1 = black, 2 = blue, 3 = sienna, 4 = red, 5 = green, 6 = grey, 7 =
8549 gainsborough.
8550 Note that it should be fairly easy for you to hardwire some more colors
8552 by tweaking the files "rect.h" and "plotX.c". User-defined colormaps
8553 would be nice, and \emph{may} be available in future versions.
8554 plotcopy"(w1,w2,dx,dy)"
8556 copy the contents of rectwindow "w1" to rectwindow "w2", with offset
8557 "(dx,dy)".
8558 plotcursor"(w)"
8560 give as a 2-component vector the current (scaled) position of the
8561 virtual cursor corresponding to the rectwindow "w".
8562 plotdraw"(list)"
8564 physically draw the rectwindows given in "list" which must be a vector
8565 whose number of components is divisible by 3. If "list =
8566 [w1,x1,y1,w2,x2,y2,...]", the windows "w1", "w2", etc. are physically
8567 placed with their upper left corner at physical position "(x1,y1)",
8568 "(x2,y2)",...respectively, and are then drawn together. Overlapping
8569 regions will thus be drawn twice, and the windows are considered
8570 transparent. Then display the whole drawing in a special window on your
8571 screen.
8572 ploth"(X = a,b,expr,{flag = 0},{n = 0})"
8574 high precision plot of the function "y = f(x)" represented by the
8575 expression expr, "x" going from "a" to "b". This opens a specific
8576 window (which is killed whenever you click on it), and returns a four-
8577 component vector giving the coordinates of the bounding box in the form
8578 "[xmin,xmax,ymin,ymax]".
8579 Important note: Since this may involve a lot of function calls, it is
8581 advised to keep the current precision to a minimum (e.g. 9) before
8582 calling this function.
8583 "n" specifies the number of reference point on the graph (0 means use
8585 the hardwired default values, that is: 1000 for general plot, 1500 for
8586 parametric plot, and 15 for recursive plot).
8587 If no "flag" is given, expr is either a scalar expression f(X), in
8589 which case the plane curve "y = f(X)" will be drawn, or a vector
8590 "[f_1(X),...,f_k(X)]", and then all the curves "y = f_i(X)" will be
8591 drawn in the same window.
8592 The binary digits of "flag" mean:
8594 \item "1 = Parametric": parametric plot. Here expr must be a vector
8596 with an even number of components. Successive pairs are then understood
8597 as the parametric coordinates of a plane curve. Each of these are then
8598 drawn.
8599 For instance:
8601 "ploth(X = 0,2*Pi,[sin(X),cos(X)],1)" will draw a circle.
8603 "ploth(X = 0,2*Pi,[sin(X),cos(X)])" will draw two entwined sinusoidal
8605 curves.
8606 "ploth(X = 0,2*Pi,[X,X,sin(X),cos(X)],1)" will draw a circle and the
8608 line "y = x".
8609 \item "2 = Recursive": recursive plot. If this flag is set, only
8611 \emph{one} curve can be drawn at a time, i.e. expr must be either a
8612 two-component vector (for a single parametric curve, and the parametric
8613 flag \emph{has} to be set), or a scalar function. The idea is to choose
8614 pairs of successive reference points, and if their middle point is not
8615 too far away from the segment joining them, draw this as a local
8616 approximation to the curve. Otherwise, add the middle point to the
8617 reference points. This is fast, and usually more precise than usual
8618 plot. Compare the results of
8619 "ploth(X = -1,1,sin(1/X),2) and ploth(X = -1,1,sin(1/X))"
8621 for instance. But beware that if you are extremely unlucky, or choose
8623 too few reference points, you may draw some nice polygon bearing little
8624 resemblance to the original curve. For instance you should \emph{never}
8625 plot recursively an odd function in a symmetric interval around 0. Try
8626 ploth(x = -20, 20, sin(x), 2)
8628 to see why. Hence, it's usually a good idea to try and plot the same
8630 curve with slightly different parameters.
8631 The other values toggle various display options:
8633 \item "4 = no_Rescale": do not rescale plot according to the computed
8635 extrema. This is meant to be used when graphing multiple functions on a
8636 rectwindow (as a "plotrecth" call), in conjunction with "plotscale".
8637 \item "8 = no_X_axis": do not print the "x"-axis.
8639 \item "16 = no_Y_axis": do not print the "y"-axis.
8641 \item "32 = no_Frame": do not print frame.
8643 \item "64 = no_Lines": only plot reference points, do not join them.
8645 \item "128 = Points_too": plot both lines and points.
8647 \item "256 = Splines": use splines to interpolate the points.
8649 \item "512 = no_X_ticks": plot no "x"-ticks.
8651 \item "1024 = no_Y_ticks": plot no "y"-ticks.
8653 \item "2048 = Same_ticks": plot all ticks with the same length.
8655 plothraw"(listx,listy,{flag = 0})"
8657 given listx and listy two vectors of equal length, plots (in high
8658 precision) the points whose "(x,y)"-coordinates are given in listx and
8659 listy. Automatic positioning and scaling is done, but with the same
8660 scaling factor on "x" and "y". If "flag" is 1, join points, other non-0
8661 flags toggle display options and should be combinations of bits "2^k",
8662 "k
8663 >= 3" as in "ploth".
8664 plothsizes"()"
8666 return data corresponding to the output window in the form of a
8667 6-component vector: window width and height, sizes for ticks in
8668 horizontal and vertical directions (this is intended for the "gnuplot"
8669 interface and is currently not significant), width and height of
8670 characters.
8671 plotinit"(w,x,y,{flag})"
8673 initialize the rectwindow "w", destroying any rect objects you may have
8674 already drawn in "w". The virtual cursor is set to "(0,0)". The
8675 rectwindow size is set to width "x" and height "y". If "flag = 0", "x"
8676 and "y" represent pixel units. Otherwise, "x" and "y" are understood as
8677 fractions of the size of the current output device (hence must be
8678 between 0 and 1) and internally converted to pixels.
8679 The plotting device imposes an upper bound for "x" and "y", for
8681 instance the number of pixels for screen output. These bounds are
8682 available through the "plothsizes" function. The following sequence
8683 initializes in a portable way (i.e independent of the output device) a
8684 window of maximal size, accessed through coordinates in the "[0,1000]
8685 x [0,1000]" range:
8686 s = plothsizes();
8688 plotinit(0, s[1]-1, s[2]-1);
8689 plotscale(0, 0,1000, 0,1000);
8690 plotkill"(w)"
8692 erase rectwindow "w" and free the corresponding memory. Note that if
8693 you want to use the rectwindow "w" again, you have to use "plotinit"
8694 first to specify the new size. So it's better in this case to use
8695 "plotinit" directly as this throws away any previous work in the given
8696 rectwindow.
8697 plotlines"(w,X,Y,{flag = 0})"
8699 draw on the rectwindow "w" the polygon such that the (x,y)-coordinates
8700 of the vertices are in the vectors of equal length "X" and "Y". For
8701 simplicity, the whole polygon is drawn, not only the part of the
8702 polygon which is inside the rectwindow. If "flag" is non-zero, close
8703 the polygon. In any case, the virtual cursor does not move.
8704 "X" and "Y" are allowed to be scalars (in this case, both have to).
8706 There, a single segment will be drawn, between the virtual cursor
8707 current position and the point "(X,Y)". And only the part thereof which
8708 actually lies within the boundary of "w". Then \emph{move} the virtual
8709 cursor to "(X,Y)", even if it is outside the window. If you want to
8710 draw a line from "(x1,y1)" to "(x2,y2)" where "(x1,y1)" is not
8711 necessarily the position of the virtual cursor, use "plotmove(w,x1,y1)"
8712 before using this function.
8713 plotlinetype"(w,type)"
8715 change the type of lines subsequently plotted in rectwindow "w". type
8716 "-2" corresponds to frames, "-1" to axes, larger values may correspond
8717 to something else. "w = -1" changes highlevel plotting. This is only
8718 taken into account by the "gnuplot" interface.
8719 plotmove"(w,x,y)"
8721 move the virtual cursor of the rectwindow "w" to position "(x,y)".
8722 plotpoints"(w,X,Y)"
8724 draw on the rectwindow "w" the points whose "(x,y)"-coordinates are in
8725 the vectors of equal length "X" and "Y" and which are inside "w". The
8726 virtual cursor does \emph{not} move. This is basically the same
8727 function as "plothraw", but either with no scaling factor or with a
8728 scale chosen using the function "plotscale".
8729 As was the case with the "plotlines" function, "X" and "Y" are allowed
8731 to be (simultaneously) scalar. In this case, draw the single point
8732 "(X,Y)" on the rectwindow "w" (if it is actually inside "w"), and in
8733 any case \emph{move} the virtual cursor to position "(x,y)".
8734 plotpointsize"(w,size)"
8736 changes the ``size'' of following points in rectwindow "w". If "w =
8737 -1", change it in all rectwindows. This only works in the "gnuplot"
8738 interface.
8739 plotpointtype"(w,type)"
8741 change the type of points subsequently plotted in rectwindow "w". "type
8742 = -1" corresponds to a dot, larger values may correspond to something
8743 else. "w = -1" changes highlevel plotting. This is only taken into
8744 account by the "gnuplot" interface.
8745 plotrbox"(w,dx,dy)"
8747 draw in the rectwindow "w" the outline of the rectangle which is such
8748 that the points "(x1,y1)" and "(x1+dx,y1+dy)" are opposite corners,
8749 where "(x1,y1)" is the current position of the cursor. Only the part
8750 of the rectangle which is in "w" is drawn. The virtual cursor does
8751 \emph{not} move.
8752 plotrecth"(w,X = a,b,expr,{flag = 0},{n = 0})"
8754 writes to rectwindow "w" the curve output of "ploth""(w,X =
8755 a,b,expr,flag,n)".
8756 plotrecthraw"(w,data,{flag = 0})"
8758 plot graph(s) for data in rectwindow "w". "flag" has the same
8759 significance here as in "ploth", though recursive plot is no more
8760 significant.
8761 data is a vector of vectors, each corresponding to a list a
8763 coordinates. If parametric plot is set, there must be an even number
8764 of vectors, each successive pair corresponding to a curve. Otherwise,
8765 the first one contains the "x" coordinates, and the other ones contain
8766 the "y"-coordinates of curves to plot.
8767 plotrline"(w,dx,dy)"
8769 draw in the rectwindow "w" the part of the segment
8770 "(x1,y1)-(x1+dx,y1+dy)" which is inside "w", where "(x1,y1)" is the
8771 current position of the virtual cursor, and move the virtual cursor to
8772 "(x1+dx,y1+dy)" (even if it is outside the window).
8773 plotrmove"(w,dx,dy)"
8775 move the virtual cursor of the rectwindow "w" to position
8776 "(x1+dx,y1+dy)", where "(x1,y1)" is the initial position of the cursor
8777 (i.e. to position "(dx,dy)" relative to the initial cursor).
8778 plotrpoint"(w,dx,dy)"
8780 draw the point "(x1+dx,y1+dy)" on the rectwindow "w" (if it is inside
8781 "w"), where "(x1,y1)" is the current position of the cursor, and in any
8782 case move the virtual cursor to position "(x1+dx,y1+dy)".
8783 plotscale"(w,x1,x2,y1,y2)"
8785 scale the local coordinates of the rectwindow "w" so that "x" goes from
8786 "x1" to "x2" and "y" goes from "y1" to "y2" ("x2 < x1" and "y2 < y1"
8787 being allowed). Initially, after the initialization of the rectwindow
8788 "w" using the function "plotinit", the default scaling is the graphic
8789 pixel count, and in particular the "y" axis is oriented downwards since
8790 the origin is at the upper left. The function "plotscale" allows to
8791 change all these defaults and should be used whenever functions are
8792 graphed.
8793 plotstring"(w,x,{flag = 0})"
8795 draw on the rectwindow "w" the String "x" (see "Label se:strings"), at
8796 the current position of the cursor.
8797 flag is used for justification: bits 1 and 2 regulate horizontal
8799 alignment: left if 0, right if 2, center if 1. Bits 4 and 8 regulate
8800 vertical alignment: bottom if 0, top if 8, v-center if 4. Can insert
8801 additional small gap between point and string: horizontal if bit 16 is
8802 set, vertical if bit 32 is set (see the tutorial for an example).
8803 psdraw"(list)"
8805 same as "plotdraw", except that the output is a PostScript program
8806 appended to the "psfile".
8807 psploth"(X = a,b,expr)"
8809 same as "ploth", except that the output is a PostScript program
8810 appended to the "psfile".
8811 psplothraw"(listx,listy)"
8813 same as "plothraw", except that the output is a PostScript program
8814 appended to the "psfile".
8815
8817 =head2 Control statements.
8818 A number of control statements are available in GP. They are simpler
8820 and have a syntax slightly different from their C counterparts, but are
8821 quite powerful enough to write any kind of program. Some of them are
8822 specific to GP, since they are made for number theorists. As usual, "X"
8823 will denote any simple variable name, and seq will always denote a
8824 sequence of expressions, including the empty sequence.
8825 Caveat: in constructs like
8827 for (X = a,b, seq)
8829 the variable "X" is considered local to the loop, leading to possibly
8831 unexpected behaviour:
8832 n = 5;
8834 for (n = 1, 10,
8835 if (something_nice(), break);
8836 );
8837 \\ at this point n is 5 !
8838 If the sequence "seq" modifies the loop index, then the loop is
8840 modified accordingly:
8841 ? for (n = 1, 10, n += 2; print(n))
8843 3
8844 6
8845 9
8846 12
8847 break"({n = 1})"
8849 interrupts execution of current seq, and immediately exits from the
8850 "n" innermost enclosing loops, within the current function call (or
8851 the top level loop). "n" must be bigger than 1. If "n" is greater
8852 than the number of enclosing loops, all enclosing loops are exited.
8853 for"(X = a,b,seq)"
8855 evaluates seq, where the formal variable "X" goes from "a" to "b".
8856 Nothing is done if "a > b". "a" and "b" must be in R.
8857 fordiv"(n,X,seq)"
8859 evaluates seq, where the formal variable "X" ranges through the
8860 divisors of "n" (see "divisors", which is used as a subroutine). It
8861 is assumed that "factor" can handle "n", without negative
8862 exponents. Instead of "n", it is possible to input a factorization
8863 matrix, i.e. the output of factor(n).
8864 This routine uses "divisors" as a subroutine, then loops over the
8866 divisors. In particular, if "n" is an integer, divisors are sorted
8867 by increasing size.
8868 To avoid storing all divisors, possibly using a lot of memory, the
8870 following (much slower) routine loops over the divisors using
8871 essentially constant space:
8872 FORDIV(N)=
8874 { local(P, E);
8875 P = factor(N); E = P[,2]; P = P[,1];
8877 forvec( v = vector(#E, i, [0,E[i]]),
8878 X = factorback(P, v)
8879 \\ ...
8880 );
8881 }
8882 ? for(i=1,10^5, FORDIV(i))
8883 time = 3,445 ms.
8884 ? for(i=1,10^5, fordiv(i, d, ))
8885 time = 490 ms.
8886 forell"(E,a,b,seq)"
8888 evaluates seq, where the formal variable "E" ranges through all
8889 elliptic curves of conductors from "a" to "b". Th "elldata"
8890 database must be installed and contain data for the specified
8891 conductors.
8892 forprime"(X = a,b,seq)"
8894 evaluates seq, where the formal variable "X" ranges over the prime
8895 numbers between "a" to "b" (including "a" and "b" if they are
8896 prime). More precisely, the value of "X" is incremented to the
8897 smallest prime strictly larger than "X" at the end of each
8898 iteration. Nothing is done if "a > b". Note that "a" and "b" must
8899 be in R.
8900 ? { forprime(p = 2, 12,
8902 print(p);
8903 if (p == 3, p = 6);
8904 )
8905 }
8906 2
8907 3
8908 7
8909 11
8910 forstep"(X = a,b,s,seq)"
8912 evaluates seq, where the formal variable "X" goes from "a" to "b",
8913 in increments of "s". Nothing is done if "s > 0" and "a > b" or if
8914 "s < 0" and "a < b". "s" must be in "R^*" or a vector of steps
8915 "[s_1,...,s_n]". In the latter case, the successive steps are used
8916 in the order they appear in "s".
8917 ? forstep(x=5, 20, [2,4], print(x))
8919 5
8920 7
8921 11
8922 13
8923 17
8924 19
8925 forsubgroup"(H = G,{B},seq)"
8927 evaluates seq for each subgroup "H" of the \emph{abelian} group "G"
8928 (given in SNF form or as a vector of elementary divisors), whose
8929 index is bounded by "B". The subgroups are not ordered in any
8930 obvious way, unless "G" is a "p"-group in which case Birkhoff's
8931 algorithm produces them by decreasing index. A subgroup is given as
8932 a matrix whose columns give its generators on the implicit
8933 generators of "G". For example, the following prints all subgroups
8934 of index less than 2 in "G = Z/2Z g_1 x Z/2Z g_2":
8935 ? G = [2,2]; forsubgroup(H=G, 2, print(H))
8937 [1; 1]
8938 [1; 2]
8939 [2; 1]
8940 [1, 0; 1, 1]
8941 The last one, for instance is generated by "(g_1, g_1 + g_2)". This
8943 routine is intended to treat huge groups, when "subgrouplist" is
8944 not an option due to the sheer size of the output.
8945 For maximal speed the subgroups have been left as produced by the
8947 algorithm. To print them in canonical form (as left divisors of
8948 "G" in HNF form), one can for instance use
8949 ? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H))))
8951 [2, 1; 0, 1]
8952 [1, 0; 0, 2]
8953 [2, 0; 0, 1]
8954 [1, 0; 0, 1]
8955 Note that in this last representation, the index "[G:H]" is given
8957 by the determinant. See "galoissubcyclo" and "galoisfixedfield" for
8958 "nfsubfields" applications to Galois theory.
8959 Warning: the present implementation cannot treat a group "G", if
8961 one of its "p"-Sylow subgroups has a cyclic factor with more than
8962 "2^{31}", resp. "2^{63}" elements on a 32-bit, resp. 64-bit
8963 architecture.
8964 forvec"(X = v,seq,{flag = 0})"
8966 Let "v" be an "n"-component vector (where "n" is arbitrary) of two-
8967 component vectors "[a_i,b_i]" for "1 <= i <= n". This routine
8968 evaluates seq, where the formal variables "X[1],..., X[n]" go from
8969 "a_1" to "b_1",..., from "a_n" to "b_n", i.e. "X" goes from
8970 "[a_1,...,a_n]" to "[b_1,...,b_n]" with respect to the
8971 lexicographic ordering. (The formal variable with the highest index
8972 moves the fastest.) If "flag = 1", generate only nondecreasing
8973 vectors "X", and if "flag = 2", generate only strictly increasing
8974 vectors "X".
8975 if"(a,{seq1},{seq2})"
8977 evaluates the expression sequence seq1 if "a" is non-zero,
8978 otherwise the expression seq2. Of course, seq1 or seq2 may be
8979 empty:
8980 "if (a,seq)" evaluates seq if "a" is not equal to zero (you don't
8982 have to write the second comma), and does nothing otherwise,
8983 "if (a,,seq)" evaluates seq if "a" is equal to zero, and does
8985 nothing otherwise. You could get the same result using the "!"
8986 ("not") operator: "if (!a,seq)".
8987 Note that the boolean operators "&&" and "||" are evaluated
8989 according to operator precedence as explained in "Label
8990 se:operators", but that, contrary to other operators, the
8991 evaluation of the arguments is stopped as soon as the final truth
8992 value has been determined. For instance
8993 if (reallydoit && longcomplicatedfunction(), ...)%
8995 is a perfectly safe statement.
8997 Recall that functions such as "break" and "next" operate on
8999 \emph{loops} (such as "forxxx", "while", "until"). The "if"
9000 statement is \emph{not} a loop (obviously!).
9001 next"({n = 1})"
9003 interrupts execution of current "seq", resume the next iteration of
9004 the innermost enclosing loop, within the current function call (or
9005 top level loop). If "n" is specified, resume at the "n"-th
9006 enclosing loop. If "n" is bigger than the number of enclosing
9007 loops, all enclosing loops are exited.
9008 return"({x = 0})"
9010 returns from current subroutine, with result "x". If "x" is
9011 omitted, return the "(void)" value (return no result, like
9012 "print").
9013 until"(a,seq)"
9015 evaluates seq until "a" is not equal to 0 (i.e. until "a" is true).
9016 If "a" is initially not equal to 0, seq is evaluated once (more
9017 generally, the condition on "a" is tested \emph{after} execution of
9018 the seq, not before as in "while").
9019 while"(a,seq)"
9021 while "a" is non-zero, evaluates the expression sequence seq. The
9022 test is made \emph{before} evaluating the "seq", hence in
9023 particular if "a" is initially equal to zero the seq will not be
9024 evaluated at all.
9025 Specific functions used in GP programming
9027 In addition to the general PARI functions, it is necessary to have some
9028 functions which will be of use specifically for "gp", though a few of
9029 these can be accessed under library mode. Before we start describing
9030 these, we recall the difference between \emph{strings} and
9031 \emph{keywords} (see "Label se:strings"): the latter don't get expanded
9032 at all, and you can type them without any enclosing quotes. The former
9033 are dynamic objects, where everything outside quotes gets immediately
9034 expanded.
9035 addhelp"(S,str)"
9037 changes the help message for the symbol "S". The string str is
9038 expanded on the spot and stored as the online help for "S". If "S"
9039 is a function \emph{you} have defined, its definition will still be
9040 printed before the message str. It is recommended that you
9041 document global variables and user functions in this way. Of course
9042 "gp" will not protest if you skip this.
9043 Nothing prevents you from modifying the help of built-in PARI
9045 functions. (But if you do, we would like to hear why you needed to
9046 do it!)
9047 alias"(newkey,key)"
9049 defines the keyword newkey as an alias for keyword key. key must
9050 correspond to an existing \emph{function} name. This is different
9051 from the general user macros in that alias expansion takes place
9052 immediately upon execution, without having to look up any function
9053 code, and is thus much faster. A sample alias file "misc/gpalias"
9054 is provided with the standard distribution. Alias commands are
9055 meant to be read upon startup from the ".gprc" file, to cope with
9056 function names you are dissatisfied with, and should be useless in
9057 interactive usage.
9058 allocatemem"({x = 0})"
9060 this is a very special operation which allows the user to change
9061 the stack size \emph{after} initialization. "x" must be a non-
9062 negative integer. If "x ! = 0", a new stack of size
9063 "16*\ceil{x/16}" bytes is allocated, all the PARI data on the old
9064 stack is moved to the new one, and the old stack is discarded. If
9065 "x = 0", the size of the new stack is twice the size of the old
9066 one.
9067 Although it is a function, "allocatemem" cannot be used in loop-
9069 like constructs, or as part of a larger expression, e.g "2 +
9070 allocatemem()". Such an attempt will raise an error. The technical
9071 reason is that this routine usually moves the stack, so objects
9072 from the current expression may not be correct anymore, e.g. loop
9073 indexes.
9074 The library syntax is allocatemoremem"(x)", where "x" is an
9076 unsigned long, and the return type is void. "gp" uses a variant
9077 which makes sure it was not called within a loop.
9078 default"({key},{val})"
9080 returns the default corresponding to keyword key. If val is
9081 present, sets the default to val first (which is subject to string
9082 expansion first). Typing "default()" (or "\d") yields the complete
9083 default list as well as their current values. See "Label
9084 se:defaults" for a list of available defaults, and "Label se:meta"
9085 for some shortcut alternatives. Note that the shortcut are meant
9086 for interactive use and usually display more information than
9087 "default".
9088 The library syntax is gp_default"(key, val)", where key and val are
9090 "char *".
9091 error"({str}*)"
9093 outputs its argument list (each of them interpreted as a string),
9094 then interrupts the running "gp" program, returning to the input
9095 prompt. For instance
9096 error("n = ", n, " is not squarefree !")
9098 extern"(str)"
9100 the string str is the name of an external command (i.e. one you
9101 would type from your UNIX shell prompt). This command is
9102 immediately run and its input fed into "gp", just as if read from a
9103 file.
9104 The library syntax is extern0"(str)", where str is a "char *".
9106 getheap"()"
9108 returns a two-component row vector giving the number of objects on
9109 the heap and the amount of memory they occupy in long words. Useful
9110 mainly for debugging purposes.
9111 The library syntax is getheap"()".
9113 getrand"()"
9115 returns the current value of the random number seed. Useful mainly
9116 for debugging purposes.
9117 The library syntax is getrand"()", returns a C long.
9119 getstack"()"
9121 returns the current value of "top-avma", i.e. the number of bytes
9122 used up to now on the stack. Should be equal to 0 in between
9123 commands. Useful mainly for debugging purposes.
9124 The library syntax is getstack"()", returns a C long.
9126 gettime"()"
9128 returns the time (in milliseconds) elapsed since either the last
9129 call to "gettime", or to the beginning of the containing GP
9130 instruction (if inside "gp"), whichever came last.
9131 The library syntax is gettime"()", returns a C long.
9133 global"(list of variables)"
9135 declares the corresponding variables to be global. From now on, you
9137 will be forbidden to use them as formal parameters for function
9138 definitions or as loop indexes. This is especially useful when
9139 patching together various scripts, possibly written with different
9140 naming conventions. For instance the following situation is
9141 dangerous:
9142 p = 3 \\ fix characteristic
9144 ...
9145 forprime(p = 2, N, ...)
9146 f(p) = ...
9147 since within the loop or within the function's body (even worse: in
9149 the subroutines called in that scope), the true global value of "p"
9150 will be hidden. If the statement "global(p = 3)" appears at the
9151 beginning of the script, then both expressions will trigger syntax
9152 errors.
9153 Calling "global" without arguments prints the list of global
9155 variables in use. In particular, "eval(global)" will output the
9156 values of all global variables.
9157 input"()"
9159 reads a string, interpreted as a GP expression, from the input
9160 file, usually standard input (i.e. the keyboard). If a sequence of
9161 expressions is given, the result is the result of the last
9162 expression of the sequence. When using this instruction, it is
9163 useful to prompt for the string by using the "print1" function.
9164 Note that in the present version 2.19 of "pari.el", when using "gp"
9165 under GNU Emacs (see "Label se:emacs") one \emph{must} prompt for
9166 the string, with a string which ends with the same prompt as any of
9167 the previous ones (a "? " will do for instance).
9168 install"(name,code,{gpname},{lib})"
9170 loads from dynamic library lib the function name. Assigns to it the
9171 name gpname in this "gp" session, with argument code code (see the
9172 Libpari Manual for an explanation of those). If lib is omitted,
9173 uses "libpari.so". If gpname is omitted, uses name.
9174 This function is useful for adding custom functions to the "gp"
9176 interpreter, or picking useful functions from unrelated libraries.
9177 For instance, it makes the function "system" obsolete:
9178 ? install(system, vs, sys, "libc.so")
9180 ? sys("ls gp*")
9181 gp.c gp.h gp_rl.c
9182 But it also gives you access to all (non static) functions defined
9184 in the PARI library. For instance, the function "GEN addii(GEN x,
9185 GEN y)" adds two PARI integers, and is not directly accessible
9186 under "gp" (it's eventually called by the "+" operator of course):
9187 ? install("addii", "GG")
9189 ? addii(1, 2)
9190 %1 = 3
9191 Re-installing a function will print a Warning, and update the
9193 prototype code if needed, but will reload a symbol from the
9194 library, even it the latter has been recompiled.
9195 Caution: This function may not work on all systems, especially when
9197 "gp" has been compiled statically. In that case, the first use of
9198 an installed function will provoke a Segmentation Fault, i.e. a
9199 major internal blunder (this should never happen with a dynamically
9200 linked executable). Hence, if you intend to use this function,
9201 please check first on some harmless example such as the ones above
9202 that it works properly on your machine.
9203 kill"(s)"
9205 kills the present value of the variable, alias or user-defined
9206 function "s". The corresponding identifier can now be used to name
9207 any GP object (variable or function). This is the only way to
9208 replace a variable by a function having the same name (or the other
9209 way round), as in the following example:
9210 ? f = 1
9212 %1 = 1
9213 ? f(x) = 0
9214 *** unused characters: f(x)=0
9215 ^----
9216 ? kill(f)
9217 ? f(x) = 0
9218 ? f()
9219 %2 = 0
9220 When you kill a variable, all objects that used it become invalid.
9222 You can still display them, even though the killed variable will be
9223 printed in a funny way. For example:
9224 ? a^2 + 1
9226 %1 = a^2 + 1
9227 ? kill(a)
9228 ? %1
9229 %2 = #<1>^2 + 1
9230 If you simply want to restore a variable to its ``undefined'' value
9232 (monomial of degree one), use the quote operator: "a = 'a".
9233 Predefined symbols ("x" and GP function names) cannot be killed.
9234 print"({str}*)"
9236 outputs its (string) arguments in raw format, ending with a
9237 newline.
9238 print1"({str}*)"
9240 outputs its (string) arguments in raw format, without ending with a
9241 newline (note that you can still embed newlines within your
9242 strings, using the "\n" notation !).
9243 printp"({str}*)"
9245 outputs its (string) arguments in prettyprint (beautified) format,
9246 ending with a newline.
9247 printp1"({str}*)"
9249 outputs its (string) arguments in prettyprint (beautified) format,
9250 without ending with a newline.
9251 printtex"({str}*)"
9253 outputs its (string) arguments in TeX format. This output can then
9254 be used in a TeX manuscript. The printing is done on the standard
9255 output. If you want to print it to a file you should use "writetex"
9256 (see there).
9257 Another possibility is to enable the "log" default (see "Label
9259 se:defaults"). You could for instance do:
9260 default(logfile, "new.tex");
9262 default(log, 1);
9263 printtex(result);
9264 quit"()"
9266 exits "gp".
9267 read"({filename})"
9269 reads in the file filename (subject to string expansion). If
9270 filename is omitted, re-reads the last file that was fed into "gp".
9271 The return value is the result of the last expression evaluated.
9272 If a GP "binary file" is read using this command (see "Label
9274 se:writebin"), the file is loaded and the last object in the file
9275 is returned.
9276 readvec"({str})"
9278 reads in the file filename (subject to string expansion). If
9279 filename is omitted, re-reads the last file that was fed into "gp".
9280 The return value is a vector whose components are the evaluation of
9281 all sequences of instructions contained in the file. For instance,
9282 if file contains
9283 1
9285 2
9286 3
9287 then we will get:
9289 ? \r a
9291 %1 = 1
9292 %2 = 2
9293 %3 = 3
9294 ? read(a)
9295 %4 = 3
9296 ? readvec(a)
9297 %5 = [1, 2, 3]
9298 In general a sequence is just a single line, but as usual braces
9300 and "\\" may be used to enter multiline sequences.
9301 reorder"({x = []})"
9303 "x" must be a vector. If "x" is the empty vector, this gives the
9304 vector whose components are the existing variables in increasing
9305 order (i.e. in decreasing importance). Killed variables (see
9306 "kill") will be shown as 0. If "x" is non-empty, it must be a
9307 permutation of variable names, and this permutation gives a new
9308 order of importance of the variables, \emph{for output only}. For
9309 example, if the existing order is "[x,y,z]", then after
9310 "reorder([z,x])" the order of importance of the variables, with
9311 respect to output, will be "[z,y,x]". The internal representation
9312 is unaffected.
9313 setrand"(n)"
9315 reseeds the random number generator to the value "n". The initial
9316 seed is "n = 1".
9317 The library syntax is setrand"(n)", where "n" is a "long". Returns
9319 "n".
9320 system"(str)"
9322 str is a string representing a system command. This command is
9323 executed, its output written to the standard output (this won't get
9324 into your logfile), and control returns to the PARI system. This
9325 simply calls the C "system" command.
9326 trap"({e}, {rec}, {seq})"
9328 tries to evaluate seq, trapping error "e", that is effectively
9329 preventing it from aborting computations in the usual way; the
9330 recovery sequence rec is executed if the error occurs and the
9331 evaluation of rec becomes the result of the command. If "e" is
9332 omitted, all exceptions are trapped. Note in particular that
9333 hitting "^C" (Control-C) raises an exception. See "Label
9334 se:errorrec" for an introduction to error recovery under "gp".
9335 ? \\ trap division by 0
9337 ? inv(x) = trap (gdiver, INFINITY, 1/x)
9338 ? inv(2)
9339 %1 = 1/2
9340 ? inv(0)
9341 %2 = INFINITY
9342 If seq is omitted, defines rec as a default action when catching
9344 exception "e", provided no other trap as above intercepts it first.
9345 The error message is printed, as well as the result of the
9346 evaluation of rec, and control is given back to the "gp" prompt. In
9347 particular, current computation is then lost.
9348 The following error handler prints the list of all user variables,
9350 then stores in a file their name and their values:
9351 ? { trap( ,
9353 print(reorder);
9354 writebin("crash")) }
9355 If no recovery code is given (rec is omitted) a break loop will be
9357 started (see "Label se:breakloop"). In particular
9358 ? trap()
9360 by itself installs a default error handler, that will start a break
9362 loop whenever an exception is raised.
9363 If rec is the empty string "" the default handler (for that error
9365 if "e" is present) is disabled.
9366 Note: The interface is currently not adequate for trapping
9368 individual exceptions. In the current version 2.2.0, the following
9369 keywords are recognized, but the name list will be expanded and
9370 changed in the future (all library mode errors can be trapped: it's
9371 a matter of defining the keywords to "gp", and there are currently
9372 far too many useless ones):
9373 "accurer": accuracy problem
9375 "archer": not available on this architecture or operating system
9377 "errpile": the PARI stack overflows
9379 "gdiver": division by 0
9381 "invmoder": impossible inverse modulo
9383 "siginter": SIGINT received (usually from Control-C)
9385 "talker": miscellaneous error
9387 "typeer": wrong type
9389 "user": user error (from the "error" function)
9391 type"(x)"
9393 this is useful only under "gp". Returns the internal type name of
9394 the PARI object "x" as a string. Check out existing type names
9395 with the metacommand "\t". For example type(1) will return
9396 ""t_INT"".
9397 The library syntax is type0"(x)", though the macro "typ" is usually
9399 simpler to use since it return an integer that can easily be
9400 matched with the symbols "t_*". The name "type" was avoided due to
9401 the fact that "type" is a reserved identifier for some C(++)
9402 compilers.
9403 version"()"
9405 Returns the current version number as a "t_VEC" with three integer
9406 components: major version number, minor version number and
9407 patchlevel. To check against a particular version number, you can
9408 use:
9409 if (lex(version(), [2,2,0]) >= 0,
9411 \\ code to be executed if we are running 2.2.0 or more recent.
9412 ,
9413 \\ compatibility code
9414 );
9415 whatnow"(key)"
9417 if keyword key is the name of a function that was present in GP
9418 version 1.39.15 or lower, outputs the new function name and syntax,
9419 if it changed at all (387 out of 560 did).
9420 write"(filename,{str}*)"
9422 writes (appends) to filename the remaining arguments, and appends a
9423 newline (same output as "print").
9424 write1"(filename,{str}*)"
9426 writes (appends) to filename the remaining arguments without a
9427 trailing newline (same output as "print1").
9428 writebin"(filename,{x})"
9430 writes (appends) to filename the object "x" in binary format. This
9431 format is not human readable, but contains the exact internal
9432 structure of "x", and is much faster to save/load than a string
9433 expression, as would be produced by "write". The binary file format
9434 includes a magic number, so that such a file can be recognized and
9435 correctly input by the regular "read" or "\r" function. If saved
9436 objects refer to (polynomial) variables that are not defined in the
9437 new session, they will be displayed in a funny way (see "Label
9438 se:kill").
9439 If "x" is omitted, saves all user variables from the session,
9441 together with their names. Reading such a ``named object'' back in
9442 a "gp" session will set the corresponding user variable to the
9443 saved value. E.g after
9444 x = 1; writebin("log")
9446 reading "log" into a clean session will set "x" to 1. The relative
9448 variables priorities (see "Label se:priority") of new variables set
9449 in this way remain the same (preset variables retain their former
9450 priority, but are set to the new value). In particular, reading
9451 such a session log into a clean session will restore all variables
9452 exactly as they were in the original one.
9453 User functions, installed functions and history objects can not be
9455 saved via this function. Just as a regular input file, a binary
9456 file can be compressed using "gzip", provided the file name has the
9457 standard ".gz" extension.
9458 In the present implementation, the binary files are architecture
9460 dependent and compatibility with future versions of "gp" is not
9461 guaranteed. Hence binary files should not be used for long term
9462 storage (also, they are larger and harder to compress than text
9463 files).
9464 writetex"(filename,{str}*)"
9466 as "write", in TeX format.
9467
9469 Hey! The above document had some coding errors, which are explained
9470 below:
9471 Around line 9514:
9473 '=item' outside of any '=over'
9474 Around line 9705:
9476 You forgot a '=back' before '=head2'
9477 Around line 9716:
9479 '=item' outside of any '=over'
9480perl v5.12.1 2010-07-09 libPARI(3)