1libPARI(3) User Contributed Perl Documentation libPARI(3)
2
6 Math::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 /usr/share/libpari23. It should be noted that
12 many of these functions accept quite different types as arguments, but
13 others are more restricted. The list of acceptable types will be given
14 for each function or class of functions. Except when stated otherwise,
15 it is understood that a function or operation which should make natural
16 sense is legal. In this chapter, we will describe the functions
17 according to a rough classification. The general entry looks something
18 like:
19 foo"(x,{flag = 0})": short description.
21 The library syntax is foo"(x,flag)".
23 This means that the GP function "foo" has one mandatory argument "x",
25 and an optional one, "flag", whose default value is 0. (The "{}" should
26 not be typed, it is just a convenient notation we will use throughout
27 to denote optional arguments.) That is, you can type "foo(x,2)", or
28 foo(x), which is then understood to mean "foo(x,0)". As well, a comma
29 or closing parenthesis, where an optional argument should have been,
30 signals to GP it should use the default. Thus, the syntax "foo(x,)" is
31 also accepted as a synonym for our last expression. When a function has
32 more than one optional argument, the argument list is filled with user
33 supplied values, in order. When none are left, the defaults are used
34 instead. Thus, assuming that "foo"'s prototype had been
35 " foo({x = 1},{y = 2},{z = 3}), "
37 typing in "foo(6,4)" would give you "foo(6,4,3)". In the rare case when
39 you want to set some far away argument, and leave the defaults in
40 between as they stand, you can use the ``empty arg'' trick alluded to
41 above: "foo(6,,1)" would yield "foo(6,2,1)". By the way, "foo()" by
42 itself yields "foo(1,2,3)" as was to be expected.
43 In this rather special case of a function having no mandatory argument,
45 you can even omit the "()": a standalone "foo" would be enough (though
46 we do not recommend it for your scripts, for the sake of clarity). In
47 defining GP syntax, we strove to put optional arguments at the end of
48 the argument list (of course, since they would not make sense
49 otherwise), and in order of decreasing usefulness so that, most of the
50 time, you will be able to ignore them.
51 Finally, an optional argument (between braces) followed by a star, like
53 "{x}*", means that any number of such arguments (possibly none) can be
54 given. This is in particular used by the various "print" routines.
55 Flags. A flag is an argument which, rather than conveying actual
57 information to the routine, intructs it to change its default
58 behaviour, e.g. return more or less information. All such flags are
59 optional, and will be called flag in the function descriptions to
60 follow. There are two different kind of flags
61 \item generic: all valid values for the flag are individually described
63 (``If flag is equal to 1, then...'').
64 \item binary: use customary binary notation as a compact way to
66 represent many toggles with just one integer. Let "(p_0,...,p_n)" be a
67 list of switches (i.e. of properties which take either the value 0
68 or 1), the number "2^3 + 2^5 = 40" means that "p_3" and "p_5" are set
69 (that is, set to 1), and none of the others are (that is, they are set
70 to 0). This is announced as ``The binary digits of "flag" mean 1:
71 "p_0", 2: "p_1", 4: "p_2"'', and so on, using the available consecutive
72 powers of 2.
73 Mnemonics for flags. Numeric flags as mentionned above are obscure,
75 error-prone, and quite rigid: should the authors want to adopt a new
76 flag numbering scheme (for instance when noticing flags with the same
77 meaning but different numeric values across a set of routines), it
78 would break backward compatibility. The only advantage of explicit
79 numeric values is that they are fast to type, so their use is only
80 advised when using the calculator "gp".
81 As an alternative, one can replace a numeric flag by a character string
83 containing symbolic identifiers. For a generic flag, the mnemonic
84 corresponding to the numeric identifier is given after it as in
85 fun(x, {flag = 0} ):
87 If flag is equal to 1 = AGM, use an agm formula\dots
89 which means that one can use indifferently "fun(x, 1)" or "fun(x,
91 AGM)".
92 For a binary flag, mnemonics corresponding to the various toggles are
94 given after each of them. They can be negated by prepending "no_" to
95 the mnemonic, or by removing such a prefix. These toggles are grouped
96 together using any punctuation character (such as ',' or ';'). For
97 instance (taken from description of "ploth(X = a,b,expr,{flag = 0},{n =
98 0})")
99 Binary digits of flags mean: C<1 = Parametric>,
101 C<2 = Recursive>,...
102 so that, instead of 1, one could use the mnemonic "Parametric;
104 no_Recursive", or simply "Parametric" since "Recursive" is unset by
105 default (default value of "flag" is 0, i.e. everything unset).
106 Pointers.\varsidx{pointer} If a parameter in the function prototype is
108 prefixed with a & sign, as in
109 foo"(x,&e)"
111 it means that, besides the normal return value, the function may assign
113 a value to "e" as a side effect. When passing the argument, the & sign
114 has to be typed in explicitly. As of version /usr/share/libpari23, this
115 pointer argument is optional for all documented functions, hence the &
116 will always appear between brackets as in "Z_issquare""(x,{&e})".
117 About library programming. the library function "foo", as defined at
119 the beginning of this section, is seen to have two mandatory arguments,
120 "x" and flag: no PARI mathematical function has been implemented so as
121 to accept a variable number of arguments, so all arguments are
122 mandatory when programming with the library (often, variants are
123 provided corresponding to the various flag values). When not mentioned
124 otherwise, the result and arguments of a function are assumed
125 implicitly to be of type "GEN". Most other functions return an object
126 of type "long" integer in C (see Chapter 4). The variable or parameter
127 names prec and flag always denote "long" integers.
128 The "entree" type is used by the library to implement iterators (loops,
130 sums, integrals, etc.) when a formal variable has to successively
131 assume a number of values in a given set. When programming with the
132 library, it is easier and much more efficient to code loops and the
133 like directly. Hence this type is not documented, although it does
134 appear in a few library function prototypes below. See "Label se:sums"
135 for more details.
136
138 +"/"-
139 The expressions "+""x" and "-""x" refer to monadic operators (the first
140 does nothing, the second negates "x").
141 The library syntax is gneg"(x)" for "-""x".
143 +, "-"
145 The expression "x" "+" "y" is the sum and "x" "-" "y" is the difference
146 of "x" and "y". Among the prominent impossibilities are
147 addition/subtraction between a scalar type and a vector or a matrix,
148 between vector/matrices of incompatible sizes and between an intmod and
149 a real number.
150 The library syntax is gadd"(x,y)" "x" "+" "y", " gsub(x,y)" for "x" "-"
152 "y".
153 *
155 The expression "x" "*" "y" is the product of "x" and "y". Among the
156 prominent impossibilities are multiplication between vector/matrices of
157 incompatible sizes, between an intmod and a real number. Note that
158 because of vector and matrix operations, "*" is not necessarily
159 commutative. Note also that since multiplication between two column or
160 two row vectors is not allowed, to obtain the scalar product of two
161 vectors of the same length, you must multiply a line vector by a column
162 vector, if necessary by transposing one of the vectors (using the
163 operator "~" or the function "mattranspose", see "Label
164 se:linear_algebra").
165 If "x" and "y" are binary quadratic forms, compose them. See also
167 "qfbnucomp" and "qfbnupow".
168 The library syntax is gmul"(x,y)" for "x" "*" "y". Also available is "
170 gsqr(x)" for "x" "*" "x" (faster of course!).
171 /
173 The expression "x" "/" "y" is the quotient of "x" and "y". In addition
174 to the impossibilities for multiplication, note that if the divisor is
175 a matrix, it must be an invertible square matrix, and in that case the
176 result is "x*y^{-1}". Furthermore note that the result is as exact as
177 possible: in particular, division of two integers always gives a
178 rational number (which may be an integer if the quotient is exact) and
179 \emph{not} the Euclidean quotient (see "x" "\" "y" for that), and
180 similarly the quotient of two polynomials is a rational function in
181 general. To obtain the approximate real value of the quotient of two
182 integers, add 0. to the result; to obtain the approximate "p"-adic
183 value of the quotient of two integers, add "O(p^k)" to the result;
184 finally, to obtain the Taylor series expansion of the quotient of two
185 polynomials, add "O(X^k)" to the result or use the "taylor" function
186 (see "Label se:taylor").
187 The library syntax is gdiv"(x,y)" for "x" "/" "y".
189 \
191 The expression "x \y" is the Euclidean quotient of "x" and "y". If "y"
192 is a real scalar, this is defined as "floor(x/y)" if "y > 0", and
193 "ceil(x/y)" if "y < 0" and the division is not exact. Hence the
194 remainder "x - (x\y)*y" is in "[0, |y|[".
195 Note that when "y" is an integer and "x" a polynomial, "y" is first
197 promoted to a polynomial of degree 0. When "x" is a vector or matrix,
198 the operator is applied componentwise.
199 The library syntax is gdivent"(x,y)" for "x" "\" "y".
201 \/
203 The expression "x" "\/" "y" evaluates to the rounded Euclidean quotient
204 of "x" and "y". This is the same as "x \y" except for scalar division:
205 the quotient is such that the corresponding remainder is smallest in
206 absolute value and in case of a tie the quotient closest to "+ oo " is
207 chosen (hence the remainder would belong to "]-|y|/2, |y|/2]").
208 When "x" is a vector or matrix, the operator is applied componentwise.
210 The library syntax is gdivround"(x,y)" for "x" "\/" "y".
212 %
214 The expression "x % y" evaluates to the modular Euclidean remainder of
215 "x" and "y", which we now define. If "y" is an integer, this is the
216 smallest non-negative integer congruent to "x" modulo "y". If "y" is a
217 polynomial, this is the polynomial of smallest degree congruent to "x"
218 modulo "y". When "y" is a non-integral real number, "x%y" is defined as
219 "x - (x\y)*y". This coincides with the definition for "y" integer if
220 and only if "x" is an integer, but still belongs to "[0, |y|[". For
221 instance:
222 ? (1/2) % 3
224 %1 = 2
225 ? 0.5 % 3
226 *** forbidden division t_REAL % t_INT.
227 ? (1/2) % 3.0
228 %2 = 1/2
229 Note that when "y" is an integer and "x" a polynomial, "y" is first
231 promoted to a polynomial of degree 0. When "x" is a vector or matrix,
232 the operator is applied componentwise.
233 The library syntax is gmod"(x,y)" for "x" "%" "y".
235 divrem"(x,y,{v})"
237 creates a column vector with two components, the first being the
238 Euclidean quotient ("x \y"), the second the Euclidean remainder ("x -
239 (x\y)*y"), of the division of "x" by "y". This avoids the need to do
240 two divisions if one needs both the quotient and the remainder. If "v"
241 is present, and "x", "y" are multivariate polynomials, divide with
242 respect to the variable "v".
243 Beware that "divrem(x,y)[2]" is in general not the same as "x % y";
245 there is no operator to obtain it in GP:
246 ? divrem(1/2, 3)[2]
248 %1 = 1/2
249 ? (1/2) % 3
250 %2 = 2
251 ? divrem(Mod(2,9), 3)[2]
252 *** forbidden division t_INTMOD \ t_INT.
253 ? Mod(2,9) % 6
254 %3 = Mod(2,3)
255 The library syntax is divrem"(x,y,v)",where "v" is a "long". Also
257 available as " gdiventres(x,y)" when "v" is not needed.
258 ^
260 The expression "x^n" is powering. If the exponent is an integer, then
261 exact operations are performed using binary (left-shift) powering
262 techniques. In particular, in this case "x" cannot be a vector or
263 matrix unless it is a square matrix (invertible if the exponent is
264 negative). If "x" is a "p"-adic number, its precision will increase if
265 "v_p(n) > 0". Powering a binary quadratic form (types "t_QFI" and
266 "t_QFR") returns a reduced representative of the class, provided the
267 input is reduced. In particular, "x^1" is identical to "x".
268 PARI is able to rewrite the multiplication "x * x" of two
270 \emph{identical} objects as "x^2", or sqr(x). Here, identical means the
271 operands are two different labels referencing the same chunk of memory;
272 no equality test is performed. This is no longer true when more than
273 two arguments are involved.
274 If the exponent is not of type integer, this is treated as a
276 transcendental function (see "Label se:trans"), and in particular has
277 the effect of componentwise powering on vector or matrices.
278 As an exception, if the exponent is a rational number "p/q" and "x" an
280 integer modulo a prime or a "p"-adic number, return a solution "y" of
281 "y^q = x^p" if it exists. Currently, "q" must not have large prime
282 factors. Beware that
283 ? Mod(7,19)^(1/2)
285 %1 = Mod(11, 19) /* is any square root */
286 ? sqrt(Mod(7,19))
287 %2 = Mod(8, 19) /* is the smallest square root */
288 ? Mod(7,19)^(3/5)
289 %3 = Mod(1, 19)
290 ? %3^(5/3)
291 %4 = Mod(1, 19) /* Mod(7,19) is just another cubic root */
292 If the exponent is a negative integer, an inverse must be computed.
294 For non-invertible "t_INTMOD", this will fail and implicitly exhibit a
295 non trivial factor of the modulus:
296 ? Mod(4,6)^(-1)
298 *** impossible inverse modulo: Mod(2, 6).
299 (Here, a factor 2 is obtained directly. In general, take the gcd of the
301 representative and the modulus.) This is most useful when performing
302 complicated operations modulo an integer "N" whose factorization is
303 unknown. Either the computation succeeds and all is well, or a factor
304 "d" is discovered and the computation may be restarted modulo "d" or
305 "N/d".
306 For non-invertible "t_POLMOD", this will fail without exhibiting a
308 factor.
309 ? Mod(x^2, x^3-x)^(-1)
311 *** non-invertible polynomial in RgXQ_inv.
312 ? a = Mod(3,4)*y^3 + Mod(1,4); b = y^6+y^5+y^4+y^3+y^2+y+1;
314 ? Mod(a, b)^(-1);
315 *** non-invertible polynomial in RgXQ_inv.
316 In fact the latter polynomial is invertible, but the algorithm used
318 (subresultant) assumes the base ring is a domain. If it is not the
319 case, as here for "Z/4Z", a result will be correct but chances are an
320 error will occur first. In this specific case, one should work with
321 2-adics. In general, one can try the following approach
322 ? inversemod(a, b) =
324 { local(m);
325 m = polsylvestermatrix(polrecip(a), polrecip(b));
326 m = matinverseimage(m, matid(#m)[,1]);
327 Polrev( vecextract(m, Str("..", poldegree(b))), variable(b) )
328 }
329 ? inversemod(a,b)
330 %2 = Mod(2,4)*y^5 + Mod(3,4)*y^3 + Mod(1,4)*y^2 + Mod(3,4)*y + Mod(2,4)
331 This is not guaranteed to work either since it must invert pivots. See
333 "Label se:linear_algebra".
334 The library syntax is gpow"(x,n,prec)" for "x^n".
336 bittest"(x,n)"
338 outputs the "n^{th}" bit of "x" starting from the right (i.e. the
339 coefficient of "2^n" in the binary expansion of "x"). The result is 0
340 or 1. To extract several bits at once as a vector, pass a vector for
341 "n".
342 See "Label se:bitand" for the behaviour at negative arguments.
344 The library syntax is bittest"(x,n)", where "n" and the result are
346 "long"s.
347 shift"(x,n)" or "x" "<< " "n" ( = "x" ">> " "(-n)")
349 shifts "x" componentwise left by "n" bits if "n >= 0" and right by
350 "|n|" bits if "n < 0". A left shift by "n" corresponds to
351 multiplication by "2^n". A right shift of an integer "x" by "|n|"
352 corresponds to a Euclidean division of "x" by "2^{|n|}" with a
353 remainder of the same sign as "x", hence is not the same (in general)
354 as "x \ 2^n".
355 The library syntax is gshift"(x,n)" where "n" is a "long".
357 shiftmul"(x,n)"
359 multiplies "x" by "2^n". The difference with "shift" is that when "n <
360 0", ordinary division takes place, hence for example if "x" is an
361 integer the result may be a fraction, while for shifts Euclidean
362 division takes place when "n < 0" hence if "x" is an integer the result
363 is still an integer.
364 The library syntax is gmul2n"(x,n)" where "n" is a "long".
366 Comparison and boolean operators
368 The six standard comparison operators "<= ", "< ", ">= ", "> ", " == ",
369 "! = " are available in GP, and in library mode under the names "gle",
370 "glt", "gge", "ggt", "geq", "gne" respectively. The library syntax is
371 "co(x,y)", where co is the comparison operator. The result is 1 (as a
372 "GEN") if the comparison is true, 0 (as a "GEN") if it is false. For
373 the purpose of comparison, "t_STR" objects are strictly larger than any
374 other non-string type; two "t_STR" objects are compared using the
375 standard lexicographic order.
376 The standard boolean functions "||" (inclusive or), "&&" (and) and "!"
378 (not) are also available, and the library syntax is " gor(x,y)", "
379 gand(x,y)" and " gnot(x)" respectively.
380 In library mode, it is in fact usually preferable to use the two basic
382 functions which are " gcmp(x,y)" which gives the sign (1, 0, or -1) of
383 "x-y", where "x" and "y" must be in R, and " gequal(x,y)" which can be
384 applied to any two PARI objects "x" and "y" and gives 1 (i.e. true) if
385 they are equal (but not necessarily identical), 0 (i.e. false)
386 otherwise. Comparisons to special constants are implemented and should
387 be used instead of "gequal": " gcmp0(x)" ("x == 0" ?), " gcmp1(x)" ("x
388 == 1" ?), and " gcmp_1(x)" ("x == -1" ?).
389 Note that gcmp0(x) tests whether "x" is equal to zero, even if "x" is
391 not an exact object. To test whether "x" is an exact object which is
392 equal to zero, one must use " isexactzero(x)".
393 Also note that the "gcmp" and "gequal" functions return a C-integer,
395 and \emph{not} a "GEN" like "gle" etc.
396 GP accepts the following synonyms for some of the above functions:
398 since we thought it might easily lead to confusion, we don't use the
399 customary C operators for bitwise "and" or bitwise "or" (use "bitand"
400 or "bitor"), hence "|" and "&" are accepted as synonyms of "||" and
401 "&&" respectively. Also, "< > " is accepted as a synonym for "! = ".
402 On the other hand, " = " is definitely \emph{not} a synonym for " == "
403 since it is the assignment statement.
404 lex"(x,y)"
406 gives the result of a lexicographic comparison between "x" and "y" (as
407 "-1", 0 or 1). This is to be interpreted in quite a wide sense: It is
408 admissible to compare objects of different types (scalars, vectors,
409 matrices), provided the scalars can be compared, as well as
410 vectors/matrices of different lengths. The comparison is recursive.
411 In case all components are equal up to the smallest length of the
413 operands, the more complex is considered to be larger. More precisely,
414 the longest is the largest; when lengths are equal, we have matrix " >
415 " vector " > " scalar. For example:
416 ? lex([1,3], [1,2,5])
418 %1 = 1
419 ? lex([1,3], [1,3,-1])
420 %2 = -1
421 ? lex([1], [[1]])
422 %3 = -1
423 ? lex([1], [1]~)
424 %4 = 0
425 The library syntax is lexcmp"(x,y)".
427 sign"(x)"
429 sign (0, 1 or "-1") of "x", which must be of type integer, real or
430 fraction.
431 The library syntax is gsigne"(x)". The result is a "long".
433 max"(x,y)" and " min(x,y)"
435 creates the maximum and minimum of "x" and "y" when they can be
436 compared.
437 The library syntax is gmax"(x,y)" and " gmin(x,y)".
439 vecmax"(x)"
441 if "x" is a vector or a matrix, returns the maximum of the elements of
442 "x", otherwise returns a copy of "x". Error if "x" is empty.
443 The library syntax is vecmax"(x)".
445 vecmin"(x)"
447 if "x" is a vector or a matrix, returns the minimum of the elements of
448 "x", otherwise returns a copy of "x". Error if "x" is empty.
449 The library syntax is vecmin"(x)".
451
453 Many of the conversion functions are rounding or truncating operations.
454 In this case, if the argument is a rational function, the result is the
455 Euclidean quotient of the numerator by the denominator, and if the
456 argument is a vector or a matrix, the operation is done componentwise.
457 This will not be restated for every function.
458 Col"({x = []})"
460 transforms the object "x" into a column vector. The vector will be
461 with one component only, except when "x" is a vector or a quadratic
462 form (in which case the resulting vector is simply the initial object
463 considered as a column vector), a matrix (the column of row vectors
464 comprising the matrix is returned), a character string (a column of
465 individual characters is returned), but more importantly when "x" is a
466 polynomial or a power series. In the case of a polynomial, the
467 coefficients of the vector start with the leading coefficient of the
468 polynomial, while for power series only the significant coefficients
469 are taken into account, but this time by increasing order of degree.
470 The library syntax is gtocol"(x)".
472 List"({x = []})"
474 transforms a (row or column) vector "x" into a list. The only other way
475 to create a "t_LIST" is to use the function "listcreate".
476 This is useless in library mode.
478 Mat"({x = []})"
480 transforms the object "x" into a matrix. If "x" is already a matrix, a
481 copy of "x" is created. If "x" is not a vector or a matrix, this
482 creates a "1 x 1" matrix. If "x" is a row (resp. column) vector, this
483 creates a 1-row (resp. 1-column) matrix, \emph{unless} all elements
484 are column (resp. row) vectors of the same length, in which case the
485 vectors are concatenated sideways and the associated big matrix is
486 returned.
487 ? Mat(x + 1)
489 %1 =
490 [x + 1]
491 ? Vec( matid(3) )
492 %2 = [[1, 0, 0]~, [0, 1, 0]~, [0, 0, 1]~]
493 ? Mat(%)
494 %3 =
495 [1 0 0]
496 [0 1 0]
498 [0 0 1]
500 ? Col( [1,2; 3,4] )
501 %4 = [[1, 2], [3, 4]]~
502 ? Mat(%)
503 %5 =
504 [1 2]
505 [3 4]
507 The library syntax is gtomat"(x)".
509 Mod"(x,y,{flag = 0})"
511 creates the PARI object "(x mod y)", i.e. an intmod or a polmod. "y"
512 must be an integer or a polynomial. If "y" is an integer, "x" must be
513 an integer, a rational number, or a "p"-adic number compatible with the
514 modulus "y". If "y" is a polynomial, "x" must be a scalar (which is not
515 a polmod), a polynomial, a rational function, or a power series.
516 This function is not the same as "x" "%" "y", the result of which is an
518 integer or a polynomial.
519 "flag" is obsolete and should not be used.
521 The library syntax is gmodulo"(x,y)".
523 Pol"(x,{v = x})"
525 transforms the object "x" into a polynomial with main variable "v". If
526 "x" is a scalar, this gives a constant polynomial. If "x" is a power
527 series, the effect is identical to "truncate" (see there), i.e. it
528 chops off the "O(X^k)". If "x" is a vector, this function creates the
529 polynomial whose coefficients are given in "x", with "x[1]" being the
530 leading coefficient (which can be zero).
531 Warning: this is \emph{not} a substitution function. It will not
533 transform an object containing variables of higher priority than "v".
534 ? Pol(x + y, y)
536 *** Pol: variable must have higher priority in gtopoly.
537 The library syntax is gtopoly"(x,v)", where "v" is a variable number.
539 Polrev"(x,{v = x})"
541 transform the object "x" into a polynomial with main variable "v". If
542 "x" is a scalar, this gives a constant polynomial. If "x" is a power
543 series, the effect is identical to "truncate" (see there), i.e. it
544 chops off the "O(X^k)". If "x" is a vector, this function creates the
545 polynomial whose coefficients are given in "x", with "x[1]" being the
546 constant term. Note that this is the reverse of "Pol" if "x" is a
547 vector, otherwise it is identical to "Pol".
548 The library syntax is gtopolyrev"(x,v)", where "v" is a variable
550 number.
551 Qfb"(a,b,c,{D = 0.})"
553 creates the binary quadratic form "ax^2+bxy+cy^2". If "b^2-4ac > 0",
554 initialize Shanks' distance function to "D". Negative definite forms
555 are not implemented, use their positive definite counterpart instead.
556 The library syntax is Qfb0"(a,b,c,D,prec)". Also available are "
558 qfi(a,b,c)" (when "b^2-4ac < 0"), and " qfr(a,b,c,d)" (when "b^2-4ac >
559 0").
560 Ser"(x,{v = x})"
562 transforms the object "x" into a power series with main variable "v"
563 ("x" by default). If "x" is a scalar, this gives a constant power
564 series with precision given by the default "serieslength"
565 (corresponding to the C global variable "precdl"). If "x" is a
566 polynomial, the precision is the greatest of "precdl" and the degree of
567 the polynomial. If "x" is a vector, the precision is similarly given,
568 and the coefficients of the vector are understood to be the
569 coefficients of the power series starting from the constant term
570 (i.e. the reverse of the function "Pol").
571 The warning given for "Pol" also applies here: this is not a
573 substitution function.
574 The library syntax is gtoser"(x,v)", where "v" is a variable number
576 (i.e. a C integer).
577 Set"({x = []})"
579 converts "x" into a set, i.e. into a row vector of character strings,
580 with strictly increasing entries with respect to lexicographic
581 ordering. The components of "x" are put in canonical form (type
582 "t_STR") so as to be easily sorted. To recover an ordinary "GEN" from
583 such an element, you can apply "eval" to it.
584 The library syntax is gtoset"(x)".
586 Str"({x}*)"
588 converts its argument list into a single character string (type
589 "t_STR", the empty string if "x" is omitted). To recover an ordinary
590 "GEN" from a string, apply "eval" to it. The arguments of "Str" are
591 evaluated in string context, see "Label se:strings".
592 ? x2 = 0; i = 2; Str(x, i)
594 %1 = "x2"
595 ? eval(%)
596 %2 = 0
597 This function is mostly useless in library mode. Use the pair
599 "strtoGEN"/"GENtostr" to convert between "GEN" and "char*". The latter
600 returns a malloced string, which should be freed after usage.
601 Strchr"(x)"
603 converts "x" to a string, translating each integer into a character.
604 ? Strchr(97)
606 %1 = "a"
607 ? Vecsmall("hello world")
608 %2 = Vecsmall([104, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100])
609 ? Strchr(%)
610 %3 = "hello world"
611 Strexpand"({x}*)"
613 converts its argument list into a single character string (type
614 "t_STR", the empty string if "x" is omitted). Then performe
615 environment expansion, see "Label se:envir". This feature can be used
616 to read environment variable values.
617 ? Strexpand("$HOME/doc")
619 %1 = "/home/pari/doc"
620 The individual arguments are read in string context, see "Label
622 se:strings".
623 Strtex"({x}*)"
625 translates its arguments to TeX format, and concatenates the results
626 into a single character string (type "t_STR", the empty string if "x"
627 is omitted).
628 The individual arguments are read in string context, see "Label
630 se:strings".
631 Vec"({x = []})"
633 transforms the object "x" into a row vector. The vector will be with
634 one component only, except when "x" is a vector or a quadratic form (in
635 which case the resulting vector is simply the initial object considered
636 as a row vector), a matrix (the vector of columns comprising the matrix
637 is return), a character string (a vector of individual characters is
638 returned), but more importantly when "x" is a polynomial or a power
639 series. In the case of a polynomial, the coefficients of the vector
640 start with the leading coefficient of the polynomial, while for power
641 series only the significant coefficients are taken into account, but
642 this time by increasing order of degree.
643 The library syntax is gtovec"(x)".
645 Vecsmall"({x = []})"
647 transforms the object "x" into a row vector of type "t_VECSMALL". This
648 acts as "Vec", but only on a limited set of objects (the result must be
649 representable as a vector of small integers). In particular,
650 polynomials and power series are forbidden. If "x" is a character
651 string, a vector of individual characters in ASCII encoding is returned
652 ("Strchr" yields back the character string).
653 The library syntax is gtovecsmall"(x)".
655 binary"(x)"
657 outputs the vector of the binary digits of "|x|". Here "x" can be an
658 integer, a real number (in which case the result has two components,
659 one for the integer part, one for the fractional part) or a
660 vector/matrix.
661 The library syntax is binaire"(x)".
663 bitand"(x,y)"
665 bitwise "and" of two integers "x" and "y", that is the integer
666 "sum_i (x_i and y_i) 2^i"
668 Negative numbers behave 2-adically, i.e. the result is the 2-adic limit
670 of "bitand""(x_n,y_n)", where "x_n" and "y_n" are non-negative integers
671 tending to "x" and "y" respectively. (The result is an ordinary
672 integer, possibly negative.)
673 ? bitand(5, 3)
675 %1 = 1
676 ? bitand(-5, 3)
677 %2 = 3
678 ? bitand(-5, -3)
679 %3 = -7
680 The library syntax is gbitand"(x,y)".
682 bitneg"(x,{n = -1})"
684 bitwise negation of an integer "x", truncated to "n" bits, that is the
685 integer
686 "sum_{i = 0}^{n-1} not(x_i) 2^i"
688 The special case "n = -1" means no truncation: an infinite sequence of
690 leading 1 is then represented as a negative number.
691 See "Label se:bitand" for the behaviour for negative arguments.
693 The library syntax is gbitneg"(x)".
695 bitnegimply"(x,y)"
697 bitwise negated imply of two integers "x" and "y" (or "not" "(x ==>
698 y)"), that is the integer
699 "sum (x_i and not(y_i)) 2^i"
701 See "Label se:bitand" for the behaviour for negative arguments.
703 The library syntax is gbitnegimply"(x,y)".
705 bitor"(x,y)"
707 bitwise (inclusive) "or" of two integers "x" and "y", that is the
708 integer
709 "sum (x_i or y_i) 2^i"
711 See "Label se:bitand" for the behaviour for negative arguments.
713 The library syntax is gbitor"(x,y)".
715 bittest"(x,n)"
717 outputs the "n^{th}" bit of "|x|" starting from the right (i.e. the
718 coefficient of "2^n" in the binary expansion of "x"). The result is 0
719 or 1. To extract several bits at once as a vector, pass a vector for
720 "n".
721 The library syntax is bittest"(x,n)", where "n" and the result are
723 "long"s.
724 bitxor"(x,y)"
726 bitwise (exclusive) "or" of two integers "x" and "y", that is the
727 integer
728 "sum (x_i xor y_i) 2^i"
730 See "Label se:bitand" for the behaviour for negative arguments.
732 The library syntax is gbitxor"(x,y)".
734 ceil"(x)"
736 ceiling of "x". When "x" is in R, the result is the smallest integer
737 greater than or equal to "x". Applied to a rational function, ceil(x)
738 returns the euclidian quotient of the numerator by the denominator.
739 The library syntax is gceil"(x)".
741 centerlift"(x,{v})"
743 lifts an element "x = a mod n" of "Z/nZ" to "a" in Z, and similarly
744 lifts a polmod to a polynomial. This is the same as "lift" except that
745 in the particular case of elements of "Z/nZ", the lift "y" is such that
746 "-n/2 < y <= n/2". If "x" is of type fraction, complex, quadratic,
747 polynomial, power series, rational function, vector or matrix, the lift
748 is done for each coefficient. Reals are forbidden.
749 The library syntax is centerlift0"(x,v)", where "v" is a "long" and an
751 omitted "v" is coded as "-1". Also available is " centerlift(x)" =
752 "centerlift0(x,-1)".
753 changevar"(x,y)"
755 creates a copy of the object "x" where its variables are modified
756 according to the permutation specified by the vector "y". For example,
757 assume that the variables have been introduced in the order "x", "a",
758 "b", "c". Then, if "y" is the vector "[x,c,a,b]", the variable "a" will
759 be replaced by "c", "b" by "a", and "c" by "b", "x" being unchanged.
760 Note that the permutation must be completely specified, e.g. "[c,a,b]"
761 would not work, since this would replace "x" by "c", and leave "a" and
762 "b" unchanged (as well as "c" which is the fourth variable of the
763 initial list). In particular, the new variable names must be distinct.
764 The library syntax is changevar"(x,y)".
766 components of a PARI object
768 There are essentially three ways to extract the components from a PARI
769 object.
770 The first and most general, is the function " component(x,n)" which
772 extracts the "n^{th}"-component of "x". This is to be understood as
773 follows: every PARI type has one or two initial code words. The
774 components are counted, starting at 1, after these code words. In
775 particular if "x" is a vector, this is indeed the "n^{th}"-component of
776 "x", if "x" is a matrix, the "n^{th}" column, if "x" is a polynomial,
777 the "n^{th}" coefficient (i.e. of degree "n-1"), and for power series,
778 the "n^{th}" significant coefficient. The use of the function
779 "component" implies the knowledge of the structure of the different
780 PARI types, which can be recalled by typing "\t" under "gp".
781 The library syntax is compo"(x,n)", where "n" is a "long".
783 The two other methods are more natural but more restricted. The
785 function " polcoeff(x,n)" gives the coefficient of degree "n" of the
786 polynomial or power series "x", with respect to the main variable of
787 "x" (to check variable ordering, or to change it, use the function
788 "reorder", see "Label se:reorder"). In particular if "n" is less than
789 the valuation of "x" or in the case of a polynomial, greater than the
790 degree, the result is zero (contrary to "compo" which would send an
791 error message). If "x" is a power series and "n" is greater than the
792 largest significant degree, then an error message is issued.
793 For greater flexibility, vector or matrix types are also accepted for
795 "x", and the meaning is then identical with that of "compo".
796 Finally note that a scalar type is considered by "polcoeff" as a
798 polynomial of degree zero.
799 The library syntax is truecoeff"(x,n)".
801 The third method is specific to vectors or matrices in GP. If "x" is a
803 (row or column) vector, then "x[n]" represents the "n^{th}" component
804 of "x", i.e. "compo(x,n)". It is more natural and shorter to write. If
805 "x" is a matrix, "x[m,n]" represents the coefficient of row "m" and
806 column "n" of the matrix, "x[m,]" represents the "m^{th}" \emph{row} of
807 "x", and "x[,n]" represents the "n^{th}" \emph{column} of "x".
808 Finally note that in library mode, the macros gcoeff and gmael are
810 available as direct accessors to a "GEN component". See Chapter 4 for
811 details.
812 conj"(x)"
814 conjugate of "x". The meaning of this is clear, except that for real
815 quadratic numbers, it means conjugation in the real quadratic field.
816 This function has no effect on integers, reals, intmods, fractions or
817 "p"-adics. The only forbidden type is polmod (see "conjvec" for this).
818 The library syntax is gconj"(x)".
820 conjvec"(x)"
822 conjugate vector representation of "x". If "x" is a polmod, equal to
823 "Mod""(a,q)", this gives a vector of length degree(q) containing the
824 complex embeddings of the polmod if "q" has integral or rational
825 coefficients, and the conjugates of the polmod if "q" has some intmod
826 coefficients. The order is the same as that of the "polroots"
827 functions. If "x" is an integer or a rational number, the result
828 is "x". If "x" is a (row or column) vector, the result is a matrix
829 whose columns are the conjugate vectors of the individual elements of
830 "x".
831 The library syntax is conjvec"(x,prec)".
833 denominator"(x)"
835 denominator of "x". The meaning of this is clear when "x" is a rational
836 number or function. If "x" is an integer or a polynomial, it is treated
837 as a rational number of function, respectively, and the result is equal
838 to 1. For polynomials, you probably want to use
839 denominator( content(x) )
841 instead. As for modular objects, "t_INTMOD" and "t_PADIC" have
843 denominator 1, and the denominator of a "t_POLMOD" is the denominator
844 of its (minimal degree) polynomial representative.
845 If "x" is a recursive structure, for instance a vector or matrix, the
847 lcm of the denominators of its components (a common denominator) is
848 computed. This also applies for "t_COMPLEX"s and "t_QUAD"s.
849 Warning: multivariate objects are created according to variable
851 priorities, with possibly surprising side effects ("x/y" is a
852 polynomial, but "y/x" is a rational function). See "Label se:priority".
853 The library syntax is denom"(x)".
855 floor"(x)"
857 floor of "x". When "x" is in R, the result is the largest integer
858 smaller than or equal to "x". Applied to a rational function, floor(x)
859 returns the euclidian quotient of the numerator by the denominator.
860 The library syntax is gfloor"(x)".
862 frac"(x)"
864 fractional part of "x". Identical to "x-floor(x)". If "x" is real, the
865 result is in "[0,1[".
866 The library syntax is gfrac"(x)".
868 imag"(x)"
870 imaginary part of "x". When "x" is a quadratic number, this is the
871 coefficient of "omega" in the ``canonical'' integral basis "(1,omega)".
872 The library syntax is gimag"(x)". This returns a copy of the imaginary
874 part. The internal routine "imag_i" is faster, since it returns the
875 pointer and skips the copy.
876 length"(x)"
878 number of non-code words in "x" really used (i.e. the effective length
879 minus 2 for integers and polynomials). In particular, the degree of a
880 polynomial is equal to its length minus 1. If "x" has type "t_STR",
881 output number of letters.
882 The library syntax is glength"(x)" and the result is a C long.
884 lift"(x,{v})"
886 lifts an element "x = a mod n" of "Z/nZ" to "a" in Z, and similarly
887 lifts a polmod to a polynomial if "v" is omitted. Otherwise, lifts
888 only polmods whose modulus has main variable "v" (if "v" does not occur
889 in "x", lifts only intmods). If "x" is of recursive (non modular) type,
890 the lift is done coefficientwise. For "p"-adics, this routine acts as
891 "truncate". It is not allowed to have "x" of type "t_REAL".
892 ? lift(Mod(5,3))
894 %1 = 2
895 ? lift(3 + O(3^9))
896 %2 = 3
897 ? lift(Mod(x,x^2+1))
898 %3 = x
899 ? lift(x * Mod(1,3) + Mod(2,3))
900 %4 = x + 2
901 ? lift(x * Mod(y,y^2+1) + Mod(2,3))
902 %5 = y*x + Mod(2, 3) \\ do you understand this one ?
903 ? lift(x * Mod(y,y^2+1) + Mod(2,3), x)
904 %6 = Mod(y, y^2+1) * x + Mod(2, y^2+1)
905 The library syntax is lift0"(x,v)", where "v" is a "long" and an
907 omitted "v" is coded as "-1". Also available is " lift(x)" =
908 "lift0(x,-1)".
909 norm"(x)"
911 algebraic norm of "x", i.e. the product of "x" with its conjugate (no
912 square roots are taken), or conjugates for polmods. For vectors and
913 matrices, the norm is taken componentwise and hence is not the
914 "L^2"-norm (see "norml2"). Note that the norm of an element of R is its
915 square, so as to be compatible with the complex norm.
916 The library syntax is gnorm"(x)".
918 norml2"(x)"
920 square of the "L^2"-norm of "x". More precisely, if "x" is a scalar,
921 norml2(x) is defined to be "x * conj(x)". If "x" is a (row or column)
922 vector or a matrix, norml2(x) is defined recursively as "sum_i
923 norml2(x_i)", where "(x_i)" run through the components of "x". In
924 particular, this yields the usual "sum |x_i|^2" (resp. "sum
925 |x_{i,j}|^2") if "x" is a vector (resp. matrix) with complex
926 components.
927 ? norml2( [ 1, 2, 3 ] ) \\ vector
929 %1 = 14
930 ? norml2( [ 1, 2; 3, 4] ) \\ matrix
931 %1 = 30
932 ? norml2( I + x )
933 %3 = x^2 + 1
934 ? norml2( [ [1,2], [3,4], 5, 6 ] ) \\ recursively defined
935 %4 = 91
936 The library syntax is gnorml2"(x)".
938 numerator"(x)"
940 numerator of "x". The meaning of this is clear when "x" is a rational
941 number or function. If "x" is an integer or a polynomial, it is treated
942 as a rational number of function, respectively, and the result is "x"
943 itself. For polynomials, you probably want to use
944 numerator( content(x) )
946 instead.
948 In other cases, numerator(x) is defined to be "denominator(x)*x". This
950 is the case when "x" is a vector or a matrix, but also for "t_COMPLEX"
951 or "t_QUAD". In particular since a "t_PADIC" or "t_INTMOD" has
952 denominator 1, its numerator is itself.
953 Warning: multivariate objects are created according to variable
955 priorities, with possibly surprising side effects ("x/y" is a
956 polynomial, but "y/x" is a rational function). See "Label se:priority".
957 The library syntax is numer"(x)".
959 numtoperm"(n,k)"
961 generates the "k"-th permutation (as a row vector of length "n") of the
962 numbers 1 to "n". The number "k" is taken modulo "n!", i.e. inverse
963 function of "permtonum".
964 The library syntax is numtoperm"(n,k)", where "n" is a "long".
966 padicprec"(x,p)"
968 absolute "p"-adic precision of the object "x". This is the minimum
969 precision of the components of "x". The result is "VERYBIGINT"
970 ("2^{31}-1" for 32-bit machines or "2^{63}-1" for 64-bit machines) if
971 "x" is an exact object.
972 The library syntax is padicprec"(x,p)" and the result is a "long"
974 integer.
975 permtonum"(x)"
977 given a permutation "x" on "n" elements, gives the number "k" such that
978 "x = numtoperm(n,k)", i.e. inverse function of "numtoperm".
979 The library syntax is permtonum"(x)".
981 precision"(x,{n})"
983 gives the precision in decimal digits of the PARI object "x". If "x" is
984 an exact object, the largest single precision integer is returned. If
985 "n" is not omitted, creates a new object equal to "x" with a new
986 precision "n". This is to be understood as follows:
987 For exact types, no change. For "x" a vector or a matrix, the operation
989 is done componentwise.
990 For real "x", "n" is the number of desired significant \emph{decimal}
992 digits. If "n" is smaller than the precision of "x", "x" is truncated,
993 otherwise "x" is extended with zeros.
994 For "x" a "p"-adic or a power series, "n" is the desired number of
996 significant "p"-adic or "X"-adic digits, where "X" is the main variable
997 of "x".
998 Note that the function "precision" never changes the type of the
1000 result. In particular it is not possible to use it to obtain a
1001 polynomial from a power series. For that, see "truncate".
1002 The library syntax is precision0"(x,n)", where "n" is a "long". Also
1004 available are " ggprecision(x)" (result is a "GEN") and " gprec(x,n)",
1005 where "n" is a "long".
1006 random"({N = 2^{31}})"
1008 returns a random integer between 0 and "N-1". "N" is an integer, which
1009 can be arbitrary large. This is an internal PARI function and does not
1010 depend on the system's random number generator.
1011 The resulting integer is obtained by means of linear congruences and
1013 will not be well distributed in arithmetic progressions. The random
1014 seed may be obtained via "getrand", and reset using "setrand".
1015 Note that "random(2^31)" is \emph{not} equivalent to "random()",
1017 although both return an integer between 0 and "2^{31}-1". In fact,
1018 calling "random" with an argument generates a number of random words
1019 (32bit or 64bit depending on the architecture), rescaled to the desired
1020 interval. The default uses directly a 31-bit generator.
1021 Important technical note: the implementation of this function is
1023 incorrect unless "N" is a power of 2 (integers less than the bound are
1024 not equally likely, some may not even occur). It is kept for backward
1025 compatibility only, and has been rewritten from scratch in the 2.4.x
1026 unstable series. Use the following script for a correct version:
1027 RANDOM(N) =
1029 { local(n, L);
1030 L = 1; while (L < N, L <<= 1;);
1032 /* L/2 < N <= L, L power of 2 */
1033 until(n < N, n = random(L)); n
1034 }
1035 The library syntax is genrand"(N)". Also available are "pari_rand""()"
1037 which returns a random "unsigned long" (32bit or 64bit depending on the
1038 architecture), and "pari_rand31""()" which returns a 31bit "long"
1039 integer.
1040 real"(x)"
1042 real part of "x". In the case where "x" is a quadratic number, this is
1043 the coefficient of 1 in the ``canonical'' integral basis "(1,omega)".
1044 The library syntax is greal"(x)". This returns a copy of the real part.
1046 The internal routine "real_i" is faster, since it returns the pointer
1047 and skips the copy.
1048 round"(x,{&e})"
1050 If "x" is in R, rounds "x" to the nearest integer and sets "e" to the
1051 number of error bits, that is the binary exponent of the difference
1052 between the original and the rounded value (the ``fractional part'').
1053 If the exponent of "x" is too large compared to its precision (i.e. "e
1054 > 0"), the result is undefined and an error occurs if "e" was not
1055 given.
1056 Important remark: note that, contrary to the other truncation
1058 functions, this function operates on every coefficient at every level
1059 of a PARI object. For example
1060 "truncate((2.4*X^2-1.7)/(X)) = 2.4*X,"
1062 whereas
1064 "round((2.4*X^2-1.7)/(X)) = (2*X^2-2)/(X)."
1066 An important use of "round" is to get exact results after a long
1068 approximate computation, when theory tells you that the coefficients
1069 must be integers.
1070 The library syntax is grndtoi"(x,&e)", where "e" is a "long" integer.
1072 Also available is " ground(x)".
1073 simplify"(x)"
1075 this function simplifies "x" as much as it can. Specifically, a
1076 complex or quadratic number whose imaginary part is an exact 0
1077 (i.e. not an approximate one as a O(3) or "0.E-28") is converted to its
1078 real part, and a polynomial of degree 0 is converted to its constant
1079 term. Simplifications occur recursively.
1080 This function is especially useful before using arithmetic functions,
1082 which expect integer arguments:
1083 ? x = 1 + y - y
1085 %1 = 1
1086 ? divisors(x)
1087 *** divisors: not an integer argument in an arithmetic function
1088 ? type(x)
1089 %2 = "t_POL"
1090 ? type(simplify(x))
1091 %3 = "t_INT"
1092 Note that GP results are simplified as above before they are stored in
1094 the history. (Unless you disable automatic simplification with "\y",
1095 that is.) In particular
1096 ? type(%1)
1098 %4 = "t_INT"
1099 The library syntax is simplify"(x)".
1101 sizebyte"(x)"
1103 outputs the total number of bytes occupied by the tree representing the
1104 PARI object "x".
1105 The library syntax is taille2"(x)" which returns a "long"; " taille(x)"
1107 returns the number of \emph{words} instead.
1108 sizedigit"(x)"
1110 outputs a quick bound for the number of decimal digits of (the
1111 components of) "x", off by at most 1. If you want the exact value, you
1112 can use "#Str(x)", which is slower.
1113 The library syntax is sizedigit"(x)" which returns a "long".
1115 truncate"(x,{&e})"
1117 truncates "x" and sets "e" to the number of error bits. When "x" is in
1118 R, this means that the part after the decimal point is chopped away,
1119 "e" is the binary exponent of the difference between the original and
1120 the truncated value (the ``fractional part''). If the exponent of "x"
1121 is too large compared to its precision (i.e. "e > 0"), the result is
1122 undefined and an error occurs if "e" was not given. The function
1123 applies componentwise on vector / matrices; "e" is then the maximal
1124 number of error bits. If "x" is a rational function, the result is the
1125 ``integer part'' (Euclidean quotient of numerator by denominator) and
1126 "e" is not set.
1127 Note a very special use of "truncate": when applied to a power series,
1129 it transforms it into a polynomial or a rational function with
1130 denominator a power of "X", by chopping away the "O(X^k)". Similarly,
1131 when applied to a "p"-adic number, it transforms it into an integer or
1132 a rational number by chopping away the "O(p^k)".
1133 The library syntax is gcvtoi"(x,&e)", where "e" is a "long" integer.
1135 Also available is " gtrunc(x)".
1136 valuation"(x,p)"
1138 computes the highest exponent of "p" dividing "x". If "p" is of type
1139 integer, "x" must be an integer, an intmod whose modulus is divisible
1140 by "p", a fraction, a "q"-adic number with "q = p", or a polynomial or
1141 power series in which case the valuation is the minimum of the
1142 valuation of the coefficients.
1143 If "p" is of type polynomial, "x" must be of type polynomial or
1145 rational function, and also a power series if "x" is a monomial.
1146 Finally, the valuation of a vector, complex or quadratic number is the
1147 minimum of the component valuations.
1148 If "x = 0", the result is "VERYBIGINT" ("2^{31}-1" for 32-bit machines
1150 or "2^{63}-1" for 64-bit machines) if "x" is an exact object. If "x" is
1151 a "p"-adic numbers or power series, the result is the exponent of the
1152 zero. Any other type combinations gives an error.
1153 The library syntax is ggval"(x,p)", and the result is a "long".
1155 variable"(x)"
1157 gives the main variable of the object "x", and "p" if "x" is a "p"-adic
1158 number. Gives an error if "x" has no variable associated to it. Note
1159 that this function is useful only in GP, since in library mode the
1160 function "gvar" is more appropriate.
1161 The library syntax is gpolvar"(x)". However, in library mode, this
1163 function should not be used. Instead, test whether "x" is a "p"-adic
1164 (type "t_PADIC"), in which case "p" is in "x[2]", or call the function
1165 " gvar(x)" which returns the variable \emph{number} of "x" if it
1166 exists, "BIGINT" otherwise.
1167
1169 As a general rule, which of course in some cases may have exceptions,
1170 transcendental functions operate in the following way:
1171 \item If the argument is either an integer, a real, a rational, a
1173 complex or a quadratic number, it is, if necessary, first converted to
1174 a real (or complex) number using the current precision held in the
1175 default "realprecision". Note that only exact arguments are converted,
1176 while inexact arguments such as reals are not.
1177 In GP this is transparent to the user, but when programming in library
1179 mode, care must be taken to supply a meaningful parameter prec as the
1180 last argument of the function if the first argument is an exact object.
1181 This parameter is ignored if the argument is inexact.
1182 Note that in library mode the precision argument prec is a word count
1184 including codewords, i.e. represents the length in words of a real
1185 number, while under "gp" the precision (which is changed by the
1186 metacommand "\p" or using "default(realprecision,...)") is the number
1187 of significant decimal digits.
1188 Note that some accuracies attainable on 32-bit machines cannot be
1190 attained on 64-bit machines for parity reasons. For example the default
1191 "gp" accuracy is 28 decimal digits on 32-bit machines, corresponding to
1192 prec having the value 5, but this cannot be attained on 64-bit
1193 machines.
1194 After possible conversion, the function is computed. Note that even if
1196 the argument is real, the result may be complex (e.g. "acos(2.0)" or
1197 "acosh(0.0)"). Note also that the principal branch is always chosen.
1198 \item If the argument is an intmod or a "p"-adic, at present only a few
1200 functions like "sqrt" (square root), "sqr" (square), "log", "exp",
1201 powering, "teichmuller" (Teichmüller character) and "agm" (arithmetic-
1202 geometric mean) are implemented.
1203 Note that in the case of a 2-adic number, sqr(x) may not be identical
1205 to "x*x": for example if "x = 1+O(2^5)" and "y = 1+O(2^5)" then "x*y =
1206 1+O(2^5)" while "sqr(x) = 1+O(2^6)". Here, "x * x" yields the same
1207 result as sqr(x) since the two operands are known to be
1208 \emph{identical}. The same statement holds true for "p"-adics raised to
1209 the power "n", where "v_p(n) > 0".
1210 Remark: note that if we wanted to be strictly consistent with the PARI
1212 philosophy, we should have "x*y = (4 mod 8)" and "sqr(x) = (4 mod 32)"
1213 when both "x" and "y" are congruent to 2 modulo 4. However, since
1214 intmod is an exact object, PARI assumes that the modulus must not
1215 change, and the result is hence "(0 mod 4)" in both cases. On the other
1216 hand, "p"-adics are not exact objects, hence are treated differently.
1217 \item If the argument is a polynomial, power series or rational
1219 function, it is, if necessary, first converted to a power series using
1220 the current precision held in the variable "precdl". Under "gp" this
1221 again is transparent to the user. When programming in library mode,
1222 however, the global variable "precdl" must be set before calling the
1223 function if the argument has an exact type (i.e. not a power series).
1224 Here "precdl" is not an argument of the function, but a global
1225 variable.
1226 Then the Taylor series expansion of the function around "X = 0" (where
1228 "X" is the main variable) is computed to a number of terms depending on
1229 the number of terms of the argument and the function being computed.
1230 \item If the argument is a vector or a matrix, the result is the
1232 componentwise evaluation of the function. In particular, transcendental
1233 functions on square matrices, which are not implemented in the present
1234 version /usr/share/libpari23, will have a different name if they are
1235 implemented some day.
1236 ^
1238 If "y" is not of type integer, "x^y" has the same effect as
1239 "exp(y*log(x))". It can be applied to "p"-adic numbers as well as to
1240 the more usual types.
1241 The library syntax is gpow"(x,y,prec)".
1243 Euler
1245 Euler's constant "gamma = 0.57721...". Note that "Euler" is one of the
1246 few special reserved names which cannot be used for variables (the
1247 others are "I" and "Pi", as well as all function names).
1248 The library syntax is mpeuler"(prec)" where "prec" \emph{must} be
1250 given. Note that this creates "gamma" on the PARI stack, but a copy is
1251 also created on the heap for quicker computations next time the
1252 function is called.
1253 I
1255 the complex number " sqrt {-1}".
1256 The library syntax is the global variable "gi" (of type "GEN").
1258 Pi
1260 the constant "Pi" (3.14159...).
1261 The library syntax is mppi"(prec)" where "prec" \emph{must} be given.
1263 Note that this creates "Pi" on the PARI stack, but a copy is also
1264 created on the heap for quicker computations next time the function is
1265 called.
1266 abs"(x)"
1268 absolute value of "x" (modulus if "x" is complex). Rational functions
1269 are not allowed. Contrary to most transcendental functions, an exact
1270 argument is \emph{not} converted to a real number before applying "abs"
1271 and an exact result is returned if possible.
1272 ? abs(-1)
1274 %1 = 1
1275 ? abs(3/7 + 4/7*I)
1276 %2 = 5/7
1277 ? abs(1 + I)
1278 %3 = 1.414213562373095048801688724
1279 If "x" is a polynomial, returns "-x" if the leading coefficient is real
1281 and negative else returns "x". For a power series, the constant
1282 coefficient is considered instead.
1283 The library syntax is gabs"(x,prec)".
1285 acos"(x)"
1287 principal branch of "cos^{-1}(x)", i.e. such that "Re(acos(x)) belongs
1288 to [0,Pi]". If "x belongs to R" and "|x| > 1", then acos(x) is complex.
1289 The library syntax is gacos"(x,prec)".
1291 acosh"(x)"
1293 principal branch of "cosh^{-1}(x)", i.e. such that "Im(acosh(x))
1294 belongs to [0,Pi]". If "x belongs to R" and "x < 1", then acosh(x) is
1295 complex.
1296 The library syntax is gach"(x,prec)".
1298 agm"(x,y)"
1300 arithmetic-geometric mean of "x" and "y". In the case of complex or
1301 negative numbers, the principal square root is always chosen. "p"-adic
1302 or power series arguments are also allowed. Note that a "p"-adic agm
1303 exists only if "x/y" is congruent to 1 modulo "p" (modulo 16 for "p =
1304 2"). "x" and "y" cannot both be vectors or matrices.
1305 The library syntax is agm"(x,y,prec)".
1307 arg"(x)"
1309 argument of the complex number "x", such that "-Pi < arg(x) <= Pi".
1310 The library syntax is garg"(x,prec)".
1312 asin"(x)"
1314 principal branch of "sin^{-1}(x)", i.e. such that "Re(asin(x)) belongs
1315 to [-Pi/2,Pi/2]". If "x belongs to R" and "|x| > 1" then asin(x) is
1316 complex.
1317 The library syntax is gasin"(x,prec)".
1319 asinh"(x)"
1321 principal branch of "sinh^{-1}(x)", i.e. such that "Im(asinh(x))
1322 belongs to [-Pi/2,Pi/2]".
1323 The library syntax is gash"(x,prec)".
1325 atan"(x)"
1327 principal branch of "tan^{-1}(x)", i.e. such that "Re(atan(x)) belongs
1328 to ]-Pi/2,Pi/2[".
1329 The library syntax is gatan"(x,prec)".
1331 atanh"(x)"
1333 principal branch of "tanh^{-1}(x)", i.e. such that "Im(atanh(x))
1334 belongs to ]-Pi/2,Pi/2]". If "x belongs to R" and "|x| > 1" then
1335 atanh(x) is complex.
1336 The library syntax is gath"(x,prec)".
1338 bernfrac"(x)"
1340 Bernoulli number "B_x", where "B_0 = 1", "B_1 = -1/2", "B_2 = 1/6",...,
1341 expressed as a rational number. The argument "x" should be of type
1342 integer.
1343 The library syntax is bernfrac"(x)".
1345 bernreal"(x)"
1347 Bernoulli number "B_x", as "bernfrac", but "B_x" is returned as a real
1348 number (with the current precision).
1349 The library syntax is bernreal"(x,prec)".
1351 bernvec"(x)"
1353 creates a vector containing, as rational numbers, the Bernoulli numbers
1354 "B_0", "B_2",..., "B_{2x}". This routine is obsolete. Use "bernfrac"
1355 instead each time you need a Bernoulli number in exact form.
1356 Note: this routine is implemented using repeated independent calls to
1358 "bernfrac", which is faster than the standard recursion in exact
1359 arithmetic. It is only kept for backward compatibility: it is not
1360 faster than individual calls to "bernfrac", its output uses a lot of
1361 memory space, and coping with the index shift is awkward.
1362 The library syntax is bernvec"(x)".
1364 besselh1"(nu,x)"
1366 "H^1"-Bessel function of index nu and argument "x".
1367 The library syntax is hbessel1"(nu,x,prec)".
1369 besselh2"(nu,x)"
1371 "H^2"-Bessel function of index nu and argument "x".
1372 The library syntax is hbessel2"(nu,x,prec)".
1374 besseli"(nu,x)"
1376 "I"-Bessel function of index nu and argument "x". If "x" converts to a
1377 power series, the initial factor "(x/2)^nu/Gamma(nu+1)" is omitted
1378 (since it cannot be represented in PARI when "nu" is not integral).
1379 The library syntax is ibessel"(nu,x,prec)".
1381 besselj"(nu,x)"
1383 "J"-Bessel function of index nu and argument "x". If "x" converts to a
1384 power series, the initial factor "(x/2)^nu/Gamma(nu+1)" is omitted
1385 (since it cannot be represented in PARI when "nu" is not integral).
1386 The library syntax is jbessel"(nu,x,prec)".
1388 besseljh"(n,x)"
1390 "J"-Bessel function of half integral index. More precisely,
1391 "besseljh(n,x)" computes "J_{n+1/2}(x)" where "n" must be of type
1392 integer, and "x" is any element of C. In the present version
1393 /usr/share/libpari23, this function is not very accurate when "x" is
1394 small.
1395 The library syntax is jbesselh"(n,x,prec)".
1397 besselk"(nu,x,{flag = 0})"
1399 "K"-Bessel function of index nu (which can be complex) and argument
1400 "x". Only real and positive arguments "x" are allowed in the present
1401 version /usr/share/libpari23. If "flag" is equal to 1, uses another
1402 implementation of this function which is faster when "x\gg 1".
1403 The library syntax is kbessel"(nu,x,prec)" and " kbessel2(nu,x,prec)"
1405 respectively.
1406 besseln"(nu,x)"
1408 "N"-Bessel function of index nu and argument "x".
1409 The library syntax is nbessel"(nu,x,prec)".
1411 cos"(x)"
1413 cosine of "x".
1414 The library syntax is gcos"(x,prec)".
1416 cosh"(x)"
1418 hyperbolic cosine of "x".
1419 The library syntax is gch"(x,prec)".
1421 cotan"(x)"
1423 cotangent of "x".
1424 The library syntax is gcotan"(x,prec)".
1426 dilog"(x)"
1428 principal branch of the dilogarithm of "x", i.e. analytic continuation
1429 of the power series " log _2(x) = sum_{n >= 1}x^n/n^2".
1430 The library syntax is dilog"(x,prec)".
1432 eint1"(x,{n})"
1434 exponential integral "int_x^ oo (e^{-t})/(t)dt" ("x belongs to R")
1435 If "n" is present, outputs the "n"-dimensional vector
1437 "[eint1(x),...,eint1(nx)]" ("x >= 0"). This is faster than repeatedly
1438 calling "eint1(i * x)".
1439 The library syntax is veceint1"(x,n,prec)". Also available is "
1441 eint1(x,prec)".
1442 erfc"(x)"
1444 complementary error function "(2/ sqrt Pi)int_x^ oo e^{-t^2}dt" ("x
1445 belongs to R").
1446 The library syntax is erfc"(x,prec)".
1448 eta"(x,{flag = 0})"
1450 Dedekind's "eta" function, without the "q^{1/24}". This means the
1451 following: if "x" is a complex number with positive imaginary part, the
1452 result is "prod_{n = 1}^ oo (1-q^n)", where "q = e^{2iPi x}". If "x" is
1453 a power series (or can be converted to a power series) with positive
1454 valuation, the result is "prod_{n = 1}^ oo (1-x^n)".
1455 If "flag = 1" and "x" can be converted to a complex number (i.e. is not
1457 a power series), computes the true "eta" function, including the
1458 leading "q^{1/24}".
1459 The library syntax is eta"(x,prec)".
1461 exp"(x)"
1463 exponential of "x". "p"-adic arguments with positive valuation are
1464 accepted.
1465 The library syntax is gexp"(x,prec)".
1467 gammah"(x)"
1469 gamma function evaluated at the argument "x+1/2".
1470 The library syntax is ggamd"(x,prec)".
1472 gamma"(x)"
1474 gamma function of "x".
1475 The library syntax is ggamma"(x,prec)".
1477 hyperu"(a,b,x)"
1479 "U"-confluent hypergeometric function with parameters "a" and "b". The
1480 parameters "a" and "b" can be complex but the present implementation
1481 requires "x" to be positive.
1482 The library syntax is hyperu"(a,b,x,prec)".
1484 incgam"(s,x,{y})"
1486 incomplete gamma function. The argument "x" and "s" are complex numbers
1487 ("x" must be a positive real number if "s = 0"). The result returned
1488 is "int_x^ oo e^{-t}t^{s-1}dt". When "y" is given, assume (of course
1489 without checking!) that "y = Gamma(s)". For small "x", this will speed
1490 up the computation.
1491 The library syntax is incgam"(s,x,prec)" and " incgam0(s,x,y,prec)",
1493 respectively (an omitted "y" is coded as "NULL").
1494 incgamc"(s,x)"
1496 complementary incomplete gamma function. The arguments "x" and "s" are
1497 complex numbers such that "s" is not a pole of "Gamma" and
1498 "|x|/(|s|+1)" is not much larger than 1 (otherwise the convergence is
1499 very slow). The result returned is "int_0^x e^{-t}t^{s-1}dt".
1500 The library syntax is incgamc"(s,x,prec)".
1502 log"(x)"
1504 principal branch of the natural logarithm of "x", i.e. such that
1505 "Im(log(x)) belongs to ]-Pi,Pi]". The result is complex (with
1506 imaginary part equal to "Pi") if "x belongs to R" and "x < 0". In
1507 general, the algorithm uses the formula
1508 " log (x) ~ (Pi)/(2agm(1, 4/s)) - m log 2, "
1510 if "s = x 2^m" is large enough. (The result is exact to "B" bits
1512 provided "s > 2^{B/2}".) At low accuracies, the series expansion near 1
1513 is used.
1514 "p"-adic arguments are also accepted for "x", with the convention that
1516 " log (p) = 0". Hence in particular " exp ( log (x))/x" is not in
1517 general equal to 1 but to a "(p-1)"-th root of unity (or "+-1" if "p =
1518 2") times a power of "p".
1519 The library syntax is glog"(x,prec)".
1521 lngamma"(x)"
1523 principal branch of the logarithm of the gamma function of "x". This
1524 function is analytic on the complex plane with non-positive integers
1525 removed. Can have much larger arguments than "gamma" itself. The
1526 "p"-adic "lngamma" function is not implemented.
1527 The library syntax is glngamma"(x,prec)".
1529 polylog"(m,x,{flag = 0})"
1531 one of the different polylogarithms, depending on flag:
1532 If "flag = 0" or is omitted: "m^th" polylogarithm of "x", i.e. analytic
1534 continuation of the power series "Li_m(x) = sum_{n >= 1}x^n/n^m" ("x <
1535 1"). Uses the functional equation linking the values at "x" and "1/x"
1536 to restrict to the case "|x| <= 1", then the power series when "|x|^2
1537 <= 1/2", and the power series expansion in " log (x)" otherwise.
1538 Using "flag", computes a modified "m^th" polylogarithm of "x". We use
1540 Zagier's notations; let " Re _m" denotes " Re " or " Im " depending
1541 whether "m" is odd or even:
1542 If "flag = 1": compute "~ D_m(x)", defined for "|x| <= 1" by
1544 " Re _m(sum_{k = 0}^{m-1} ((- log |x|)^k)/(k!)Li_{m-k}(x) +((- log
1546 |x|)^{m-1})/(m!) log |1-x|)."
1547 If "flag = 2": compute D_m(x), defined for "|x| <= 1" by
1549 " Re _m(sum_{k = 0}^{m-1}((- log |x|)^k)/(k!)Li_{m-k}(x) -(1)/(2)((-
1551 log |x|)^m)/(m!))."
1552 If "flag = 3": compute P_m(x), defined for "|x| <= 1" by
1554 " Re _m(sum_{k = 0}^{m-1}(2^kB_k)/(k!)( log |x|)^kLi_{m-k}(x)
1556 -(2^{m-1}B_m)/(m!)( log |x|)^m)."
1557 These three functions satisfy the functional equation "f_m(1/x) =
1559 (-1)^{m-1}f_m(x)".
1560 The library syntax is polylog0"(m,x,flag,prec)".
1562 psi"(x)"
1564 the "psi"-function of "x", i.e. the logarithmic derivative
1565 "Gamma'(x)/Gamma(x)".
1566 The library syntax is gpsi"(x,prec)".
1568 sin"(x)"
1570 sine of "x".
1571 The library syntax is gsin"(x,prec)".
1573 sinh"(x)"
1575 hyperbolic sine of "x".
1576 The library syntax is gsh"(x,prec)".
1578 sqr"(x)"
1580 square of "x". This operation is not completely straightforward,
1581 i.e. identical to "x * x", since it can usually be computed more
1582 efficiently (roughly one-half of the elementary multiplications can be
1583 saved). Also, squaring a 2-adic number increases its precision. For
1584 example,
1585 ? (1 + O(2^4))^2
1587 %1 = 1 + O(2^5)
1588 ? (1 + O(2^4)) * (1 + O(2^4))
1589 %2 = 1 + O(2^4)
1590 Note that this function is also called whenever one multiplies two
1592 objects which are known to be \emph{identical}, e.g. they are the value
1593 of the same variable, or we are computing a power.
1594 ? x = (1 + O(2^4)); x * x
1596 %3 = 1 + O(2^5)
1597 ? (1 + O(2^4))^4
1598 %4 = 1 + O(2^6)
1599 (note the difference between %2 and %3 above).
1601 The library syntax is gsqr"(x)".
1603 sqrt"(x)"
1605 principal branch of the square root of "x", i.e. such that
1606 "Arg(sqrt(x)) belongs to ]-Pi/2, Pi/2]", or in other words such that "
1607 Re (sqrt(x)) > 0" or " Re (sqrt(x)) = 0" and " Im (sqrt(x)) >= 0". If
1608 "x belongs to R" and "x < 0", then the result is complex with positive
1609 imaginary part.
1610 Intmod a prime and "p"-adics are allowed as arguments. In that case,
1612 the square root (if it exists) which is returned is the one whose first
1613 "p"-adic digit (or its unique "p"-adic digit in the case of intmods) is
1614 in the interval "[0,p/2]". When the argument is an intmod a non-prime
1615 (or a non-prime-adic), the result is undefined.
1616 The library syntax is gsqrt"(x,prec)".
1618 sqrtn"(x,n,{&z})"
1620 principal branch of the "n"th root of "x", i.e. such that "Arg(sqrt(x))
1621 belongs to ]-Pi/n, Pi/n]". Intmod a prime and "p"-adics are allowed as
1622 arguments.
1623 If "z" is present, it is set to a suitable root of unity allowing to
1625 recover all the other roots. If it was not possible, z is set to zero.
1626 In the case this argument is present and no square root exist, 0 is
1627 returned instead or raising an error.
1628 ? sqrtn(Mod(2,7), 2)
1630 %1 = Mod(4, 7)
1631 ? sqrtn(Mod(2,7), 2, &z); z
1632 %2 = Mod(6, 7)
1633 ? sqrtn(Mod(2,7), 3)
1634 *** sqrtn: nth-root does not exist in gsqrtn.
1635 ? sqrtn(Mod(2,7), 3, &z)
1636 %2 = 0
1637 ? z
1638 %3 = 0
1639 The following script computes all roots in all possible cases:
1641 sqrtnall(x,n)=
1643 {
1644 local(V,r,z,r2);
1645 r = sqrtn(x,n, &z);
1646 if (!z, error("Impossible case in sqrtn"));
1647 if (type(x) == "t_INTMOD" || type(x)=="t_PADIC" ,
1648 r2 = r*z; n = 1;
1649 while (r2!=r, r2*=z;n++));
1650 V = vector(n); V[1] = r;
1651 for(i=2, n, V[i] = V[i-1]*z);
1652 V
1653 }
1654 addhelp(sqrtnall,"sqrtnall(x,n):compute the vector of nth-roots of x");
1655 The library syntax is gsqrtn"(x,n,&z,prec)".
1657 tan"(x)"
1659 tangent of "x".
1660 The library syntax is gtan"(x,prec)".
1662 tanh"(x)"
1664 hyperbolic tangent of "x".
1665 The library syntax is gth"(x,prec)".
1667 teichmuller"(x)"
1669 Teichmüller character of the "p"-adic number "x", i.e. the unique
1670 "(p-1)"-th root of unity congruent to "x / p^{v_p(x)}" modulo "p".
1671 The library syntax is teich"(x)".
1673 theta"(q,z)"
1675 Jacobi sine theta-function.
1676 The library syntax is theta"(q,z,prec)".
1678 thetanullk"(q,k)"
1680 "k"-th derivative at "z = 0" of "theta(q,z)".
1681 The library syntax is thetanullk"(q,k,prec)", where "k" is a "long".
1683 weber"(x,{flag = 0})"
1685 one of Weber's three "f" functions. If "flag = 0", returns
1686 "f(x) = exp (-iPi/24).eta((x+1)/2)/eta(x) such that j =
1688 (f^{24}-16)^3/f^{24},"
1689 where "j" is the elliptic "j"-invariant (see the function "ellj"). If
1691 "flag = 1", returns
1692 "f_1(x) = eta(x/2)/eta(x) such that j = (f_1^{24}+16)^3/f_1^{24}."
1694 Finally, if "flag = 2", returns
1696 "f_2(x) = sqrt {2}eta(2x)/eta(x) such that j =
1698 (f_2^{24}+16)^3/f_2^{24}."
1699 Note the identities "f^8 = f_1^8+f_2^8" and "ff_1f_2 = sqrt 2".
1701 The library syntax is weber0"(x,flag,prec)". Associated to the various
1703 values of flag, the following functions are also available: "
1704 werberf(x,prec)", " werberf1(x,prec)" or " werberf2(x,prec)".
1705 zeta"(s)"
1707 For "s" a complex number, Riemann's zeta function "zeta(s) = sum_{n >=
1708 1}n^{-s}", computed using the Euler-Maclaurin summation formula, except
1709 when "s" is of type integer, in which case it is computed using
1710 Bernoulli numbers for "s <= 0" or "s > 0" and even, and using modular
1711 forms for "s > 0" and odd.
1712 For "s" a "p"-adic number, Kubota-Leopoldt zeta function at "s", that
1714 is the unique continuous "p"-adic function on the "p"-adic integers
1715 that interpolates the values of "(1 - p^{-k}) zeta(k)" at negative
1716 integers "k" such that "k = 1 (mod p-1)" (resp. "k" is odd) if "p" is
1717 odd (resp. "p = 2").
1718 The library syntax is gzeta"(s,prec)".
1720
1722 These functions are by definition functions whose natural domain of
1723 definition is either Z (or "Z_{ > 0}"), or sometimes polynomials over a
1724 base ring. Functions which concern polynomials exclusively will be
1725 explained in the next section. The way these functions are used is
1726 completely different from transcendental functions: in general only the
1727 types integer and polynomial are accepted as arguments. If a vector or
1728 matrix type is given, the function will be applied on each coefficient
1729 independently.
1730 In the present version /usr/share/libpari23, all arithmetic functions
1732 in the narrow sense of the word --- Euler's totient function, the
1733 Moebius function, the sums over divisors or powers of divisors etc.---
1734 call, after trial division by small primes, the same versatile
1735 factoring machinery described under "factorint". It includes Shanks
1736 SQUFOF, Pollard Rho, ECM and MPQS stages, and has an early exit option
1737 for the functions moebius and (the integer function underlying)
1738 issquarefree. Note that it relies on a (fairly strong) probabilistic
1739 primality test, see "ispseudoprime".
1740 addprimes"({x = []})"
1742 adds the integers contained in the vector "x" (or the single integer
1743 "x") to a special table of ``user-defined primes'', and returns that
1744 table. Whenever "factor" is subsequently called, it will trial divise
1745 by the elements in this table. If "x" is empty or omitted, just
1746 returns the current list of extra primes.
1747 The entries in "x" are not checked for primality, and in fact they need
1749 only be positive integers. The algorithm makes sure that all elements
1750 in the table are pairwise coprime, so it may end up containing divisors
1751 of the input integers.
1752 It is a useful trick to add known composite numbers, which the function
1754 "factor(x,0)" was not able to factor. In case the message ``impossible
1755 inverse modulo "<"some INTMOD">"'' shows up afterwards, you have just
1756 stumbled over a non-trivial factor. Note that the arithmetic functions
1757 in the narrow sense, like eulerphi, do \emph{not} use this extra table.
1758 To remove primes from the list use "removeprimes".
1760 The library syntax is addprimes"(x)".
1762 bestappr"(x,A,{B})"
1764 if "B" is omitted, finds the best rational approximation to "x belongs
1765 to R" (or "R[X]", or "R^n",...) with denominator at most equal to "A"
1766 using continued fractions.
1767 If "B" is present, "x" is assumed to be of type "t_INTMOD" modulo "M"
1769 (or a recursive combination of those), and the routine returns the
1770 unique fraction "a/b" in coprime integers "a <= A" and "b <= B" which
1771 is congruent to "x" modulo "M". If "M <= 2AB", uniqueness is not
1772 guaranteed and the function fails with an error message. If rational
1773 reconstruction is not possible (no such "a/b" exists for at least one
1774 component of "x"), returns "-1".
1775 The library syntax is bestappr0"(x,A,B)". Also available is "
1777 bestappr(x,A)" corresponding to an omitted "B".
1778 bezout"(x,y)"
1780 finds "u" and "v" minimal in a natural sense such that "x*u+y*v =
1781 gcd(x,y)". The arguments must be both integers or both polynomials, and
1782 the result is a row vector with three components "u", "v", and
1783 "gcd(x,y)".
1784 The library syntax is vecbezout"(x,y)" to get the vector, or "
1786 gbezout(x,y, &u, &v)" which gives as result the address of the created
1787 gcd, and puts the addresses of the corresponding created objects into
1788 "u" and "v".
1789 bezoutres"(x,y)"
1791 as "bezout", with the resultant of "x" and "y" replacing the gcd. The
1792 algorithm uses (subresultant) assumes the base ring is a domain.
1793 The library syntax is vecbezoutres"(x,y)" to get the vector, or "
1795 subresext(x,y, &u, &v)" which gives as result the address of the
1796 created gcd, and puts the addresses of the corresponding created
1797 objects into "u" and "v".
1798 bigomega"(x)"
1800 number of prime divisors of "|x|" counted with multiplicity. "x" must
1801 be an integer.
1802 The library syntax is bigomega"(x)", the result is a "long".
1804 binomial"(x,y)"
1806 binomial coefficient "\binom{x}{y}". Here "y" must be an integer, but
1807 "x" can be any PARI object.
1808 The library syntax is binomial"(x,y)", where "y" must be a "long".
1810 chinese"(x,{y})"
1812 if "x" and "y" are both intmods or both polmods, creates (with the same
1813 type) a "z" in the same residue class as "x" and in the same residue
1814 class as "y", if it is possible.
1815 This function also allows vector and matrix arguments, in which case
1817 the operation is recursively applied to each component of the vector or
1818 matrix. For polynomial arguments, it is applied to each coefficient.
1819 If "y" is omitted, and "x" is a vector, "chinese" is applied
1821 recursively to the components of "x", yielding a residue belonging to
1822 the same class as all components of "x".
1823 Finally "chinese(x,x) = x" regardless of the type of "x"; this allows
1825 vector arguments to contain other data, so long as they are identical
1826 in both vectors.
1827 The library syntax is chinese"(x,y)". Also available is
1829 "chinese1""(x)", corresponding to an ommitted "y".
1830 content"(x)"
1832 computes the gcd of all the coefficients of "x", when this gcd makes
1833 sense. This is the natural definition if "x" is a polynomial (and by
1834 extension a power series) or a vector/matrix. This is in general a
1835 weaker notion than the \emph{ideal} generated by the coefficients:
1836 ? content(2*x+y)
1838 %1 = 1 \\ = gcd(2,y) over Q[y]
1839 If "x" is a scalar, this simply returns the absolute value of "x" if
1841 "x" is rational ("t_INT" or "t_FRAC"), and either 1 (inexact input) or
1842 "x" (exact input) otherwise; the result should be identical to "gcd(x,
1843 0)".
1844 The content of a rational function is the ratio of the contents of the
1846 numerator and the denominator. In recursive structures, if a matrix or
1847 vector \emph{coefficient} "x" appears, the gcd is taken not with "x",
1848 but with its content:
1849 ? content([ [2], 4*matid(3) ])
1851 %1 = 2
1852 The library syntax is content"(x)".
1854 contfrac"(x,{b},{nmax})"
1856 creates the row vector whose components are the partial quotients of
1857 the continued fraction expansion of "x". That is a result
1858 "[a_0,...,a_n]" means that "x ~ a_0+1/(a_1+...+1/a_n)...)". The output
1859 is normalized so that "a_n ! = 1" (unless we also have "n = 0").
1860 The number of partial quotients "n" is limited to "nmax". If "x" is a
1862 real number, the expansion stops at the last significant partial
1863 quotient if "nmax" is omitted. "x" can also be a rational function or a
1864 power series.
1865 If a vector "b" is supplied, the numerators will be equal to the
1867 coefficients of "b" (instead of all equal to 1 as above). The length of
1868 the result is then equal to the length of "b", unless a partial
1869 remainder is encountered which is equal to zero, in which case the
1870 expansion stops. In the case of real numbers, the stopping criterion is
1871 thus different from the one mentioned above since, if "b" is too long,
1872 some partial quotients may not be significant.
1873 If "b" is an integer, the command is understood as "contfrac(x,nmax)".
1875 The library syntax is contfrac0"(x,b,nmax)". Also available are "
1877 gboundcf(x,nmax)", " gcf(x)", or " gcf2(b,x)", where "nmax" is a C
1878 integer.
1879 contfracpnqn"(x)"
1881 when "x" is a vector or a one-row matrix, "x" is considered as the list
1882 of partial quotients "[a_0,a_1,...,a_n]" of a rational number, and the
1883 result is the 2 by 2 matrix "[p_n,p_{n-1};q_n,q_{n-1}]" in the standard
1884 notation of continued fractions, so "p_n/q_n =
1885 a_0+1/(a_1+...+1/a_n)...)". If "x" is a matrix with two rows
1886 "[b_0,b_1,...,b_n]" and "[a_0,a_1,...,a_n]", this is then considered as
1887 a generalized continued fraction and we have similarly "p_n/q_n =
1888 1/b_0(a_0+b_1/(a_1+...+b_n/a_n)...)". Note that in this case one
1889 usually has "b_0 = 1".
1890 The library syntax is pnqn"(x)".
1892 core"(n,{flag = 0})"
1894 if "n" is a non-zero integer written as "n = df^2" with "d" squarefree,
1895 returns "d". If "flag" is non-zero, returns the two-element row vector
1896 "[d,f]".
1897 The library syntax is core0"(n,flag)". Also available are " core(n)" (
1899 = " core0(n,0)") and " core2(n)" ( = " core0(n,1)").
1900 coredisc"(n,{flag})"
1902 if "n" is a non-zero integer written as "n = df^2" with "d" fundamental
1903 discriminant (including 1), returns "d". If "flag" is non-zero, returns
1904 the two-element row vector "[d,f]". Note that if "n" is not congruent
1905 to 0 or 1 modulo 4, "f" will be a half integer and not an integer.
1906 The library syntax is coredisc0"(n,flag)". Also available are "
1908 coredisc(n)" ( = " coredisc(n,0)") and " coredisc2(n)" ( = "
1909 coredisc(n,1)").
1910 dirdiv"(x,y)"
1912 "x" and "y" being vectors of perhaps different lengths but with "y[1] !
1913 = 0" considered as Dirichlet series, computes the quotient of "x" by
1914 "y", again as a vector.
1915 The library syntax is dirdiv"(x,y)".
1917 direuler"(p = a,b,expr,{c})"
1919 computes the Dirichlet series associated to the Euler product of
1920 expression expr as "p" ranges through the primes from "a" to "b". expr
1921 must be a polynomial or rational function in another variable than "p"
1922 (say "X") and "expr(X)" is understood as the local factor
1923 "expr(p^{-s})".
1924 The series is output as a vector of coefficients. If "c" is present,
1926 output only the first "c" coefficients in the series. The following
1927 command computes the sigma function, associated to "zeta(s)zeta(s-1)":
1928 ? direuler(p=2, 10, 1/((1-X)*(1-p*X)))
1930 %1 = [1, 3, 4, 7, 6, 12, 8, 15, 13, 18]
1931 The library syntax is direuler"(void *E, GEN (*eval)(GEN,void*), GEN a,
1933 GEN b)"
1934 dirmul"(x,y)"
1936 "x" and "y" being vectors of perhaps different lengths considered as
1937 Dirichlet series, computes the product of "x" by "y", again as a
1938 vector.
1939 The library syntax is dirmul"(x,y)".
1941 divisors"(x)"
1943 creates a row vector whose components are the divisors of "x". The
1944 factorization of "x" (as output by "factor") can be used instead.
1945 By definition, these divisors are the products of the irreducible
1947 factors of "n", as produced by factor(n), raised to appropriate powers
1948 (no negative exponent may occur in the factorization). If "n" is an
1949 integer, they are the positive divisors, in increasing order.
1950 The library syntax is divisors"(x)".
1952 eulerphi"(x)"
1954 Euler's "phi" (totient) function of "|x|", in other words "|(Z/xZ)^*|".
1955 "x" must be of type integer.
1956 The library syntax is phi"(x)".
1958 factor"(x,{lim = -1})"
1960 general factorization function. If "x" is of type integer, rational,
1961 polynomial or rational function, the result is a two-column matrix, the
1962 first column being the irreducibles dividing "x" (prime numbers or
1963 polynomials), and the second the exponents. If "x" is a vector or a
1964 matrix, the factoring is done componentwise (hence the result is a
1965 vector or matrix of two-column matrices). By definition, 0 is factored
1966 as "0^1".
1967 If "x" is of type integer or rational, the factors are pseudoprimes
1969 (see "ispseudoprime"), and in general not rigorously proven primes. In
1970 fact, any factor which is " <= 10^{13}" is a genuine prime number. Use
1971 "isprime" to prove primality of other factors, as in
1972 fa = factor(2^2^7 +1)
1974 isprime( fa[,1] )
1975 An argument lim can be added, meaning that we look only for prime
1977 factors "p < lim", or up to "primelimit", whichever is lowest (except
1978 when "lim = 0" where the effect is identical to setting "lim =
1979 primelimit"). In this case, the remaining part may actually be a proven
1980 composite! See "factorint" for more information about the algorithms
1981 used.
1982 The polynomials or rational functions to be factored must have scalar
1984 coefficients. In particular PARI does \emph{not} know how to factor
1985 multivariate polynomials. See "factormod" and "factorff" for the
1986 algorithms used over finite fields, "factornf" for the algorithms over
1987 number fields. Over Q, van Hoeij's method is used, which is able to
1988 cope with hundreds of modular factors.
1989 Note that PARI tries to guess in a sensible way over which ring you
1991 want to factor. Note also that factorization of polynomials is done up
1992 to multiplication by a constant. In particular, the factors of rational
1993 polynomials will have integer coefficients, and the content of a
1994 polynomial or rational function is discarded and not included in the
1995 factorization. If needed, you can always ask for the content
1996 explicitly:
1997 ? factor(t^2 + 5/2*t + 1)
1999 %1 =
2000 [2*t + 1 1]
2001 [t + 2 1]
2003 ? content(t^2 + 5/2*t + 1)
2005 %2 = 1/2
2006 See also "factornf" and "nffactor".
2008 The library syntax is factor0"(x,lim)", where lim is a C integer. Also
2010 available are " factor(x)" ( = " factor0(x,-1)"), " smallfact(x)" ( = "
2011 factor0(x,0)").
2012 factorback"(f,{e},{nf})"
2014 gives back the factored object corresponding to a factorization. The
2015 integer 1 corresponds to the empty factorization. If the last argument
2016 is of number field type (e.g. created by "nfinit"), assume we are
2017 dealing with an ideal factorization in the number field. The resulting
2018 ideal product is given in HNF form.
2019 If "e" is present, "e" and "f" must be vectors of the same length ("e"
2021 being integral), and the corresponding factorization is the product of
2022 the "f[i]^{e[i]}".
2023 If not, and "f" is vector, it is understood as in the preceding case
2025 with "e" a vector of 1 (the product of the "f[i]" is returned).
2026 Finally, "f" can be a regular factorization, as produced with any
2027 "factor" command. A few examples:
2028 ? factorback([2,2; 3,1])
2030 %1 = 12
2031 ? factorback([2,2], [3,1])
2032 %2 = 12
2033 ? factorback([5,2,3])
2034 %3 = 30
2035 ? factorback([2,2], [3,1], nfinit(x^3+2))
2036 %4 =
2037 [16 0 0]
2038 [0 16 0]
2040 [0 0 16]
2042 ? nf = nfinit(x^2+1); fa = idealfactor(nf, 10)
2043 %5 =
2044 [[2, [1, 1]~, 2, 1, [1, 1]~] 2]
2045 [[5, [-2, 1]~, 1, 1, [2, 1]~] 1]
2047 [[5, [2, 1]~, 1, 1, [-2, 1]~] 1]
2049 ? factorback(fa)
2050 *** forbidden multiplication t_VEC * t_VEC.
2051 ? factorback(fa, nf)
2052 %6 =
2053 [10 0]
2054 [0 10]
2056 In the fourth example, 2 and 3 are interpreted as principal ideals in a
2058 cubic field. In the fifth one, "factorback(fa)" is meaningless since we
2059 forgot to indicate the number field, and the entries in the first
2060 column of "fa" can't be multiplied.
2061 The library syntax is factorback0"(f,e,nf)", where an omitted "nf" or
2063 "e" is entered as "NULL". Also available is "factorback""(f,nf)" (case
2064 "e = NULL") where an omitted "nf" is entered as "NULL".
2065 factorcantor"(x,p)"
2067 factors the polynomial "x" modulo the prime "p", using distinct degree
2068 plus Cantor-Zassenhaus. The coefficients of "x" must be operation-
2069 compatible with "Z/pZ". The result is a two-column matrix, the first
2070 column being the irreducible polynomials dividing "x", and the second
2071 the exponents. If you want only the \emph{degrees} of the irreducible
2072 polynomials (for example for computing an "L"-function), use
2073 "factormod(x,p,1)". Note that the "factormod" algorithm is usually
2074 faster than "factorcantor".
2075 The library syntax is factcantor"(x,p)".
2077 factorff"(x,p,a)"
2079 factors the polynomial "x" in the field "F_q" defined by the
2080 irreducible polynomial "a" over "F_p". The coefficients of "x" must be
2081 operation-compatible with "Z/pZ". The result is a two-column matrix:
2082 the first column contains the irreducible factors of "x", and the
2083 second their exponents. If all the coefficients of "x" are in "F_p", a
2084 much faster algorithm is applied, using the computation of isomorphisms
2085 between finite fields.
2086 The library syntax is factorff"(x,p,a)".
2088 factorial"(x)" or "x!"
2090 factorial of "x". The expression "x!" gives a result which is an
2091 integer, while factorial(x) gives a real number.
2092 The library syntax is mpfact"(x)" for "x!" and " mpfactr(x,prec)" for
2094 factorial(x). "x" must be a "long" integer and not a PARI integer.
2095 factorint"(n,{flag = 0})"
2097 factors the integer "n" into a product of pseudoprimes (see
2098 "ispseudoprime"), using a combination of the Shanks SQUFOF and Pollard
2099 Rho method (with modifications due to Brent), Lenstra's ECM (with
2100 modifications by Montgomery), and MPQS (the latter adapted from the
2101 LiDIA code with the kind permission of the LiDIA maintainers), as well
2102 as a search for pure powers with exponents" <= 10". The output is a
2103 two-column matrix as for "factor". Use "isprime" on the result if you
2104 want to guarantee primality.
2105 This gives direct access to the integer factoring engine called by most
2107 arithmetical functions. flag is optional; its binary digits mean 1:
2108 avoid MPQS, 2: skip first stage ECM (we may still fall back to it
2109 later), 4: avoid Rho and SQUFOF, 8: don't run final ECM (as a result, a
2110 huge composite may be declared to be prime). Note that a (strong)
2111 probabilistic primality test is used; thus composites might (very
2112 rarely) not be detected.
2113 You are invited to play with the flag settings and watch the internals
2115 at work by using "gp"'s "debuglevel" default parameter (level 3 shows
2116 just the outline, 4 turns on time keeping, 5 and above show an
2117 increasing amount of internal details). If you see anything funny
2118 happening, please let us know.
2119 The library syntax is factorint"(n,flag)".
2121 factormod"(x,p,{flag = 0})"
2123 factors the polynomial "x" modulo the prime integer "p", using
2124 Berlekamp. The coefficients of "x" must be operation-compatible with
2125 "Z/pZ". The result is a two-column matrix, the first column being the
2126 irreducible polynomials dividing "x", and the second the exponents. If
2127 "flag" is non-zero, outputs only the \emph{degrees} of the irreducible
2128 polynomials (for example, for computing an "L"-function). A different
2129 algorithm for computing the mod "p" factorization is "factorcantor"
2130 which is sometimes faster.
2131 The library syntax is factormod"(x,p,flag)". Also available are "
2133 factmod(x,p)" (which is equivalent to " factormod(x,p,0)") and "
2134 simplefactmod(x,p)" ( = " factormod(x,p,1)").
2135 fibonacci"(x)"
2137 "x^{th}" Fibonacci number.
2138 The library syntax is fibo"(x)". "x" must be a "long".
2140 ffinit"(p,n,{v = x})"
2142 computes a monic polynomial of degree "n" which is irreducible over
2143 "F_p". For instance if "P = ffinit(3,2,y)", you can represent elements
2144 in "F_{3^2}" as polmods modulo "P". This function uses a fast variant
2145 of Adleman-Lenstra's algorithm.
2146 The library syntax is ffinit"(p,n,v)", where "v" is a variable number.
2148 gcd"(x,{y})"
2150 creates the greatest common divisor of "x" and "y". "x" and "y" can be
2151 of quite general types, for instance both rational numbers. If "y" is
2152 omitted and "x" is a vector, returns the "gcd" of all components of
2153 "x", i.e. this is equivalent to content(x).
2154 When "x" and "y" are both given and one of them is a vector/matrix
2156 type, the GCD is again taken recursively on each component, but in a
2157 different way. If "y" is a vector, resp. matrix, then the result has
2158 the same type as "y", and components equal to "gcd(x, y[i])",
2159 resp. "gcd(x, y[,i])". Else if "x" is a vector/matrix the result has
2160 the same type as "x" and an analogous definition. Note that for these
2161 types, "gcd" is not commutative.
2162 The algorithm used is a naive Euclid except for the following inputs:
2164 \item integers: use modified right-shift binary (``plus-minus''
2166 variant).
2167 \item univariate polynomials with coeffients in the same number field
2169 (in particular rational): use modular gcd algorithm.
2170 \item general polynomials: use the subresultant algorithm if
2172 coefficient explosion is likely (exact, non modular, coefficients).
2173 The library syntax is ggcd"(x,y)". For general polynomial inputs, "
2175 srgcd(x,y)" is also available. For univariate \emph{rational}
2176 polynomials, one also has " modulargcd(x,y)".
2177 hilbert"(x,y,{p})"
2179 Hilbert symbol of "x" and "y" modulo "p". If "x" and "y" are of type
2180 integer or fraction, an explicit third parameter "p" must be supplied,
2181 "p = 0" meaning the place at infinity. Otherwise, "p" needs not be
2182 given, and "x" and "y" can be of compatible types integer, fraction,
2183 real, intmod a prime (result is undefined if the modulus is not prime),
2184 or "p"-adic.
2185 The library syntax is hil"(x,y,p)".
2187 isfundamental"(x)"
2189 true (1) if "x" is equal to 1 or to the discriminant of a quadratic
2190 field, false (0) otherwise.
2191 The library syntax is gisfundamental"(x)", but the simpler function "
2193 isfundamental(x)" which returns a "long" should be used if "x" is known
2194 to be of type integer.
2195 ispower"(x,{k}, {&n})"
2197 if "k" is given, returns true (1) if "x" is a "k"-th power, false (0)
2198 if not. In this case, "x" may be an integer or polynomial, a rational
2199 number or function, or an intmod a prime or "p"-adic.
2200 If "k" is omitted, only integers and fractions are allowed and the
2202 function returns the maximal "k >= 2" such that "x = n^k" is a perfect
2203 power, or 0 if no such "k" exist; in particular "ispower(-1)",
2204 ispower(0), and ispower(1) all return 0.
2205 If a third argument &n is given and a "k"-th root was computed in the
2207 process, then "n" is set to that root.
2208 The library syntax is ispower"(x, k, &n)", the result is a "long".
2210 Omitted "k" or "n" are coded as "NULL".
2211 isprime"(x,{flag = 0})"
2213 true (1) if "x" is a (proven) prime number, false (0) otherwise. This
2214 can be very slow when "x" is indeed prime and has more than 1000
2215 digits, say. Use "ispseudoprime" to quickly check for pseudo primality.
2216 See also "factor".
2217 If "flag = 0", use a combination of Baillie-PSW pseudo primality test
2219 (see "ispseudoprime"), Selfridge ``"p-1"'' test if "x-1" is smooth
2220 enough, and Adleman-Pomerance-Rumely-Cohen-Lenstra (APRCL) for general
2221 "x".
2222 If "flag = 1", use Selfridge-Pocklington-Lehmer ``"p-1"'' test and
2224 output a primality certificate as follows: return 0 if "x" is
2225 composite, 1 if "x" is small enough that passing Baillie-PSW test
2226 guarantees its primality (currently "x < 10^{13}"), 2 if "x" is a large
2227 prime whose primality could only sensibly be proven (given the
2228 algorithms implemented in PARI) using the APRCL test. Otherwise ("x" is
2229 large and "x-1" is smooth) output a three column matrix as a primality
2230 certificate. The first column contains the prime factors "p" of "x-1",
2231 the second the corresponding elements "a_p" as in Proposition 8.3.1 in
2232 GTM 138, and the third the output of isprime(p,1). The algorithm fails
2233 if one of the pseudo-prime factors is not prime, which is exceedingly
2234 unlikely (and well worth a bug report).
2235 If "flag = 2", use APRCL.
2237 The library syntax is gisprime"(x,flag)", but the simpler function "
2239 isprime(x)" which returns a "long" should be used if "x" is known to be
2240 of type integer.
2241 ispseudoprime"(x,{flag})"
2243 true (1) if "x" is a strong pseudo prime (see below), false (0)
2244 otherwise. If this function returns false, "x" is not prime; if, on the
2245 other hand it returns true, it is only highly likely that "x" is a
2246 prime number. Use "isprime" (which is of course much slower) to prove
2247 that "x" is indeed prime.
2248 If "flag = 0", checks whether "x" is a Baillie-Pomerance-Selfridge-
2250 Wagstaff pseudo prime (strong Rabin-Miller pseudo prime for base 2,
2251 followed by strong Lucas test for the sequence "(P,-1)", "P" smallest
2252 positive integer such that "P^2 - 4" is not a square mod "x").
2253 There are no known composite numbers passing this test (in particular,
2255 all composites " <= 10^{13}" are correctly detected), although it is
2256 expected that infinitely many such numbers exist.
2257 If "flag > 0", checks whether "x" is a strong Miller-Rabin pseudo prime
2259 for "flag" randomly chosen bases (with end-matching to catch square
2260 roots of "-1").
2261 The library syntax is gispseudoprime"(x,flag)", but the simpler
2263 function " ispseudoprime(x)" which returns a "long" should be used if
2264 "x" is known to be of type integer.
2265 issquare"(x,{&n})"
2267 true (1) if "x" is a square, false (0) if not. What ``being a square''
2268 means depends on the type of "x": all "t_COMPLEX" are squares, as well
2269 as all non-negative "t_REAL"; for exact types such as "t_INT", "t_FRAC"
2270 and "t_INTMOD", squares are numbers of the form "s^2" with "s" in Z, Q
2271 and "Z/NZ" respectively.
2272 ? issquare(3) \\ as an integer
2274 %1 = 0
2275 ? issquare(3.) \\ as a real number
2276 %2 = 1
2277 ? issquare(Mod(7, 8)) \\ in Z/8Z
2278 %3 = 0
2279 ? issquare( 5 + O(13^4) ) \\ in Q_13
2280 %4 = 0
2281 If "n" is given and an exact square root had to be computed in the
2283 checking process, puts that square root in "n". This is the case when
2284 "x" is a "t_INT", "t_FRAC", "t_POL" or "t_RFRAC" (or a vector of such
2285 objects):
2286 ? issquare(4, &n)
2288 %1 = 1
2289 ? n
2290 %2 = 2
2291 ? issquare([4, x^2], &n)
2292 %3 = [1, 1] \\ both are squares
2293 ? n
2294 %4 = [2, x] \\ the square roots
2295 This will \emph{not} work for "t_INTMOD" (use quadratic reciprocity) or
2297 "t_SER" (only check the leading coefficient).
2298 The library syntax is gissquarerem"(x,&n)". Also available is "
2300 gissquare(x)".
2301 issquarefree"(x)"
2303 true (1) if "x" is squarefree, false (0) if not. Here "x" can be an
2304 integer or a polynomial.
2305 The library syntax is gissquarefree"(x)", but the simpler function "
2307 issquarefree(x)" which returns a "long" should be used if "x" is known
2308 to be of type integer. This issquarefree is just the square of the
2309 Moebius function, and is computed as a multiplicative arithmetic
2310 function much like the latter.
2311 kronecker"(x,y)"
2313 Kronecker symbol "(x|y)", where "x" and "y" must be of type integer. By
2314 definition, this is the extension of Legendre symbol to "Z x Z" by
2315 total multiplicativity in both arguments with the following special
2316 rules for "y = 0, -1" or 2:
2317 \item "(x|0) = 1" if "|x |= 1" and 0 otherwise.
2319 \item "(x|-1) = 1" if "x >= 0" and "-1" otherwise.
2321 \item "(x|2) = 0" if "x" is even and 1 if "x = 1,-1 mod 8" and "-1" if
2323 "x = 3,-3 mod 8".
2324 The library syntax is kronecker"(x,y)", the result (0 or "+- 1") is a
2326 "long".
2327 lcm"(x,{y})"
2329 least common multiple of "x" and "y", i.e. such that "lcm(x,y)*gcd(x,y)
2330 = abs(x*y)". If "y" is omitted and "x" is a vector, returns the "lcm"
2331 of all components of "x".
2332 When "x" and "y" are both given and one of them is a vector/matrix
2334 type, the LCM is again taken recursively on each component, but in a
2335 different way. If "y" is a vector, resp. matrix, then the result has
2336 the same type as "y", and components equal to "lcm(x, y[i])",
2337 resp. "lcm(x, y[,i])". Else if "x" is a vector/matrix the result has
2338 the same type as "x" and an analogous definition. Note that for these
2339 types, "lcm" is not commutative.
2340 Note that lcm(v) is quite different from
2342 l = v[1]; for (i = 1, #v, l = lcm(l, v[i]))
2344 Indeed, lcm(v) is a scalar, but "l" may not be (if one of the "v[i]" is
2346 a vector/matrix). The computation uses a divide-conquer tree and should
2347 be much more efficient, especially when using the GMP multiprecision
2348 kernel (and more subquadratic algorithms become available):
2349 ? v = vector(10^4, i, random);
2351 ? lcm(v);
2352 time = 323 ms.
2353 ? l = v[1]; for (i = 1, #v, l = lcm(l, v[i]))
2354 time = 833 ms.
2355 The library syntax is glcm"(x,y)".
2357 moebius"(x)"
2359 Moebius "mu"-function of "|x|". "x" must be of type integer.
2360 The library syntax is mu"(x)", the result (0 or "+- 1") is a "long".
2362 nextprime"(x)"
2364 finds the smallest pseudoprime (see "ispseudoprime") greater than or
2365 equal to "x". "x" can be of any real type. Note that if "x" is a
2366 pseudoprime, this function returns "x" and not the smallest pseudoprime
2367 strictly larger than "x". To rigorously prove that the result is prime,
2368 use "isprime".
2369 The library syntax is nextprime"(x)".
2371 numdiv"(x)"
2373 number of divisors of "|x|". "x" must be of type integer.
2374 The library syntax is numbdiv"(x)".
2376 numbpart"(n)"
2378 gives the number of unrestricted partitions of "n", usually called p(n)
2379 in the litterature; in other words the number of nonnegative integer
2380 solutions to "a+2b+3c+.. .= n". "n" must be of type integer and "1 <= n
2381 < 10^{15}". The algorithm uses the Hardy-Ramanujan-Rademacher formula.
2382 The library syntax is numbpart"(n)".
2384 omega"(x)"
2386 number of distinct prime divisors of "|x|". "x" must be of type
2387 integer.
2388 The library syntax is omega"(x)", the result is a "long".
2390 precprime"(x)"
2392 finds the largest pseudoprime (see "ispseudoprime") less than or equal
2393 to "x". "x" can be of any real type. Returns 0 if "x <= 1". Note that
2394 if "x" is a prime, this function returns "x" and not the largest prime
2395 strictly smaller than "x". To rigorously prove that the result is
2396 prime, use "isprime".
2397 The library syntax is precprime"(x)".
2399 prime"(x)"
2401 the "x^{th}" prime number, which must be among the precalculated
2402 primes.
2403 The library syntax is prime"(x)". "x" must be a "long".
2405 primepi"(x)"
2407 the prime counting function. Returns the number of primes "p", "p <=
2408 x". Uses a naive algorithm so that "x" must be less than "primelimit".
2409 The library syntax is primepi"(x)".
2411 primes"(x)"
2413 creates a row vector whose components are the first "x" prime numbers,
2414 which must be among the precalculated primes.
2415 The library syntax is primes"(x)". "x" must be a "long".
2417 qfbclassno"(D,{flag = 0})"
2419 ordinary class number of the quadratic order of discriminant "D". In
2420 the present version /usr/share/libpari23, a "O(D^{1/2})" algorithm is
2421 used for "D > 0" (using Euler product and the functional equation) so
2422 "D" should not be too large, say "D < 10^8", for the time to be
2423 reasonable. On the other hand, for "D < 0" one can reasonably compute
2424 qfbclassno(D) for "|D| < 10^{25}", since the routine uses Shanks's
2425 method which is in "O(|D|^{1/4})". For larger values of "|D|", see
2426 "quadclassunit".
2427 If "flag = 1", compute the class number using Euler products and the
2429 functional equation. However, it is in "O(|D|^{1/2})".
2430 Important warning. For "D < 0", this function may give incorrect
2432 results when the class group has a low exponent (has many cyclic
2433 factors), because implementing Shanks's method in full generality slows
2434 it down immensely. It is therefore strongly recommended to double-check
2435 results using either the version with "flag = 1" or the function
2436 "quadclassunit".
2437 Warning. contrary to what its name implies, this routine does not
2439 compute the number of classes of binary primitive forms of discriminant
2440 "D", which is equal to the \emph{narrow} class number. The two notions
2441 are the same when "D < 0" or the fundamental unit "varepsilon" has
2442 negative norm; when "D > 0" and "Nvarepsilon > 0", the number of
2443 classes of forms is twice the ordinary class number. This is a problem
2444 which we cannot fix for backward compatibility reasons. Use the
2445 following routine if you are only interested in the number of classes
2446 of forms:
2447 QFBclassno(D) =
2449 qfbclassno(D) * if (D < 0 || norm(quadunit(D)) < 0, 1, 2)
2450 Here are a few examples:
2452 %2 = 1
2454 ? qfbclassno(-400000028)
2455 time = 0 ms.
2456 %3 = 7253 \{ much faster}
2457 %2 = 1
2458 ? qfbclassno(-400000028)
2459 time = 0 ms.
2460 %3 = 7253 \{ correct, and fast enough}
2461 ? quadclassunit(-400000028).no
2462 time = 0 ms.
2463 %4 = 7253
2464 The library syntax is qfbclassno0"(D,flag)". Also available: "
2466 classno(D)" ( = " qfbclassno(D)"), " classno2(D)" ( = "
2467 qfbclassno(D,1)"), and finally we have the function " hclassno(D)"
2468 which computes the class number of an imaginary quadratic field by
2469 counting reduced forms, an "O(|D|)" algorithm. See also "qfbhclassno".
2470 qfbcompraw"(x,y)"
2472 composition of the binary quadratic forms "x" and "y", without
2473 reduction of the result. This is useful e.g. to compute a generating
2474 element of an ideal.
2475 The library syntax is compraw"(x,y)".
2477 qfbhclassno"(x)"
2479 Hurwitz class number of "x", where "x" is non-negative and congruent to
2480 0 or 3 modulo 4. For "x > 5. 10^5", we assume the GRH, and use
2481 "quadclassunit" with default parameters.
2482 The library syntax is hclassno"(x)".
2484 qfbnucomp"(x,y,l)"
2486 composition of the primitive positive definite binary quadratic forms
2487 "x" and "y" (type "t_QFI") using the NUCOMP and NUDUPL algorithms of
2488 Shanks, à la Atkin. "l" is any positive constant, but for optimal
2489 speed, one should take "l = |D|^{1/4}", where "D" is the common
2490 discriminant of "x" and "y". When "x" and "y" do not have the same
2491 discriminant, the result is undefined.
2492 The current implementation is straightforward and in general
2494 \emph{slower} than the generic routine (since the latter take
2495 advantadge of asymptotically fast operations and careful
2496 optimizations).
2497 The library syntax is nucomp"(x,y,l)". The auxiliary function "
2499 nudupl(x,l)" can be used when "x = y".
2500 qfbnupow"(x,n)"
2502 "n"-th power of the primitive positive definite binary quadratic form
2503 "x" using Shanks's NUCOMP and NUDUPL algorithms (see "qfbnucomp", in
2504 particular the final warning).
2505 The library syntax is nupow"(x,n)".
2507 qfbpowraw"(x,n)"
2509 "n"-th power of the binary quadratic form "x", computed without doing
2510 any reduction (i.e. using "qfbcompraw"). Here "n" must be non-negative
2511 and "n < 2^{31}".
2512 The library syntax is powraw"(x,n)" where "n" must be a "long" integer.
2514 qfbprimeform"(x,p)"
2516 prime binary quadratic form of discriminant "x" whose first coefficient
2517 is the prime number "p". By abuse of notation, "p = +- 1" is a valid
2518 special case which returns the unit form. Returns an error if "x" is
2519 not a quadratic residue mod "p". In the case where "x > 0", "p < 0" is
2520 allowed, and the ``distance'' component of the form is set equal to
2521 zero according to the current precision. (Note that negative definite
2522 "t_QFI" are not implemented.)
2523 The library syntax is primeform"(x,p,prec)", where the third variable
2525 "prec" is a "long", but is only taken into account when "x > 0".
2526 qfbred"(x,{flag = 0},{D},{isqrtD},{sqrtD})"
2528 reduces the binary quadratic form "x" (updating Shanks's distance
2529 function if "x" is indefinite). The binary digits of "flag" are toggles
2530 meaning
2531 1: perform a single reduction step
2533 2: don't update Shanks's distance
2535 "D", isqrtD, sqrtD, if present, supply the values of the discriminant,
2537 "\floor{ sqrt {D}}", and " sqrt {D}" respectively (no checking is done
2538 of these facts). If "D < 0" these values are useless, and all
2539 references to Shanks's distance are irrelevant.
2540 The library syntax is qfbred0"(x,flag,D,isqrtD,sqrtD)". Use "NULL" to
2542 omit any of "D", isqrtD, sqrtD.
2543 Also available are
2545 " redimag(x)" ( = " qfbred(x)" where "x" is definite),
2547 and for indefinite forms:
2549 " redreal(x)" ( = " qfbred(x)"),
2551 " rhoreal(x)" ( = " qfbred(x,1)"),
2553 " redrealnod(x,sq)" ( = " qfbred(x,2,,isqrtD)"),
2555 " rhorealnod(x,sq)" ( = " qfbred(x,3,,isqrtD)").
2557 qfbsolve"(Q,p)"
2559 Solve the equation "Q(x,y) = p" over the integers, where "Q" is a
2560 binary quadratic form and "p" a prime number.
2561 Return "[x,y]" as a two-components vector, or zero if there is no
2563 solution. Note that this function returns only one solution and not
2564 all the solutions.
2565 Let "D = \disc Q". The algorithm used runs in probabilistic polynomial
2567 time in "p" (through the computation of a square root of "D" modulo
2568 "p"); it is polynomial time in "D" if "Q" is imaginary, but exponential
2569 time if "Q" is real (through the computation of a full cycle of reduced
2570 forms). In the latter case, note that "bnfisprincipal" provides a
2571 solution in heuristic subexponential time in "D" assuming the GRH.
2572 The library syntax is qfbsolve"(Q,n)".
2574 quadclassunit"(D,{flag = 0},{tech = []})"
2576 Buchmann-McCurley's sub-exponential algorithm for computing the class
2577 group of a quadratic order of discriminant "D".
2578 This function should be used instead of "qfbclassno" or "quadregula"
2580 when "D < -10^{25}", "D > 10^{10}", or when the \emph{structure} is
2581 wanted. It is a special case of "bnfinit", which is slower, but more
2582 robust.
2583 If "flag" is non-zero \emph{and} "D > 0", computes the narrow class
2585 group and regulator, instead of the ordinary (or wide) ones. In the
2586 current version /usr/share/libpari23, this does not work at all: use
2587 the general function "bnfnarrow".
2588 Optional parameter tech is a row vector of the form "[c_1, c_2]", where
2590 "c_1 <= c_2" are positive real numbers which control the execution time
2591 and the stack size. For a given "c_1", set "c_2 = c_1" to get maximum
2592 speed. To get a rigorous result under GRH, you must take "c_2 >= 6".
2593 Reasonable values for "c_1" are between 0.1 and 2. More precisely, the
2594 algorithm will \emph{assume} that prime ideals of norm less than "c_2 (
2595 log |D|)^2" generate the class group, but the bulk of the work is done
2596 with prime ideals of norm less than "c_1 ( log |D|)^2". A larger "c_1"
2597 means that relations are easier to find, but more relations are needed
2598 and the linear algebra will be harder. The default is "c_1 = c_2 =
2599 0.2", so the result is \emph{not} rigorously proven.
2600 The result is a vector "v" with 3 components if "D < 0", and 4
2602 otherwise. The correspond respectively to
2603 \item "v[1]": the class number
2605 \item "v[2]": a vector giving the structure of the class group as a
2607 product of cyclic groups;
2608 \item "v[3]": a vector giving generators of those cyclic groups (as
2610 binary quadratic forms).
2611 \item "v[4]": (omitted if "D < 0") the regulator, computed to an
2613 accuracy which is the maximum of an internal accuracy determined by the
2614 program and the current default (note that once the regulator is known
2615 to a small accuracy it is trivial to compute it to very high accuracy,
2616 see the tutorial).
2617 The library syntax is quadclassunit0"(D,flag,tech)". Also available are
2619 " buchimag(D,c_1,c_2)" and " buchreal(D,flag,c_1,c_2)".
2620 quaddisc"(x)"
2622 discriminant of the quadratic field "Q( sqrt {x})", where "x belongs to
2623 Q".
2624 The library syntax is quaddisc"(x)".
2626 quadhilbert"(D,{pq})"
2628 relative equation defining the Hilbert class field of the quadratic
2629 field of discriminant "D".
2630 If "D < 0", uses complex multiplication (Schertz's variant). The
2632 technical component "pq", if supplied, is a vector "[p,q]" where "p",
2633 "q" are the prime numbers needed for the Schertz's method. More
2634 precisely, prime ideals above "p" and "q" should be non-principal and
2635 coprime to all reduced representatives of the class group. In addition,
2636 if one of these ideals has order 2 in the class group, they should have
2637 the same class. Finally, for efficiency, "gcd(24,(p-1)(q-1))" should be
2638 as large as possible. The routine returns 0 if "[p,q]" is not
2639 suitable.
2640 If "D > 0" Stark units are used and (in rare cases) a vector of
2642 extensions may be returned whose compositum is the requested class
2643 field. See "bnrstark" for details.
2644 The library syntax is quadhilbert"(D,pq,prec)".
2646 quadgen"(D)"
2648 creates the quadratic number "omega = (a+ sqrt {D})/2" where "a = 0" if
2649 "x = 0 mod 4", "a = 1" if "D = 1 mod 4", so that "(1,omega)" is an
2650 integral basis for the quadratic order of discriminant "D". "D" must be
2651 an integer congruent to 0 or 1 modulo 4, which is not a square.
2652 The library syntax is quadgen"(x)".
2654 quadpoly"(D,{v = x})"
2656 creates the ``canonical'' quadratic polynomial (in the variable "v")
2657 corresponding to the discriminant "D", i.e. the minimal polynomial of
2658 quadgen(D). "D" must be an integer congruent to 0 or 1 modulo 4, which
2659 is not a square.
2660 The library syntax is quadpoly0"(x,v)".
2662 quadray"(D,f,{lambda})"
2664 relative equation for the ray class field of conductor "f" for the
2665 quadratic field of discriminant "D" using analytic methods. A "bnf" for
2666 "x^2 - D" is also accepted in place of "D".
2667 For "D < 0", uses the "sigma" function. If supplied, lambda is is the
2669 technical element "lambda" of "bnf" necessary for Schertz's method. In
2670 that case, returns 0 if "lambda" is not suitable.
2671 For "D > 0", uses Stark's conjecture, and a vector of relative
2673 equations may be returned. See "bnrstark" for more details.
2674 The library syntax is quadray"(D,f,lambda,prec)", where an omitted
2676 "lambda" is coded as "NULL".
2677 quadregulator"(x)"
2679 regulator of the quadratic field of positive discriminant "x". Returns
2680 an error if "x" is not a discriminant (fundamental or not) or if "x" is
2681 a square. See also "quadclassunit" if "x" is large.
2682 The library syntax is regula"(x,prec)".
2684 quadunit"(D)"
2686 fundamental unit of the real quadratic field "Q( sqrt D)" where "D"
2687 is the positive discriminant of the field. If "D" is not a fundamental
2688 discriminant, this probably gives the fundamental unit of the
2689 corresponding order. "D" must be an integer congruent to 0 or 1 modulo
2690 4, which is not a square; the result is a quadratic number (see "Label
2691 se:quadgen").
2692 The library syntax is fundunit"(x)".
2694 removeprimes"({x = []})"
2696 removes the primes listed in "x" from the prime number table. In
2697 particular "removeprimes(addprimes)" empties the extra prime table. "x"
2698 can also be a single integer. List the current extra primes if "x" is
2699 omitted.
2700 The library syntax is removeprimes"(x)".
2702 sigma"(x,{k = 1})"
2704 sum of the "k^{th}" powers of the positive divisors of "|x|". "x" and
2705 "k" must be of type integer.
2706 The library syntax is sumdiv"(x)" ( = " sigma(x)") or " gsumdivk(x,k)"
2708 ( = " sigma(x,k)"), where "k" is a C long integer.
2709 sqrtint"(x)"
2711 integer square root of "x", which must be a non-negative integer. The
2712 result is non-negative and rounded towards zero.
2713 The library syntax is sqrti"(x)". Also available is "sqrtremi""(x,&r)"
2715 which returns "s" such that "s^2 = x+r", with "0 <= r <= 2s".
2716 zncoppersmith"(P, N, X, {B = N})"
2718 finds all integers "x_0" with "|x_0| <= X" such that
2719 "gcd(N, P(x_0)) >= B."
2721 If "N" is prime or a prime power, "polrootsmod" or "polrootspadic" will
2723 be much faster. "X" must be smaller than " exp ( log ^2 B / ( deg (P)
2724 log N))".
2725 The library syntax is zncoppersmith"(P, N, X, B)", where an omitted "B"
2727 is coded as "NULL".
2728 znlog"(x,g)"
2730 "g" must be a primitive root mod a prime "p", and the result is the
2731 discrete log of "x" in the multiplicative group "(Z/pZ)^*". This
2732 function uses a simple-minded combination of Pohlig-Hellman algorithm
2733 and Shanks baby-step/giant-step which requires "O( sqrt {q})" storage,
2734 where "q" is the largest prime factor of "p-1". Hence it cannot be used
2735 when the largest prime divisor of "p-1" is greater than about
2736 "10^{13}".
2737 The library syntax is znlog"(x,g)".
2739 znorder"(x,{o})"
2741 "x" must be an integer mod "n", and the result is the order of "x" in
2742 the multiplicative group "(Z/nZ)^*". Returns an error if "x" is not
2743 invertible. If optional parameter "o" is given it is assumed to be a
2744 multiple of the order (used to limit the search space).
2745 The library syntax is znorder"(x,o)", where an omitted "o" is coded as
2747 "NULL". Also available is " order(x)".
2748 znprimroot"(n)"
2750 returns a primitive root (generator) of "(Z/nZ)^*", whenever this
2751 latter group is cyclic ("n = 4" or "n = 2p^k" or "n = p^k", where "p"
2752 is an odd prime and "k >= 0").
2753 The library syntax is gener"(x)".
2755 znstar"(n)"
2757 gives the structure of the multiplicative group "(Z/nZ)^*" as a
2758 3-component row vector "v", where "v[1] = phi(n)" is the order of that
2759 group, "v[2]" is a "k"-component row-vector "d" of integers "d[i]" such
2760 that "d[i] > 1" and "d[i] | d[i-1]" for "i >= 2" and "(Z/nZ)^* ~
2761 prod_{i = 1}^k(Z/d[i]Z)", and "v[3]" is a "k"-component row vector
2762 giving generators of the image of the cyclic groups "Z/d[i]Z".
2763 The library syntax is znstar"(n)".
2765
2767 We have implemented a number of functions which are useful for number
2768 theorists working on elliptic curves. We always use Tate's notations.
2769 The functions assume that the curve is given by a general Weierstrass
2770 model
2771 " y^2+a_1xy+a_3y = x^3+a_2x^2+a_4x+a_6, "
2773 where a priori the "a_i" can be of any scalar type. This curve can be
2775 considered as a five-component vector "E = [a1,a2,a3,a4,a6]". Points on
2776 "E" are represented as two-component vectors "[x,y]", except for the
2777 point at infinity, i.e. the identity element of the group law,
2778 represented by the one-component vector "[0]".
2779 It is useful to have at one's disposal more information. This is given
2781 by the function "ellinit" (see there), which initalizes and returns an
2782 ell structure by default. If a specific flag is added, a shortened
2783 sell, for small ell, is returned, which is much faster to compute but
2784 contains less information. The following member functions are available
2785 to deal with the output of "ellinit", both ell and sell:
2786 "a1"--"a6", "b2"--"b8", "c4"--"c6" : coefficients of the elliptic
2788 curve.
2789 "area" : volume of the complex lattice defining "E".
2791 "disc" : discriminant of the curve.
2793 "j" : "j"-invariant of the curve.
2795 "omega" : "[omega_1,omega_2]", periods forming a basis of the
2797 complex lattice defining "E" ("omega_1" is the
2798 real period, and "omega_2/omega_1" belongs to
2800 Poincaré's half-plane).
2801 "eta" : quasi-periods "[eta_1, eta_2]", such that
2803 "eta_1omega_2-eta_2omega_1 = iPi".
2804 "roots" : roots of the associated Weierstrass equation.
2806 "tate" : "[u^2,u,v]" in the notation of Tate.
2808 "w" : Mestre's "w" (this is technical).
2810 The member functions "area", "eta" and "omega" are only available for
2812 curves over Q. Conversely, "tate" and "w" are only available for curves
2813 defined over "Q_p". The use of member functions is best described by an
2814 example:
2815 ? E = ellinit([0,0,0,0,1]); \\ The curve y^2 = x^3 + 1
2817 ? E.a6
2818 %2 = 1
2819 ? E.c6
2820 %3 = -864
2821 ? E.disc
2822 %4 = -432
2823 Some functions, in particular those relative to height computations
2825 (see "ellheight") require also that the curve be in minimal Weierstrass
2826 form, which is duly stressed in their description below. This is
2827 achieved by the function "ellminimalmodel". \emph{Using a non-minimal
2828 model in such a routine will yield a wrong result!}
2829 All functions related to elliptic curves share the prefix "ell", and
2831 the precise curve we are interested in is always the first argument, in
2832 either one of the three formats discussed above, unless otherwise
2833 specified. The requirements are given as the \emph{minimal} ones: any
2834 richer structure may replace the ones requested. For instance, in
2835 functions which have no use for the extra information given by an ell
2836 structure, the curve can be given either as a five-component vector, as
2837 an sell, or as an ell; if an sell is requested, an ell may equally be
2838 given.
2839 elladd"(E,z1,z2)"
2841 sum of the points "z1" and "z2" on the elliptic curve corresponding to
2842 "E".
2843 The library syntax is addell"(E,z1,z2)".
2845 ellak"(E,n)"
2847 computes the coefficient "a_n" of the "L"-function of the elliptic
2848 curve "E", i.e. in principle coefficients of a newform of weight 2
2849 assuming Taniyama-Weil conjecture (which is now known to hold in full
2850 generality thanks to the work of Breuil, Conrad, Diamond, Taylor and
2851 Wiles). "E" must be an sell as output by "ellinit". For this function
2852 to work for every "n" and not just those prime to the conductor, "E"
2853 must be a minimal Weierstrass equation. If this is not the case, use
2854 the function "ellminimalmodel" before using "ellak".
2855 The library syntax is akell"(E,n)".
2857 ellan"(E,n)"
2859 computes the vector of the first "n" "a_k" corresponding to the
2860 elliptic curve "E". All comments in "ellak" description remain valid.
2861 The library syntax is anell"(E,n)", where "n" is a C integer.
2863 ellap"(E,p,{flag = 0})"
2865 computes the "a_p" corresponding to the elliptic curve "E" and the
2866 prime number "p". These are defined by the equation "#E(F_p) = p+1 -
2867 a_p", where "#E(F_p)" stands for the number of points of the curve "E"
2868 over the finite field "F_p". When "flag" is 0, this uses the baby-step
2869 giant-step method and a trick due to Mestre. This runs in time
2870 "O(p^{1/4})" and requires "O(p^{1/4})" storage, hence becomes
2871 unreasonable when "p" has about 30 digits.
2872 If "flag" is 1, computes the "a_p" as a sum of Legendre symbols. This
2874 is slower than the previous method as soon as "p" is greater than 100,
2875 say.
2876 No checking is done that "p" is indeed prime. "E" must be an sell as
2878 output by "ellinit", defined over Q, "F_p" or "Q_p". "E" must be given
2879 by a Weierstrass equation minimal at "p".
2880 The library syntax is ellap0"(E,p,flag)". Also available are "
2882 apell(E,p)", corresponding to "flag = 0", and " apell2(E,p)" ("flag =
2883 1").
2884 ellbil"(E,z1,z2)"
2886 if "z1" and "z2" are points on the elliptic curve "E", assumed to be
2887 integral given by a minimal model, this function computes the value of
2888 the canonical bilinear form on "z1", "z2":
2889 " ( h(E,z1+z2) - h(E,z1) - h(E,z2) ) / 2 "
2891 where "+" denotes of course addition on "E". In addition, "z1" or "z2"
2893 (but not both) can be vectors or matrices.
2894 The library syntax is bilhell"(E,z1,z2,prec)".
2896 ellchangecurve"(E,v)"
2898 changes the data for the elliptic curve "E" by changing the coordinates
2899 using the vector "v = [u,r,s,t]", i.e. if "x'" and "y'" are the new
2900 coordinates, then "x = u^2x'+r", "y = u^3y'+su^2x'+t". "E" must be an
2901 sell as output by "ellinit".
2902 The library syntax is coordch"(E,v)".
2904 ellchangepoint"(x,v)"
2906 changes the coordinates of the point or vector of points "x" using the
2907 vector "v = [u,r,s,t]", i.e. if "x'" and "y'" are the new coordinates,
2908 then "x = u^2x'+r", "y = u^3y'+su^2x'+t" (see also "ellchangecurve").
2909 The library syntax is pointch"(x,v)".
2911 ellconvertname"(name)"
2913 converts an elliptic curve name, as found in the "elldata" database,
2914 from a string to a triplet "[conductor, isogeny class, index]". It will
2915 also convert a triplet back to a curve name. Examples:
2916 ? ellconvertname("123b1")
2918 %1 = [123, 1, 1]
2919 ? ellconvertname(%)
2920 %2 = "123b1"
2921 The library syntax is ellconvertname"(name)".
2923 elleisnum"(E,k,{flag = 0})"
2925 "E" being an elliptic curve as output by "ellinit" (or, alternatively,
2926 given by a 2-component vector "[omega_1,omega_2]" representing its
2927 periods), and "k" being an even positive integer, computes the
2928 numerical value of the Eisenstein series of weight "k" at "E", namely
2929 " (2i Pi/omega_2)^k \Big(1 + 2/zeta(1-k) sum_{n >= 0} n^{k-1}q^n /
2931 (1-q^n)\Big), "
2932 where "q = e(omega_1/omega_2)".
2934 When flag is non-zero and "k = 4" or 6, returns the elliptic invariants
2936 "g_2" or "g_3", such that
2937 "y^2 = 4x^3 - g_2 x - g_3"
2939 is a Weierstrass equation for "E".
2941 The library syntax is elleisnum"(E,k,flag)".
2943 elleta"(om)"
2945 returns the two-component row vector "[eta_1,eta_2]" of quasi-periods
2946 associated to "om = [omega_1, omega_2]"
2947 The library syntax is elleta"(om, prec)"
2949 ellgenerators"(E)"
2951 returns a Z-basis of the free part of the Mordell-Weil group associated
2952 to "E". This function depends on the "elldata" database being
2953 installed and referencing the curve, and so is only available for
2954 curves over Z of small conductors.
2955 The library syntax is ellgenerators"(E)".
2957 ellglobalred"(E)"
2959 calculates the arithmetic conductor, the global minimal model of "E"
2960 and the global Tamagawa number "c". "E" must be an sell as output by
2961 "ellinit", \emph{and is supposed to have all its coefficients "a_i" in}
2962 Q. The result is a 3 component vector "[N,v,c]". "N" is the arithmetic
2963 conductor of the curve. "v" gives the coordinate change for "E" over Q
2964 to the minimal integral model (see "ellminimalmodel"). Finally "c" is
2965 the product of the local Tamagawa numbers "c_p", a quantity which
2966 enters in the Birch and Swinnerton-Dyer conjecture.
2967 The library syntax is ellglobalred"(E)".
2969 ellheight"(E,z,{flag = 2})"
2971 global Néron-Tate height of the point "z" on the elliptic curve "E"
2972 (defined over Q), given by a standard minimal integral model. "E" must
2973 be an "ell" as output by "ellinit". flag selects the algorithm used to
2974 compute the archimedean local height. If "flag = 0", this computation
2975 is done using sigma and theta-functions and a trick due to J.
2976 Silverman. If "flag = 1", use Tate's "4^n" algorithm. If "flag = 2",
2977 use Mestre's AGM algorithm. The latter is much faster than the other
2978 two, both in theory (converges quadratically) and in practice.
2979 The library syntax is ellheight0"(E,z,flag,prec)". Also available are "
2981 ghell(E,z,prec)" ("flag = 0") and " ghell2(E,z,prec)" ("flag = 1").
2982 ellheightmatrix"(E,x)"
2984 "x" being a vector of points, this function outputs the Gram matrix of
2985 "x" with respect to the Néron-Tate height, in other words, the "(i,j)"
2986 component of the matrix is equal to "ellbil(E,x[i],x[j])". The rank of
2987 this matrix, at least in some approximate sense, gives the rank of the
2988 set of points, and if "x" is a basis of the Mordell-Weil group of "E",
2989 its determinant is equal to the regulator of "E". Note that this matrix
2990 should be divided by 2 to be in accordance with certain normalizations.
2991 "E" is assumed to be integral, given by a minimal model.
2992 The library syntax is mathell"(E,x,prec)".
2994 ellidentify"(E)"
2996 look up the elliptic curve "E" (over Z) in the "elldata" database and
2997 return "[[N, M, G], C]" where "N" is the name of the curve in J. E.
2998 Cremona database, "M" the minimal model, "G" a Z-basis of the free part
2999 of the Mordell-Weil group of "E" and "C" the coordinates change (see
3000 "ellchangecurve").
3001 The library syntax is ellidentify"(E)".
3003 ellinit"(E,{flag = 0})"
3005 initialize an "ell" structure, associated to the elliptic curve "E".
3006 "E" is a 5-component vector "[a_1,a_2,a_3,a_4,a_6]" defining the
3007 elliptic curve with Weierstrass equation
3008 " Y^2 + a_1 XY + a_3 Y = X^3 + a_2 X^2 + a_4 X + a_6 "
3010 or a string, in this case the coefficients of the curve with matching
3012 name are looked in the "elldata" database if available. For the time
3013 being, only curves over a prime field "F_p" and over the "p"-adic or
3014 real numbers (including rational numbers) are fully supported. Other
3015 domains are only supported for very basic operations such as point
3016 addition.
3017 The result of "ellinit" is a an ell structure by default, and a shorted
3019 sell if "flag = 1". Both contain the following information in their
3020 components:
3021 " a_1,a_2,a_3,a_4,a_6,b_2,b_4,b_6,b_8,c_4,c_6,Delta,j."
3023 All are accessible via member functions. In particular, the
3025 discriminant is "E.disc", and the "j"-invariant is "E.j".
3026 The other six components are only present if "flag" is 0 or omitted.
3028 Their content depends on whether the curve is defined over R or not:
3029 \item When "E" is defined over R, "E.roots" is a vector whose three
3031 components contain the roots of the right hand side of the associated
3032 Weierstrass equation.
3033 " (y + a_1x/2 + a_3/2)^2 = g(x) "
3035 If the roots are all real, then they are ordered by decreasing value.
3037 If only one is real, it is the first component.
3038 Then "omega_1 = ""E.omega[1]" is the real period of "E" (integral of
3040 "dx/(2y+a_1x+a_3)" over the connected component of the identity element
3041 of the real points of the curve), and "omega_2 = ""E.omega[2]" is a
3042 complex period. In other words, "E.omega" forms a basis of the complex
3043 lattice defining "E", with "tau = (omega_2)/(omega_1)" having positive
3044 imaginary part.
3045 "E.eta" is a row vector containing the corresponding values "eta_1" and
3047 "eta_2" such that "eta_1omega_2-eta_2omega_1 = iPi".
3048 Finally, "E.area" is the volume of the complex lattice defining "E".
3050 \item When "E" is defined over "Q_p", the "p"-adic valuation of "j"
3052 must be negative. Then "E.roots" is the vector with a single component
3053 equal to the "p"-adic root of the associated Weierstrass equation
3054 corresponding to "-1" under the Tate parametrization.
3055 "E.tate" yields the three-component vector "[u^2,u,q]", in the
3057 notations of Tate. If the "u"-component does not belong to "Q_p", it is
3058 set to zero.
3059 "E.w" is Mestre's "w" (this is technical).
3061 For all other base fields or rings, the last six components are
3063 arbitrarily set equal to zero. See also the description of member
3064 functions related to elliptic curves at the beginning of this section.
3065 The library syntax is ellinit0"(E,flag,prec)". Also available are "
3067 initell(E,prec)" ("flag = 0") and " smallinitell(E,prec)" ("flag = 1").
3068 ellisoncurve"(E,z)"
3070 gives 1 (i.e. true) if the point "z" is on the elliptic curve "E", 0
3071 otherwise. If "E" or "z" have imprecise coefficients, an attempt is
3072 made to take this into account, i.e. an imprecise equality is checked,
3073 not a precise one. It is allowed for "z" to be a vector of points in
3074 which case a vector (of the same type) is returned.
3075 The library syntax is ellisoncurve"(E,z)". Also available is "
3077 oncurve(E,z)" which returns a "long" but does not accept vector of
3078 points.
3079 ellj"(x)"
3081 elliptic "j"-invariant. "x" must be a complex number with positive
3082 imaginary part, or convertible into a power series or a "p"-adic number
3083 with positive valuation.
3084 The library syntax is jell"(x,prec)".
3086 elllocalred"(E,p)"
3088 calculates the Kodaira type of the local fiber of the elliptic curve
3089 "E" at the prime "p". "E" must be an sell as output by "ellinit", and
3090 is assumed to have all its coefficients "a_i" in Z. The result is a
3091 4-component vector "[f,kod,v,c]". Here "f" is the exponent of "p" in
3092 the arithmetic conductor of "E", and "kod" is the Kodaira type which is
3093 coded as follows:
3094 1 means good reduction (type I"_0"), 2, 3 and 4 mean types II, III and
3096 IV respectively, "4+nu" with "nu > 0" means type I"_nu"; finally the
3097 opposite values "-1", "-2", etc. refer to the starred types I"_0^*",
3098 II"^*", etc. The third component "v" is itself a vector "[u,r,s,t]"
3099 giving the coordinate changes done during the local reduction.
3100 Normally, this has no use if "u" is 1, that is, if the given equation
3101 was already minimal. Finally, the last component "c" is the local
3102 Tamagawa number "c_p".
3103 The library syntax is elllocalred"(E,p)".
3105 elllseries"(E,s,{A = 1})"
3107 "E" being an sell as output by "ellinit", this computes the value of
3108 the L-series of "E" at "s". It is assumed that "E" is defined over Q,
3109 not necessarily minimal. The optional parameter "A" is a cutoff point
3110 for the integral, which must be chosen close to 1 for best speed. The
3111 result must be independent of "A", so this allows some internal
3112 checking of the function.
3113 Note that if the conductor of the curve is large, say greater than
3115 "10^{12}", this function will take an unreasonable amount of time since
3116 it uses an "O(N^{1/2})" algorithm.
3117 The library syntax is elllseries"(E,s,A,prec)" where "prec" is a "long"
3119 and an omitted "A" is coded as "NULL".
3120 ellminimalmodel"(E,{&v})"
3122 return the standard minimal integral model of the rational elliptic
3123 curve "E". If present, sets "v" to the corresponding change of
3124 variables, which is a vector "[u,r,s,t]" with rational components. The
3125 return value is identical to that of "ellchangecurve(E, v)".
3126 The resulting model has integral coefficients, is everywhere minimal,
3128 "a_1" is 0 or 1, "a_2" is 0, 1 or "-1" and "a_3" is 0 or 1. Such a
3129 model is unique, and the vector "v" is unique if we specify that "u" is
3130 positive, which we do.
3131 The library syntax is ellminimalmodel"(E,&v)", where an omitted "v" is
3133 coded as "NULL".
3134 ellorder"(E,z)"
3136 gives the order of the point "z" on the elliptic curve "E" if it is a
3137 torsion point, zero otherwise. In the present version
3138 /usr/share/libpari23, this is implemented only for elliptic curves
3139 defined over Q.
3140 The library syntax is orderell"(E,z)".
3142 ellordinate"(E,x)"
3144 gives a 0, 1 or 2-component vector containing the "y"-coordinates of
3145 the points of the curve "E" having "x" as "x"-coordinate.
3146 The library syntax is ordell"(E,x)".
3148 ellpointtoz"(E,z)"
3150 if "E" is an elliptic curve with coefficients in R, this computes a
3151 complex number "t" (modulo the lattice defining "E") corresponding to
3152 the point "z", i.e. such that, in the standard Weierstrass model, " wp
3153 (t) = z[1], wp '(t) = z[2]". In other words, this is the inverse
3154 function of "ellztopoint". More precisely, if "(w1,w2)" are the real
3155 and complex periods of "E", "t" is such that "0 <= Re (t) < w1" and "0
3156 <= Im (t) < Im (w2)".
3157 If "E" has coefficients in "Q_p", then either Tate's "u" is in "Q_p",
3159 in which case the output is a "p"-adic number "t" corresponding to the
3160 point "z" under the Tate parametrization, or only its square is, in
3161 which case the output is "t+1/t". "E" must be an ell as output by
3162 "ellinit".
3163 The library syntax is zell"(E,z,prec)".
3165 ellpow"(E,z,n)"
3167 computes "n" times the point "z" for the group law on the elliptic
3168 curve "E". Here, "n" can be in Z, or "n" can be a complex quadratic
3169 integer if the curve "E" has complex multiplication by "n" (if not, an
3170 error message is issued).
3171 The library syntax is powell"(E,z,n)".
3173 ellrootno"(E,{p = 1})"
3175 "E" being an sell as output by "ellinit", this computes the local (if
3176 "p ! = 1") or global (if "p = 1") root number of the L-series of the
3177 elliptic curve "E". Note that the global root number is the sign of the
3178 functional equation and conjecturally is the parity of the rank of the
3179 Mordell-Weil group. The equation for "E" must have coefficients in Q
3180 but need \emph{not} be minimal.
3181 The library syntax is ellrootno"(E,p)" and the result (equal to "+-1")
3183 is a "long".
3184 ellsigma"(E,z,{flag = 0})"
3186 value of the Weierstrass "sigma" function of the lattice associated to
3187 "E" as given by "ellinit" (alternatively, "E" can be given as a lattice
3188 "[omega_1,omega_2]").
3189 If "flag = 1", computes an (arbitrary) determination of " log
3191 (sigma(z))".
3192 If "flag = 2,3", same using the product expansion instead of theta
3194 series. The library syntax is ellsigma"(E,z,flag)"
3195 ellsearch"(N)"
3197 if "N" is an integer, it is taken as a conductor else if "N" is a
3198 string, it can be a curve name ("11a1"), a isogeny class ("11a") or a
3199 conductor "11". This function finds all curves in the "elldata"
3200 database with the given property.
3201 If "N" is a full curve name, the output format is "[N,
3203 [a_1,a_2,a_3,a_4,a_6], G]" where "[a_1,a_2,a_3,a_4,a_6]" are the
3204 coefficients of the Weierstrass equation of the curve and "G" is a
3205 Z-basis of the free part of the Mordell-Weil group associated to the
3206 curve.
3207 If "N" is not a full-curve name, the output is the list (as a vector)
3209 of all matching curves in the above format.
3210 The library syntax is ellsearch"(N)". Also available is "
3212 ellsearchcurve(N)" that only accept complete curve names.
3213 ellsub"(E,z1,z2)"
3215 difference of the points "z1" and "z2" on the elliptic curve
3216 corresponding to "E".
3217 The library syntax is subell"(E,z1,z2)".
3219 elltaniyama"(E)"
3221 computes the modular parametrization of the elliptic curve "E", where
3222 "E" is an sell as output by "ellinit", in the form of a two-component
3223 vector "[u,v]" of power series, given to the current default series
3224 precision. This vector is characterized by the following two
3225 properties. First the point "(x,y) = (u,v)" satisfies the equation of
3226 the elliptic curve. Second, the differential "du/(2v+a_1u+a_3)" is
3227 equal to "f(z)dz", a differential form on "H/Gamma_0(N)" where "N" is
3228 the conductor of the curve. The variable used in the power series for
3229 "u" and "v" is "x", which is implicitly understood to be equal to " exp
3230 (2iPi z)". It is assumed that the curve is a \emph{strong} Weil curve,
3231 and that the Manin constant is equal to 1. The equation of the curve
3232 "E" must be minimal (use "ellminimalmodel" to get a minimal equation).
3233 The library syntax is elltaniyama"(E, prec)", and the precision of the
3235 result is determined by "prec".
3236 elltors"(E,{flag = 0})"
3238 if "E" is an elliptic curve \emph{defined over Q}, outputs the torsion
3239 subgroup of "E" as a 3-component vector "[t,v1,v2]", where "t" is the
3240 order of the torsion group, "v1" gives the structure of the torsion
3241 group as a product of cyclic groups (sorted by decreasing order), and
3242 "v2" gives generators for these cyclic groups. "E" must be an ell as
3243 output by "ellinit".
3244 ? E = ellinit([0,0,0,-1,0]);
3246 ? elltors(E)
3247 %1 = [4, [2, 2], [[0, 0], [1, 0]]]
3248 Here, the torsion subgroup is isomorphic to "Z/2Z x Z/2Z", with
3250 generators "[0,0]" and "[1,0]".
3251 If "flag = 0", use Doud's algorithm: bound torsion by computing
3253 "#E(F_p)" for small primes of good reduction, then look for torsion
3254 points using Weierstrass parametrization (and Mazur's classification).
3255 If "flag = 1", use Lutz-Nagell (\emph{much} slower), "E" is allowed to
3257 be an sell.
3258 The library syntax is elltors0"(E,flag)".
3260 ellwp"(E,{z = x},{flag = 0})"
3262 Computes the value at "z" of the Weierstrass " wp " function attached
3263 to the elliptic curve "E" as given by "ellinit" (alternatively, "E" can
3264 be given as a lattice "[omega_1,omega_2]").
3265 If "z" is omitted or is a simple variable, computes the \emph{power
3267 series} expansion in "z" (starting "z^{-2}+O(z^2)"). The number of
3268 terms to an \emph{even} power in the expansion is the default
3269 serieslength in "gp", and the second argument (C long integer) in
3270 library mode.
3271 Optional flag is (for now) only taken into account when "z" is numeric,
3273 and means 0: compute only " wp (z)", 1: compute "[ wp (z), wp '(z)]".
3274 The library syntax is ellwp0"(E,z,flag,prec,precdl)". Also available is
3276 " weipell(E,precdl)" for the power series.
3277 ellzeta"(E,z)"
3279 value of the Weierstrass "zeta" function of the lattice associated to
3280 "E" as given by "ellinit" (alternatively, "E" can be given as a lattice
3281 "[omega_1,omega_2]").
3282 The library syntax is ellzeta"(E,z)".
3284 ellztopoint"(E,z)"
3286 "E" being an ell as output by "ellinit", computes the coordinates
3287 "[x,y]" on the curve "E" corresponding to the complex number "z". Hence
3288 this is the inverse function of "ellpointtoz". In other words, if the
3289 curve is put in Weierstrass form, "[x,y]" represents the Weierstrass "
3290 wp "-function and its derivative. If "z" is in the lattice defining "E"
3291 over C, the result is the point at infinity "[0]".
3292 The library syntax is pointell"(E,z,prec)".
3294
3296 In this section can be found functions which are used almost
3297 exclusively for working in general number fields. Other less specific
3298 functions can be found in the next section on polynomials. Functions
3299 related to quadratic number fields are found in section "Label
3300 se:arithmetic" (Arithmetic functions).
3301 Number field structures
3303 Let "K = Q[X] / (T)" a number field, "Z_K" its ring of integers, "T
3304 belongs to Z[X]" is monic. Three basic number field structures can be
3305 associated to "K" in GP:
3306 \item "nf" denotes a number field, i.e. a data structure output by
3308 "nfinit". This contains the basic arithmetic data associated to the
3309 number field: signature, maximal order (given by a basis "nf.zk"),
3310 discriminant, defining polynomial "T", etc.
3311 \item "bnf" denotes a ``Buchmann's number field'', i.e. a data
3313 structure output by "bnfinit". This contains "nf" and the deeper
3314 invariants of the field: units U(K), class group "\Cl(K)", as well as
3315 technical data required to solve the two associated discrete logarithm
3316 problems.
3317 \item "bnr" denotes a ``ray number field'', i.e. a data structure
3319 output by "bnrinit", corresponding to the ray class group structure of
3320 the field, for some modulus "f". It contains a bnf, the modulus "f",
3321 the ray class group "\Cl_f(K)" and data associated to the discrete
3322 logarithm problem therein.
3323 Algebraic numbers and ideals
3325 An algebraic number belonging to "K = Q[X]/(T)" is given as
3326 \item a "t_INT", "t_FRAC" or "t_POL" (implicitly modulo "T"), or
3328 \item a "t_POLMOD" (modulo "T"), or
3330 \item a "t_COL" "v" of dimension "N = [K:Q]", representing the element
3332 in terms of the computed integral basis, as "sum(i = 1, N, v[i] *
3333 nf.zk[i])". Note that a "t_VEC" will not be recognized.
3334 An ideal is given in any of the following ways:
3336 \item an algebraic number in one of the above forms, defining a
3338 principal ideal.
3339 \item a prime ideal, i.e. a 5-component vector in the format output by
3341 "idealprimedec".
3342 \item a "t_MAT", square and in Hermite Normal Form (or at least upper
3344 triangular with non-negative coefficients), whose columns represent a
3345 basis of the ideal.
3346 One may use "idealhnf" to convert an ideal to the last (preferred)
3348 format.
3349 Note. Some routines accept non-square matrices, but using this format
3351 is strongly discouraged. Nevertheless, their behaviour is as follows:
3352 If strictly less than "N = [K:Q]" generators are given, it is assumed
3353 they form a "Z_K"-basis. If "N" or more are given, a Z-basis is
3354 assumed. If exactly "N" are given, it is further assumed the matrix is
3355 in HNF. If any of these assumptions is not correct the behaviour of the
3356 routine is undefined.
3357 \item an idele is a 2-component vector, the first being an ideal as
3359 above, the second being a "R_1+R_2"-component row vector giving
3360 Archimedean information, as complex numbers.
3361 Finite abelian groups
3363 A finite abelian group "G" in user-readable format is given by its
3364 Smith Normal Form as a pair "[h,d]" or triple "[h,d,g]". Here "h" is
3365 the cardinality of "G", "(d_i)" is the vector of elementary divisors,
3366 and "(g_i)" is a vector of generators. In short, "G = oplus _{i <= n}
3367 (Z/d_iZ) g_i", with "d_n | ... | d_2 | d_1" and "prod d_i = h". This
3368 information can also be retrieved as "G.no", "G.cyc" and "G.gen".
3369 \item a character on the abelian group " oplus (Z/d_iZ) g_i" is given
3371 by a row vector "chi = [a_1,...,a_n]" such that "chi(prod g_i^{n_i}) =
3372 exp (2iPisum a_i n_i / d_i)".
3373 \item given such a structure, a subgroup "H" is input as a square
3375 matrix, whose column express generators of "H" on the given generators
3376 "g_i". Note that the absolute value of the determinant of that matrix
3377 is equal to the index "(G:H)".
3378 Relative extensions
3380 When defining a relative extension, the base field "nf" must be defined
3381 by a variable having a lower priority (see "Label se:priority") than
3382 the variable defining the extension. For example, you may use the
3383 variable name "y" to define the base field, and "x" to define the
3384 relative extension.
3385 \item "rnf" denotes a relative number field, i.e. a data structure
3387 output by "rnfinit".
3388 \item A \emph{relative matrix} is a matrix whose entries are elements
3390 of a (fixed) number field "nf", always expressed as column vectors on
3391 the integral basis "nf.zk". Hence it is a matrix of vectors.
3392 \item An ideal list is a row vector of (fractional) ideals of the
3394 number field "nf".
3395 \item A pseudo-matrix is a pair "(A,I)" where "A" is a relative matrix
3397 and "I" an ideal list whose length is the same as the number of columns
3398 of "A". This pair is represented by a 2-component row vector.
3399 \item The projective module generated by a pseudo-matrix "(A,I)" is the
3401 sum "sum_i {a}_j A_j" where the "{a}_j" are the ideals of "I" and "A_j"
3402 is the "j"-th column of "A".
3403 \item A pseudo-matrix "(A,I)" is a pseudo-basis of the module it
3405 generates if "A" is a square matrix with non-zero determinant and all
3406 the ideals of "I" are non-zero. We say that it is in Hermite Normal
3407 Form (HNF) if it is upper triangular and all the elements of the
3408 diagonal are equal to 1.
3409 \item The \emph{determinant} of a pseudo-basis "(A,I)" is the ideal
3411 equal to the product of the determinant of "A" by all the ideals of
3412 "I". The determinant of a pseudo-matrix is the determinant of any
3413 pseudo-basis of the module it generates.
3414 Class field theory
3416 A "modulus", in the sense of class field theory, is a divisor supported
3417 on the non-complex places of "K". In PARI terms, this means either an
3418 ordinary ideal "I" as above (no archimedean component), or a pair
3419 "[I,a]", where "a" is a vector with "r_1" "{0,1}"-components,
3420 corresponding to the infinite part of the divisor. More precisely, the
3421 "i"-th component of "a" corresponds to the real embedding associated to
3422 the "i"-th real root of "K.roots". (That ordering is not canonical, but
3423 well defined once a defining polynomial for "K" is chosen.) For
3424 instance, "[1, [1,1]]" is a modulus for a real quadratic field,
3425 allowing ramification at any of the two places at infinity.
3426 A bid or ``big ideal'' is a structure output by "idealstar" needed to
3428 compute in "(Z_K/I)^*", where "I" is a modulus in the above sense. If
3429 is a finite abelian group as described above, supplemented by technical
3430 data needed to solve discrete log problems.
3431 Finally we explain how to input ray number fields (or bnr), using class
3433 field theory. These are defined by a triple "a1", "a2", "a3", where the
3434 defining set "[a1,a2,a3]" can have any of the following forms: "[bnr]",
3435 "[bnr,subgroup]", "[bnf,module]", "[bnf,module,subgroup]".
3436 \item "bnf" is as output by "bnfinit", where units are mandatory unless
3438 the modulus is trivial; bnr is as output by "bnrinit". This is the
3439 ground field "K".
3440 \item \emph{module} is a modulus "\goth{f}", as described above.
3442 \item \emph{subgroup} a subgroup of the ray class group modulo
3444 "\goth{f}" of "K". As described above, this is input as a square matrix
3445 expressing generators of a subgroup of the ray class group "bnr.clgp"
3446 on the given generators.
3447 The corresponding bnr is the subfield of the ray class field of "K"
3449 modulo "\goth{f}", fixed by the given subgroup.
3450 General use
3452 All the functions which are specific to relative extensions, number
3453 fields, Buchmann's number fields, Buchmann's number rays, share the
3454 prefix "rnf", "nf", "bnf", "bnr" respectively. They take as first
3455 argument a number field of that precise type, respectively output by
3456 "rnfinit", "nfinit", "bnfinit", and "bnrinit".
3457 However, and even though it may not be specified in the descriptions of
3459 the functions below, it is permissible, if the function expects a "nf",
3460 to use a "bnf" instead, which contains much more information. On the
3461 other hand, if the function requires a "bnf", it will \emph{not} launch
3462 "bnfinit" for you, which is a costly operation. Instead, it will give
3463 you a specific error message. In short, the types
3464 " nf <= bnf <= bnr"
3466 are ordered, each function requires a minimal type to work properly,
3468 but you may always substitute a larger type.
3469 The data types corresponding to the structures described above are
3471 rather complicated. Thus, as we already have seen it with elliptic
3472 curves, GP provides ``member functions'' to retrieve data from these
3473 structures (once they have been initialized of course). The relevant
3474 types of number fields are indicated between parentheses:
3475 "bid" (bnr, ) : bid ideal structure.
3477 "bnf" (bnr, bnf ) : Buchmann's number field.
3479 "clgp" (bnr, bnf ) : classgroup. This one admits the following
3481 three subclasses:
3482 "cyc" : cyclic decomposition (SNF).
3484 "gen" : generators.
3486 "no" : number of elements.
3488 "diff" (bnr, bnf, nf ) : the different ideal.
3490 "codiff" (bnr, bnf, nf ) : the codifferent (inverse of the
3492 different in the ideal group).
3493 "disc" (bnr, bnf, nf ) : discriminant.
3495 "fu" (bnr, bnf, nf ) : fundamental units.
3497 "index" (bnr, bnf, nf ) : index of the power order in the ring of
3499 integers.
3500 "nf" (bnr, bnf, nf ) : number field.
3502 "r1" (bnr, bnf, nf ) : the number of real embeddings.
3504 "r2" (bnr, bnf, nf ) : the number of pairs of complex embeddings.
3506 "reg" (bnr, bnf, ) : regulator.
3508 "roots" (bnr, bnf, nf ) : roots of the polynomial generating the
3510 field.
3511 "t2" (bnr, bnf, nf ) : the T2 matrix (see "nfinit").
3513 "tu" (bnr, bnf, ) : a generator for the torsion units.
3515 "tufu" (bnr, bnf, ) : "[w,u_1,...,u_r]", "(u_i)" is a vector of
3517 fundamental units, "w" generates the torsion units.
3518 "zk" (bnr, bnf, nf ) : integral basis, i.e. a Z-basis of the
3520 maximal order.
3521 For instance, assume that "bnf = bnfinit(pol)", for some polynomial.
3523 Then "bnf.clgp" retrieves the class group, and "bnf.clgp.no" the class
3524 number. If we had set "bnf = nfinit(pol)", both would have output an
3525 error message. All these functions are completely recursive, thus for
3526 instance "bnr.bnf.nf.zk" will yield the maximal order of bnr, which you
3527 could get directly with a simple "bnr.zk".
3528 Class group, units, and the GRH
3530 Some of the functions starting with "bnf" are implementations of the
3531 sub-exponential algorithms for finding class and unit groups under GRH,
3532 due to Hafner-McCurley, Buchmann and Cohen-Diaz-Olivier. The general
3533 call to the functions concerning class groups of general number fields
3534 (i.e. excluding "quadclassunit") involves a polynomial "P" and a
3535 technical vector
3536 "tech = [c, c2, nrpid ],"
3538 where the parameters are to be understood as follows:
3540 "P" is the defining polynomial for the number field, which must be in
3542 "Z[X]", irreducible and monic. In fact, if you supply a non-monic
3543 polynomial at this point, "gp" issues a warning, then \emph{transforms
3544 your polynomial} so that it becomes monic. The "nfinit" routine will
3545 return a different result in this case: instead of "res", you get a
3546 vector "[res,Mod(a,Q)]", where "Mod(a,Q) = Mod(X,P)" gives the change
3547 of variables. In all other routines, the variable change is simply
3548 lost.
3549 The numbers "c <= c_2" are positive real numbers which control the
3551 execution time and the stack size. For a given "c", set "c_2 = c" to
3552 get maximum speed. To get a rigorous result under GRH you must take "c2
3553 >= 12" (or "c2 >= 6" in "P" is quadratic). Reasonable values for "c"
3554 are between 0.1 and 2. The default is "c = c_2 = 0.3".
3555 "nrpid" is the maximal number of small norm relations associated to
3557 each ideal in the factor base. Set it to 0 to disable the search for
3558 small norm relations. Otherwise, reasonable values are between 4 and
3559 20. The default is 4.
3560 Warning. Make sure you understand the above! By default, most of the
3562 "bnf" routines depend on the correctness of a heuristic assumption
3563 which is stronger than the GRH. In particular, any of the class number,
3564 class group structure, class group generators, regulator and
3565 fundamental units may be wrong, independently of each other. Any result
3566 computed from such a "bnf" may be wrong. The only guarantee is that the
3567 units given generate a subgroup of finite index in the full unit group.
3568 In practice, very few counter-examples are known, requiring unlucky
3569 random seeds. No counter-example has been reported for "c_2 = 0.5"
3570 (which should be almost as fast as "c_2 = 0.3", and shall very probably
3571 become the default). If you use "c_2 = 12", then everything is correct
3572 assuming the GRH holds. You can use "bnfcertify" to certify the
3573 computations unconditionally.
3574 Remarks.
3576 Apart from the polynomial "P", you do not need to supply the technical
3578 parameters (under the library you still need to send at least an empty
3579 vector, coded as "NULL"). However, should you choose to set some of
3580 them, they \emph{must} be given in the requested order. For example, if
3581 you want to specify a given value of nrpid, you must give some values
3582 as well for "c" and "c_2", and provide a vector "[c,c_2,nrpid]".
3583 Note also that you can use an "nf" instead of "P", which avoids
3585 recomputing the integral basis and analogous quantities.
3586 bnfcertify"(bnf)"
3588 "bnf" being as output by "bnfinit", checks whether the result is
3589 correct, i.e. whether it is possible to remove the assumption of the
3590 Generalized Riemann Hypothesis. It is correct if and only if the answer
3591 is 1. If it is incorrect, the program may output some error message, or
3592 loop indefinitely. You can check its progress by increasing the debug
3593 level.
3594 The library syntax is certifybuchall"(bnf)", and the result is a C
3596 long.
3597 bnfclassunit"(P,{flag = 0},{tech = []})"
3599 \emph{this function is DEPRECATED, use "bnfinit"}.
3600 Buchmann's sub-exponential algorithm for computing the class group, the
3602 regulator and a system of fundamental units of the general algebraic
3603 number field "K" defined by the irreducible polynomial "P" with integer
3604 coefficients.
3605 The result of this function is a vector "v" with many components, which
3607 for ease of presentation is in fact output as a one column matrix. It
3608 is \emph{not} a "bnf", you need "bnfinit" for that. First we describe
3609 the default behaviour ("flag = 0"):
3610 "v[1]" is equal to the polynomial "P".
3612 "v[2]" is the 2-component vector "[r1,r2]", where "r1" and "r2" are as
3614 usual the number of real and half the number of complex embeddings of
3615 the number field "K".
3616 "v[3]" is the 2-component vector containing the field discriminant and
3618 the index.
3619 "v[4]" is an integral basis in Hermite normal form.
3621 "v[5]" ("v.clgp") is a 3-component vector containing the class number
3623 ("v.clgp.no"), the structure of the class group as a product of cyclic
3624 groups of order "n_i" ("v.clgp.cyc"), and the corresponding generators
3625 of the class group of respective orders "n_i" ("v.clgp.gen").
3626 "v[6]" ("v.reg") is the regulator computed to an accuracy which is the
3628 maximum of an internally determined accuracy and of the default.
3629 "v[7]" is deprecated, maintained for backward compatibility and always
3631 equal to 1.
3632 "v[8]" ("v.tu") a vector with 2 components, the first being the number
3634 "w" of roots of unity in "K" and the second a primitive "w"-th root of
3635 unity expressed as a polynomial.
3636 "v[9]" ("v.fu") is a system of fundamental units also expressed as
3638 polynomials.
3639 If "flag = 1", and the precision happens to be insufficient for
3641 obtaining the fundamental units, the internal precision is doubled and
3642 the computation redone, until the exact results are obtained. Be warned
3643 that this can take a very long time when the coefficients of the
3644 fundamental units on the integral basis are very large, for example in
3645 large real quadratic fields. For this case, there are alternate
3646 compact representations for algebraic numbers, implemented in PARI but
3647 currently not available in GP.
3648 If "flag = 2", the fundamental units and roots of unity are not
3650 computed. Hence the result has only 7 components, the first seven
3651 ones.
3652 The library syntax is bnfclassunit0"(P,flag,tech,prec)".
3654 bnfclgp"(P,{tech = []})"
3656 as "bnfinit", but only outputs "bnf.clgp", i.e. the class group.
3657 The library syntax is classgrouponly"(P,tech,prec)", where tech is as
3659 described under "bnfinit".
3660 bnfdecodemodule"(nf,m)"
3662 if "m" is a module as output in the first component of an extension
3663 given by "bnrdisclist", outputs the true module.
3664 The library syntax is decodemodule"(nf,m)".
3666 bnfinit"(P,{flag = 0},{tech = []})"
3668 initializes a bnf structure. Used in programs such as "bnfisprincipal",
3669 "bnfisunit" or "bnfnarrow". By default, the results are conditional on
3670 a heuristic strengthening of the GRH, see se:GRHbnf. The result is a
3671 10-component vector bnf.
3672 This implements Buchmann's sub-exponential algorithm for computing the
3674 class group, the regulator and a system of fundamental units of the
3675 general algebraic number field "K" defined by the irreducible
3676 polynomial "P" with integer coefficients.
3677 If the precision becomes insufficient, "gp" outputs a warning
3679 ("fundamental units too large, not given") and does not strive to
3680 compute the units by default ("flag = 0").
3681 When "flag = 1", we insist on finding the fundamental units exactly. Be
3683 warned that this can take a very long time when the coefficients of the
3684 fundamental units on the integral basis are very large. If the
3685 fundamental units are simply too large to be represented in this form,
3686 an error message is issued. They could be obtained using the so-called
3687 compact representation of algebraic numbers as a formal product of
3688 algebraic integers. The latter is implemented internally but not
3689 publicly accessible yet.
3690 When "flag = 2", on the contrary, it is initially agreed that units are
3692 not computed. Note that the resulting bnf will not be suitable for
3693 "bnrinit", and that this flag provides negligible time savings compared
3694 to the default. In short, it is deprecated.
3695 When "flag = 3", computes a very small version of "bnfinit", a ``small
3697 Buchmann's number field'' (or sbnf for short) which contains enough
3698 information to recover the full "bnf" vector very rapidly, but which is
3699 much smaller and hence easy to store and print. It is supposed to be
3700 used in conjunction with "bnfmake".
3701 "tech" is a technical vector (empty by default, see se:GRHbnf).
3703 Careful use of this parameter may speed up your computations
3704 considerably.
3705 The components of a bnf or sbnf are technical and never used by the
3707 casual user. In fact: \emph{never access a component directly, always
3708 use a proper member function.} However, for the sake of completeness
3709 and internal documentation, their description is as follows. We use the
3710 notations explained in the book by H. Cohen, \emph{A Course in
3711 Computational Algebraic Number Theory}, Graduate Texts in Maths 138,
3712 Springer-Verlag, 1993, Section 6.5, and subsection 6.5.5 in particular.
3713 "bnf[1]" contains the matrix "W", i.e. the matrix in Hermite normal
3715 form giving relations for the class group on prime ideal generators "(
3716 wp _i)_{1 <= i <= r}".
3717 "bnf[2]" contains the matrix "B", i.e. the matrix containing the
3719 expressions of the prime ideal factorbase in terms of the " wp _i". It
3720 is an "r x c" matrix.
3721 "bnf[3]" contains the complex logarithmic embeddings of the system of
3723 fundamental units which has been found. It is an "(r_1+r_2) x
3724 (r_1+r_2-1)" matrix.
3725 "bnf[4]" contains the matrix "M''_C" of Archimedean components of the
3727 relations of the matrix "(W|B)".
3728 "bnf[5]" contains the prime factor base, i.e. the list of prime ideals
3730 used in finding the relations.
3731 "bnf[6]" used to contain a permutation of the prime factor base, but
3733 has been obsoleted. It contains a dummy 0.
3734 "bnf[7]" or "bnf.nf" is equal to the number field data "nf" as would be
3736 given by "nfinit".
3737 "bnf[8]" is a vector containing the classgroup "bnf.clgp" as a finite
3739 abelian group, the regulator "bnf.reg", a 1 (used to contain an
3740 obsolete ``check number''), the number of roots of unity and a
3741 generator "bnf.tu", the fundamental units "bnf.fu".
3742 "bnf[9]" is a 3-element row vector used in "bnfisprincipal" only and
3744 obtained as follows. Let "D = U W V" obtained by applying the Smith
3745 normal form algorithm to the matrix "W" ( = "bnf[1]") and let "U_r" be
3746 the reduction of "U" modulo "D". The first elements of the factorbase
3747 are given (in terms of "bnf.gen") by the columns of "U_r", with
3748 Archimedean component "g_a"; let also "GD_a" be the Archimedean
3749 components of the generators of the (principal) ideals defined by the
3750 "bnf.gen[i]^bnf.cyc[i]". Then "bnf[9] = [U_r, g_a, GD_a]".
3751 "bnf[10]" is by default unused and set equal to 0. This field is used
3753 to store further information about the field as it becomes available,
3754 which is rarely needed, hence would be too expensive to compute during
3755 the initial "bnfinit" call. For instance, the generators of the
3756 principal ideals "bnf.gen[i]^bnf.cyc[i]" (during a call to
3757 "bnrisprincipal"), or those corresponding to the relations in "W" and
3758 "B" (when the "bnf" internal precision needs to be increased).
3759 An sbnf is a 12 component vector "v", as follows. Let "bnf" be the
3761 result of a full "bnfinit", complete with units. Then "v[1]" is the
3762 polynomial "P", "v[2]" is the number of real embeddings "r_1", "v[3]"
3763 is the field discriminant, "v[4]" is the integral basis, "v[5]" is the
3764 list of roots as in the sixth component of "nfinit", "v[6]" is the
3765 matrix "MD" of "nfinit" giving a Z-basis of the different, "v[7]" is
3766 the matrix "W = bnf[1]", "v[8]" is the matrix "matalpha = bnf[2]",
3767 "v[9]" is the prime ideal factor base "bnf[5]" coded in a compact way,
3768 and ordered according to the permutation "bnf[6]", "v[10]" is the
3769 2-component vector giving the number of roots of unity and a generator,
3770 expressed on the integral basis, "v[11]" is the list of fundamental
3771 units, expressed on the integral basis, "v[12]" is a vector containing
3772 the algebraic numbers alpha corresponding to the columns of the matrix
3773 "matalpha", expressed on the integral basis.
3774 Note that all the components are exact (integral or rational), except
3776 for the roots in "v[5]". Note also that member functions will
3777 \emph{not} work on sbnf, you have to use "bnfmake" explicitly first.
3778 The library syntax is bnfinit0"(P,flag,tech,prec)".
3780 bnfisintnorm"(bnf,x)"
3782 computes a complete system of solutions (modulo units of positive norm)
3783 of the absolute norm equation "\Norm(a) = x", where "a" is an integer
3784 in "bnf". If "bnf" has not been certified, the correctness of the
3785 result depends on the validity of GRH.
3786 See also "bnfisnorm".
3788 The library syntax is bnfisintnorm"(bnf,x)".
3790 bnfisnorm"(bnf,x,{flag = 1})"
3792 tries to tell whether the rational number "x" is the norm of some
3793 element y in "bnf". Returns a vector "[a,b]" where "x = Norm(a)*b".
3794 Looks for a solution which is an "S"-unit, with "S" a certain set of
3795 prime ideals containing (among others) all primes dividing "x". If
3796 "bnf" is known to be Galois, set "flag = 0" (in this case, "x" is a
3797 norm iff "b = 1"). If "flag" is non zero the program adds to "S" the
3798 following prime ideals, depending on the sign of "flag". If "flag > 0",
3799 the ideals of norm less than "flag". And if "flag < 0" the ideals
3800 dividing "flag".
3801 Assuming GRH, the answer is guaranteed (i.e. "x" is a norm iff "b =
3803 1"), if "S" contains all primes less than "12 log (\disc(Bnf))^2",
3804 where "Bnf" is the Galois closure of "bnf".
3805 See also "bnfisintnorm".
3807 The library syntax is bnfisnorm"(bnf,x,flag,prec)", where "flag" and
3809 "prec" are "long"s.
3810 bnfissunit"(bnf,sfu,x)"
3812 "bnf" being output by "bnfinit", sfu by "bnfsunit", gives the column
3813 vector of exponents of "x" on the fundamental "S"-units and the roots
3814 of unity. If "x" is not a unit, outputs an empty vector.
3815 The library syntax is bnfissunit"(bnf,sfu,x)".
3817 bnfisprincipal"(bnf,x,{flag = 1})"
3819 "bnf" being the number field data output by "bnfinit", and "x" being
3820 either a Z-basis of an ideal in the number field (not necessarily in
3821 HNF) or a prime ideal in the format output by the function
3822 "idealprimedec", this function tests whether the ideal is principal or
3823 not. The result is more complete than a simple true/false answer: it
3824 gives a row vector "[v_1,v_2]", where
3825 "v_1" is the vector of components "c_i" of the class of the ideal "x"
3827 in the class group, expressed on the generators "g_i" given by
3828 "bnfinit" (specifically "bnf.gen"). The "c_i" are chosen so that "0 <=
3829 c_i < n_i" where "n_i" is the order of "g_i" (the vector of "n_i" being
3830 "bnf.cyc").
3831 "v_2" gives on the integral basis the components of "alpha" such that
3833 "x = alphaprod_ig_i^{c_i}". In particular, "x" is principal if and only
3834 if "v_1" is equal to the zero vector. In the latter case, "x =
3835 alphaZ_K" where "alpha" is given by "v_2". Note that if "alpha" is too
3836 large to be given, a warning message will be printed and "v_2" will be
3837 set equal to the empty vector.
3838 If "flag = 0", outputs only "v_1", which is much easier to compute.
3840 If "flag = 2", does as if "flag" were 0, but doubles the precision
3842 until a result is obtained.
3843 If "flag = 3", as in the default behaviour ("flag = 1"), but doubles
3845 the precision until a result is obtained.
3846 The user is warned that these two last setting may induce \emph{very}
3848 lengthy computations.
3849 The library syntax is isprincipalall"(bnf,x,flag)".
3851 bnfisunit"(bnf,x)"
3853 "bnf" being the number field data output by "bnfinit" and "x" being an
3854 algebraic number (type integer, rational or polmod), this outputs the
3855 decomposition of "x" on the fundamental units and the roots of unity if
3856 "x" is a unit, the empty vector otherwise. More precisely, if
3857 "u_1",...,"u_r" are the fundamental units, and "zeta" is the generator
3858 of the group of roots of unity ("bnf.tu"), the output is a vector
3859 "[x_1,...,x_r,x_{r+1}]" such that "x = u_1^{x_1}...
3860 u_r^{x_r}.zeta^{x_{r+1}}". The "x_i" are integers for "i <= r" and is
3861 an integer modulo the order of "zeta" for "i = r+1".
3862 The library syntax is isunit"(bnf,x)".
3864 bnfmake"(sbnf)"
3866 sbnf being a ``small "bnf"'' as output by "bnfinit""(x,3)", computes
3867 the complete "bnfinit" information. The result is \emph{not} identical
3868 to what "bnfinit" would yield, but is functionally identical. The
3869 execution time is very small compared to a complete "bnfinit". Note
3870 that if the default precision in "gp" (or "prec" in library mode) is
3871 greater than the precision of the roots "sbnf[5]", these are recomputed
3872 so as to get a result with greater accuracy.
3873 Note that the member functions are \emph{not} available for sbnf, you
3875 have to use "bnfmake" explicitly first.
3876 The library syntax is makebigbnf"(sbnf,prec)", where "prec" is a C long
3878 integer.
3879 bnfnarrow"(bnf)"
3881 "bnf" being as output by "bnfinit", computes the narrow class group of
3882 "bnf". The output is a 3-component row vector "v" analogous to the
3883 corresponding class group component "bnf.clgp" ("bnf[8][1]"): the first
3884 component is the narrow class number "v.no", the second component is a
3885 vector containing the SNF cyclic components "v.cyc" of the narrow class
3886 group, and the third is a vector giving the generators of the
3887 corresponding "v.gen" cyclic groups. Note that this function is a
3888 special case of "bnrinit".
3889 The library syntax is buchnarrow"(bnf)".
3891 bnfsignunit"(bnf)"
3893 "bnf" being as output by "bnfinit", this computes an "r_1 x
3894 (r_1+r_2-1)" matrix having "+-1" components, giving the signs of the
3895 real embeddings of the fundamental units. The following functions
3896 compute generators for the totally positive units:
3897 /* exponents of totally positive units generators on bnf.tufu */
3899 tpuexpo(bnf)=
3900 { local(S,d,K);
3901 S = bnfsignunit(bnf); d = matsize(S);
3903 S = matrix(d[1],d[2], i,j, if (S[i,j] < 0, 1,0));
3904 S = concat(vectorv(d[1],i,1), S); \\ add sign(-1)
3905 K = lift(matker(S * Mod(1,2)));
3906 if (K, mathnfmodid(K, 2), 2*matid(d[1]))
3907 }
3908 /* totally positive units */
3910 tpu(bnf)=
3911 { local(vu = bnf.tufu, ex = tpuexpo(bnf));
3912 vector(#ex-1, i, factorback(vu, ex[,i+1])) \\ ex[,1] is 1
3914 }
3915 The library syntax is signunits"(bnf)".
3917 bnfreg"(bnf)"
3919 "bnf" being as output by "bnfinit", computes its regulator.
3920 The library syntax is regulator"(bnf,tech,prec)", where tech is as in
3922 "bnfinit".
3923 bnfsunit"(bnf,S)"
3925 computes the fundamental "S"-units of the number field "bnf" (output by
3926 "bnfinit"), where "S" is a list of prime ideals (output by
3927 "idealprimedec"). The output is a vector "v" with 6 components.
3928 "v[1]" gives a minimal system of (integral) generators of the "S"-unit
3930 group modulo the unit group.
3931 "v[2]" contains technical data needed by "bnfissunit".
3933 "v[3]" is an empty vector (used to give the logarithmic embeddings of
3935 the generators in "v[1]" in version 2.0.16).
3936 "v[4]" is the "S"-regulator (this is the product of the regulator, the
3938 determinant of "v[2]" and the natural logarithms of the norms of the
3939 ideals in "S").
3940 "v[5]" gives the "S"-class group structure, in the usual format (a row
3942 vector whose three components give in order the "S"-class number, the
3943 cyclic components and the generators).
3944 "v[6]" is a copy of "S".
3946 The library syntax is bnfsunit"(bnf,S,prec)".
3948 bnfunit"(bnf)"
3950 "bnf" being as output by "bnfinit", outputs the vector of fundamental
3951 units of the number field.
3952 This function is mostly useless, since it will only succeed if bnf
3954 contains the units, in which case "bnf.fu" is recommanded instead, or
3955 bnf was produced with "bnfinit(,,2)", which is itself deprecated.
3956 The library syntax is buchfu"(bnf)".
3958 bnrL1"(bnr,{subgroup},{flag = 0})"
3960 bnr being the number field data which is output by "bnrinit(,,1)" and
3961 subgroup being a square matrix defining a congruence subgroup of the
3962 ray class group corresponding to bnr (the trivial congruence subgroup
3963 if omitted), returns for each character "chi" of the ray class group
3964 which is trivial on this subgroup, the value at "s = 1" (or "s = 0") of
3965 the abelian "L"-function associated to "chi". For the value at "s = 0",
3966 the function returns in fact for each character "chi" a vector "[r_chi
3967 , c_chi]" where "r_chi" is the order of "L(s, chi)" at "s = 0" and
3968 "c_chi" the first non-zero term in the expansion of "L(s, chi)" at "s =
3969 0"; in other words
3970 "L(s, chi) = c_chi.s^{r_chi} + O(s^{r_chi + 1})"
3972 near 0. flag is optional, default value is 0; its binary digits mean 1:
3974 compute at "s = 1" if set to 1 or "s = 0" if set to 0, 2: compute the
3975 primitive "L"-functions associated to "chi" if set to 0 or the
3976 "L"-function with Euler factors at prime ideals dividing the modulus of
3977 bnr removed if set to 1 (this is the so-called "L_S(s, chi)" function
3978 where "S" is the set of infinite places of the number field together
3979 with the finite prime ideals dividing the modulus of bnr, see the
3980 example below), 3: returns also the character. Example:
3981 bnf = bnfinit(x^2 - 229);
3983 bnr = bnrinit(bnf,1,1);
3984 bnrL1(bnr)
3985 returns the order and the first non-zero term of the abelian
3987 "L"-functions "L(s, chi)" at "s = 0" where "chi" runs through the
3988 characters of the class group of "Q( sqrt {229})". Then
3989 bnr2 = bnrinit(bnf,2,1);
3991 bnrL1(bnr2,,2)
3992 returns the order and the first non-zero terms of the abelian
3994 "L"-functions "L_S(s, chi)" at "s = 0" where "chi" runs through the
3995 characters of the class group of "Q( sqrt {229})" and "S" is the set of
3996 infinite places of "Q( sqrt {229})" together with the finite prime 2.
3997 Note that the ray class group modulo 2 is in fact the class group, so
3998 "bnrL1(bnr2,0)" returns exactly the same answer as "bnrL1(bnr,0)".
3999 The library syntax is bnrL1"(bnr,subgroup,flag,prec)", where an omitted
4001 subgroup is coded as "NULL".
4002 bnrclass"(bnf,ideal,{flag = 0})"
4004 \emph{this function is DEPRECATED, use "bnrinit"}.
4005 "bnf" being as output by "bnfinit" (the units are mandatory unless the
4007 ideal is trivial), and ideal being a modulus, computes the ray class
4008 group of the number field for the modulus ideal, as a finite abelian
4009 group.
4010 The library syntax is bnrclass0"(bnf,ideal,flag)".
4012 bnrclassno"(bnf,I)"
4014 "bnf" being as output by "bnfinit" (units are mandatory unless the
4015 ideal is trivial), and "I" being a modulus, computes the ray class
4016 number of the number field for the modulus "I". This is faster than
4017 "bnrinit" and should be used if only the ray class number is desired.
4018 See "bnrclassnolist" if you need ray class numbers for all moduli less
4019 than some bound.
4020 The library syntax is bnrclassno"(bnf,I)".
4022 bnrclassnolist"(bnf,list)"
4024 "bnf" being as output by "bnfinit", and list being a list of moduli
4025 (with units) as output by "ideallist" or "ideallistarch", outputs the
4026 list of the class numbers of the corresponding ray class groups. To
4027 compute a single class number, "bnrclassno" is more efficient.
4028 ? bnf = bnfinit(x^2 - 2);
4030 ? L = ideallist(bnf, 100, 2);
4031 ? H = bnrclassnolist(bnf, L);
4032 ? H[98]
4033 %4 = [1, 3, 1]
4034 ? l = L[1][98]; ids = vector(#l, i, l[i].mod[1])
4035 %5 = [[98, 88; 0, 1], [14, 0; 0, 7], [98, 10; 0, 1]]
4036 The weird "l[i].mod[1]", is the first component of "l[i].mod", i.e.
4038 the finite part of the conductor. (This is cosmetic: since by
4039 construction the archimedean part is trivial, I do not want to see it).
4040 This tells us that the ray class groups modulo the ideals of norm 98
4041 (printed as %5) have respectively order 1, 3 and 1. Indeed, we may
4042 check directly :
4043 ? bnrclassno(bnf, ids[2])
4045 %6 = 3
4046 The library syntax is bnrclassnolist"(bnf,list)".
4048 bnrconductor"(a_1,{a_2},{a_3}, {flag = 0})"
4050 conductor "f" of the subfield of a ray class field as defined by
4051 "[a_1,a_2,a_3]" (see "bnr" at the beginning of this section).
4052 If "flag = 0", returns "f".
4054 If "flag = 1", returns "[f, Cl_f, H]", where "Cl_f" is the ray class
4056 group modulo "f", as a finite abelian group; finally "H" is the
4057 subgroup of "Cl_f" defining the extension.
4058 If "flag = 2", returns "[f, bnr(f), H]", as above except "Cl_f" is
4060 replaced by a "bnr" structure, as output by "bnrinit(,f,1)".
4061 The library syntax is conductor"(bnr, subgroup, flag)", where an
4063 omitted subgroup (trivial subgroup, i.e. ray class field) is input as
4064 "NULL", and "flag" is a C long.
4065 bnrconductorofchar"(bnr,chi)"
4067 bnr being a big ray number field as output by "bnrinit", and chi being
4068 a row vector representing a character as expressed on the generators of
4069 the ray class group, gives the conductor of this character as a
4070 modulus.
4071 The library syntax is bnrconductorofchar"(bnr,chi)".
4073 bnrdisc"(a1,{a2},{a3},{flag = 0})"
4075 "a1", "a2", "a3" defining a big ray number field "L" over a ground
4076 field "K" (see "bnr" at the beginning of this section for the meaning
4077 of "a1", "a2", "a3"), outputs a 3-component row vector "[N,R_1,D]",
4078 where "N" is the (absolute) degree of "L", "R_1" the number of real
4079 places of "L", and "D" the discriminant of "L/Q", including sign (if
4080 "flag = 0").
4081 If "flag = 1", as above but outputs relative data. "N" is now the
4083 degree of "L/K", "R_1" is the number of real places of "K" unramified
4084 in "L" (so that the number of real places of "L" is equal to "R_1"
4085 times the relative degree "N"), and "D" is the relative discriminant
4086 ideal of "L/K".
4087 If "flag = 2", as the default case, except that if the modulus is not
4089 the exact conductor corresponding to the "L", no data is computed and
4090 the result is 0.
4091 If "flag = 3", as case 2, but output relative data.
4093 The library syntax is bnrdisc0"(a1,a2,a3,flag)".
4095 bnrdisclist"(bnf,bound,{arch})"
4097 "bnf" being as output by "bnfinit" (with units), computes a list of
4098 discriminants of Abelian extensions of the number field by increasing
4099 modulus norm up to bound bound. The ramified Archimedean places are
4100 given by arch; all possible values are taken if arch is omitted.
4101 The alternative syntax "bnrdisclist(bnf,list)" is supported, where list
4103 is as output by "ideallist" or "ideallistarch" (with units), in which
4104 case arch is disregarded.
4105 The output "v" is a vector of vectors, where "v[i][j]" is understood to
4107 be in fact "V[2^{15}(i-1)+j]" of a unique big vector "V". (This akward
4108 scheme allows for larger vectors than could be otherwise represented.)
4109 "V[k]" is itself a vector "W", whose length is the number of ideals of
4111 norm "k". We consider first the case where arch was specified. Each
4112 component of "W" corresponds to an ideal "m" of norm "k", and gives
4113 invariants associated to the ray class field "L" of "bnf" of conductor
4114 "[m, arch]". Namely, each contains a vector "[m,d,r,D]" with the
4115 following meaning: "m" is the prime ideal factorization of the modulus,
4116 "d = [L:Q]" is the absolute degree of "L", "r" is the number of real
4117 places of "L", and "D" is the factorization of its absolute
4118 discriminant. We set "d = r = D = 0" if "m" is not the finite part of a
4119 conductor.
4120 If arch was omitted, all "t = 2^{r_1}" possible values are taken and a
4122 component of "W" has the form "[m, [[d_1,r_1,D_1],...,
4123 [d_t,r_t,D_t]]]", where "m" is the finite part of the conductor as
4124 above, and "[d_i,r_i,D_i]" are the invariants of the ray class field of
4125 conductor "[m,v_i]", where "v_i" is the "i"-th archimedean component,
4126 ordered by inverse lexicographic order; so "v_1 = [0,...,0]", "v_2 =
4127 [1,0...,0]", etc. Again, we set "d_i = r_i = D_i = 0" if "[m,v_i]" is
4128 not a conductor.
4129 Finally, each prime ideal "pr = [p,alpha,e,f,beta]" in the prime
4131 factorization "m" is coded as the integer "p.n^2+(f-1).n+(j-1)", where
4132 "n" is the degree of the base field and "j" is such that
4133 "pr = idealprimedec(nf,p)[j]".
4135 "m" can be decoded using "bnfdecodemodule".
4137 Note that to compute such data for a single field, either "bnrclassno"
4139 or "bnrdisc" is more efficient.
4140 The library syntax is bnrdisclist0"(bnf,bound,arch)".
4142 bnrinit"(bnf,f,{flag = 0})"
4144 "bnf" is as output by "bnfinit", "f" is a modulus, initializes data
4145 linked to the ray class group structure corresponding to this module, a
4146 so-called bnr structure. The following member functions are available
4147 on the result: ".bnf" is the underlying bnf, ".mod" the modulus, ".bid"
4148 the bid structure associated to the modulus; finally, ".clgp", ".no",
4149 ".cyc", "clgp" refer to the ray class group (as a finite abelian
4150 group), its cardinality, its elementary divisors, its generators.
4151 The last group of functions are different from the members of the
4153 underlying bnf, which refer to the class group; use "bnr.bnf.xxx" to
4154 access these, e.g. "bnr.bnf.cyc" to get the cyclic decomposition of the
4155 class group.
4156 They are also different from the members of the underlying bid, which
4158 refer to "(\O_K/f)^*"; use "bnr.bid.xxx" to access these,
4159 e.g. "bnr.bid.no" to get "phi(f)".
4160 If "flag = 0" (default), the generators of the ray class group are not
4162 computed, which saves time. Hence "bnr.gen" would produce an error.
4163 If "flag = 1", as the default, except that generators are computed.
4165 The library syntax is bnrinit0"(bnf,f,flag)".
4167 bnrisconductor"(a1,{a2},{a3})"
4169 "a1", "a2", "a3" represent an extension of the base field, given by
4170 class field theory for some modulus encoded in the parameters. Outputs
4171 1 if this modulus is the conductor, and 0 otherwise. This is slightly
4172 faster than "bnrconductor".
4173 The library syntax is bnrisconductor"(a1,a2,a3)" and the result is a
4175 "long".
4176 bnrisprincipal"(bnr,x,{flag = 1})"
4178 bnr being the number field data which is output by "bnrinit""(,,1)" and
4179 "x" being an ideal in any form, outputs the components of "x" on the
4180 ray class group generators in a way similar to "bnfisprincipal". That
4181 is a 2-component vector "v" where "v[1]" is the vector of components of
4182 "x" on the ray class group generators, "v[2]" gives on the integral
4183 basis an element "alpha" such that "x = alphaprod_ig_i^{x_i}".
4184 If "flag = 0", outputs only "v_1". In that case, bnr need not contain
4186 the ray class group generators, i.e. it may be created with
4187 "bnrinit""(,,0)"
4188 The library syntax is bnrisprincipal"(bnr,x,flag)".
4190 bnrrootnumber"(bnr,chi,{flag = 0})"
4192 if "chi = chi" is a (not necessarily primitive) character over bnr, let
4193 "L(s,chi) = sum_{id} chi(id) N(id)^{-s}" be the associated Artin
4194 L-function. Returns the so-called Artin root number, i.e. the complex
4195 number "W(chi)" of modulus 1 such that
4196 "Lambda(1-s,chi) = W(chi) Lambda(s,\overline{chi})"
4198 where "Lambda(s,chi) = A(chi)^{s/2}gamma_chi(s) L(s,chi)" is the
4200 enlarged L-function associated to "L".
4201 The generators of the ray class group are needed, and you can set "flag
4203 = 1" if the character is known to be primitive. Example:
4204 bnf = bnfinit(x^2 - 145);
4206 bnr = bnrinit(bnf,7,1);
4207 bnrrootnumber(bnr, [5])
4208 returns the root number of the character "chi" of "\Cl_7(Q( sqrt
4210 {145}))" such that "chi(g) = zeta^5", where "g" is the generator of the
4211 ray-class field and "zeta = e^{2iPi/N}" where "N" is the order of "g"
4212 ("N = 12" as "bnr.cyc" readily tells us).
4213 The library syntax is bnrrootnumber"(bnf,chi,flag)"
4215 bnrstark"{(bnr,{subgroup})}"
4217 bnr being as output by "bnrinit(,,1)", finds a relative equation for
4218 the class field corresponding to the modulus in bnr and the given
4219 congruence subgroup (as usual, omit "subgroup" if you want the whole
4220 ray class group).
4221 The routine uses Stark units and needs to find a suitable auxilliary
4223 conductor, which may not exist when the class field is not cyclic over
4224 the base. In this case "bnrstark" is allowed to return a vector of
4225 polynomials defining \emph{independent} relative extensions, whose
4226 compositum is the requested class field. It was decided that it was
4227 more useful to keep the extra information thus made available, hence
4228 the user has to take the compositum herself.
4229 The main variable of bnr must not be "x", and the ground field and the
4231 class field must be totally real. When the base field is Q, the vastly
4232 simpler "galoissubcyclo" is used instead. Here is an example:
4233 bnf = bnfinit(y^2 - 3);
4235 bnr = bnrinit(bnf, 5, 1);
4236 pol = bnrstark(bnr)
4237 returns the ray class field of "Q( sqrt {3})" modulo 5. Usually, one
4239 wants to apply to the result one of
4240 rnfpolredabs(bnf, pol, 16 + 2) \\ compute a reduced relative polynomial
4242 rnfpolredabs(bnf, pol, 16 + 2) \\ compute a reduced absolute polynomial
4243 The library syntax is bnrstark"(bnr,subgroup)", where an omitted
4245 subgroup is coded by "NULL".
4246 dirzetak"(nf,b)"
4248 gives as a vector the first "b" coefficients of the Dedekind zeta
4249 function of the number field "nf" considered as a Dirichlet series.
4250 The library syntax is dirzetak"(nf,b)".
4252 factornf"(x,t)"
4254 factorization of the univariate polynomial "x" over the number field
4255 defined by the (univariate) polynomial "t". "x" may have coefficients
4256 in Q or in the number field. The algorithm reduces to factorization
4257 over Q (Trager's trick). The direct approach of "nffactor", which uses
4258 van Hoeij's method in a relative setting, is in general faster.
4259 The main variable of "t" must be of \emph{lower} priority than that of
4261 "x" (see "Label se:priority"). However if non-rational number field
4262 elements occur (as polmods or polynomials) as coefficients of "x", the
4263 variable of these polmods \emph{must} be the same as the main variable
4264 of "t". For example
4265 ? factornf(x^2 + Mod(y, y^2+1), y^2+1);
4267 ? factornf(x^2 + y, y^2+1); \\ these two are OK
4268 ? factornf(x^2 + Mod(z,z^2+1), y^2+1)
4269 *** factornf: inconsistent data in rnf function.
4270 ? factornf(x^2 + z, y^2+1)
4271 *** factornf: incorrect variable in rnf function.
4272 The library syntax is polfnf"(x,t)".
4274 galoisexport"(gal,{flag = 0})"
4276 gal being be a Galois field as output by "galoisinit", export the
4277 underlying permutation group as a string suitable for (no flags or
4278 "flag = 0") GAP or ("flag = 1") Magma. The following example compute
4279 the index of the underlying abstract group in the GAP library:
4280 ? G = galoisinit(x^6+108);
4282 ? s = galoisexport(G)
4283 %2 = "Group((1, 2, 3)(4, 5, 6), (1, 4)(2, 6)(3, 5))"
4284 ? extern("echo \"IdGroup("s");\" | gap -q")
4285 %3 = [6, 1]
4286 ? galoisidentify(G)
4287 %4 = [6, 1]
4288 This command also accepts subgroups returned by "galoissubgroups".
4290 The library syntax is galoisexport"(gal,flag)".
4292 galoisfixedfield"(gal,perm,{flag = 0},{v = y}))"
4294 gal being be a Galois field as output by "galoisinit" and perm an
4295 element of "gal.group" or a vector of such elements, computes the fixed
4296 field of gal by the automorphism defined by the permutations perm of
4297 the roots "gal.roots". "P" is guaranteed to be squarefree modulo
4298 "gal.p".
4299 If no flags or "flag = 0", output format is the same as for
4301 "nfsubfield", returning "[P,x]" such that "P" is a polynomial defining
4302 the fixed field, and "x" is a root of "P" expressed as a polmod in
4303 "gal.pol".
4304 If "flag = 1" return only the polynomial "P".
4306 If "flag = 2" return "[P,x,F]" where "P" and "x" are as above and "F"
4308 is the factorization of "gal.pol" over the field defined by "P", where
4309 variable "v" ("y" by default) stands for a root of "P". The priority of
4310 "v" must be less than the priority of the variable of "gal.pol" (see
4311 "Label se:priority"). Example:
4312 ? G = galoisinit(x^4+1);
4314 ? galoisfixedfield(G,G.group[2],2)
4315 %2 = [x^2 + 2, Mod(x^3 + x, x^4 + 1), [x^2 - y*x - 1, x^2 + y*x - 1]]
4316 computes the factorization "x^4+1 = (x^2- sqrt {-2}x-1)(x^2+ sqrt
4318 {-2}x-1)"
4319 The library syntax is galoisfixedfield"(gal,perm,flag,"v")", where "v"
4321 is a variable number, an omitted "v" being coded by "-1".
4322 galoisidentify"(gal)"
4324 gal being be a Galois field as output by "galoisinit", output the
4325 isomorphism class of the underlying abstract group as a two-components
4326 vector "[o,i]", where "o" is the group order, and "i" is the group
4327 index in the GAP4 Small Group library, by Hans Ulrich Besche, Bettina
4328 Eick and Eamonn O'Brien.
4329 This command also accepts subgroups returned by "galoissubgroups".
4331 The current implementation is limited to degree less or equal to 127.
4333 Some larger ``easy'' orders are also supported.
4334 The output is similar to the output of the function "IdGroup" in GAP4.
4336 Note that GAP4 "IdGroup" handles all groups of order less than 2000
4337 except 1024, so you can use "galoisexport" and GAP4 to identify large
4338 Galois groups.
4339 The library syntax is galoisidentify"(gal)".
4341 galoisinit"(pol,{den})"
4343 computes the Galois group and all necessary information for computing
4344 the fixed fields of the Galois extension "K/Q" where "K" is the number
4345 field defined by "pol" (monic irreducible polynomial in "Z[X]" or a
4346 number field as output by "nfinit"). The extension "K/Q" must be Galois
4347 with Galois group ``weakly'' super-solvable (see "nfgaloisconj")
4348 This is a prerequisite for most of the "galois""xxx" routines. For
4350 instance:
4351 P = x^6 + 108;
4353 G = galoisinit(P);
4354 L = galoissubgroups(G);
4355 vector(#L, i, galoisisabelian(L[i],1))
4356 vector(#L, i, galoisidentify(L[i]))
4357 The output is an 8-component vector gal.
4359 "gal[1]" contains the polynomial pol ("gal.pol").
4361 "gal[2]" is a three-components vector "[p,e,q]" where "p" is a prime
4363 number ("gal.p") such that pol totally split modulo "p" , "e" is an
4364 integer and "q = p^e" ("gal.mod") is the modulus of the roots in
4365 "gal.roots".
4366 "gal[3]" is a vector "L" containing the "p"-adic roots of pol as
4368 integers implicitly modulo "gal.mod". ("gal.roots").
4369 "gal[4]" is the inverse of the Van der Monde matrix of the "p"-adic
4371 roots of pol, multiplied by "gal[5]".
4372 "gal[5]" is a multiple of the least common denominator of the
4374 automorphisms expressed as polynomial in a root of pol.
4375 "gal[6]" is the Galois group "G" expressed as a vector of permutations
4377 of "L" ("gal.group").
4378 "gal[7]" is a generating subset "S = [s_1,...,s_g]" of "G" expressed as
4380 a vector of permutations of "L" ("gal.gen").
4381 "gal[8]" contains the relative orders "[o_1,...,o_g]" of the generators
4383 of "S" ("gal.orders").
4384 Let "H" be the maximal normal supersolvable subgroup of "G", we have
4386 the following properties:
4387 \item if "G/H ~ A_4" then "[o_1,...,o_g]" ends by "[2,2,3]".
4389 \item if "G/H ~ S_4" then "[o_1,...,o_g]" ends by "[2,2,3,2]".
4391 \item else "G" is super-solvable.
4393 \item for "1 <= i <= g" the subgroup of "G" generated by
4395 "[s_1,...,s_g]" is normal, with the exception of "i = g-2" in the
4396 second case and of "i = g-3" in the third.
4397 \item the relative order "o_i" of "s_i" is its order in the quotient
4399 group "G/<s_1,...,s_{i-1}>", with the same exceptions.
4400 \item for any "x belongs to G" there exists a unique family
4402 "[e_1,...,e_g]" such that (no exceptions):
4403 -- for "1 <= i <= g" we have "0 <= e_i < o_i"
4405 -- "x = g_1^{e_1}g_2^{e_2}...g_n^{e_n}"
4407 If present "den" must be a suitable value for "gal[5]".
4409 The library syntax is galoisinit"(gal,den)".
4411 galoisisabelian"(gal,{fl = 0})"
4413 gal being as output by "galoisinit", return 0 if gal is not an abelian
4414 group, and the HNF matrix of gal over "gal.gen" if "fl = 0", 1 if "fl =
4415 1".
4416 This command also accepts subgroups returned by "galoissubgroups".
4418 The library syntax is galoisisabelian"(gal,fl)" where fl is a C long
4420 integer.
4421 galoispermtopol"(gal,perm)"
4423 gal being a Galois field as output by "galoisinit" and perm a element
4424 of "gal.group", return the polynomial defining the Galois automorphism,
4425 as output by "nfgaloisconj", associated with the permutation perm of
4426 the roots "gal.roots". perm can also be a vector or matrix, in this
4427 case, "galoispermtopol" is applied to all components recursively.
4428 Note that
4430 G = galoisinit(pol);
4432 galoispermtopol(G, G[6])~
4433 is equivalent to "nfgaloisconj(pol)", if degree of pol is greater or
4435 equal to 2.
4436 The library syntax is galoispermtopol"(gal,perm)".
4438 galoissubcyclo"(N,H,{fl = 0},{v})"
4440 computes the subextension of "Q(zeta_n)" fixed by the subgroup "H
4441 \subset (Z/nZ)^*". By the Kronecker-Weber theorem, all abelian number
4442 fields can be generated in this way (uniquely if "n" is taken to be
4443 minimal).
4444 The pair "(n, H)" is deduced from the parameters "(N, H)" as follows
4446 \item "N" an integer: then "n = N"; "H" is a generator, i.e. an integer
4448 or an integer modulo "n"; or a vector of generators.
4449 \item "N" the output of znstar(n). "H" as in the first case above, or a
4451 matrix, taken to be a HNF left divisor of the SNF for "(Z/nZ)^*" (of
4452 type "N.cyc"), giving the generators of "H" in terms of "N.gen".
4453 \item "N" the output of "bnrinit(bnfinit(y), m, 1)" where "m" is a
4455 module. "H" as in the first case, or a matrix taken to be a HNF left
4456 divisor of the SNF for the ray class group modulo "m" (of type
4457 "N.cyc"), giving the generators of "H" in terms of "N.gen".
4458 In this last case, beware that "H" is understood relatively to "N"; in
4460 particular, if the infinite place does not divide the module, e.g if
4461 "m" is an integer, then it is not a subgroup of "(Z/nZ)^*", but of its
4462 quotient by "{+- 1}".
4463 If "fl = 0", compute a polynomial (in the variable v) defining the the
4465 subfield of "Q(zeta_n)" fixed by the subgroup H of "(Z/nZ)^*".
4466 If "fl = 1", compute only the conductor of the abelian extension, as a
4468 module.
4469 If "fl = 2", output "[pol, N]", where "pol" is the polynomial as output
4471 when "fl = 0" and "N" the conductor as output when "fl = 1".
4472 The following function can be used to compute all subfields of
4474 "Q(zeta_n)" (of exact degree "d", if "d" is set):
4475 subcyclo(n, d = -1)=
4477 {
4478 local(bnr,L,IndexBound);
4479 IndexBound = if (d < 0, n, [d]);
4480 bnr = bnrinit(bnfinit(y), [n,[1]], 1);
4481 L = subgrouplist(bnr, IndexBound, 1);
4482 vector(#L,i, galoissubcyclo(bnr,L[i]));
4483 }
4484 Setting "L = subgrouplist(bnr, IndexBound)" would produce subfields of
4486 exact conductor "n oo ".
4487 The library syntax is galoissubcyclo"(N,H,fl,v)" where fl is a C long
4489 integer, and v a variable number.
4490 galoissubfields"(G,{fl = 0},{v})"
4492 Output all the subfields of the Galois group G, as a vector. This
4493 works by applying "galoisfixedfield" to all subgroups. The meaning of
4494 the flag fl is the same as for "galoisfixedfield".
4495 The library syntax is galoissubfields"(G,fl,v)", where fl is a long and
4497 v a variable number.
4498 galoissubgroups"(gal)"
4500 Output all the subgroups of the Galois group "gal". A subgroup is a
4501 vector [gen, orders], with the same meaning as for "gal.gen" and
4502 "gal.orders". Hence gen is a vector of permutations generating the
4503 subgroup, and orders is the relatives orders of the generators. The
4504 cardinal of a subgroup is the product of the relative orders. Such
4505 subgroup can be used instead of a Galois group in the following
4506 command: "galoisisabelian", "galoissubgroups", "galoisexport" and
4507 "galoisidentify".
4508 To get the subfield fixed by a subgroup sub of gal, use
4510 galoisfixedfield(gal,sub[1])
4512 The library syntax is galoissubgroups"(gal)".
4514 idealadd"(nf,x,y)"
4516 sum of the two ideals "x" and "y" in the number field "nf". When "x"
4517 and "y" are given by Z-bases, this does not depend on "nf" and can be
4518 used to compute the sum of any two Z-modules. The result is given in
4519 HNF.
4520 The library syntax is idealadd"(nf,x,y)".
4522 idealaddtoone"(nf,x,{y})"
4524 "x" and "y" being two co-prime integral ideals (given in any form),
4525 this gives a two-component row vector "[a,b]" such that "a belongs to
4526 x", "b belongs to y" and "a+b = 1".
4527 The alternative syntax "idealaddtoone(nf,v)", is supported, where "v"
4529 is a "k"-component vector of ideals (given in any form) which sum to
4530 "Z_K". This outputs a "k"-component vector "e" such that "e[i] belongs
4531 to x[i]" for "1 <= i <= k" and "sum_{1 <= i <= k}e[i] = 1".
4532 The library syntax is idealaddtoone0"(nf,x,y)", where an omitted "y" is
4534 coded as "NULL".
4535 idealappr"(nf,x,{flag = 0})"
4537 if "x" is a fractional ideal (given in any form), gives an element
4538 "alpha" in "nf" such that for all prime ideals " wp " such that the
4539 valuation of "x" at " wp " is non-zero, we have "v_{ wp }(alpha) = v_{
4540 wp }(x)", and. "v_{ wp }(alpha) >= 0" for all other "{ wp }".
4541 If "flag" is non-zero, "x" must be given as a prime ideal
4543 factorization, as output by "idealfactor", but possibly with zero or
4544 negative exponents. This yields an element "alpha" such that for all
4545 prime ideals " wp " occurring in "x", "v_{ wp }(alpha)" is equal to the
4546 exponent of " wp " in "x", and for all other prime ideals, "v_{ wp
4547 }(alpha) >= 0". This generalizes "idealappr(nf,x,0)" since zero
4548 exponents are allowed. Note that the algorithm used is slightly
4549 different, so that "idealappr(nf,idealfactor(nf,x))" may not be the
4550 same as "idealappr(nf,x,1)".
4551 The library syntax is idealappr0"(nf,x,flag)".
4553 idealchinese"(nf,x,y)"
4555 "x" being a prime ideal factorization (i.e. a 2 by 2 matrix whose first
4556 column contain prime ideals, and the second column integral exponents),
4557 "y" a vector of elements in "nf" indexed by the ideals in "x", computes
4558 an element "b" such that
4559 "v_ wp (b - y_ wp ) >= v_ wp (x)" for all prime ideals in "x" and "v_
4561 wp (b) >= 0" for all other " wp ".
4562 The library syntax is idealchinese"(nf,x,y)".
4564 idealcoprime"(nf,x,y)"
4566 given two integral ideals "x" and "y" in the number field "nf", finds a
4567 "beta" in the field, expressed on the integral basis "nf[7]", such that
4568 "beta.x" is an integral ideal coprime to "y".
4569 The library syntax is idealcoprime"(nf,x,y)".
4571 idealdiv"(nf,x,y,{flag = 0})"
4573 quotient "x.y^{-1}" of the two ideals "x" and "y" in the number field
4574 "nf". The result is given in HNF.
4575 If "flag" is non-zero, the quotient "x.y^{-1}" is assumed to be an
4577 integral ideal. This can be much faster when the norm of the quotient
4578 is small even though the norms of "x" and "y" are large.
4579 The library syntax is idealdiv0"(nf,x,y,flag)". Also available are "
4581 idealdiv(nf,x,y)" ("flag = 0") and " idealdivexact(nf,x,y)" ("flag =
4582 1").
4583 idealfactor"(nf,x)"
4585 factors into prime ideal powers the ideal "x" in the number field "nf".
4586 The output format is similar to the "factor" function, and the prime
4587 ideals are represented in the form output by the "idealprimedec"
4588 function, i.e. as 5-element vectors.
4589 The library syntax is idealfactor"(nf,x)".
4591 idealhnf"(nf,a,{b})"
4593 gives the Hermite normal form matrix of the ideal "a". The ideal can be
4594 given in any form whatsoever (typically by an algebraic number if it is
4595 principal, by a "Z_K"-system of generators, as a prime ideal as given
4596 by "idealprimedec", or by a Z-basis).
4597 If "b" is not omitted, assume the ideal given was "aZ_K+bZ_K", where
4599 "a" and "b" are elements of "K" given either as vectors on the integral
4600 basis "nf[7]" or as algebraic numbers.
4601 The library syntax is idealhnf0"(nf,a,b)" where an omitted "b" is coded
4603 as "NULL". Also available is " idealhermite(nf,a)" ("b" omitted).
4604 idealintersect"(nf,A,B)"
4606 intersection of the two ideals "A" and "B" in the number field "nf".
4607 The result is given in HNF.
4608 ? nf = nfinit(x^2+1);
4610 ? idealintersect(nf, 2, x+1)
4611 %2 =
4612 [2 0]
4613 [0 2]
4615 This function does not apply to general Z-modules, e.g. orders, since
4617 its arguments are replaced by the ideals they generate. The following
4618 script intersects Z-modules "A" and "B" given by matrices of compatible
4619 dimensions with integer coefficients:
4620 ZM_intersect(A,B) =
4622 { local( Ker = matkerint(concat(A,B)) );
4623 mathnf(A * vecextract(Ker, Str("..", #A), ".."))
4624 }
4625 The library syntax is idealintersect"(nf,A,B)".
4627 idealinv"(nf,x)"
4629 inverse of the ideal "x" in the number field "nf". The result is the
4630 Hermite normal form of the inverse of the ideal, together with the
4631 opposite of the Archimedean information if it is given.
4632 The library syntax is idealinv"(nf,x)".
4634 ideallist"(nf,bound,{flag = 4})"
4636 computes the list of all ideals of norm less or equal to bound in the
4637 number field nf. The result is a row vector with exactly bound
4638 components. Each component is itself a row vector containing the
4639 information about ideals of a given norm, in no specific order,
4640 depending on the value of "flag":
4641 The possible values of "flag" are:
4643 0: give the bid associated to the ideals, without generators.
4645 1: as 0, but include the generators in the bid.
4647 2: in this case, nf must be a bnf with units. Each component is of
4649 the form "[bid,U]", where bid is as case 0 and "U" is a vector of
4650 discrete logarithms of the units. More precisely, it gives the
4651 "ideallog"s with respect to bid of "bnf.tufu". This structure is
4652 technical, and only meant to be used in conjunction with
4653 "bnrclassnolist" or "bnrdisclist".
4654 3: as 2, but include the generators in the bid.
4656 4: give only the HNF of the ideal.
4658 ? #L[65]
4660 %4 = 4 \\ A single ideal of norm 1
4661 ? #L[65]
4662 %4 = 4 \\ There are 4 ideals of norm 4 in Z[i]
4663 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 ? L = ideallist(bnf, 100, 0);
4696 ? l = L[98]; vector(#l, i, l[i].clgp)
4697 %4 = [[42, [42]], [36, [6, 6]], [42, [42]]]
4698 ? La = ideallistarch(bnf, L, [1,1]); \\ two places at infinity
4699 ? L = ideallist(bnf, 100, 0);
4700 ? l = L[98]; vector(#l, i, l[i].clgp)
4701 %4 = [[42, [42]], [36, [6, 6]], [42, [42]]]
4702 ? La = ideallistarch(bnf, L, [1,1]); \\ add them to the modulus
4703 ? l = La[98]; vector(#l, i, l[i].clgp)
4704 %6 = [[168, [42, 2, 2]], [144, [6, 6, 2, 2]], [168, [42, 2, 2]]]
4705 Of course, the results above are obvious: adding "t" places at infinity
4707 will add "t" copies of "Z/2Z" to the ray class group. The following
4708 application is more typical:
4709 ? L = ideallist(bnf, 100, 2); \\ units are required now
4711 ? La = ideallistarch(bnf, L, [1,1]);
4712 ? H = bnrclassnolist(bnf, La);
4713 ? H[98];
4714 %6 = [2, 12, 2]
4715 The library syntax is ideallistarch"(nf,list,arch)".
4717 ideallog"(nf,x,bid)"
4719 "nf" is a number field, bid a ``big ideal'' as output by "idealstar"
4720 and "x" a non-necessarily integral element of nf which must have
4721 valuation equal to 0 at all prime ideals dividing "I = bid[1]". This
4722 function computes the ``discrete logarithm'' of "x" on the generators
4723 given in "bid[2]". In other words, if "g_i" are these generators, of
4724 orders "d_i" respectively, the result is a column vector of integers
4725 "(x_i)" such that "0 <= x_i < d_i" and
4726 "x = prod_ig_i^{x_i} (mod ^*I) ."
4728 Note that when "I" is a module, this implies also sign conditions on
4730 the embeddings.
4731 The library syntax is zideallog"(nf,x,bid)".
4733 idealmin"(nf,x,{vdir})"
4735 computes a minimum of the ideal "x" in the direction vdir in the number
4736 field nf.
4737 The library syntax is minideal"(nf,x,vdir,prec)", where an omitted vdir
4739 is coded as "NULL".
4740 idealmul"(nf,x,y,{flag = 0})"
4742 ideal multiplication of the ideals "x" and "y" in the number field nf.
4743 The result is a generating set for the ideal product with at most "n"
4744 elements, and is in Hermite normal form if either "x" or "y" is in HNF
4745 or is a prime ideal as output by "idealprimedec", and this is given
4746 together with the sum of the Archimedean information in "x" and "y" if
4747 both are given.
4748 If "flag" is non-zero, reduce the result using "idealred".
4750 The library syntax is idealmul"(nf,x,y)" ("flag = 0") or "
4752 idealmulred(nf,x,y,prec)" ("flag ! = 0"), where as usual, "prec" is a C
4753 long integer representing the precision.
4754 idealnorm"(nf,x)"
4756 computes the norm of the ideal "x" in the number field "nf".
4757 The library syntax is idealnorm"(nf, x)".
4759 idealpow"(nf,x,k,{flag = 0})"
4761 computes the "k"-th power of the ideal "x" in the number field "nf".
4762 "k" can be positive, negative or zero. The result is NOT reduced, it is
4763 really the "k"-th ideal power, and is given in HNF.
4764 If "flag" is non-zero, reduce the result using "idealred". Note however
4766 that this is NOT the same as as "idealpow(nf,x,k)" followed by
4767 reduction, since the reduction is performed throughout the powering
4768 process.
4769 The library syntax corresponding to "flag = 0" is " idealpow(nf,x,k)".
4771 If "k" is a "long", you can use " idealpows(nf,x,k)". Corresponding to
4772 "flag = 1" is " idealpowred(nf,vp,k,prec)", where "prec" is a "long".
4773 idealprimedec"(nf,p)"
4775 computes the prime ideal decomposition of the prime number "p" in the
4776 number field "nf". "p" must be a (positive) prime number. Note that the
4777 fact that "p" is prime is not checked, so if a non-prime "p" is given
4778 the result is undefined.
4779 The result is a vector of pr structures, each representing one of the
4781 prime ideals above "p" in the number field "nf". The representation "P
4782 = [p,a,e,f,b]" of a prime ideal means the following. The prime ideal is
4783 equal to "pZ_K+alphaZ_K" where "Z_K" is the ring of integers of the
4784 field and "alpha = sum_i a_iomega_i" where the "omega_i" form the
4785 integral basis "nf.zk", "e" is the ramification index, "f" is the
4786 residual index, and "b" represents a "beta belongs to Z_K" such that
4787 "P^{-1} = Z_K+beta/pZ_K" which will be useful for computing valuations,
4788 but which the user can ignore. The number "alpha" is guaranteed to have
4789 a valuation equal to 1 at the prime ideal (this is automatic if "e >
4790 1").
4791 The components of "P" should be accessed by member functions: "P.p",
4793 "P.e", "P.f", and "P.gen" (returns the vector "[p,a]").
4794 The library syntax is primedec"(nf,p)".
4796 idealprincipal"(nf,x)"
4798 creates the principal ideal generated by the algebraic number "x"
4799 (which must be of type integer, rational or polmod) in the number field
4800 "nf". The result is a one-column matrix.
4801 The library syntax is principalideal"(nf,x)".
4803 idealred"(nf,I,{vdir = 0})"
4805 LLL reduction of the ideal "I" in the number field nf, along the
4806 direction vdir. If vdir is present, it must be an "r1+r2"-component
4807 vector ("r1" and "r2" number of real and complex places of nf as
4808 usual).
4809 This function finds a ``small'' "a" in "I" (it is an LLL pseudo-minimum
4811 along direction vdir). The result is the Hermite normal form of the
4812 LLL-reduced ideal "r I/a", where "r" is a rational number such that the
4813 resulting ideal is integral and primitive. This is often, but not
4814 always, a reduced ideal in the sense of Buchmann. If "I" is an idele,
4815 the logarithmic embeddings of "a" are subtracted to the Archimedean
4816 part.
4817 More often than not, a principal ideal will yield the identity matrix.
4819 This is a quick and dirty way to check if ideals are principal without
4820 computing a full "bnf" structure, but it's not a necessary condition;
4821 hence, a non-trivial result doesn't prove the ideal is non-trivial in
4822 the class group.
4823 Note that this is \emph{not} the same as the LLL reduction of the
4825 lattice "I" since ideal operations are involved.
4826 The library syntax is ideallllred"(nf,x,vdir,prec)", where an omitted
4828 vdir is coded as "NULL".
4829 idealstar"(nf,I,{flag = 1})"
4831 outputs a bid structure, necessary for computing in the finite abelian
4832 group "G = (Z_K/I)^*". Here, nf is a number field and "I" is a modulus:
4833 either an ideal in any form, or a row vector whose first component is
4834 an ideal and whose second component is a row vector of "r_1" 0 or 1.
4835 This bid is used in "ideallog" to compute discrete logarithms. It also
4837 contains useful information which can be conveniently retrieved as
4838 "bid.mod" (the modulus), "bid.clgp" ("G" as a finite abelian group),
4839 "bid.no" (the cardinality of "G"), "bid.cyc" (elementary divisors) and
4840 "bid.gen" (generators).
4841 If "flag = 1" (default), the result is a bid structure without
4843 generators.
4844 If "flag = 2", as "flag = 1", but including generators, which wastes
4846 some time.
4847 If "flag = 0", \emph{deprecated}. Only outputs "(Z_K/I)^*" as an
4849 abelian group, i.e as a 3-component vector "[h,d,g]": "h" is the order,
4850 "d" is the vector of SNF cyclic components and "g" the corresponding
4851 generators. This flag is deprecated: it is in fact slightly faster to
4852 compute a true bid structure, which contains much more information.
4853 The library syntax is idealstar0"(nf,I,flag)".
4855 idealtwoelt"(nf,x,{a})"
4857 computes a two-element representation of the ideal "x" in the number
4858 field "nf", using a straightforward (exponential time) search. "x" can
4859 be an ideal in any form, (including perhaps an Archimedean part, which
4860 is ignored) and the result is a row vector "[a,alpha]" with two
4861 components such that "x = aZ_K+alphaZ_K" and "a belongs to Z", where
4862 "a" is the one passed as argument if any. If "x" is given by at least
4863 two generators, "a" is chosen to be the positive generator of "x cap
4864 Z".
4865 Note that when an explicit "a" is given, we use an asymptotically
4867 faster method, however in practice it is usually slower.
4868 The library syntax is ideal_two_elt0"(nf,x,a)", where an omitted "a" is
4870 entered as "NULL".
4871 idealval"(nf,x,vp)"
4873 gives the valuation of the ideal "x" at the prime ideal vp in the
4874 number field "nf", where vp must be a 5-component vector as given by
4875 "idealprimedec".
4876 The library syntax is idealval"(nf,x,vp)", and the result is a "long"
4878 integer.
4879 ideleprincipal"(nf,x)"
4881 creates the principal idele generated by the algebraic number "x"
4882 (which must be of type integer, rational or polmod) in the number field
4883 "nf". The result is a two-component vector, the first being a one-
4884 column matrix representing the corresponding principal ideal, and the
4885 second being the vector with "r_1+r_2" components giving the complex
4886 logarithmic embedding of "x".
4887 The library syntax is principalidele"(nf,x)".
4889 matalgtobasis"(nf,x)"
4891 "nf" being a number field in "nfinit" format, and "x" a matrix whose
4892 coefficients are expressed as polmods in "nf", transforms this matrix
4893 into a matrix whose coefficients are expressed on the integral basis of
4894 "nf". This is the same as applying "nfalgtobasis" to each entry, but it
4895 would be dangerous to use the same name.
4896 The library syntax is matalgtobasis"(nf,x)".
4898 matbasistoalg"(nf,x)"
4900 "nf" being a number field in "nfinit" format, and "x" a matrix whose
4901 coefficients are expressed as column vectors on the integral basis of
4902 "nf", transforms this matrix into a matrix whose coefficients are
4903 algebraic numbers expressed as polmods. This is the same as applying
4904 "nfbasistoalg" to each entry, but it would be dangerous to use the same
4905 name.
4906 The library syntax is matbasistoalg"(nf,x)".
4908 modreverse"(a)"
4910 "a" being a polmod A(X) modulo T(X), finds the ``reverse polmod'' B(X)
4911 modulo Q(X), where "Q" is the minimal polynomial of "a", which must be
4912 equal to the degree of "T", and such that if "theta" is a root of "T"
4913 then "theta = B(alpha)" for a certain root "alpha" of "Q".
4914 This is very useful when one changes the generating element in
4916 algebraic extensions.
4917 The library syntax is polmodrecip"(x)".
4919 newtonpoly"(x,p)"
4921 gives the vector of the slopes of the Newton polygon of the polynomial
4922 "x" with respect to the prime number "p". The "n" components of the
4923 vector are in decreasing order, where "n" is equal to the degree of
4924 "x". Vertical slopes occur iff the constant coefficient of "x" is zero
4925 and are denoted by "VERYBIGINT", the biggest single precision integer
4926 representable on the machine ("2^{31}-1" (resp. "2^{63}-1") on 32-bit
4927 (resp. 64-bit) machines), see "Label se:valuation".
4928 The library syntax is newtonpoly"(x,p)".
4930 nfalgtobasis"(nf,x)"
4932 this is the inverse function of "nfbasistoalg". Given an object "x"
4933 whose entries are expressed as algebraic numbers in the number field
4934 "nf", transforms it so that the entries are expressed as a column
4935 vector on the integral basis "nf.zk".
4936 The library syntax is algtobasis"(nf,x)".
4938 nfbasis"(x,{flag = 0},{fa})"
4940 integral basis of the number field defined by the irreducible,
4941 preferably monic, polynomial "x", using a modified version of the round
4942 4 algorithm by default, due to David Ford, Sebastian Pauli and Xavier
4943 Roblot. The binary digits of "flag" have the following meaning:
4944 1: assume that no square of a prime greater than the default
4946 "primelimit" divides the discriminant of "x", i.e. that the index of
4947 "x" has only small prime divisors.
4948 2: use round 2 algorithm. For small degrees and coefficient size, this
4950 is sometimes a little faster. (This program is the translation into C
4951 of a program written by David Ford in Algeb.)
4952 Thus for instance, if "flag = 3", this uses the round 2 algorithm and
4954 outputs an order which will be maximal at all the small primes.
4955 If fa is present, we assume (without checking!) that it is the two-
4957 column matrix of the factorization of the discriminant of the
4958 polynomial "x". Note that it does \emph{not} have to be a complete
4959 factorization. This is especially useful if only a local integral basis
4960 for some small set of places is desired: only factors with exponents
4961 greater or equal to 2 will be considered.
4962 The library syntax is nfbasis0"(x,flag,fa)". An extended version is "
4964 nfbasis(x,&d,flag,fa)", where "d" receives the discriminant of the
4965 number field (\emph{not} of the polynomial "x"), and an omitted fa is
4966 input as "NULL". Also available are " base(x,&d)" ("flag = 0"), "
4967 base2(x,&d)" ("flag = 2") and " factoredbase(x,fa,&d)".
4968 nfbasistoalg"(nf,x)"
4970 this is the inverse function of "nfalgtobasis". Given an object "x"
4971 whose entries are expressed on the integral basis "nf.zk", transforms
4972 it into an object whose entries are algebraic numbers (i.e. polmods).
4973 The library syntax is basistoalg"(nf,x)".
4975 nfdetint"(nf,x)"
4977 given a pseudo-matrix "x", computes a non-zero ideal contained in
4978 (i.e. multiple of) the determinant of "x". This is particularly useful
4979 in conjunction with "nfhnfmod".
4980 The library syntax is nfdetint"(nf,x)".
4982 nfdisc"(x,{flag = 0},{fa})"
4984 field discriminant of the number field defined by the integral,
4985 preferably monic, irreducible polynomial "x". "flag" and "fa" are
4986 exactly as in "nfbasis". That is, "fa" provides the matrix of a partial
4987 factorization of the discriminant of "x", and binary digits of "flag"
4988 are as follows:
4989 1: assume that no square of a prime greater than "primelimit" divides
4991 the discriminant.
4992 2: use the round 2 algorithm, instead of the default round 4. This
4994 should be slower except maybe for polynomials of small degree and
4995 coefficients.
4996 The library syntax is nfdiscf0"(x,flag,fa)" where an omitted "fa" is
4998 input as "NULL". You can also use " discf(x)" ("flag = 0").
4999 nfeltdiv"(nf,x,y)"
5001 given two elements "x" and "y" in nf, computes their quotient "x/y" in
5002 the number field "nf".
5003 The library syntax is element_div"(nf,x,y)".
5005 nfeltdiveuc"(nf,x,y)"
5007 given two elements "x" and "y" in nf, computes an algebraic integer "q"
5008 in the number field "nf" such that the components of "x-qy" are
5009 reasonably small. In fact, this is functionally identical to
5010 "round(nfeltdiv(nf,x,y))".
5011 The library syntax is nfdiveuc"(nf,x,y)".
5013 nfeltdivmodpr"(nf,x,y,pr)"
5015 given two elements "x" and "y" in nf and pr a prime ideal in "modpr"
5016 format (see "nfmodprinit"), computes their quotient "x / y" modulo the
5017 prime ideal pr.
5018 The library syntax is element_divmodpr"(nf,x,y,pr)".
5020 nfeltdivrem"(nf,x,y)"
5022 given two elements "x" and "y" in nf, gives a two-element row vector
5023 "[q,r]" such that "x = qy+r", "q" is an algebraic integer in "nf", and
5024 the components of "r" are reasonably small.
5025 The library syntax is nfdivrem"(nf,x,y)".
5027 nfeltmod"(nf,x,y)"
5029 given two elements "x" and "y" in nf, computes an element "r" of "nf"
5030 of the form "r = x-qy" with "q" and algebraic integer, and such that
5031 "r" is small. This is functionally identical to
5032 "x - nfeltmul(nf,round(nfeltdiv(nf,x,y)),y)."
5034 The library syntax is nfmod"(nf,x,y)".
5036 nfeltmul"(nf,x,y)"
5038 given two elements "x" and "y" in nf, computes their product "x*y" in
5039 the number field "nf".
5040 The library syntax is element_mul"(nf,x,y)".
5042 nfeltmulmodpr"(nf,x,y,pr)"
5044 given two elements "x" and "y" in nf and pr a prime ideal in "modpr"
5045 format (see "nfmodprinit"), computes their product "x*y" modulo the
5046 prime ideal pr.
5047 The library syntax is element_mulmodpr"(nf,x,y,pr)".
5049 nfeltpow"(nf,x,k)"
5051 given an element "x" in nf, and a positive or negative integer "k",
5052 computes "x^k" in the number field "nf".
5053 The library syntax is element_pow"(nf,x,k)".
5055 nfeltpowmodpr"(nf,x,k,pr)"
5057 given an element "x" in nf, an integer "k" and a prime ideal pr in
5058 "modpr" format (see "nfmodprinit"), computes "x^k" modulo the prime
5059 ideal pr.
5060 The library syntax is element_powmodpr"(nf,x,k,pr)".
5062 nfeltreduce"(nf,x,ideal)"
5064 given an ideal in Hermite normal form and an element "x" of the number
5065 field "nf", finds an element "r" in "nf" such that "x-r" belongs to the
5066 ideal and "r" is small.
5067 The library syntax is element_reduce"(nf,x,ideal)".
5069 nfeltreducemodpr"(nf,x,pr)"
5071 given an element "x" of the number field "nf" and a prime ideal pr in
5072 "modpr" format compute a canonical representative for the class of "x"
5073 modulo pr.
5074 The library syntax is nfreducemodpr"(nf,x,pr)".
5076 nfeltval"(nf,x,pr)"
5078 given an element "x" in nf and a prime ideal pr in the format output by
5079 "idealprimedec", computes their the valuation at pr of the element "x".
5080 The same result could be obtained using "idealval(nf,x,pr)" (since "x"
5081 would then be converted to a principal ideal), but it would be less
5082 efficient.
5083 The library syntax is element_val"(nf,x,pr)", and the result is a
5085 "long".
5086 nffactor"(nf,x)"
5088 factorization of the univariate polynomial "x" over the number field
5089 "nf" given by "nfinit". "x" has coefficients in "nf" (i.e. either
5090 scalar, polmod, polynomial or column vector). The main variable of "nf"
5091 must be of \emph{lower} priority than that of "x" (see "Label
5092 se:priority"). However if the polynomial defining the number field
5093 occurs explicitly in the coefficients of "x" (as modulus of a
5094 "t_POLMOD"), its main variable must be \emph{the same} as the main
5095 variable of "x". For example,
5096 ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ OK
5098 ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ OK
5099 ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ WRONG
5100 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. Klüners's algorithm in the general case, and
5402 B. Allombert's "galoissubfields" when nf is Galois (with weakly
5403 supersolvable Galois group).
5404 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 étale Q-algebra "A = Q(X,
5456 Y) / (P(X), Q(Y))". The factors are given by a list of polynomials "R"
5457 in "Z[X]", associated to the number field "Q(X)/ (R)", and sorted by
5458 increasing degree (with respect to lexicographic ordering for factors
5459 of equal degrees). Returns an error if one of the polynomials is not
5460 squarefree.
5461 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 ? pol = z[1]
5487 %5 = x^20 + 25*x^10 + 5
5488 ? a = subst(a.pol, x, z[2]) \\ pol defines the compositum
5489 ? pol = z[1]
5490 %5 = x^20 + 25*x^10 + 5
5491 ? a = subst(a.pol, x, z[2]) \\ a is a fifth root of 5
5492 ? pol = z[1]
5493 %5 = x^20 + 25*x^10 + 5
5494 ? a = subst(a.pol, x, z[2]) \\ look for a simpler polynomial
5495 ? pol = z[1]
5496 %5 = x^20 + 25*x^10 + 5
5497 ? a = subst(a.pol, x, z[2]) \\ a in the new coordinates
5498 %6 = Mod(-5/22*x^19 + 1/22*x^14 - 123/22*x^9 + 9/11*x^4, x^20 + 25*x^10 + 5)
5499 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 /usr/share/libpari23, "x" must be irreducible and the
5505 degree of "x" must be less than or equal to 7. On certain versions for
5506 which the data file of Galois resolvents has been installed (available
5507 in the Unix distribution as a separate package), degrees 8, 9, 10 and
5508 11 are also implemented.
5509 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 étale 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 étale 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 /usr/share/libpari23, this is slower and less
6071 efficient than "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 %2 = [[2, 1; 0, 1], [1, 0; 0, 2], [2, 0; 0, 1], [3, 0; 0, 1], [1, 0; 0, 1]]
6147 ? subgrouplist([6,2],[3]) \\ index less than 3
6148 %2 = [[2, 1; 0, 1], [1, 0; 0, 2], [2, 0; 0, 1], [3, 0; 0, 1], [1, 0; 0, 1]]
6149 ? subgrouplist([6,2],[3]) \\ index 3
6150 %3 = [[3, 0; 0, 1]]
6151 ? bnr = bnrinit(bnfinit(x), [120,[1]], 1);
6152 ? L = subgrouplist(bnr, [8]);
6153 In the last example, "L" corresponds to the 24 subfields of
6155 "Q(zeta_{120})", of degree 8 and conductor "120 oo " (by setting flag,
6156 we see there are a total of 43 subgroups of degree 8).
6157 ? vector(#L, i, galoissubcyclo(bnr, L[i]))
6159 will produce their equations. (For a general base field, you would have
6161 to rely on "bnrstark", or "rnfkummer".)
6162 The library syntax is subgrouplist0"(bnr,bound,flag)", where "flag" is
6164 a long integer, and an omitted bound is coded by "NULL".
6165 zetak"(znf,x,{flag = 0})"
6167 znf being a number field initialized by "zetakinit" (\emph{not} by
6168 "nfinit"), computes the value of the Dedekind zeta function of the
6169 number field at the complex number "x". If "flag = 1" computes Dedekind
6170 "Lambda" function instead (i.e. the product of the Dedekind zeta
6171 function by its gamma and exponential factors).
6172 CAVEAT. This implementation is not satisfactory and must be rewritten.
6174 In particular
6175 "*" The accuracy of the result depends in an essential way on the
6177 accuracy of both the "zetakinit" program and the current accuracy. Be
6178 wary in particular that "x" of large imaginary part or, on the
6179 contrary, very close to an ordinary integer will suffer from precision
6180 loss, yielding fewer significant digits than expected. Computing with
6181 28 eight digits of relative accuracy, we have
6182 ? zeta(3)
6184 %1 = 1.202056903159594285399738161
6185 ? zeta(3-1e-20)
6186 %2 = 1.202056903159594285401719424
6187 ? zetak(zetakinit(x), 3-1e-20)
6188 %3 = 1.2020569031595952919 \\ 5 digits are wrong
6189 ? zetak(zetakinit(x), 3-1e-28)
6190 %4 = -25.33411749 \\ junk
6191 "*" As the precision increases, results become unexpectedly completely
6193 wrong:
6194 ? \p100
6196 ? zetak(zetakinit(x^2-5), -1) - 1/30
6197 %1 = 7.26691813 E-108 \\ perfect
6198 ? \p150
6199 ? zetak(zetakinit(x^2-5), -1) - 1/30
6200 %2 = -2.486113578 E-156 \\ perfect
6201 ? \p200
6202 ? zetak(zetakinit(x^2-5), -1) - 1/30
6203 %3 = 4.47... E-75 \\ more than half of the digits are wrong
6204 ? \p250
6205 ? zetak(zetakinit(x^2-5), -1) - 1/30
6206 %4 = 1.6 E43 \\ junk
6207 The library syntax is glambdak"(znf,x,prec)" or " gzetak(znf,x,prec)".
6209 zetakinit"(x)"
6211 computes a number of initialization data concerning the number field
6212 defined by the polynomial "x" so as to be able to compute the Dedekind
6213 zeta and lambda functions (respectively zetak(x) and "zetak(x,1)").
6214 This function calls in particular the "bnfinit" program. The result is
6215 a 9-component vector "v" whose components are very technical and cannot
6216 really be used by the user except through the "zetak" function. The
6217 only component which can be used if it has not been computed already is
6218 "v[1][4]" which is the result of the "bnfinit" call.
6219 This function is very inefficient and should be rewritten. It needs to
6221 computes millions of coefficients of the corresponding Dirichlet series
6222 if the precision is big. Unless the discriminant is small it will not
6223 be able to handle more than 9 digits of relative precision. For
6224 instance, "zetakinit(x^8 - 2)" needs 440MB of memory at default
6225 precision.
6226 The library syntax is initzeta"(x)".
6228
6230 We group here all functions which are specific to polynomials or power
6231 series. Many other functions which can be applied on these objects are
6232 described in the other sections. Also, some of the functions described
6233 here can be applied to other types.
6234 O"(p^e)"
6236 if "p" is an integer greater than 2, returns a "p"-adic 0 of precision
6237 "e". In all other cases, returns a power series zero with precision
6238 given by "e v", where "v" is the "X"-adic valuation of "p" with respect
6239 to its main variable.
6240 The library syntax is zeropadic"(p,e)" for a "p"-adic and "
6242 zeroser(v,e)" for a power series zero in variable "v", which is a
6243 "long". The precision "e" is a "long".
6244 deriv"(x,{v})"
6246 derivative of "x" with respect to the main variable if "v" is omitted,
6247 and with respect to "v" otherwise. The derivative of a scalar type is
6248 zero, and the derivative of a vector or matrix is done componentwise.
6249 One can use "x'" as a shortcut if the derivative is with respect to the
6250 main variable of "x".
6251 By definition, the main variable of a "t_POLMOD" is the main variable
6253 among the coefficients from its two polynomial components
6254 (representative and modulus); in other words, assuming a polmod
6255 represents an element of "R[X]/(T(X))", the variable "X" is a mute
6256 variable and the derivative is taken with respect to the main variable
6257 used in the base ring "R".
6258 The library syntax is deriv"(x,v)", where "v" is a "long", and an
6260 omitted "v" is coded as "-1". When "x" is a "t_POL", derivpol(x) is a
6261 shortcut for "deriv(x, -1)".
6262 eval"(x)"
6264 replaces in "x" the formal variables by the values that have been
6265 assigned to them after the creation of "x". This is mainly useful in
6266 GP, and not in library mode. Do not confuse this with substitution (see
6267 "subst").
6268 If "x" is a character string, eval(x) executes "x" as a GP command, as
6270 if directly input from the keyboard, and returns its output. For
6271 convenience, "x" is evaluated as if "strictmatch" was off. In
6272 particular, unused characters at the end of "x" do not prevent its
6273 evaluation:
6274 ? eval("1a")
6276 % 1 = 1
6277 The library syntax is geval"(x)". The more basic functions "
6279 poleval(q,x)", " qfeval(q,x)", and " hqfeval(q,x)" evaluate "q" at "x",
6280 where "q" is respectively assumed to be a polynomial, a quadratic form
6281 (a symmetric matrix), or an Hermitian form (an Hermitian complex
6282 matrix).
6283 factorpadic"(pol,p,r,{flag = 0})"
6285 "p"-adic factorization of the polynomial pol to precision "r", the
6286 result being a two-column matrix as in "factor". The factors are
6287 normalized so that their leading coefficient is a power of "p". "r"
6288 must be strictly larger than the "p"-adic valuation of the discriminant
6289 of pol for the result to make any sense. The method used is a modified
6290 version of the round 4 algorithm of Zassenhaus.
6291 If "flag = 1", use an algorithm due to Buchmann and Lenstra, which is
6293 usually less efficient.
6294 The library syntax is factorpadic4"(pol,p,r)", where "r" is a "long"
6296 integer.
6297 intformal"(x,{v})"
6299 formal integration of "x" with respect to the main variable if "v" is
6300 omitted, with respect to the variable "v" otherwise. Since PARI does
6301 not know about ``abstract'' logarithms (they are immediately evaluated,
6302 if only to a power series), logarithmic terms in the result will yield
6303 an error. "x" can be of any type. When "x" is a rational function, it
6304 is assumed that the base ring is an integral domain of characteristic
6305 zero.
6306 The library syntax is integ"(x,v)", where "v" is a "long" and an
6308 omitted "v" is coded as "-1".
6309 padicappr"(pol,a)"
6311 vector of "p"-adic roots of the polynomial "pol" congruent to the
6312 "p"-adic number "a" modulo "p", and with the same "p"-adic precision as
6313 "a". The number "a" can be an ordinary "p"-adic number (type "t_PADIC",
6314 i.e. an element of "Z_p") or can be an integral element of a finite
6315 extension of "Q_p", given as a "t_POLMOD" at least one of whose
6316 coefficients is a "t_PADIC". In this case, the result is the vector of
6317 roots belonging to the same extension of "Q_p" as "a".
6318 The library syntax is padicappr"(pol,a)".
6320 polcoeff"(x,s,{v})"
6322 coefficient of degree "s" of the polynomial "x", with respect to the
6323 main variable if "v" is omitted, with respect to "v" otherwise. Also
6324 applies to power series, scalars (polynomial of degree 0), and to
6325 rational functions provided the denominator is a monomial.
6326 The library syntax is polcoeff0"(x,s,v)", where "v" is a "long" and an
6328 omitted "v" is coded as "-1". Also available is " truecoeff(x,v)".
6329 poldegree"(x,{v})"
6331 degree of the polynomial "x" in the main variable if "v" is omitted, in
6332 the variable "v" otherwise.
6333 The degree of 0 is a fixed negative number, whose exact value should
6335 not be used. The degree of a non-zero scalar is 0. Finally, when "x" is
6336 a non-zero polynomial or rational function, returns the ordinary degree
6337 of "x". Raise an error otherwise.
6338 The library syntax is poldegree"(x,v)", where "v" and the result are
6340 "long"s (and an omitted "v" is coded as "-1"). Also available is "
6341 degree(x)", which is equivalent to "poldegree(x,-1)".
6342 polcyclo"(n,{v = x})"
6344 "n"-th cyclotomic polynomial, in variable "v" ("x" by default). The
6345 integer "n" must be positive.
6346 The library syntax is cyclo"(n,v)", where "n" and "v" are "long"
6348 integers ("v" is a variable number, usually obtained through "varn").
6349 poldisc"(pol,{v})"
6351 discriminant of the polynomial pol in the main variable is "v" is
6352 omitted, in "v" otherwise. The algorithm used is the subresultant
6353 algorithm.
6354 The library syntax is poldisc0"(x,v)". Also available is " discsr(x)",
6356 equivalent to "poldisc0(x,-1)".
6357 poldiscreduced"(f)"
6359 reduced discriminant vector of the (integral, monic) polynomial "f".
6360 This is the vector of elementary divisors of
6361 "Z[alpha]/f'(alpha)Z[alpha]", where "alpha" is a root of the polynomial
6362 "f". The components of the result are all positive, and their product
6363 is equal to the absolute value of the discriminant of "f".
6364 The library syntax is reduceddiscsmith"(x)".
6366 polhensellift"(x, y, p, e)"
6368 given a prime "p", an integral polynomial "x" whose leading coefficient
6369 is a "p"-unit, a vector "y" of integral polynomials that are pairwise
6370 relatively prime modulo "p", and whose product is congruent to "x"
6371 modulo "p", lift the elements of "y" to polynomials whose product is
6372 congruent to "x" modulo "p^e".
6373 The library syntax is polhensellift"(x,y,p,e)" where "e" must be a
6375 "long".
6376 polinterpolate"(xa,{ya},{v = x},{&e})"
6378 given the data vectors "xa" and "ya" of the same length "n" ("xa"
6379 containing the "x"-coordinates, and "ya" the corresponding
6380 "y"-coordinates), this function finds the interpolating polynomial
6381 passing through these points and evaluates it at "v". If "ya" is
6382 omitted, return the polynomial interpolating the "(i,xa[i])". If
6383 present, "e" will contain an error estimate on the returned value.
6384 The library syntax is polint"(xa,ya,v,&e)", where "e" will contain an
6386 error estimate on the returned value.
6387 polisirreducible"(pol)"
6389 pol being a polynomial (univariate in the present version
6390 /usr/share/libpari23), returns 1 if pol is non-constant and
6391 irreducible, 0 otherwise. Irreducibility is checked over the smallest
6392 base field over which pol seems to be defined.
6393 The library syntax is gisirreducible"(pol)".
6395 pollead"(x,{v})"
6397 leading coefficient of the polynomial or power series "x". This is
6398 computed with respect to the main variable of "x" if "v" is omitted,
6399 with respect to the variable "v" otherwise.
6400 The library syntax is pollead"(x,v)", where "v" is a "long" and an
6402 omitted "v" is coded as "-1". Also available is " leading_term(x)".
6403 pollegendre"(n,{v = x})"
6405 creates the "n^{th}" Legendre polynomial, in variable "v".
6406 The library syntax is legendre"(n)", where "x" is a "long".
6408 polrecip"(pol)"
6410 reciprocal polynomial of pol, i.e. the coefficients are in reverse
6411 order. pol must be a polynomial.
6412 The library syntax is polrecip"(x)".
6414 polresultant"(x,y,{v},{flag = 0})"
6416 resultant of the two polynomials "x" and "y" with exact entries, with
6417 respect to the main variables of "x" and "y" if "v" is omitted, with
6418 respect to the variable "v" otherwise. The algorithm assumes the base
6419 ring is a domain.
6420 If "flag = 0", uses the subresultant algorithm.
6422 If "flag = 1", uses the determinant of Sylvester's matrix instead (here
6424 "x" and "y" may have non-exact coefficients).
6425 If "flag = 2", uses Ducos's modified subresultant algorithm. It should
6427 be much faster than the default if the coefficient ring is complicated
6428 (e.g multivariate polynomials or huge coefficients), and slightly
6429 slower otherwise.
6430 The library syntax is polresultant0"(x,y,v,flag)", where "v" is a
6432 "long" and an omitted "v" is coded as "-1". Also available are "
6433 subres(x,y)" ("flag = 0") and " resultant2(x,y)" ("flag = 1").
6434 polroots"(pol,{flag = 0})"
6436 complex roots of the polynomial pol, given as a column vector where
6437 each root is repeated according to its multiplicity. The precision is
6438 given as for transcendental functions: in GP it is kept in the variable
6439 "realprecision" and is transparent to the user, but it must be
6440 explicitly given as a second argument in library mode.
6441 The algorithm used is a modification of A. Schönhage's root-finding
6443 algorithm, due to and implemented by X. Gourdon. Barring bugs, it is
6444 guaranteed to converge and to give the roots to the required accuracy.
6445 If "flag = 1", use a variant of the Newton-Raphson method, which is
6447 \emph{not} guaranteed to converge, but is rather fast. If you get the
6448 messages ``too many iterations in roots'' or ``INTERNAL ERROR:
6449 incorrect result in roots'', use the default algorithm. This used to be
6450 the default root-finding function in PARI until version 1.39.06.
6451 The library syntax is roots"(pol,prec)" or " rootsold(pol,prec)".
6453 polrootsmod"(pol,p,{flag = 0})"
6455 row vector of roots modulo "p" of the polynomial pol. The particular
6456 non-prime value "p = 4" is accepted, mainly for 2-adic computations.
6457 Multiple roots are \emph{not} repeated.
6458 If "p" is very small, you may try setting "flag = 1", which uses a
6460 naive search.
6461 The library syntax is rootmod"(pol,p)" ("flag = 0") or "
6463 rootmod2(pol,p)" ("flag = 1").
6464 polrootspadic"(pol,p,r)"
6466 row vector of "p"-adic roots of the polynomial pol, given to "p"-adic
6467 precision "r". Multiple roots are \emph{not} repeated. "p" is assumed
6468 to be a prime, and pol to be non-zero modulo "p". Note that this is not
6469 the same as the roots in "Z/p^rZ", rather it gives approximations in
6470 "Z/p^rZ" of the true roots living in "Q_p".
6471 If pol has inexact "t_PADIC" coefficients, this is not always well-
6473 defined; in this case, the equation is first made integral, then lifted
6474 to Z. Hence the roots given are approximations of the roots of a
6475 polynomial which is "p"-adically close to the input.
6476 The library syntax is rootpadic"(pol,p,r)", where "r" is a "long".
6478 polsturm"(pol,{a},{b})"
6480 number of real roots of the real polynomial pol in the interval
6481 "]a,b]", using Sturm's algorithm. "a" (resp. "b") is taken to be "- oo
6482 " (resp. "+ oo ") if omitted.
6483 The library syntax is sturmpart"(pol,a,b)". Use "NULL" to omit an
6485 argument. " sturm(pol)" is equivalent to " sturmpart(pol,NULL,NULL)".
6486 The result is a "long".
6487 polsubcyclo"(n,d,{v = x})"
6489 gives polynomials (in variable "v") defining the sub-Abelian extensions
6490 of degree "d" of the cyclotomic field "Q(zeta_n)", where "d | phi(n)".
6491 If there is exactly one such extension the output is a polynomial, else
6493 it is a vector of polynomials, eventually empty.
6494 To be sure to get a vector, you can use "concat([],polsubcyclo(n,d))"
6496 The function "galoissubcyclo" allows to specify more closely which sub-
6498 Abelian extension should be computed.
6499 The library syntax is polsubcyclo"(n,d,v)", where "n", "d" and "v" are
6501 "long" and "v" is a variable number. When "(Z/nZ)^*" is cyclic, you can
6502 use " subcyclo(n,d,v)", where "n", "d" and "v" are "long" and "v" is a
6503 variable number.
6504 polsylvestermatrix"(x,y)"
6506 forms the Sylvester matrix corresponding to the two polynomials "x" and
6507 "y", where the coefficients of the polynomials are put in the columns
6508 of the matrix (which is the natural direction for solving equations
6509 afterwards). The use of this matrix can be essential when dealing with
6510 polynomials with inexact entries, since polynomial Euclidean division
6511 doesn't make much sense in this case.
6512 The library syntax is sylvestermatrix"(x,y)".
6514 polsym"(x,n)"
6516 creates the vector of the symmetric powers of the roots of the
6517 polynomial "x" up to power "n", using Newton's formula.
6518 The library syntax is polsym"(x)".
6520 poltchebi"(n,{v = x})"
6522 creates the "n^{th}" Chebyshev polynomial "T_n" of the first kind in
6523 variable "v".
6524 The library syntax is tchebi"(n,v)", where "n" and "v" are "long"
6526 integers ("v" is a variable number).
6527 polzagier"(n,m)"
6529 creates Zagier's polynomial "P_n^{(m)}" used in the functions "sumalt"
6530 and "sumpos" (with "flag = 1"). One must have "m <= n". The exact
6531 definition can be found in ``Convergence acceleration of alternating
6532 series'', Cohen et al., Experiment. Math., vol. 9, 2000, pp. 3--12.
6533 The library syntax is polzagreel"(n,m,prec)" if the result is only
6535 wanted as a polynomial with real coefficients to the precision "prec",
6536 or " polzag(n,m)" if the result is wanted exactly, where "n" and "m"
6537 are "long"s.
6538 serconvol"(x,y)"
6540 convolution (or Hadamard product) of the two power series "x" and "y";
6541 in other words if "x = sum a_k*X^k" and "y = sum b_k*X^k" then
6542 "serconvol(x,y) = sum a_k*b_k*X^k".
6543 The library syntax is convol"(x,y)".
6545 serlaplace"(x)"
6547 "x" must be a power series with non-negative exponents. If "x = sum
6548 (a_k/k!)*X^k" then the result is "sum a_k*X^k".
6549 The library syntax is laplace"(x)".
6551 serreverse"(x)"
6553 reverse power series (i.e. "x^{-1}", not "1/x") of "x". "x" must be a
6554 power series whose valuation is exactly equal to one.
6555 The library syntax is recip"(x)".
6557 subst"(x,y,z)"
6559 replace the simple variable "y" by the argument "z" in the
6560 ``polynomial'' expression "x". Every type is allowed for "x", but if it
6561 is not a genuine polynomial (or power series, or rational function),
6562 the substitution will be done as if the scalar components were
6563 polynomials of degree zero. In particular, beware that:
6564 ? subst(1, x, [1,2; 3,4])
6566 %1 =
6567 [1 0]
6568 [0 1]
6570 ? subst(1, x, Mat([0,1]))
6572 *** forbidden substitution by a non square matrix
6573 If "x" is a power series, "z" must be either a polynomial, a power
6575 series, or a rational function.
6576 The library syntax is gsubst"(x,y,z)", where "y" is the variable
6578 number.
6579 substpol"(x,y,z)"
6581 replace the ``variable'' "y" by the argument "z" in the ``polynomial''
6582 expression "x". Every type is allowed for "x", but the same behaviour
6583 as "subst" above apply.
6584 The difference with "subst" is that "y" is allowed to be any polynomial
6586 here. The substitution is done as per the following script:
6587 subst_poly(pol, from, to) =
6589 { local(t = 'subst_poly_t, M = from - t);
6590 subst(lift(Mod(pol,M), variable(M)), t, to)
6592 }
6593 For instance
6595 ? substpol(x^4 + x^2 + 1, x^2, y)
6597 %1 = y^2 + y + 1
6598 ? substpol(x^4 + x^2 + 1, x^3, y)
6599 %2 = x^2 + y*x + 1
6600 ? substpol(x^4 + x^2 + 1, (x+1)^2, y)
6601 %3 = (-4*y - 6)*x + (y^2 + 3*y - 3)
6602 The library syntax is gsubstpol"(x,y,z)".
6604 substvec"(x,v,w)"
6606 "v" being a vector of monomials (variables), "w" a vector of
6607 expressions of the same length, replace in the expression "x" all
6608 occurences of "v_i" by "w_i". The substitutions are done
6609 simultaneously; more precisely, the "v_i" are first replaced by new
6610 variables in "x", then these are replaced by the "w_i":
6611 ? substvec([x,y], [x,y], [y,x])
6613 %1 = [y, x]
6614 ? substvec([x,y], [x,y], [y,x+y])
6615 %2 = [y, x + y] \\ not [y, 2*y]
6616 The library syntax is gsubstvec"(x,v,w)".
6618 taylor"(x,y)"
6620 Taylor expansion around 0 of "x" with respect to the simple variable
6621 "y". "x" can be of any reasonable type, for example a rational
6622 function. The number of terms of the expansion is transparent to the
6623 user in GP, but must be given as a second argument in library mode.
6624 The library syntax is tayl"(x,y,n)", where the "long" integer "n" is
6626 the desired number of terms in the expansion.
6627 thue"(tnf,a,{sol})"
6629 solves the equation "P(x,y) = a" in integers "x" and "y", where tnf was
6630 created with thueinit(P). sol, if present, contains the solutions of
6631 "\Norm(x) = a" modulo units of positive norm in the number field
6632 defined by "P" (as computed by "bnfisintnorm"). If the result is
6633 conditional (on the GRH or some heuristic strenghtening), a Warning is
6634 printed. Otherwise, the result is unconditional, barring bugs. For
6635 instance, here's how to solve the Thue equation "x^{13} - 5y^{13} = -
6636 4":
6637 ? tnf = thueinit(x^13 - 5);
6639 ? thue(tnf, -4)
6640 %1 = [[1, 1]]
6641 Hence, the only solution is "x = 1", "y = 1" and the result is
6643 unconditional. On the other hand:
6644 ? tnf = thueinit(x^3-2*x^2+3*x-17);
6646 ? thue(tnf, -15)
6647 *** thue: Warning: Non trivial conditional class group.
6648 *** May miss solutions of the norm equation.
6649 %2 = [[1, 1]]
6650 This time the result is conditional. All results computed using this
6652 tnf are likewise conditional, \emph{except} for a right-hand side of
6653 "+- 1".
6654 The library syntax is thue"(tnf,a,sol)", where an omitted sol is coded
6656 as "NULL".
6657 thueinit"(P,{flag = 0})"
6659 initializes the tnf corresponding to "P". It is meant to be used in
6660 conjunction with "thue" to solve Thue equations "P(x,y) = a", where "a"
6661 is an integer. If "flag" is non-zero, certify the result
6662 unconditionnally. Otherwise, assume GRH, this being much faster of
6663 course.
6664 \emph{If} the conditional computed class group is trivial \emph{or} you
6666 are only interested in the case "a = +-1", then results are
6667 unconditional anyway. So one should only use the flag is "thue" prints
6668 a Warning (see the example there).
6669 The library syntax is thueinit"(P,flag,prec)".
6671
6673 Note that most linear algebra functions operating on subspaces defined
6674 by generating sets (such as "mathnf", "qflll", etc.) take matrices as
6675 arguments. As usual, the generating vectors are taken to be the
6676 \emph{columns} of the given matrix.
6677 Since PARI does not have a strong typing system, scalars live in
6679 unspecified commutative base rings. It is very difficult to write
6680 robust linear algebra routines in such a general setting. The
6681 developpers's choice has been to assume the base ring is a domain and
6682 work over its field of fractions. If the base ring is \emph{not} a
6683 domain, one gets an error as soon as a non-zero pivot turns out to be
6684 non-invertible. Some functions, e.g. "mathnf" or "mathnfmod",
6685 specifically assume the base ring is Z.
6686 algdep"(x,k,{flag = 0})"
6688 "x" being real/complex, or "p"-adic, finds a polynomial of degree at
6689 most "k" with integer coefficients having "x" as approximate root.
6690 Note that the polynomial which is obtained is not necessarily the
6691 ``correct'' one. In fact it is not even guaranteed to be irreducible.
6692 One can check the closeness either by a polynomial evaluation (use
6693 "subst"), or by computing the roots of the polynomial given by "algdep"
6694 (use "polroots").
6695 Internally, "lindep""([1,x,...,x^k], flag)" is used. If "lindep" is not
6697 able to find a relation and returns a lower bound for the sup norm of
6698 the smallest relation, "algdep" returns that bound instead. A suitable
6699 non-zero value of "flag" may improve on the default behaviour:
6700 \\\\\\\\\ LLL
6702 ? \p200
6703 ? algdep(2^(1/6)+3^(1/5), 30); \\ wrong in 3.8s
6704 ? algdep(2^(1/6)+3^(1/5), 30, 100); \\ wrong in 1s
6705 ? algdep(2^(1/6)+3^(1/5), 30, 170); \\ right in 3.3s
6706 ? algdep(2^(1/6)+3^(1/5), 30, 200); \\ wrong in 2.9s
6707 ? \p250
6708 ? algdep(2^(1/6)+3^(1/5), 30); \\ right in 2.8s
6709 ? algdep(2^(1/6)+3^(1/5), 30, 200); \\ right in 3.4s
6710 \\\\\\\\\ PSLQ
6711 ? \p200
6712 ? algdep(2^(1/6)+3^(1/5), 30, -3); \\ failure in 14s.
6713 ? \p250
6714 ? algdep(2^(1/6)+3^(1/5), 30, -3); \\ right in 18s
6715 Proceeding by increments of 5 digits of accuracy, "algdep" with default
6717 flag produces its first correct result at 205 digits, and from then on
6718 a steady stream of correct results. Interestingly enough, our PSLQ also
6719 reliably succeeds from 205 digits on (and is 5 times slower at that
6720 accuracy).
6721 The above example is the testcase studied in a 2000 paper by Borwein
6723 and Lisonek, Applications of integer relation algorithms,
6724 \emph{Discrete Math.}, 217, p. 65--82. The paper conludes in the
6725 superiority of the PSLQ algorithm, which either shows that PARI's
6726 implementation of PSLQ is lacking, or that its LLL is extremely good.
6727 The version of PARI tested there was 1.39, which succeeded reliably
6728 from precision 265 on, in about 60 as much time as the current version.
6729 The library syntax is algdep0"(x,k,flag,prec)", where "k" and "flag"
6731 are "long"s. Also available is " algdep(x,k,prec)" ("flag = 0").
6732 charpoly"(A,{v = x},{flag = 0})"
6734 characteristic polynomial of "A" with respect to the variable "v",
6735 i.e. determinant of "v*I-A" if "A" is a square matrix. If "A" is not a
6736 square matrix, it returns the characteristic polynomial of the map
6737 ``multiplication by "A"'' if "A" is a scalar, in particular a polmod.
6738 E.g. "charpoly(I) = x^2+1".
6739 The value of "flag" is only significant for matrices.
6741 If "flag = 0", the method used is essentially the same as for computing
6743 the adjoint matrix, i.e. computing the traces of the powers of "A".
6744 If "flag = 1", uses Lagrange interpolation which is almost always
6746 slower.
6747 If "flag = 2", uses the Hessenberg form. This is faster than the
6749 default when the coefficients are intmod a prime or real numbers, but
6750 is usually slower in other base rings.
6751 The library syntax is charpoly0"(A,v,flag)", where "v" is the variable
6753 number. Also available are the functions " caract(A,v)" ("flag = 1"), "
6754 carhess(A,v)" ("flag = 2"), and " caradj(A,v,pt)" where, in this last
6755 case, pt is a "GEN*" which, if not equal to "NULL", will receive the
6756 address of the adjoint matrix of "A" (see "matadjoint"), so both can be
6757 obtained at once.
6758 concat"(x,{y})"
6760 concatenation of "x" and "y". If "x" or "y" is not a vector or matrix,
6761 it is considered as a one-dimensional vector. All types are allowed for
6762 "x" and "y", but the sizes must be compatible. Note that matrices are
6763 concatenated horizontally, i.e. the number of rows stays the same.
6764 Using transpositions, it is easy to concatenate them vertically.
6765 To concatenate vectors sideways (i.e. to obtain a two-row or two-column
6767 matrix), use "Mat" instead (see the example there). Concatenating a row
6768 vector to a matrix having the same number of columns will add the row
6769 to the matrix (top row if the vector is "x", i.e. comes first, and
6770 bottom row otherwise).
6771 The empty matrix "[;]" is considered to have a number of rows
6773 compatible with any operation, in particular concatenation. (Note that
6774 this is definitely \emph{not} the case for empty vectors "[ ]" or
6775 "[ ]~".)
6776 If "y" is omitted, "x" has to be a row vector or a list, in which case
6778 its elements are concatenated, from left to right, using the above
6779 rules.
6780 ? concat([1,2], [3,4])
6782 %1 = [1, 2, 3, 4]
6783 ? a = [[1,2]~, [3,4]~]; concat(a)
6784 %2 =
6785 [1 3]
6786 [2 4]
6788 ? concat([1,2; 3,4], [5,6]~)
6790 %3 =
6791 [1 2 5]
6792 [3 4 6]
6794 ? concat([%, [7,8]~, [1,2,3,4]])
6795 %5 =
6796 [1 2 5 7]
6797 [3 4 6 8]
6799 [1 2 3 4]
6801 The library syntax is concat"(x,y)".
6803 lindep"(x,{flag = 0})"
6805 "x" being a vector with "p"-adic or real/complex coefficients, finds a
6806 small integral linear combination among these coefficients.
6807 If "x" is "p"-adic, "flag" is meaningless and the algorithm LLL-reduces
6809 a suitable (dual) lattice.
6810 Otherwise, the value of "flag" determines the algorithm used; in the
6812 current version of PARI, we suggest to use \emph{non-negative} values,
6813 since it is by far the fastest and most robust implementation. See the
6814 detailed example in "Label se:algdep" ("algdep").
6815 If "flag >= 0", uses a floating point (variable precision) LLL
6817 algorithm. This is in general much faster than the other variants. If
6818 "flag = 0" the accuracy is chosen internally using a crude heuristic.
6819 If "flag > 0" the computation is done with an accuracy of "flag"
6820 decimal digits. In that case, the parameter "flag" should be between
6821 0.6 and 0.9 times the number of correct decimal digits in the input.
6822 If "flag = -1", uses a variant of the LLL algorithm due to Hastad,
6824 Lagarias and Schnorr (STACS 1986). If the precision is too low, the
6825 routine may enter an infinite loop.
6826 If "flag = -2", "x" is allowed to be (and in any case interpreted as) a
6828 matrix. Returns a non trivial element of the kernel of "x", or 0 if
6829 "x" has trivial kernel. The element is defined over the field of
6830 coefficients of "x", and is in general not integral.
6831 If "flag = -3", uses the PSLQ algorithm. This may return a real number
6833 "B", indicating that the input accuracy was exhausted and that no
6834 relation exist whose sup norm is less than "B".
6835 If "flag = -4", uses an experimental 2-level PSLQ, which does not work
6837 at all. (Should be rewritten.)
6838 The library syntax is lindep0"(x,flag,prec)". Also available is "
6840 lindep(x,prec)" ("flag = 0").
6841 listcreate"(n)"
6843 creates an empty list of maximal length "n".
6844 This function is useless in library mode.
6846 listinsert"(list,x,n)"
6848 inserts the object "x" at position "n" in list (which must be of type
6849 "t_LIST"). All the remaining elements of list (from position "n+1"
6850 onwards) are shifted to the right. This and "listput" are the only
6851 commands which enable you to increase a list's effective length (as
6852 long as it remains under the maximal length specified at the time of
6853 the "listcreate").
6854 This function is useless in library mode.
6856 listkill"(list)"
6858 kill list. This deletes all elements from list and sets its effective
6859 length to 0. The maximal length is not affected.
6860 This function is useless in library mode.
6862 listput"(list,x,{n})"
6864 sets the "n"-th element of the list list (which must be of type
6865 "t_LIST") equal to "x". If "n" is omitted, or greater than the list
6866 current effective length, just appends "x". This and "listinsert" are
6867 the only commands which enable you to increase a list's effective
6868 length (as long as it remains under the maximal length specified at the
6869 time of the "listcreate").
6870 If you want to put an element into an occupied cell, i.e. if you don't
6872 want to change the effective length, you can consider the list as a
6873 vector and use the usual "list[n] = x" construct.
6874 This function is useless in library mode.
6876 listsort"(list,{flag = 0})"
6878 sorts list (which must be of type "t_LIST") in place. If "flag" is non-
6879 zero, suppresses all repeated coefficients. This is much faster than
6880 the "vecsort" command since no copy has to be made.
6881 This function is useless in library mode.
6883 matadjoint"(x)"
6885 adjoint matrix of "x", i.e. the matrix "y" of cofactors of "x",
6886 satisfying "x*y = det (x)*\Id". "x" must be a (non-necessarily
6887 invertible) square matrix.
6888 The library syntax is adj"(x)".
6890 matcompanion"(x)"
6892 the left companion matrix to the polynomial "x".
6893 The library syntax is assmat"(x)".
6895 matdet"(x,{flag = 0})"
6897 determinant of "x". "x" must be a square matrix.
6898 If "flag = 0", uses Gauss-Bareiss.
6900 If "flag = 1", uses classical Gaussian elimination, which is better
6902 when the entries of the matrix are reals or integers for example, but
6903 usually much worse for more complicated entries like multivariate
6904 polynomials.
6905 The library syntax is det"(x)" ("flag = 0") and " det2(x)" ("flag =
6907 1").
6908 matdetint"(x)"
6910 "x" being an "m x n" matrix with integer coefficients, this function
6911 computes a \emph{multiple} of the determinant of the lattice generated
6912 by the columns of "x" if it is of rank "m", and returns zero otherwise.
6913 This function can be useful in conjunction with the function
6914 "mathnfmod" which needs to know such a multiple. To obtain the exact
6915 determinant (assuming the rank is maximal), you can compute
6916 "matdet(mathnfmod(x, matdetint(x)))".
6917 Note that as soon as one of the dimensions gets large ("m" or "n" is
6919 larger than 20, say), it will often be much faster to use "mathnf(x,
6920 1)" or "mathnf(x, 4)" directly.
6921 The library syntax is detint"(x)".
6923 matdiagonal"(x)"
6925 "x" being a vector, creates the diagonal matrix whose diagonal entries
6926 are those of "x".
6927 The library syntax is diagonal"(x)".
6929 mateigen"(x)"
6931 gives the eigenvectors of "x" as columns of a matrix.
6932 The library syntax is eigen"(x)".
6934 matfrobenius"(M,{flag = 0},{v = x})"
6936 returns the Frobenius form of the square matrix "M". If "flag = 1",
6937 returns only the elementary divisors as a vectr of polynomials in the
6938 variable "v". If "flag = 2", returns a two-components vector [F,B]
6939 where "F" is the Frobenius form and "B" is the basis change so that "M
6940 = B^{-1}FB".
6941 The library syntax is matfrobenius"(M,flag,v)", where "v" is the
6943 variable number.
6944 mathess"(x)"
6946 Hessenberg form of the square matrix "x".
6947 The library syntax is hess"(x)".
6949 mathilbert"(x)"
6951 "x" being a "long", creates the Hilbert matrixof order "x", i.e. the
6952 matrix whose coefficient ("i","j") is "1/ (i+j-1)".
6953 The library syntax is mathilbert"(x)".
6955 mathnf"(x,{flag = 0})"
6957 if "x" is a (not necessarily square) matrix with integer entries, finds
6958 the \emph{upper triangular} Hermite normal form of "x". If the rank of
6959 "x" is equal to its number of rows, the result is a square matrix. In
6960 general, the columns of the result form a basis of the lattice spanned
6961 by the columns of "x".
6962 If "flag = 0", uses the naive algorithm. This should never be used if
6964 the dimension is at all large (larger than 10, say). It is recommanded
6965 to use either "mathnfmod(x, matdetint(x))" (when "x" has maximal rank)
6966 or "mathnf(x, 1)". Note that the latter is in general faster than
6967 "mathnfmod", and also provides a base change matrix.
6968 If "flag = 1", uses Batut's algorithm, which is much faster than the
6970 default. Outputs a two-component row vector "[H,U]", where "H" is the
6971 \emph{upper triangular} Hermite normal form of "x" defined as above,
6972 and "U" is the unimodular transformation matrix such that "xU = [0|H]".
6973 "U" has in general huge coefficients, in particular when the kernel is
6974 large.
6975 If "flag = 3", uses Batut's algorithm, but outputs "[H,U,P]", such that
6977 "H" and "U" are as before and "P" is a permutation of the rows such
6978 that "P" applied to "xU" gives "H". The matrix "U" is smaller than with
6979 "flag = 1", but may still be large.
6980 If "flag = 4", as in case 1 above, but uses a heuristic variant of LLL
6982 reduction along the way. The matrix "U" is in general close to optimal
6983 (in terms of smallest "L_2" norm), but the reduction is slower than in
6984 case 1.
6985 The library syntax is mathnf0"(x,flag)". Also available are " hnf(x)"
6987 ("flag = 0") and " hnfall(x)" ("flag = 1"). To reduce \emph{huge} (say
6988 "400 x 400" and more) relation matrices (sparse with small entries),
6989 you can use the pair "hnfspec" / "hnfadd". Since this is rather
6990 technical and the calling interface may change, they are not documented
6991 yet. Look at the code in "basemath/alglin1.c".
6992 mathnfmod"(x,d)"
6994 if "x" is a (not necessarily square) matrix of maximal rank with
6995 integer entries, and "d" is a multiple of the (non-zero) determinant of
6996 the lattice spanned by the columns of "x", finds the \emph{upper
6997 triangular} Hermite normal form of "x".
6998 If the rank of "x" is equal to its number of rows, the result is a
7000 square matrix. In general, the columns of the result form a basis of
7001 the lattice spanned by the columns of "x". This is much faster than
7002 "mathnf" when "d" is known.
7003 The library syntax is hnfmod"(x,d)".
7005 mathnfmodid"(x,d)"
7007 outputs the (upper triangular) Hermite normal form of "x" concatenated
7008 with "d" times the identity matrix. Assumes that "x" has integer
7009 entries.
7010 The library syntax is hnfmodid"(x,d)".
7012 matid"(n)"
7014 creates the "n x n" identity matrix.
7015 The library syntax is matid"(n)" where "n" is a "long".
7017 Related functions are " gscalmat(x,n)", which creates "x" times the
7019 identity matrix ("x" being a "GEN" and "n" a "long"), and "
7020 gscalsmat(x,n)" which is the same when "x" is a "long".
7021 matimage"(x,{flag = 0})"
7023 gives a basis for the image of the matrix "x" as columns of a matrix. A
7024 priori the matrix can have entries of any type. If "flag = 0", use
7025 standard Gauss pivot. If "flag = 1", use "matsupplement".
7026 The library syntax is matimage0"(x,flag)". Also available is "
7028 image(x)" ("flag = 0").
7029 matimagecompl"(x)"
7031 gives the vector of the column indices which are not extracted by the
7032 function "matimage". Hence the number of components of matimagecompl(x)
7033 plus the number of columns of matimage(x) is equal to the number of
7034 columns of the matrix "x".
7035 The library syntax is imagecompl"(x)".
7037 matindexrank"(x)"
7039 "x" being a matrix of rank "r", gives two vectors "y" and "z" of length
7040 "r" giving a list of rows and columns respectively (starting from 1)
7041 such that the extracted matrix obtained from these two vectors using
7042 "vecextract(x,y,z)" is invertible.
7043 The library syntax is indexrank"(x)".
7045 matintersect"(x,y)"
7047 "x" and "y" being two matrices with the same number of rows each of
7048 whose columns are independent, finds a basis of the Q-vector space
7049 equal to the intersection of the spaces spanned by the columns of "x"
7050 and "y" respectively. See also the function "idealintersect", which
7051 does the same for free Z-modules.
7052 The library syntax is intersect"(x,y)".
7054 matinverseimage"(M,y)"
7056 gives a column vector belonging to the inverse image "z" of the column
7057 vector or matrix "y" by the matrix "M" if one exists (i.e such that "Mz
7058 = y"), the empty vector otherwise. To get the complete inverse image,
7059 it suffices to add to the result any element of the kernel of "x"
7060 obtained for example by "matker".
7061 The library syntax is inverseimage"(x,y)".
7063 matisdiagonal"(x)"
7065 returns true (1) if "x" is a diagonal matrix, false (0) if not.
7066 The library syntax is isdiagonal"(x)", and this returns a "long"
7068 integer.
7069 matker"(x,{flag = 0})"
7071 gives a basis for the kernel of the matrix "x" as columns of a matrix.
7072 A priori the matrix can have entries of any type.
7073 If "x" is known to have integral entries, set "flag = 1".
7075 Note: The library function "FpM_ker(x, p)", where "x" has integer
7077 entries \emph{reduced mod p} and "p" is prime, is equivalent to, but
7078 orders of magnitude faster than, "matker(x*Mod(1,p))" and needs much
7079 less stack space. To use it under "gp", type "install(FpM_ker, GG)"
7080 first.
7081 The library syntax is matker0"(x,flag)". Also available are " ker(x)"
7083 ("flag = 0"), " keri(x)" ("flag = 1").
7084 matkerint"(x,{flag = 0})"
7086 gives an LLL-reduced Z-basis for the lattice equal to the kernel of the
7087 matrix "x" as columns of the matrix "x" with integer entries (rational
7088 entries are not permitted).
7089 If "flag = 0", uses a modified integer LLL algorithm.
7091 If "flag = 1", uses "matrixqz(x,-2)". If LLL reduction of the final
7093 result is not desired, you can save time using "matrixqz(matker(x),-2)"
7094 instead.
7095 The library syntax is matkerint0"(x,flag)". Also available is "
7097 kerint(x)" ("flag = 0").
7098 matmuldiagonal"(x,d)"
7100 product of the matrix "x" by the diagonal matrix whose diagonal entries
7101 are those of the vector "d". Equivalent to, but much faster than
7102 "x*matdiagonal(d)".
7103 The library syntax is matmuldiagonal"(x,d)".
7105 matmultodiagonal"(x,y)"
7107 product of the matrices "x" and "y" assuming that the result is a
7108 diagonal matrix. Much faster than "x*y" in that case. The result is
7109 undefined if "x*y" is not diagonal.
7110 The library syntax is matmultodiagonal"(x,y)".
7112 matpascal"(x,{q})"
7114 creates as a matrix the lower triangular Pascal triangle of order "x+1"
7115 (i.e. with binomial coefficients up to "x"). If "q" is given, compute
7116 the "q"-Pascal triangle (i.e. using "q"-binomial coefficients).
7117 The library syntax is matqpascal"(x,q)", where "x" is a "long" and "q =
7119 NULL" is used to omit "q". Also available is " matpascal(x)".
7120 matrank"(x)"
7122 rank of the matrix "x".
7123 The library syntax is rank"(x)", and the result is a "long".
7125 matrix"(m,n,{X},{Y},{expr = 0})"
7127 creation of the "m x n" matrix whose coefficients are given by the
7128 expression expr. There are two formal parameters in expr, the first one
7129 ("X") corresponding to the rows, the second ("Y") to the columns, and
7130 "X" goes from 1 to "m", "Y" goes from 1 to "n". If one of the last 3
7131 parameters is omitted, fill the matrix with zeroes.
7132 The library syntax is matrice"(GEN nlig,GEN ncol,entree *e1,entree
7134 *e2,char *expr)".
7135 matrixqz"(x,p)"
7137 "x" being an "m x n" matrix with "m >= n" with rational or integer
7138 entries, this function has varying behaviour depending on the sign of
7139 "p":
7140 If "p >= 0", "x" is assumed to be of maximal rank. This function
7142 returns a matrix having only integral entries, having the same image as
7143 "x", such that the GCD of all its "n x n" subdeterminants is equal to 1
7144 when "p" is equal to 0, or not divisible by "p" otherwise. Here "p"
7145 must be a prime number (when it is non-zero). However, if the function
7146 is used when "p" has no small prime factors, it will either work or
7147 give the message ``impossible inverse modulo'' and a non-trivial
7148 divisor of "p".
7149 If "p = -1", this function returns a matrix whose columns form a basis
7151 of the lattice equal to "Z^n" intersected with the lattice generated by
7152 the columns of "x".
7153 If "p = -2", returns a matrix whose columns form a basis of the lattice
7155 equal to "Z^n" intersected with the Q-vector space generated by the
7156 columns of "x".
7157 The library syntax is matrixqz0"(x,p)".
7159 matsize"(x)"
7161 "x" being a vector or matrix, returns a row vector with two components,
7162 the first being the number of rows (1 for a row vector), the second the
7163 number of columns (1 for a column vector).
7164 The library syntax is matsize"(x)".
7166 matsnf"(X,{flag = 0})"
7168 if "X" is a (singular or non-singular) matrix outputs the vector of
7169 elementary divisors of "X" (i.e. the diagonal of the Smith normal form
7170 of "X").
7171 The binary digits of flag mean:
7173 1 (complete output): if set, outputs "[U,V,D]", where "U" and "V" are
7175 two unimodular matrices such that "UXV" is the diagonal matrix "D".
7176 Otherwise output only the diagonal of "D".
7177 2 (generic input): if set, allows polynomial entries, in which case the
7179 input matrix must be square. Otherwise, assume that "X" has integer
7180 coefficients with arbitrary shape.
7181 4 (cleanup): if set, cleans up the output. This means that elementary
7183 divisors equal to 1 will be deleted, i.e. outputs a shortened vector
7184 "D'" instead of "D". If complete output was required, returns
7185 "[U',V',D']" so that "U'XV' = D'" holds. If this flag is set, "X" is
7186 allowed to be of the form "D" or "[U,V,D]" as would normally be output
7187 with the cleanup flag unset.
7188 The library syntax is matsnf0"(X,flag)". Also available is " smith(X)"
7190 ("flag = 0").
7191 matsolve"(x,y)"
7193 "x" being an invertible matrix and "y" a column vector, finds the
7194 solution "u" of "x*u = y", using Gaussian elimination. This has the
7195 same effect as, but is a bit faster, than "x^{-1}*y".
7196 The library syntax is gauss"(x,y)".
7198 matsolvemod"(m,d,y,{flag = 0})"
7200 "m" being any integral matrix, "d" a vector of positive integer moduli,
7201 and "y" an integral column vector, gives a small integer solution to
7202 the system of congruences "sum_i m_{i,j}x_j = y_i (mod d_i)" if one
7203 exists, otherwise returns zero. Shorthand notation: "y" (resp. "d") can
7204 be given as a single integer, in which case all the "y_i" (resp. "d_i")
7205 above are taken to be equal to "y" (resp. "d").
7206 ? m = [1,2;3,4];
7208 ? matsolvemod(m, [3,4], [1,2]~)
7209 %2 = [-2, 0]~
7210 ? matsolvemod(m, 3, 1) \\ m X = [1,1]~ over F_3
7211 %3 = [-1, 1]~
7212 If "flag = 1", all solutions are returned in the form of a two-
7214 component row vector "[x,u]", where "x" is a small integer solution to
7215 the system of congruences and "u" is a matrix whose columns give a
7216 basis of the homogeneous system (so that all solutions can be obtained
7217 by adding "x" to any linear combination of columns of "u"). If no
7218 solution exists, returns zero.
7219 The library syntax is matsolvemod0"(m,d,y,flag)". Also available are "
7221 gaussmodulo(m,d,y)" ("flag = 0") and " gaussmodulo2(m,d,y)" ("flag =
7222 1").
7223 matsupplement"(x)"
7225 assuming that the columns of the matrix "x" are linearly independent
7226 (if they are not, an error message is issued), finds a square
7227 invertible matrix whose first columns are the columns of "x",
7228 i.e. supplement the columns of "x" to a basis of the whole space.
7229 The library syntax is suppl"(x)".
7231 mattranspose"(x)" or "x~"
7233 transpose of "x". This has an effect only on vectors and matrices.
7234 The library syntax is gtrans"(x)".
7236 minpoly"(A,{v = x},{flag = 0})"
7238 minimal polynomial of "A" with respect to the variable "v"., i.e. the
7239 monic polynomial "P" of minimal degree (in the variable "v") such that
7240 "P(A) = 0".
7241 The library syntax is minpoly"(A,v)", where "v" is the variable number.
7243 qfgaussred"(q)"
7245 decomposition into squares of the quadratic form represented by the
7246 symmetric matrix "q". The result is a matrix whose diagonal entries are
7247 the coefficients of the squares, and the non-diagonal entries represent
7248 the bilinear forms. More precisely, if "(a_{ij})" denotes the output,
7249 one has
7250 " q(x) = sum_i a_{ii} (x_i + sum_{j > i} a_{ij} x_j)^2 "
7252 The library syntax is sqred"(x)".
7254 qfjacobi"(x)"
7256 "x" being a real symmetric matrix, this gives a vector having two
7257 components: the first one is the vector of eigenvalues of "x", the
7258 second is the corresponding orthogonal matrix of eigenvectors of "x".
7259 The method used is Jacobi's method for symmetric matrices.
7260 The library syntax is jacobi"(x)".
7262 qflll"(x,{flag = 0})"
7264 LLL algorithm applied to the \emph{columns} of the matrix "x". The
7265 columns of "x" must be linearly independent, unless specified otherwise
7266 below. The result is a unimodular transformation matrix "T" such that
7267 "x.T" is an LLL-reduced basis of the lattice generated by the column
7268 vectors of "x".
7269 If "flag = 0" (default), the computations are done with floating point
7271 numbers, using Householder matrices for orthogonalization. If "x" has
7272 integral entries, then computations are nonetheless approximate, with
7273 precision varying as needed (Lehmer's trick, as generalized by
7274 Schnorr).
7275 If "flag = 1", it is assumed that "x" is integral. The computation is
7277 done entirely with integers. In this case, "x" needs not be of maximal
7278 rank, but if it is not, "T" will not be square. This is slower and no
7279 more accurate than "flag = 0" above if "x" has small dimension (say 100
7280 or less).
7281 If "flag = 2", "x" should be an integer matrix whose columns are
7283 linearly independent. Returns a partially reduced basis for "x", using
7284 an unpublished algorithm by Peter Montgomery: a basis is said to be
7285 \emph{partially reduced} if "|v_i +- v_j| >= |v_i|" for any two
7286 distinct basis vectors "v_i, v_j".
7287 This is significantly faster than "flag = 1", esp. when one row is huge
7289 compared to the other rows. Note that the resulting basis is \emph{not}
7290 LLL-reduced in general.
7291 If "flag = 4", "x" is assumed to have integral entries, but needs not
7293 be of maximal rank. The result is a two-component vector of matrices:
7294 the columns of the first matrix represent a basis of the integer kernel
7295 of "x" (not necessarily LLL-reduced) and the second matrix is the
7296 transformation matrix "T" such that "x.T" is an LLL-reduced Z-basis of
7297 the image of the matrix "x".
7298 If "flag = 5", case as case 4, but "x" may have polynomial
7300 coefficients.
7301 If "flag = 8", same as case 0, but "x" may have polynomial
7303 coefficients.
7304 The library syntax is qflll0"(x,flag,prec)". Also available are "
7306 lll(x,prec)" ("flag = 0"), " lllint(x)" ("flag = 1"), and "
7307 lllkerim(x)" ("flag = 4").
7308 qflllgram"(G,{flag = 0})"
7310 same as "qflll", except that the matrix "G = x~ * x" is the Gram matrix
7311 of some lattice vectors "x", and not the coordinates of the vectors
7312 themselves. In particular, "G" must now be a square symmetric real
7313 matrix, corresponding to a positive definite quadratic form. The result
7314 is a unimodular transformation matrix "T" such that "x.T" is an LLL-
7315 reduced basis of the lattice generated by the column vectors of "x".
7316 If "flag = 0" (default): the computations are done with floating point
7318 numbers, using Householder matrices for orthogonalization. If "G" has
7319 integral entries, then computations are nonetheless approximate, with
7320 precision varying as needed (Lehmer's trick, as generalized by
7321 Schnorr).
7322 If "flag = 1": "G" has integer entries, still positive but not
7324 necessarily definite (i.e "x" needs not have maximal rank). The
7325 computations are all done in integers and should be slower than the
7326 default, unless the latter triggers accuracy problems.
7327 "flag = 4": "G" has integer entries, gives the kernel and reduced image
7329 of "x".
7330 "flag = 5": same as case 4, but "G" may have polynomial coefficients.
7332 The library syntax is qflllgram0"(G,flag,prec)". Also available are "
7334 lllgram(G,prec)" ("flag = 0"), " lllgramint(G)" ("flag = 1"), and "
7335 lllgramkerim(G)" ("flag = 4").
7336 qfminim"(x,{b},{m},{flag = 0})"
7338 "x" being a square and symmetric matrix representing a positive
7339 definite quadratic form, this function deals with the vectors of "x"
7340 whose norm is less than or equal to "b", enumerated using the Fincke-
7341 Pohst algorithm. The function searches for the minimal non-zero vectors
7342 if "b" is omitted. The precise behaviour depends on "flag".
7343 If "flag = 0" (default), seeks at most "2m" vectors. The result is a
7345 three-component vector, the first component being the number of vectors
7346 found, the second being the maximum norm found, and the last vector is
7347 a matrix whose columns are the vectors found, only one being given for
7348 each pair "+- v" (at most "m" such pairs). The vectors are returned in
7349 no particular order. In this variant, an explicit "m" must be provided.
7350 If "flag = 1", ignores "m" and returns the first vector whose norm is
7352 less than "b". In this variant, an explicit "b" must be provided.
7353 In both these cases, "x" is assumed to have integral entries. The
7355 implementation uses low precision floating point computations for
7356 maximal speed, which gives incorrect result when "x" has large entries.
7357 (The condition is checked in the code and the routine will raise an
7358 error if large rounding errors occur.) A more robust, but much slower,
7359 implementation is chosen if the following flag is used:
7360 If "flag = 2", "x" can have non integral real entries. In this case, if
7362 "b" is omitted, the ``minimal'' vectors only have approximately the
7363 same norm. If "b" is omitted, "m" is an upper bound for the number of
7364 vectors that will be stored and returned, but all minimal vectors are
7365 nevertheless enumerated. If "m" is omitted, all vectors found are
7366 stored and returned; note that this may be a huge vector!
7367 The library syntax is qfminim0"(x,b,m,flag,prec)", also available are "
7369 minim(x,b,m)" ("flag = 0"), " minim2(x,b,m)" ("flag = 1"). In all
7370 cases, an omitted "b" or "m" is coded as "NULL".
7371 qfperfection"(x)"
7373 "x" being a square and symmetric matrix with integer entries
7374 representing a positive definite quadratic form, outputs the perfection
7375 rank of the form. That is, gives the rank of the family of the "s"
7376 symmetric matrices "v_iv_i^t", where "s" is half the number of minimal
7377 vectors and the "v_i" ("1 <= i <= s") are the minimal vectors.
7378 As a side note to old-timers, this used to fail bluntly when "x" had
7380 more than 5000 minimal vectors. Beware that the computations can now be
7381 very lengthy when "x" has many minimal vectors.
7382 The library syntax is perf"(x)".
7384 qfrep"(q, B, {flag = 0})"
7386 "q" being a square and symmetric matrix with integer entries
7387 representing a positive definite quadratic form, outputs the vector
7388 whose "i"-th entry, "1 <= i <= B" is half the number of vectors "v"
7389 such that "q(v) = i". This routine uses a naive algorithm based on
7390 "qfminim", and will fail if any entry becomes larger than "2^{31}".
7391 The binary digits of flag mean:
7393 \item 1: count vectors of even norm from 1 to "2B".
7395 \item 2: return a "t_VECSMALL" instead of a "t_GEN"
7397 The library syntax is qfrep0"(q, B, flag)".
7399 qfsign"(x)"
7401 signature of the quadratic form represented by the symmetric matrix
7402 "x". The result is a two-component vector.
7403 The library syntax is signat"(x)".
7405 setintersect"(x,y)"
7407 intersection of the two sets "x" and "y".
7408 The library syntax is setintersect"(x,y)".
7410 setisset"(x)"
7412 returns true (1) if "x" is a set, false (0) if not. In PARI, a set is
7413 simply a row vector whose entries are strictly increasing. To convert
7414 any vector (and other objects) into a set, use the function "Set".
7415 The library syntax is setisset"(x)", and this returns a "long".
7417 setminus"(x,y)"
7419 difference of the two sets "x" and "y", i.e. set of elements of "x"
7420 which do not belong to "y".
7421 The library syntax is setminus"(x,y)".
7423 setsearch"(x,y,{flag = 0})"
7425 searches if "y" belongs to the set "x". If it does and "flag" is zero
7426 or omitted, returns the index "j" such that "x[j] = y", otherwise
7427 returns 0. If "flag" is non-zero returns the index "j" where "y" should
7428 be inserted, and 0 if it already belongs to "x" (this is meant to be
7429 used in conjunction with "listinsert").
7430 This function works also if "x" is a \emph{sorted} list (see
7432 "listsort").
7433 The library syntax is setsearch"(x,y,flag)" which returns a "long"
7435 integer.
7436 setunion"(x,y)"
7438 union of the two sets "x" and "y".
7439 The library syntax is setunion"(x,y)".
7441 trace"(x)"
7443 this applies to quite general "x". If "x" is not a matrix, it is equal
7444 to the sum of "x" and its conjugate, except for polmods where it is the
7445 trace as an algebraic number.
7446 For "x" a square matrix, it is the ordinary trace. If "x" is a non-
7448 square matrix (but not a vector), an error occurs.
7449 The library syntax is gtrace"(x)".
7451 vecextract"(x,y,{z})"
7453 extraction of components of the vector or matrix "x" according to "y".
7454 In case "x" is a matrix, its components are as usual the \emph{columns}
7455 of "x". The parameter "y" is a component specifier, which is either an
7456 integer, a string describing a range, or a vector.
7457 If "y" is an integer, it is considered as a mask: the binary bits of
7459 "y" are read from right to left, but correspond to taking the
7460 components from left to right. For example, if "y = 13 = (1101)_2" then
7461 the components 1,3 and 4 are extracted.
7462 If "y" is a vector, which must have integer entries, these entries
7464 correspond to the component numbers to be extracted, in the order
7465 specified.
7466 If "y" is a string, it can be
7468 \item a single (non-zero) index giving a component number (a negative
7470 index means we start counting from the end).
7471 \item a range of the form "a..b", where "a" and "b" are indexes as
7473 above. Any of "a" and "b" can be omitted; in this case, we take as
7474 default values "a = 1" and "b = -1", i.e. the first and last components
7475 respectively. We then extract all components in the interval "[a,b]",
7476 in reverse order if "b < a".
7477 In addition, if the first character in the string is "^", the
7479 complement of the given set of indices is taken.
7480 If "z" is not omitted, "x" must be a matrix. "y" is then the
7482 \emph{line} specifier, and "z" the \emph{column} specifier, where the
7483 component specifier is as explained above.
7484 %4 = [e, d, c]
7486 ? vecextract(v, "^2") \\ mask
7487 %4 = [e, d, c]
7488 ? vecextract(v, "^2") \\ component list
7489 %4 = [e, d, c]
7490 ? vecextract(v, "^2") \\ interval
7491 %4 = [e, d, c]
7492 ? vecextract(v, "^2") \\ interval + reverse order
7493 %4 = [e, d, c]
7494 ? vecextract(v, "^2") \\ complement
7495 %5 = [a, c, d, e]
7496 ? vecextract(matid(3), "2..", "..")
7497 %6 =
7498 [0 1 0]
7499 [0 0 1]
7501 The library syntax is extract"(x,y)" or " matextract(x,y,z)".
7503 vecsort"(x,{k},{flag = 0})"
7505 sorts the vector "x" in ascending order, using a mergesort method. "x"
7506 must be a vector, and its components integers, reals, or fractions.
7507 If "k" is present and is an integer, sorts according to the value of
7509 the "k"-th subcomponents of the components of "x". Note that mergesort
7510 is stable, hence is the initial ordering of "equal" entries (with
7511 respect to the sorting criterion) is not changed.
7512 "k" can also be a vector, in which case the sorting is done
7514 lexicographically according to the components listed in the vector "k".
7515 For example, if "k = [2,1,3]", sorting will be done with respect to the
7516 second component, and when these are equal, with respect to the first,
7517 and when these are equal, with respect to the third.
7518 The binary digits of flag mean:
7520 \item 1: indirect sorting of the vector "x", i.e. if "x" is an
7522 "n"-component vector, returns a permutation of "[1,2,...,n]" which
7523 applied to the components of "x" sorts "x" in increasing order. For
7524 example, "vecextract(x, vecsort(x,,1))" is equivalent to vecsort(x).
7525 \item 2: sorts "x" by ascending lexicographic order (as per the "lex"
7527 comparison function).
7528 \item 4: use descending instead of ascending order.
7530 The library syntax is vecsort0"(x,k,flag)". To omit "k", use "NULL"
7532 instead. You can also use the simpler functions
7533 " sort(x)" ( = " vecsort0(x,NULL,0)").
7535 " indexsort(x)" ( = " vecsort0(x,NULL,1)").
7537 " lexsort(x)" ( = " vecsort0(x,NULL,2)").
7539 Also available are " sindexsort(x)" and " sindexlexsort(x)" which
7541 return a "t_VECSMALL" "v", where "v[1]...v[n]" contain the indices.
7542 vector"(n,{X},{expr = 0})"
7544 creates a row vector (type "t_VEC") with "n" components whose
7545 components are the expression expr evaluated at the integer points
7546 between 1 and "n". If one of the last two arguments is omitted, fill
7547 the vector with zeroes.
7548 Avoid modifying "X" within expr; if you do, the formal variable still
7550 runs from 1 to "n". In particular, "vector(n,i,expr)" is not equivalent
7551 to
7552 v = vector(n)
7554 for (i = 1, n, v[i] = expr)
7555 as the following example shows:
7557 n = 3
7559 v = vector(n); vector(n, i, i++) ----> [2, 3, 4]
7560 v = vector(n); for (i = 1, n, v[i] = i++) ----> [2, 0, 4]
7561 The library syntax is vecteur"(GEN nmax, entree *ep, char *expr)".
7563 vectorsmall"(n,{X},{expr = 0})"
7565 creates a row vector of small integers (type "t_VECSMALL") with "n"
7566 components whose components are the expression expr evaluated at the
7567 integer points between 1 and "n". If one of the last two arguments is
7568 omitted, fill the vector with zeroes.
7569 The library syntax is vecteursmall"(GEN nmax, entree *ep, char *expr)".
7571 vectorv"(n,X,expr)"
7573 as "vector", but returns a column vector (type "t_COL").
7574 The library syntax is vvecteur"(GEN nmax, entree *ep, char *expr)".
7576
7578 Although the "gp" calculator is programmable, it is useful to have
7579 preprogrammed a number of loops, including sums, products, and a
7580 certain number of recursions. Also, a number of functions from
7581 numerical analysis like numerical integration and summation of series
7582 will be described here.
7583 One of the parameters in these loops must be the control variable,
7585 hence a simple variable name. In the descriptions, the letter "X" will
7586 always denote any simple variable name, and represents the formal
7587 parameter used in the function. The expression to be summed,
7588 integrated, etc. is any legal PARI expression, including of course
7589 expressions using loops.
7590 Library mode. Since it is easier to program directly the loops in
7592 library mode, these functions are mainly useful for GP programming.
7593 Using them in library mode is tricky and we will not give any details,
7594 although the reader can try and figure it out by himself by checking
7595 the example given for "sum".
7596 On the other hand, numerical routines code a function (to be
7598 integrated, summed, etc.) with two parameters named
7599 GEN (*eval)(GEN,void*)
7601 void *E;
7602 The second is meant to contain all auxilliary data needed by your
7604 function. The first is such that "eval(x, E)" returns your function
7605 evaluated at "x". For instance, one may code the family of functions
7606 "f_t: x \to (x+t)^2" via
7607 GEN f(GEN x, void *t) { return gsqr(gadd(x, (GEN)t)); }
7609 One can then integrate "f_1" between "a" and "b" with the call
7611 intnum((void*)stoi(1), &fun, a, b, NULL, prec);
7613 Since you can set "E" to a pointer to any "struct" (typecast to
7615 "void*") the above mechanism handles arbitrary functions. For simple
7616 functions without extra parameters, you may set "E = NULL" and ignore
7617 that argument in your function definition.
7618 Numerical integration. Starting with version 2.2.9 the powerful
7620 ``double exponential'' univariate integration method is implemented in
7621 "intnum" and its variants. Romberg integration is still available under
7622 the name "intnumromb", but superseded. It is possible to compute
7623 numerically integrals to thousands of decimal places in reasonable
7624 time, as long as the integrand is regular. It is also reasonable to
7625 compute numerically integrals in several variables, although more than
7626 two becomes lengthy. The integration domain may be non-compact, and the
7627 integrand may have reasonable singularities at endpoints. To use
7628 "intnum", the user must split the integral into a sum of subintegrals
7629 where the function has (possible) singularities only at the endpoints.
7630 Polynomials in logarithms are not considered singular, and neglecting
7631 these logs, singularities are assumed to be algebraic (in other words
7632 asymptotic to "C(x-a)^{-alpha}" for some "alpha" such that "alpha > -1"
7633 when "x" is close to "a"), or to correspond to simple discontinuities
7634 of some (higher) derivative of the function. For instance, the point 0
7635 is a singularity of abs(x).
7636 See also the discrete summation methods below (sharing the prefix
7638 "sum").
7639 intcirc"(X = a,R,expr, {tab})"
7641 numerical integration of expr with respect to "X" on the circle "|X-a
7642 |= R", divided by "2iPi". In other words, when expr is a meromorphic
7643 function, sum of the residues in the corresponding disk. tab is as in
7644 "intnum", except that if computed with "intnuminit" it should be with
7645 the endpoints "[-1, 1]".
7646 ? \p105
7648 ? intcirc(s=1, 0.5, zeta(s)) - 1
7649 time = 3,460 ms.
7650 %1 = -2.40... E-104 - 2.7... E-106*I
7651 The library syntax is intcirc"(void *E, GEN (*eval)(GEN,void*), GEN
7653 a,GEN R,GEN tab, long prec)".
7654 intfouriercos"(X = a,b,z,expr,{tab})"
7656 numerical integration of "expr(X) cos (2Pi zX)" from "a" to "b", in
7657 other words Fourier cosine transform (from "a" to "b") of the function
7658 represented by expr. "a" and "b" are coded as in "intnum", and are not
7659 necessarily at infinity, but if they are, oscillations (i.e.
7660 "[[+-1],alpha I]") are forbidden.
7661 The library syntax is intfouriercos"(void *E, GEN (*eval)(GEN,void*),
7663 GEN a, GEN b, GEN z, GEN tab, long prec)".
7664 intfourierexp"(X = a,b,z,expr,{tab})"
7666 numerical integration of "expr(X) exp (-2Pi zX)" from "a" to "b", in
7667 other words Fourier transform (from "a" to "b") of the function
7668 represented by expr. Note the minus sign. "a" and "b" are coded as in
7669 "intnum", and are not necessarily at infinity but if they are,
7670 oscillations (i.e. "[[+-1],alpha I]") are forbidden.
7671 The library syntax is intfourierexp"(void *E, GEN (*eval)(GEN,void*),
7673 GEN a, GEN b, GEN z, GEN tab, long prec)".
7674 intfouriersin"(X = a,b,z,expr,{tab})"
7676 numerical integration of "expr(X) sin (2Pi zX)" from "a" to "b", in
7677 other words Fourier sine transform (from "a" to "b") of the function
7678 represented by expr. "a" and "b" are coded as in "intnum", and are not
7679 necessarily at infinity but if they are, oscillations (i.e.
7680 "[[+-1],alpha I]") are forbidden.
7681 The library syntax is intfouriersin"(void *E, GEN (*eval)(GEN,void*),
7683 GEN a, GEN b, GEN z, GEN tab, long prec)".
7684 intfuncinit"(X = a,b,expr,{flag = 0},{m = 0})"
7686 initalize tables for use with integral transforms such as
7687 "intmellininv", etc., where "a" and "b" are coded as in "intnum",
7688 "expr" is the function s(X) to which the integral transform is to be
7689 applied (which will multiply the weights of integration) and "m" is as
7690 in "intnuminit". If "flag" is nonzero, assumes that "s(-X) =
7691 \overline{s(X)}", which makes the computation twice as fast. See
7692 "intmellininvshort" for examples of the use of this function, which is
7693 particularly useful when the function s(X) is lengthy to compute, such
7694 as a gamma product.
7695 The library syntax is intfuncinit"(void *E, GEN (*eval)(GEN,void*), GEN
7697 a,GEN b,long m, long flag, long prec)". Note that the order of "m" and
7698 "flag" are reversed compared to the "GP" syntax.
7699 intlaplaceinv"(X = sig,z,expr,{tab})"
7701 numerical integration of "expr(X)e^{Xz}" with respect to "X" on the
7702 line " Re (X) = sig", divided by "2iPi", in other words, inverse
7703 Laplace transform of the function corresponding to expr at the value
7704 "z".
7705 "sig" is coded as follows. Either it is a real number "sigma", equal to
7707 the abcissa of integration, and then the function to be integrated is
7708 assumed to be slowly decreasing when the imaginary part of the variable
7709 tends to "+- oo ". Or it is a two component vector "[sigma,alpha]",
7710 where "sigma" is as before, and either "alpha = 0" for slowly
7711 decreasing functions, or "alpha > 0" for functions decreasing like "
7712 exp (-alpha t)". Note that it is not necessary to choose the exact
7713 value of "alpha". tab is as in "intnum".
7714 It is often a good idea to use this function with a value of "m" one or
7716 two higher than the one chosen by default (which can be viewed thanks
7717 to the function "intnumstep"), or to increase the abcissa of
7718 integration "sigma". For example:
7719 ? intlaplaceinv(x=100, 1, 1/x) - 1
7721 time = 330 ms.
7722 %7 = 1.07... E-72 + 3.2... E-72*I \\ not so good
7723 ? intlaplaceinv(x=100, 1, 1/x) - 1
7724 time = 330 ms.
7725 %7 = 1.07... E-72 + 3.2... E-72*I \\ better
7726 ? intlaplaceinv(x=100, 1, 1/x) - 1
7727 time = 330 ms.
7728 %7 = 1.07... E-72 + 3.2... E-72*I \\ perfect but slow.
7729 ? intlaplaceinv(x=100, 1, 1/x) - 1
7730 time = 330 ms.
7731 %7 = 1.07... E-72 + 3.2... E-72*I \\ better than %1
7732 ? intlaplaceinv(x=100, 1, 1/x) - 1
7733 time = 330 ms.
7734 %7 = 1.07... E-72 + 3.2... E-72*I \\ perfect, fast.
7735 ? intlaplaceinv(x=100, 1, 1/x) - 1
7736 time = 330 ms.
7737 %7 = 1.07... E-72 + 3.2... E-72*I \\ perfect, fastest, but why sig = 10?
7738 ? intlaplaceinv(x=100, 1, 1/x) - 1
7739 time = 330 ms.
7740 %7 = 1.07... E-72 + 3.2... E-72*I \\ too far now...
7741 The library syntax is intlaplaceinv"(void *E, GEN (*eval)(GEN,void*),
7743 GEN sig,GEN z, GEN tab, long prec)".
7744 intmellininv"(X = sig,z,expr,{tab})"
7746 numerical integration of "expr(X)z^{-X}" with respect to "X" on the
7747 line " Re (X) = sig", divided by "2iPi", in other words, inverse Mellin
7748 transform of the function corresponding to expr at the value "z".
7749 "sig" is coded as follows. Either it is a real number "sigma", equal to
7751 the abcissa of integration, and then the function to be integrated is
7752 assumed to decrease exponentially fast, of the order of " exp (-t)"
7753 when the imaginary part of the variable tends to "+- oo ". Or it is a
7754 two component vector "[sigma,alpha]", where "sigma" is as before, and
7755 either "alpha = 0" for slowly decreasing functions, or "alpha > 0" for
7756 functions decreasing like " exp (-alpha t)", such as gamma products.
7757 Note that it is not necessary to choose the exact value of "alpha", and
7758 that "alpha = 1" (equivalent to "sig" alone) is usually sufficient. tab
7759 is as in "intnum".
7760 As all similar functions, this function is provided for the convenience
7762 of the user, who could use "intnum" directly. However it is in general
7763 better to use "intmellininvshort".
7764 ? \p 308
7766 ? intmellininv(s=2,4, gamma(s)^3);
7767 time = 51,300 ms. \\ reasonable.
7768 ? \p 308
7769 ? intmellininv(s=2,4, gamma(s)^3);
7770 time = 51,300 ms. \\ slow because of Gamma(s)^3.
7771 The library syntax is intmellininv"(void *E, GEN (*eval)(GEN,void*),
7773 GEN sig, GEN z, GEN tab, long prec)".
7774 intmellininvshort"(sig,z,tab)"
7776 numerical integration of "s(X)z^{-X}" with respect to "X" on the line "
7777 Re (X) = sig", divided by "2iPi", in other words, inverse Mellin
7778 transform of s(X) at the value "z". Here s(X) is implicitly contained
7779 in tab in "intfuncinit" format, typically
7780 tab = intfuncinit(T = [-1], [1], s(sig + I*T))
7782 or similar commands. Take the example of the inverse Mellin transform
7784 of "Gamma(s)^3" given in "intmellininv":
7785 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7787 ? intmellininvshort(2,4, tab2)
7788 %6 = -1.2...E-42 - 3.2...E-109*I \\ for clarity
7789 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7790 ? intmellininvshort(2,4, tab2)
7791 %6 = -1.2...E-42 - 3.2...E-109*I \\ not too fast because of Gamma(s)^3.
7792 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7793 ? intmellininvshort(2,4, tab2)
7794 %6 = -1.2...E-42 - 3.2...E-109*I \\ function of real type, decreasing as exp(-3Pi/2.|t|)
7795 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7796 ? intmellininvshort(2,4, tab2)
7797 %6 = -1.2...E-42 - 3.2...E-109*I \\ 50 times faster than A and perfect.
7798 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7799 ? intmellininvshort(2,4, tab2)
7800 %6 = -1.2...E-42 - 3.2...E-109*I \\ 63 digits lost
7801 In the computation of tab, it was not essential to include the
7803 \emph{exact} exponential decrease of "Gamma(2+it)^3". But as the last
7804 example shows, a rough indication \emph{must} be given, otherwise slow
7805 decrease is assumed, resulting in catastrophic loss of accuracy.
7806 The library syntax is intmellininvshort"(GEN sig, GEN z, GEN tab, long
7808 prec)".
7809 intnum"(X = a,b,expr,{tab})"
7811 numerical integration of expr on "[a,b]" (possibly infinite interval)
7812 with respect to "X", where "a" and "b" are coded as explained below.
7813 The integrand may have values belonging to a vector space over the real
7814 numbers; in particular, it can be complex-valued or vector-valued.
7815 If tab is omitted, necessary integration tables are computed using
7817 "intnuminit" according to the current precision. It may be a positive
7818 integer "m", and tables are computed assuming the integration step is
7819 "1/2^m". Finally tab can be a table output by "intnuminit", in which
7820 case it is used directly. This is important if several integrations of
7821 the same type are performed (on the same kind of interval and
7822 functions, and the same accuracy), since it saves expensive
7823 precomputations.
7824 If tab is omitted the algorithm guesses a reasonable value for "m"
7826 depending on the current precision. That value may be obtained as
7827 intnumstep()
7829 However this value may be off from the optimal one, and this is
7831 important since the integration time is roughly proportional to "2^m".
7832 One may try consecutive values of "m" until they give the same value up
7833 to an accepted error.
7834 The endpoints "a" and "b" are coded as follows. If "a" is not at "+- oo
7836 ", it is either coded as a scalar (real or complex), or as a two
7837 component vector "[a,alpha]", where the function is assumed to have a
7838 singularity of the form "(x-a)^{alpha+\epsilon}" at "a", where
7839 "\epsilon" indicates that powers of logarithms are neglected. In
7840 particular, "[a,alpha]" with "alpha >= 0" is equivalent to "a". If a
7841 wrong singularity exponent is used, the result will lose a catastrophic
7842 number of decimals, for instance approximately half the number of
7843 digits will be correct if "alpha = -1/2" is omitted.
7844 The endpoints of integration can be "+- oo ", which is coded as "[+-
7846 1]" or as "[[+-1],alpha]". Here "alpha" codes the behaviour of the
7847 function at "+- oo " as follows.
7848 \item "alpha = 0" (or no "alpha" at all, i.e. simply "[+-1]") assumes
7850 that the function to be integrated tends to zero, but not exponentially
7851 fast, and not oscillating such as " sin (x)/x".
7852 \item "alpha > 0" assumes that the function tends to zero exponentially
7854 fast approximately as " exp (-alpha x)", including reasonably
7855 oscillating functions such as " exp (-x) sin (x)". The precise choice
7856 of "alpha", while useful in extreme cases, is not critical, and may be
7857 off by a \emph{factor} of 10 or more from the correct value.
7858 \item "alpha < -1" assumes that the function tends to 0 slowly, like
7860 "x^{alpha}". Here it is essential to give the correct "alpha", if
7861 possible, but on the other hand "alpha <= -2" is equivalent to "alpha =
7862 0", in other words to no "alpha" at all.
7863 The last two codes are reserved for oscillating functions. Let "k > 0"
7865 real, and g(x) a nonoscillating function tending to 0, then
7866 \item "alpha = k I" assumes that the function behaves like " cos
7868 (kx)g(x)".
7869 \item "alpha = -kI" assumes that the function behaves like " sin
7871 (kx)g(x)".
7872 Here it is critical to give the exact value of "k". If the oscillating
7874 part is not a pure sine or cosine, one must expand it into a Fourier
7875 series, use the above codings, and sum the resulting contributions.
7876 Otherwise you will get nonsense. Note that " cos (kx)" (and similarly "
7877 sin (kx)") means that very function, and not a translated version such
7878 as " cos (kx+a)".
7879 If for instance "f(x) = cos (kx)g(x)" where g(x) tends to zero
7881 exponentially fast as " exp (-alpha x)", it is up to the user to choose
7882 between "[[+-1],alpha]" and "[[+-1],kI]", but a good rule of thumb is
7883 that if the oscillations are much weaker than the exponential decrease,
7884 choose "[[+-1],alpha]", otherwise choose "[[+-1],kI]", although the
7885 latter can reasonably be used in all cases, while the former cannot. To
7886 take a specific example, in the inverse Mellin transform, the function
7887 to be integrated is almost always exponentially decreasing times
7888 oscillating. If we choose the oscillating type of integral we perhaps
7889 obtain the best results, at the expense of having to recompute our
7890 functions for a different value of the variable "z" giving the
7891 transform, preventing us to use a function such as "intmellininvshort".
7892 On the other hand using the exponential type of integral, we obtain
7893 less accurate results, but we skip expensive recomputations. See
7894 "intmellininvshort" and "intfuncinit" for more explanations.
7895 Note. If you do not like the code "[+-1]" for "+- oo ", you are welcome
7897 to set, e.g "oo = [1]" or "INFINITY = [1]", then using "+oo", "-oo",
7898 "-INFINITY", etc. will have the expected behaviour.
7899 We shall now see many examples to get a feeling for what the various
7901 parameters achieve. All examples below assume precision is set to 105
7902 decimal digits. We first type
7903 ? \p 105
7905 ? oo = [1] \\ for clarity
7906 Apparent singularities. Even if the function f(x) represented by expr
7908 has no singularities, it may be important to define the function
7909 differently near special points. For instance, if "f(x) = 1 /( exp
7910 (x)-1) - exp (-x)/x", then "int_0^ oo f(x)dx = gamma", Euler's
7911 constant "Euler". But
7912 ? f(x) = 1/(exp(x)-1) - exp(-x)/x
7914 ? intnum(x = 0, [oo,1], f(x)) - Euler
7915 %1 = 6.00... E-67
7916 thus only correct to 76 decimal digits. This is because close to 0 the
7918 function "f" is computed with an enormous loss of accuracy. A better
7919 solution is
7920 ? intnum(x = 0, [oo,1], g(x)) - Euler
7922 %2 = 0.E-106 \\ expansion around t = 0
7923 ? intnum(x = 0, [oo,1], g(x)) - Euler
7924 %2 = 0.E-106 \\ note that 6.18 > 105
7925 ? intnum(x = 0, [oo,1], g(x)) - Euler
7926 %2 = 0.E-106 \\ perfect
7927 It is up to the user to determine constants such as the "10^{-18}" and
7929 7 used above.
7930 True singularities. With true singularities the result is much worse.
7932 For instance
7933 ? intnum(x = [0,-1/2], 1, 1/sqrt(x)) - 2
7935 %2 = 0.E-105 \\ only 59 correct decimals
7936 ? intnum(x = [0,-1/2], 1, 1/sqrt(x)) - 2
7938 %2 = 0.E-105 \\ better
7939 Oscillating functions.
7941 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7943 %6 = 0.0092... \\ nonsense
7944 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7946 %6 = 0.0092... \\ bad
7947 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7949 %6 = 0.0092... \\ perfect
7950 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7952 %6 = 0.0092... \\ oops, wrong k
7953 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7955 %6 = 0.0092... \\ perfect
7956 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7958 %6 = 0.0092... \\ bad
7959 ? sin(x)^3 - (3*sin(x)-sin(3*x))/4
7960 %7 = O(x^17)
7961 We may use the above linearization and compute two oscillating
7963 integrals with ``infinite endpoints'' "[oo, -I]" and "[oo, -3*I]"
7964 respectively, or notice the obvious change of variable, and reduce to
7965 the single integral "(1/2)int_0^ oo sin (x)/xdx". We finish with some
7966 more complicated examples:
7967 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7969 %6 = 5.45... E-107 \\ bad
7970 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7971 %6 = 5.45... E-107 \\ OK
7972 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7973 %6 = 5.45... E-107 \\ OK
7974 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7975 %6 = 5.45... E-107 \\ lost 16 decimals. Try higher m:
7976 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7977 %6 = 5.45... E-107 \\ the value of m actually used above.
7978 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7979 %6 = 5.45... E-107 \\ try m one higher.
7980 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7981 %6 = 5.45... E-107 \\ OK this time.
7982 Warning. Like "sumalt", "intnum" often assigns a reasonable value to
7984 diverging integrals. Use these values at your own risk! For example:
7985 ? intnum(x = 0, [oo, -I], x^2*sin(x))
7987 %1 = -2.0000000000...
7988 Note the formula
7990 " int_0^ oo sin (x)/x^sdx = cos (Pi s/2) Gamma(1-s) , "
7992 a priori valid only for "0 < Re (s) < 2", but the right hand side
7994 provides an analytic continuation which may be evaluated at "s = -2"...
7995 Multivariate integration. Using successive univariate integration with
7997 respect to different formal parameters, it is immediate to do naive
7998 multivariate integration. But it is important to use a suitable
7999 "intnuminit" to precompute data for the \emph{internal} integrations at
8000 least!
8001 For example, to compute the double integral on the unit disc "x^2+y^2
8003 <= 1" of the function "x^2+y^2", we can write
8004 ? tab = intnuminit(-1,1);
8006 ? intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2, tab), tab)
8007 The first tab is essential, the second optional. Compare:
8009 ? intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2, tab), tab);
8011 time = 7,210 ms. \\ slow
8012 ? intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2, tab), tab);
8013 time = 7,210 ms. \\ faster
8014 However, the "intnuminit" program is usually pessimistic when it comes
8016 to choosing the integration step "2^{-m}". It is often possible to
8017 improve the speed by trial and error. Continuing the above example:
8018 ? test(m - 3)
8020 time = 120 ms.
8021 %3 = -7.23... E-60 \\ what value of m did it take ?
8022 ? test(m - 3)
8023 time = 120 ms.
8024 %3 = -7.23... E-60 \\ 4 = 2^2 times faster and still OK.
8025 ? test(m - 3)
8026 time = 120 ms.
8027 %3 = -7.23... E-60 \\ 16 = 2^4 times faster and still OK.
8028 ? test(m - 3)
8029 time = 120 ms.
8030 %3 = -7.23... E-60 \\ 64 = 2^6 times faster, lost 45 decimals.
8031 The library syntax is intnum"(void *E, GEN (*eval)(GEN,void*), GEN
8033 a,GEN b,GEN tab, long prec)", where an omitted tab is coded as "NULL".
8034 intnuminit"(a,b,{m = 0})"
8036 initialize tables for integration from "a" to "b", where "a" and "b"
8037 are coded as in "intnum". Only the compactness, the possible existence
8038 of singularities, the speed of decrease or the oscillations at infinity
8039 are taken into account, and not the values. For instance
8040 "intnuminit(-1,1)" is equivalent to "intnuminit(0,Pi)", and
8041 "intnuminit([0,-1/2],[1])" is equivalent to "
8042 intnuminit([-1],[-1,-1/2])". If "m" is not given, it is computed
8043 according to the current precision. Otherwise the integration step is
8044 "1/2^m". Reasonable values of "m" are "m = 6" or "m = 7" for 100
8045 decimal digits, and "m = 9" for 1000 decimal digits.
8046 The result is technical, but in some cases it is useful to know the
8048 output. Let "x = phi(t)" be the change of variable which is used.
8049 tab[1] contains the integer "m" as above, either given by the user or
8050 computed from the default precision, and can be recomputed directly
8051 using the function "intnumstep". tab[2] and tab[3] contain
8052 respectively the abcissa and weight corresponding to "t = 0" ("phi(0)"
8053 and "phi'(0)"). tab[4] and tab[5] contain the abcissas and weights
8054 corresponding to positive "t = nh" for "1 <= n <= N" and "h = 1/2^m"
8055 ("phi(nh)" and "phi'(nh)"). Finally tab[6] and tab[7] contain either
8056 the abcissas and weights corresponding to negative "t = nh" for "-N <=
8057 n <= -1", or may be empty (but not always) if "phi(t)" is an odd
8058 function (implicitly we would have "tab[6] = -tab[4]" and "tab[7] =
8059 tab[5]").
8060 The library syntax is intnuminit"(GEN a, GEN b, long m, long prec)".
8062 intnumromb"(X = a,b,expr,{flag = 0})"
8064 numerical integration of expr (smooth in "]a,b["), with respect to "X".
8065 This function is deprecated, use "intnum" instead.
8066 Set "flag = 0" (or omit it altogether) when "a" and "b" are not too
8068 large, the function is smooth, and can be evaluated exactly everywhere
8069 on the interval "[a,b]".
8070 If "flag = 1", uses a general driver routine for doing numerical
8072 integration, making no particular assumption (slow).
8073 "flag = 2" is tailored for being used when "a" or "b" are infinite. One
8075 \emph{must} have "ab > 0", and in fact if for example "b = + oo ", then
8076 it is preferable to have "a" as large as possible, at least "a >= 1".
8077 If "flag = 3", the function is allowed to be undefined (but continuous)
8079 at "a" or "b", for example the function " sin (x)/x" at "x = 0".
8080 The user should not require too much accuracy: 18 or 28 decimal digits
8082 is OK, but not much more. In addition, analytical cleanup of the
8083 integral must have been done: there must be no singularities in the
8084 interval or at the boundaries. In practice this can be accomplished
8085 with a simple change of variable. Furthermore, for improper integrals,
8086 where one or both of the limits of integration are plus or minus
8087 infinity, the function must decrease sufficiently rapidly at infinity.
8088 This can often be accomplished through integration by parts. Finally,
8089 the function to be integrated should not be very small (compared to the
8090 current precision) on the entire interval. This can of course be
8091 accomplished by just multiplying by an appropriate constant.
8092 Note that infinity can be represented with essentially no loss of
8094 accuracy by 1e1000. However beware of real underflow when dealing with
8095 rapidly decreasing functions. For example, if one wants to compute the
8096 "int_0^ oo e^{-x^2}dx" to 28 decimal digits, then one should set
8097 infinity equal to 10 for example, and certainly not to 1e1000.
8098 The library syntax is intnumromb"(void *E, GEN (*eval)(GEN,void*), GEN
8100 a, GEN b, long flag, long prec)", where "eval(x, E)" returns the value
8101 of the function at "x". You may store any additional information
8102 required by "eval" in "E", or set it to "NULL".
8103 intnumstep"()"
8105 give the value of "m" used in all the "intnum" and "sumnum" programs,
8106 hence such that the integration step is equal to "1/2^m".
8107 The library syntax is intnumstep"(long prec)".
8109 prod"(X = a,b,expr,{x = 1})"
8111 product of expression expr, initialized at "x", the formal parameter
8112 "X" going from "a" to "b". As for "sum", the main purpose of the
8113 initialization parameter "x" is to force the type of the operations
8114 being performed. For example if it is set equal to the integer 1,
8115 operations will start being done exactly. If it is set equal to the
8116 real 1., they will be done using real numbers having the default
8117 precision. If it is set equal to the power series "1+O(X^k)" for a
8118 certain "k", they will be done using power series of precision at most
8119 "k". These are the three most common initializations.
8120 As an extreme example, compare
8122 ? prod(i=1, 100, 1 - X^i); \\ this has degree 5050 !!
8124 time = 3,335 ms.
8125 ? prod(i=1, 100, 1 - X^i, 1 + O(X^101))
8126 time = 43 ms.
8127 %2 = 1 - X - X^2 + X^5 + X^7 - X^12 - X^15 + X^22 + X^26 - X^35 - X^40 + \
8128 X^51 + X^57 - X^70 - X^77 + X^92 + X^100 + O(X^101)
8129 The library syntax is produit"(entree *ep, GEN a, GEN b, char *expr,
8131 GEN x)".
8132 prodeuler"(X = a,b,expr)"
8134 product of expression expr, initialized at 1. (i.e. to a \emph{real}
8135 number equal to 1 to the current "realprecision"), the formal parameter
8136 "X" ranging over the prime numbers between "a" and "b".
8137 The library syntax is prodeuler"(void *E, GEN (*eval)(GEN,void*), GEN
8139 a,GEN b, long prec)".
8140 prodinf"(X = a,expr,{flag = 0})"
8142 infinite product of expression expr, the formal parameter "X" starting
8143 at "a". The evaluation stops when the relative error of the expression
8144 minus 1 is less than the default precision. The expressions must always
8145 evaluate to an element of C.
8146 If "flag = 1", do the product of the ("1+expr") instead.
8148 The library syntax is prodinf"(void *E, GEN (*eval)(GEN, void*), GEN a,
8150 long prec)" ("flag = 0"), or prodinf1 with the same arguments ("flag =
8151 1").
8152 solve"(X = a,b,expr)"
8154 find a real root of expression expr between "a" and "b", under the
8155 condition "expr(X = a) * expr(X = b) <= 0". This routine uses Brent's
8156 method and can fail miserably if expr is not defined in the whole of
8157 "[a,b]" (try "solve(x = 1, 2, tan(x)").
8158 The library syntax is zbrent"(void *E,GEN (*eval)(GEN,void*),GEN a,GEN
8160 b,long prec)".
8161 sum"(X = a,b,expr,{x = 0})"
8163 sum of expression expr, initialized at "x", the formal parameter going
8164 from "a" to "b". As for "prod", the initialization parameter "x" may be
8165 given to force the type of the operations being performed.
8166 As an extreme example, compare
8168 ? sum(i=1, 5000, 1/i); \\ rational number: denominator has 2166 digits.
8170 time = 1,241 ms.
8171 ? sum(i=1, 5000, 1/i, 0.)
8172 time = 158 ms.
8173 %2 = 9.094508852984436967261245533
8174 The library syntax is somme"(entree *ep, GEN a, GEN b, char *expr, GEN
8176 x)". This is to be used as follows: "ep" represents the dummy variable
8177 used in the expression "expr"
8178 /* compute a^2 + ... + b^2 */
8180 {
8181 /* define the dummy variable "i" */
8182 entree *ep = is_entry("i");
8183 /* sum for a <= i <= b */
8184 return somme(ep, a, b, "i^2", gen_0);
8185 }
8186 sumalt"(X = a,expr,{flag = 0})"
8188 numerical summation of the series expr, which should be an alternating
8189 series, the formal variable "X" starting at "a". Use an algorithm of
8190 F. Villegas as modified by D. Zagier (improves on Euler-Van Wijngaarden
8191 method).
8192 If "flag = 1", use a variant with slightly different polynomials.
8194 Sometimes faster.
8195 Divergent alternating series can sometimes be summed by this method, as
8197 well as series which are not exactly alternating (see for example
8198 "Label se:user_defined"). If the series already converges
8199 geometrically, "suminf" is often a better choice:
8200 ? \p28
8202 ? sumalt(i = 1, -(-1)^i / i) - log(2)
8203 time = 0 ms.
8204 %1 = -2.524354897 E-29
8205 ? suminf(i = 1, -(-1)^i / i)
8206 *** suminf: user interrupt after 10min, 20,100 ms.
8207 ? \p1000
8208 ? sumalt(i = 1, -(-1)^i / i) - log(2)
8209 time = 90 ms.
8210 %2 = 4.459597722 E-1002
8211 ? sumalt(i = 0, (-1)^i / i!) - exp(-1)
8213 time = 670 ms.
8214 %3 = -4.03698781490633483156497361352190615794353338591897830587 E-944
8215 ? suminf(i = 0, (-1)^i / i!) - exp(-1)
8216 time = 110 ms.
8217 %4 = -8.39147638 E-1000 \\ faster and more accurate
8218 The library syntax is sumalt"(void *E, GEN (*eval)(GEN,void*),GEN
8220 a,long prec)". Also available is "sumalt2" with the same arguments
8221 ("flag = 1").
8222 sumdiv"(n,X,expr)"
8224 sum of expression expr over the positive divisors of "n".
8225 Arithmetic functions like "sigma" use the multiplicativity of the
8227 underlying expression to speed up the computation. In the present
8228 version /usr/share/libpari23, there is no way to indicate that expr is
8229 multiplicative in "n", hence specialized functions should be preferred
8230 whenever possible.
8231 The library syntax is divsum"(entree *ep, GEN num, char *expr)".
8233 suminf"(X = a,expr)"
8235 infinite sum of expression expr, the formal parameter "X" starting at
8236 "a". The evaluation stops when the relative error of the expression is
8237 less than the default precision for 3 consecutive evaluations. The
8238 expressions must always evaluate to a complex number.
8239 If the series converges slowly, make sure "realprecision" is low (even
8241 28 digits may be too much). In this case, if the series is alternating
8242 or the terms have a constant sign, "sumalt" and "sumpos" should be used
8243 instead.
8244 ? \p28
8246 ? suminf(i = 1, -(-1)^i / i)
8247 *** suminf: user interrupt after 10min, 20,100 ms.
8248 ? sumalt(i = 1, -(-1)^i / i) - log(2)
8249 time = 0 ms.
8250 %1 = -2.524354897 E-29
8251 The library syntax is suminf"(void *E, GEN (*eval)(GEN,void*), GEN a,
8253 long prec)".
8254 sumnum"(X = a,sig,expr,{tab}),{flag = 0}"
8256 numerical summation of expr, the variable "X" taking integer values
8257 from ceiling of "a" to "+ oo ", where expr is assumed to be a
8258 holomorphic function f(X) for " Re (X) >= sigma".
8259 The parameter "sigma belongs to R" is coded in the argument "sig" as
8261 follows: it is either
8262 \item a real number "sigma". Then the function "f" is assumed to
8264 decrease at least as "1/X^2" at infinity, but not exponentially;
8265 \item a two-component vector "[sigma,alpha]", where "sigma" is as
8267 before, "alpha < -1". The function "f" is assumed to decrease like
8268 "X^{alpha}". In particular, "alpha <= -2" is equivalent to no "alpha"
8269 at all.
8270 \item a two-component vector "[sigma,alpha]", where "sigma" is as
8272 before, "alpha > 0". The function "f" is assumed to decrease like " exp
8273 (-alpha X)". In this case it is essential that "alpha" be exactly the
8274 rate of exponential decrease, and it is usually a good idea to increase
8275 the default value of "m" used for the integration step. In practice, if
8276 the function is exponentially decreasing "sumnum" is slower and less
8277 accurate than "sumpos" or "suminf", so should not be used.
8278 The function uses the "intnum" routines and integration on the line "
8280 Re (s) = sigma". The optional argument tab is as in intnum, except it
8281 must be initialized with "sumnuminit" instead of "intnuminit".
8282 When tab is not precomputed, "sumnum" can be slower than "sumpos", when
8284 the latter is applicable. It is in general faster for slowly decreasing
8285 functions.
8286 Finally, if "flag" is nonzero, we assume that the function "f" to be
8288 summed is of real type, i.e. satisfies "\overline{f(z)} =
8289 f(\overline{z})", which speeds up the computation.
8290 ? d - c
8292 time = 0 ms.
8293 %5 = 1.97... E-306 \\ slower but done once and for all.
8294 ? d - c
8295 time = 0 ms.
8296 %5 = 1.97... E-306 \\ 3 times as fast as sumpos
8297 ? d - c
8298 time = 0 ms.
8299 %5 = 1.97... E-306 \\ perfect.
8300 ? d - c
8301 time = 0 ms.
8302 %5 = 1.97... E-306 \\ function of real type
8303 ? d - c
8304 time = 0 ms.
8305 %5 = 1.97... E-306 \\ twice as fast, no imaginary part.
8306 ? d - c
8307 time = 0 ms.
8308 %5 = 1.97... E-306 \\ fast
8309 ? d - c
8310 time = 0 ms.
8311 %5 = 1.97... E-306 \\ slow.
8312 ? d - c
8313 time = 0 ms.
8314 %5 = 1.97... E-306 \\ perfect.
8315 For slowly decreasing function, we must indicate singularities:
8317 time = 12,210 ms.
8319 ? b - zeta(4/3)
8320 %3 = 1.05... E-300 \\ slow because of the computation of n^{-4/3}.
8321 time = 12,210 ms.
8322 ? b - zeta(4/3)
8323 %3 = 1.05... E-300 \\ lost 200 decimals because of singularity at oo
8324 time = 12,210 ms.
8325 ? b - zeta(4/3)
8326 %3 = 1.05... E-300 \\ of real type
8327 time = 12,210 ms.
8328 ? b - zeta(4/3)
8329 %3 = 1.05... E-300 \\ better
8330 Since the \emph{complex} values of the function are used, beware of
8332 determination problems. For instance:
8333 ? sumnum(n=1,[2,-3/2], 1/n^(3/2), tab,1) - zeta(3/2)
8335 time = 8,990 ms.
8336 %3 = -1.19... E-305 \\ fast and correct
8337 ? sumnum(n=1,[2,-3/2], 1/n^(3/2), tab,1) - zeta(3/2)
8338 time = 8,990 ms.
8339 %3 = -1.19... E-305 \\ nonsense. However
8340 ? sumnum(n=1,[2,-3/2], 1/n^(3/2), tab,1) - zeta(3/2)
8341 time = 8,990 ms.
8342 %3 = -1.19... E-305 \\ perfect, as 1/(n*sqrt{n}) above but much slower
8343 For exponentially decreasing functions, "sumnum" is given for
8345 completeness, but one of "suminf" or "sumpos" should always be
8346 preferred. If you experiment with such functions and "sumnum" anyway,
8347 indicate the exact rate of decrease and increase "m" by 1 or 2:
8348 ? m = intnumstep()
8350 %4 = 9
8351 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8352 time = 11,770 ms.
8353 %5 = -1.9... E-305 \\ fast and perfect
8354 ? m = intnumstep()
8355 %4 = 9
8356 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8357 time = 11,770 ms.
8358 %5 = -1.9... E-305 \\ also fast and perfect
8359 ? m = intnumstep()
8360 %4 = 9
8361 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8362 time = 11,770 ms.
8363 %5 = -1.9... E-305 \\ nonsense
8364 ? m = intnumstep()
8365 %4 = 9
8366 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8367 time = 11,770 ms.
8368 %5 = -1.9... E-305 \\ of real type
8369 ? m = intnumstep()
8370 %4 = 9
8371 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8372 time = 11,770 ms.
8373 %5 = -1.9... E-305 \\ slow and lost 70 decimals
8374 ? m = intnumstep()
8375 %4 = 9
8376 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8377 time = 11,770 ms.
8378 %5 = -1.9... E-305 \\ now perfect, but slow.
8379 The library syntax is sumnum"(void *E, GEN (*eval)(GEN,void*), GEN
8381 a,GEN sig,GEN tab,long flag, long prec)".
8382 sumnumalt"(X = a,sig,expr,{tab},{flag = 0})"
8384 numerical summation of "(-1)^Xexpr(X)", the variable "X" taking integer
8385 values from ceiling of "a" to "+ oo ", where expr is assumed to be a
8386 holomorphic function for " Re (X) >= sig" (or "sig[1]").
8387 Warning. This function uses the "intnum" routines and is orders of
8389 magnitude slower than "sumalt". It is only given for completeness and
8390 should not be used in practice.
8391 Warning2. The expression expr must \emph{not} include the "(-1)^X"
8393 coefficient. Thus "sumalt(n = a,(-1)^nf(n))" is (approximately) equal
8394 to "sumnumalt(n = a,sig,f(n))".
8395 "sig" is coded as in "sumnum". However for slowly decreasing functions
8397 (where "sig" is coded as "[sigma,alpha]" with "alpha < -1"), it is not
8398 really important to indicate "alpha". In fact, as for "sumalt", the
8399 program will often give meaningful results (usually analytic
8400 continuations) even for divergent series. On the other hand the
8401 exponential decrease must be indicated.
8402 tab is as in "intnum", but if used must be initialized with
8404 "sumnuminit". If "flag" is nonzero, assumes that the function "f" to be
8405 summed is of real type, i.e. satisfies "\overline{f(z)} =
8406 f(\overline{z})", and then twice faster when tab is precomputed.
8407 ? a - b
8409 time = 0 ms.
8410 %1 = -1.66... E-308 \\ abcissa sigma = 2, alternating sums.
8411 ? a - b
8412 time = 0 ms.
8413 %1 = -1.66... E-308 \\ slow, but done once and for all.
8414 ? a - b
8415 time = 0 ms.
8416 %1 = -1.66... E-308 \\ similar speed to sumnum
8417 ? a - b
8418 time = 0 ms.
8419 %1 = -1.66... E-308 \\ infinitely faster!
8420 ? a - b
8421 time = 0 ms.
8422 %1 = -1.66... E-308 \\ perfect
8423 The library syntax is sumnumalt"(void *E, GEN (*eval)(GEN,void*), GEN
8425 a, GEN sig, GEN tab, long flag, long prec)".
8426 sumnuminit"(sig,{m = 0},{sgn = 1})"
8428 initialize tables for numerical summation using "sumnum" (with "sgn =
8429 1") or "sumnumalt" (with "sgn = -1"), "sig" is the abcissa of
8430 integration coded as in "sumnum", and "m" is as in "intnuminit".
8431 The library syntax is sumnuminit"(GEN sig, long m, long sgn, long
8433 prec)".
8434 sumpos"(X = a,expr,{flag = 0})"
8436 numerical summation of the series expr, which must be a series of terms
8437 having the same sign, the formal variable "X" starting at "a". The
8438 algorithm used is Van Wijngaarden's trick for converting such a series
8439 into an alternating one, and is quite slow. For regular functions, the
8440 function "sumnum" is in general much faster once the initializations
8441 have been made using "sumnuminit".
8442 If "flag = 1", use slightly different polynomials. Sometimes faster.
8444 The library syntax is sumpos"(void *E, GEN (*eval)(GEN,void*),GEN
8446 a,long prec)". Also available is "sumpos2" with the same arguments
8447 ("flag = 1").
8448
8450 Although plotting is not even a side purpose of PARI, a number of
8451 plotting functions are provided. Moreover, a lot of people suggested
8452 ideas or submitted patches for this section of the code. Among these,
8453 special thanks go to Klaus-Peter Nischke who suggested the recursive
8454 plotting and the forking/resizing stuff under X11, and Ilya Zakharevich
8455 who undertook a complete rewrite of the graphic code, so that most of
8456 it is now platform-independent and should be easy to port or expand.
8457 There are three types of graphic functions.
8458 High-level plotting functions
8460 (all the functions starting with "ploth") in which the user has little
8461 to do but explain what type of plot he wants, and whose syntax is
8462 similar to the one used in the preceding section.
8463 Low-level plotting functions
8465 (called rectplot functions, sharing the prefix "plot"), where every
8466 drawing primitive (point, line, box, etc.) is specified by the user.
8467 These low-level functions work as follows. You have at your disposal 16
8468 virtual windows which are filled independently, and can then be
8469 physically ORed on a single window at user-defined positions. These
8470 windows are numbered from 0 to 15, and must be initialized before being
8471 used by the function "plotinit", which specifies the height and width
8472 of the virtual window (called a rectwindow in the sequel). At all
8473 times, a virtual cursor (initialized at "[0,0]") is associated to the
8474 window, and its current value can be obtained using the function
8475 "plotcursor".
8476 A number of primitive graphic objects (called rect objects) can then be
8478 drawn in these windows, using a default color associated to that window
8479 (which can be changed under X11, using the "plotcolor" function, black
8480 otherwise) and only the part of the object which is inside the window
8481 will be drawn, with the exception of polygons and strings which are
8482 drawn entirely. The ones sharing the prefix "plotr" draw relatively to
8483 the current position of the virtual cursor, the others use absolute
8484 coordinates. Those having the prefix "plotrecth" put in the rectwindow
8485 a large batch of rect objects corresponding to the output of the
8486 related "ploth" function.
8487 Finally, the actual physical drawing is done using the function
8489 "plotdraw". The rectwindows are preserved so that further drawings
8490 using the same windows at different positions or different windows can
8491 be done without extra work. To erase a window (and free the
8492 corresponding memory), use the function "plotkill". It is not possible
8493 to partially erase a window. Erase it completely, initialize it again
8494 and then fill it with the graphic objects that you want to keep.
8495 In addition to initializing the window, you may use a scaled window to
8497 avoid unnecessary conversions. For this, use the function "plotscale"
8498 below. As long as this function is not called, the scaling is simply
8499 the number of pixels, the origin being at the upper left and the
8500 "y"-coordinates going downwards.
8501 Note that in the present version /usr/share/libpari23 all plotting
8503 functions (both low and high level) are written for the X11-window
8504 system (hence also for GUI's based on X11 such as Openwindows and
8505 Motif) only, though little code remains which is actually platform-
8506 dependent. It is also possible to compile "gp" with either of the Qt or
8507 FLTK graphical libraries. A Suntools/Sunview, Macintosh, and an
8508 Atari/Gem port were provided for previous versions, but are now
8509 obsolete.
8510 Under X11, the physical window (opened by "plotdraw" or any of the
8512 "ploth*" functions) is completely separated from "gp" (technically, a
8513 "fork" is done, and the non-graphical memory is immediately freed in
8514 the child process), which means you can go on working in the current
8515 "gp" session, without having to kill the window first. Under X11, this
8516 window can be closed, enlarged or reduced using the standard window
8517 manager functions. No zooming procedure is implemented though (yet).
8518 Functions for PostScript output:
8520 in the same way that "printtex" allows you to have a TeX output
8521 corresponding to printed results, the functions starting with "ps"
8522 allow you to have "PostScript" output of the plots. This will not be
8523 absolutely identical with the screen output, but will be sufficiently
8524 close. Note that you can use PostScript output even if you do not have
8525 the plotting routines enabled. The PostScript output is written in a
8526 file whose name is derived from the "psfile" default ("./pari.ps" if
8527 you did not tamper with it). Each time a new PostScript output is asked
8528 for, the PostScript output is appended to that file. Hence you probably
8529 want to remove this file, or change the value of "psfile", in between
8530 plots. On the other hand, in this manner, as many plots as desired can
8531 be kept in a single file.
8532 And library mode ?
8534 \emph{None of the graphic functions are available within the PARI
8535 library, you must be under "gp" to use them}. The reason for that is
8536 that you really should not use PARI for heavy-duty graphical work,
8537 there are better specialized alternatives around. This whole set of
8538 routines was only meant as a convenient, but simple-minded, visual aid.
8539 If you really insist on using these in your program (we warned you),
8540 the source ("plot*.c") should be readable enough for you to achieve
8541 something.
8542 plot"(X = a,b,expr,{Ymin},{Ymax})"
8544 crude ASCII plot of the function represented by expression expr from
8545 "a" to "b", with Y ranging from Ymin to Ymax. If Ymin (resp. Ymax) is
8546 not given, the minima (resp. the maxima) of the computed values of the
8547 expression is used instead.
8548 plotbox"(w,x2,y2)"
8550 let "(x1,y1)" be the current position of the virtual cursor. Draw in
8551 the rectwindow "w" the outline of the rectangle which is such that the
8552 points "(x1,y1)" and "(x2,y2)" are opposite corners. Only the part of
8553 the rectangle which is in "w" is drawn. The virtual cursor does
8554 \emph{not} move.
8555 plotclip"(w)"
8557 `clips' the content of rectwindow "w", i.e remove all parts of the
8558 drawing that would not be visible on the screen. Together with
8559 "plotcopy" this function enables you to draw on a scratchpad before
8560 commiting the part you're interested in to the final picture.
8561 plotcolor"(w,c)"
8563 set default color to "c" in rectwindow "w". In present version
8564 /usr/share/libpari23, this is only implemented for the X11 window
8565 system, and you only have the following palette to choose from:
8566 1 = black, 2 = blue, 3 = sienna, 4 = red, 5 = green, 6 = grey, 7 =
8568 gainsborough.
8569 Note that it should be fairly easy for you to hardwire some more colors
8571 by tweaking the files "rect.h" and "plotX.c". User-defined colormaps
8572 would be nice, and \emph{may} be available in future versions.
8573 plotcopy"(w1,w2,dx,dy)"
8575 copy the contents of rectwindow "w1" to rectwindow "w2", with offset
8576 "(dx,dy)".
8577 plotcursor"(w)"
8579 give as a 2-component vector the current (scaled) position of the
8580 virtual cursor corresponding to the rectwindow "w".
8581 plotdraw"(list)"
8583 physically draw the rectwindows given in "list" which must be a vector
8584 whose number of components is divisible by 3. If "list =
8585 [w1,x1,y1,w2,x2,y2,...]", the windows "w1", "w2", etc. are physically
8586 placed with their upper left corner at physical position "(x1,y1)",
8587 "(x2,y2)",...respectively, and are then drawn together. Overlapping
8588 regions will thus be drawn twice, and the windows are considered
8589 transparent. Then display the whole drawing in a special window on your
8590 screen.
8591 ploth"(X = a,b,expr,{flag = 0},{n = 0})"
8593 high precision plot of the function "y = f(x)" represented by the
8594 expression expr, "x" going from "a" to "b". This opens a specific
8595 window (which is killed whenever you click on it), and returns a four-
8596 component vector giving the coordinates of the bounding box in the form
8597 "[xmin,xmax,ymin,ymax]".
8598 Important note: Since this may involve a lot of function calls, it is
8600 advised to keep the current precision to a minimum (e.g. 9) before
8601 calling this function.
8602 "n" specifies the number of reference point on the graph (0 means use
8604 the hardwired default values, that is: 1000 for general plot, 1500 for
8605 parametric plot, and 15 for recursive plot).
8606 If no "flag" is given, expr is either a scalar expression f(X), in
8608 which case the plane curve "y = f(X)" will be drawn, or a vector
8609 "[f_1(X),...,f_k(X)]", and then all the curves "y = f_i(X)" will be
8610 drawn in the same window.
8611 The binary digits of "flag" mean:
8613 \item "1 = Parametric": parametric plot. Here expr must be a vector
8615 with an even number of components. Successive pairs are then understood
8616 as the parametric coordinates of a plane curve. Each of these are then
8617 drawn.
8618 For instance:
8620 "ploth(X = 0,2*Pi,[sin(X),cos(X)],1)" will draw a circle.
8622 "ploth(X = 0,2*Pi,[sin(X),cos(X)])" will draw two entwined sinusoidal
8624 curves.
8625 "ploth(X = 0,2*Pi,[X,X,sin(X),cos(X)],1)" will draw a circle and the
8627 line "y = x".
8628 \item "2 = Recursive": recursive plot. If this flag is set, only
8630 \emph{one} curve can be drawn at a time, i.e. expr must be either a
8631 two-component vector (for a single parametric curve, and the parametric
8632 flag \emph{has} to be set), or a scalar function. The idea is to choose
8633 pairs of successive reference points, and if their middle point is not
8634 too far away from the segment joining them, draw this as a local
8635 approximation to the curve. Otherwise, add the middle point to the
8636 reference points. This is fast, and usually more precise than usual
8637 plot. Compare the results of
8638 "ploth(X = -1,1,sin(1/X),2) and ploth(X = -1,1,sin(1/X))"
8640 for instance. But beware that if you are extremely unlucky, or choose
8642 too few reference points, you may draw some nice polygon bearing little
8643 resemblance to the original curve. For instance you should \emph{never}
8644 plot recursively an odd function in a symmetric interval around 0. Try
8645 ploth(x = -20, 20, sin(x), 2)
8647 to see why. Hence, it's usually a good idea to try and plot the same
8649 curve with slightly different parameters.
8650 The other values toggle various display options:
8652 \item "4 = no_Rescale": do not rescale plot according to the computed
8654 extrema. This is meant to be used when graphing multiple functions on a
8655 rectwindow (as a "plotrecth" call), in conjunction with "plotscale".
8656 \item "8 = no_X_axis": do not print the "x"-axis.
8658 \item "16 = no_Y_axis": do not print the "y"-axis.
8660 \item "32 = no_Frame": do not print frame.
8662 \item "64 = no_Lines": only plot reference points, do not join them.
8664 \item "128 = Points_too": plot both lines and points.
8666 \item "256 = Splines": use splines to interpolate the points.
8668 \item "512 = no_X_ticks": plot no "x"-ticks.
8670 \item "1024 = no_Y_ticks": plot no "y"-ticks.
8672 \item "2048 = Same_ticks": plot all ticks with the same length.
8674 plothraw"(listx,listy,{flag = 0})"
8676 given listx and listy two vectors of equal length, plots (in high
8677 precision) the points whose "(x,y)"-coordinates are given in listx and
8678 listy. Automatic positioning and scaling is done, but with the same
8679 scaling factor on "x" and "y". If "flag" is 1, join points, other non-0
8680 flags toggle display options and should be combinations of bits "2^k",
8681 "k
8682 >= 3" as in "ploth".
8683 plothsizes"()"
8685 return data corresponding to the output window in the form of a
8686 6-component vector: window width and height, sizes for ticks in
8687 horizontal and vertical directions (this is intended for the "gnuplot"
8688 interface and is currently not significant), width and height of
8689 characters.
8690 plotinit"(w,x,y,{flag})"
8692 initialize the rectwindow "w", destroying any rect objects you may have
8693 already drawn in "w". The virtual cursor is set to "(0,0)". The
8694 rectwindow size is set to width "x" and height "y". If "flag = 0", "x"
8695 and "y" represent pixel units. Otherwise, "x" and "y" are understood as
8696 fractions of the size of the current output device (hence must be
8697 between 0 and 1) and internally converted to pixels.
8698 The plotting device imposes an upper bound for "x" and "y", for
8700 instance the number of pixels for screen output. These bounds are
8701 available through the "plothsizes" function. The following sequence
8702 initializes in a portable way (i.e independent of the output device) a
8703 window of maximal size, accessed through coordinates in the "[0,1000]
8704 x [0,1000]" range:
8705 s = plothsizes();
8707 plotinit(0, s[1]-1, s[2]-1);
8708 plotscale(0, 0,1000, 0,1000);
8709 plotkill"(w)"
8711 erase rectwindow "w" and free the corresponding memory. Note that if
8712 you want to use the rectwindow "w" again, you have to use "plotinit"
8713 first to specify the new size. So it's better in this case to use
8714 "plotinit" directly as this throws away any previous work in the given
8715 rectwindow.
8716 plotlines"(w,X,Y,{flag = 0})"
8718 draw on the rectwindow "w" the polygon such that the (x,y)-coordinates
8719 of the vertices are in the vectors of equal length "X" and "Y". For
8720 simplicity, the whole polygon is drawn, not only the part of the
8721 polygon which is inside the rectwindow. If "flag" is non-zero, close
8722 the polygon. In any case, the virtual cursor does not move.
8723 "X" and "Y" are allowed to be scalars (in this case, both have to).
8725 There, a single segment will be drawn, between the virtual cursor
8726 current position and the point "(X,Y)". And only the part thereof which
8727 actually lies within the boundary of "w". Then \emph{move} the virtual
8728 cursor to "(X,Y)", even if it is outside the window. If you want to
8729 draw a line from "(x1,y1)" to "(x2,y2)" where "(x1,y1)" is not
8730 necessarily the position of the virtual cursor, use "plotmove(w,x1,y1)"
8731 before using this function.
8732 plotlinetype"(w,type)"
8734 change the type of lines subsequently plotted in rectwindow "w". type
8735 "-2" corresponds to frames, "-1" to axes, larger values may correspond
8736 to something else. "w = -1" changes highlevel plotting. This is only
8737 taken into account by the "gnuplot" interface.
8738 plotmove"(w,x,y)"
8740 move the virtual cursor of the rectwindow "w" to position "(x,y)".
8741 plotpoints"(w,X,Y)"
8743 draw on the rectwindow "w" the points whose "(x,y)"-coordinates are in
8744 the vectors of equal length "X" and "Y" and which are inside "w". The
8745 virtual cursor does \emph{not} move. This is basically the same
8746 function as "plothraw", but either with no scaling factor or with a
8747 scale chosen using the function "plotscale".
8748 As was the case with the "plotlines" function, "X" and "Y" are allowed
8750 to be (simultaneously) scalar. In this case, draw the single point
8751 "(X,Y)" on the rectwindow "w" (if it is actually inside "w"), and in
8752 any case \emph{move} the virtual cursor to position "(x,y)".
8753 plotpointsize"(w,size)"
8755 changes the ``size'' of following points in rectwindow "w". If "w =
8756 -1", change it in all rectwindows. This only works in the "gnuplot"
8757 interface.
8758 plotpointtype"(w,type)"
8760 change the type of points subsequently plotted in rectwindow "w". "type
8761 = -1" corresponds to a dot, larger values may correspond to something
8762 else. "w = -1" changes highlevel plotting. This is only taken into
8763 account by the "gnuplot" interface.
8764 plotrbox"(w,dx,dy)"
8766 draw in the rectwindow "w" the outline of the rectangle which is such
8767 that the points "(x1,y1)" and "(x1+dx,y1+dy)" are opposite corners,
8768 where "(x1,y1)" is the current position of the cursor. Only the part
8769 of the rectangle which is in "w" is drawn. The virtual cursor does
8770 \emph{not} move.
8771 plotrecth"(w,X = a,b,expr,{flag = 0},{n = 0})"
8773 writes to rectwindow "w" the curve output of "ploth""(w,X =
8774 a,b,expr,flag,n)".
8775 plotrecthraw"(w,data,{flag = 0})"
8777 plot graph(s) for data in rectwindow "w". "flag" has the same
8778 significance here as in "ploth", though recursive plot is no more
8779 significant.
8780 data is a vector of vectors, each corresponding to a list a
8782 coordinates. If parametric plot is set, there must be an even number
8783 of vectors, each successive pair corresponding to a curve. Otherwise,
8784 the first one contains the "x" coordinates, and the other ones contain
8785 the "y"-coordinates of curves to plot.
8786 plotrline"(w,dx,dy)"
8788 draw in the rectwindow "w" the part of the segment
8789 "(x1,y1)-(x1+dx,y1+dy)" which is inside "w", where "(x1,y1)" is the
8790 current position of the virtual cursor, and move the virtual cursor to
8791 "(x1+dx,y1+dy)" (even if it is outside the window).
8792 plotrmove"(w,dx,dy)"
8794 move the virtual cursor of the rectwindow "w" to position
8795 "(x1+dx,y1+dy)", where "(x1,y1)" is the initial position of the cursor
8796 (i.e. to position "(dx,dy)" relative to the initial cursor).
8797 plotrpoint"(w,dx,dy)"
8799 draw the point "(x1+dx,y1+dy)" on the rectwindow "w" (if it is inside
8800 "w"), where "(x1,y1)" is the current position of the cursor, and in any
8801 case move the virtual cursor to position "(x1+dx,y1+dy)".
8802 plotscale"(w,x1,x2,y1,y2)"
8804 scale the local coordinates of the rectwindow "w" so that "x" goes from
8805 "x1" to "x2" and "y" goes from "y1" to "y2" ("x2 < x1" and "y2 < y1"
8806 being allowed). Initially, after the initialization of the rectwindow
8807 "w" using the function "plotinit", the default scaling is the graphic
8808 pixel count, and in particular the "y" axis is oriented downwards since
8809 the origin is at the upper left. The function "plotscale" allows to
8810 change all these defaults and should be used whenever functions are
8811 graphed.
8812 plotstring"(w,x,{flag = 0})"
8814 draw on the rectwindow "w" the String "x" (see "Label se:strings"), at
8815 the current position of the cursor.
8816 flag is used for justification: bits 1 and 2 regulate horizontal
8818 alignment: left if 0, right if 2, center if 1. Bits 4 and 8 regulate
8819 vertical alignment: bottom if 0, top if 8, v-center if 4. Can insert
8820 additional small gap between point and string: horizontal if bit 16 is
8821 set, vertical if bit 32 is set (see the tutorial for an example).
8822 psdraw"(list)"
8824 same as "plotdraw", except that the output is a PostScript program
8825 appended to the "psfile".
8826 psploth"(X = a,b,expr)"
8828 same as "ploth", except that the output is a PostScript program
8829 appended to the "psfile".
8830 psplothraw"(listx,listy)"
8832 same as "plothraw", except that the output is a PostScript program
8833 appended to the "psfile".
8834
8836 =head2 Control statements.
8837 A number of control statements are available in GP. They are simpler
8839 and have a syntax slightly different from their C counterparts, but are
8840 quite powerful enough to write any kind of program. Some of them are
8841 specific to GP, since they are made for number theorists. As usual, "X"
8842 will denote any simple variable name, and seq will always denote a
8843 sequence of expressions, including the empty sequence.
8844 Caveat: in constructs like
8846 for (X = a,b, seq)
8848 the variable "X" is considered local to the loop, leading to possibly
8850 unexpected behaviour:
8851 n = 5;
8853 for (n = 1, 10,
8854 if (something_nice(), break);
8855 );
8856 \\ at this point n is 5 !
8857 If the sequence "seq" modifies the loop index, then the loop is
8859 modified accordingly:
8860 ? for (n = 1, 10, n += 2; print(n))
8862 3
8863 6
8864 9
8865 12
8866 break"({n = 1})"
8868 interrupts execution of current seq, and immediately exits from the
8869 "n" innermost enclosing loops, within the current function call (or
8870 the top level loop). "n" must be bigger than 1. If "n" is greater
8871 than the number of enclosing loops, all enclosing loops are exited.
8872 for"(X = a,b,seq)"
8874 evaluates seq, where the formal variable "X" goes from "a" to "b".
8875 Nothing is done if "a > b". "a" and "b" must be in R.
8876 fordiv"(n,X,seq)"
8878 evaluates seq, where the formal variable "X" ranges through the
8879 divisors of "n" (see "divisors", which is used as a subroutine). It
8880 is assumed that "factor" can handle "n", without negative
8881 exponents. Instead of "n", it is possible to input a factorization
8882 matrix, i.e. the output of factor(n).
8883 This routine uses "divisors" as a subroutine, then loops over the
8885 divisors. In particular, if "n" is an integer, divisors are sorted
8886 by increasing size.
8887 To avoid storing all divisors, possibly using a lot of memory, the
8889 following (much slower) routine loops over the divisors using
8890 essentially constant space:
8891 FORDIV(N)=
8893 { local(P, E);
8894 P = factor(N); E = P[,2]; P = P[,1];
8896 forvec( v = vector(#E, i, [0,E[i]]),
8897 X = factorback(P, v)
8898 \\ ...
8899 );
8900 }
8901 ? for(i=1,10^5, FORDIV(i))
8902 time = 3,445 ms.
8903 ? for(i=1,10^5, fordiv(i, d, ))
8904 time = 490 ms.
8905 forell"(E,a,b,seq)"
8907 evaluates seq, where the formal variable "E" ranges through all
8908 elliptic curves of conductors from "a" to "b". Th "elldata"
8909 database must be installed and contain data for the specified
8910 conductors.
8911 forprime"(X = a,b,seq)"
8913 evaluates seq, where the formal variable "X" ranges over the prime
8914 numbers between "a" to "b" (including "a" and "b" if they are
8915 prime). More precisely, the value of "X" is incremented to the
8916 smallest prime strictly larger than "X" at the end of each
8917 iteration. Nothing is done if "a > b". Note that "a" and "b" must
8918 be in R.
8919 ? { forprime(p = 2, 12,
8921 print(p);
8922 if (p == 3, p = 6);
8923 )
8924 }
8925 2
8926 3
8927 7
8928 11
8929 forstep"(X = a,b,s,seq)"
8931 evaluates seq, where the formal variable "X" goes from "a" to "b",
8932 in increments of "s". Nothing is done if "s > 0" and "a > b" or if
8933 "s < 0" and "a < b". "s" must be in "R^*" or a vector of steps
8934 "[s_1,...,s_n]". In the latter case, the successive steps are used
8935 in the order they appear in "s".
8936 ? forstep(x=5, 20, [2,4], print(x))
8938 5
8939 7
8940 11
8941 13
8942 17
8943 19
8944 forsubgroup"(H = G,{B},seq)"
8946 evaluates seq for each subgroup "H" of the \emph{abelian} group "G"
8947 (given in SNF form or as a vector of elementary divisors), whose
8948 index is bounded by "B". The subgroups are not ordered in any
8949 obvious way, unless "G" is a "p"-group in which case Birkhoff's
8950 algorithm produces them by decreasing index. A subgroup is given as
8951 a matrix whose columns give its generators on the implicit
8952 generators of "G". For example, the following prints all subgroups
8953 of index less than 2 in "G = Z/2Z g_1 x Z/2Z g_2":
8954 ? G = [2,2]; forsubgroup(H=G, 2, print(H))
8956 [1; 1]
8957 [1; 2]
8958 [2; 1]
8959 [1, 0; 1, 1]
8960 The last one, for instance is generated by "(g_1, g_1 + g_2)". This
8962 routine is intended to treat huge groups, when "subgrouplist" is
8963 not an option due to the sheer size of the output.
8964 For maximal speed the subgroups have been left as produced by the
8966 algorithm. To print them in canonical form (as left divisors of
8967 "G" in HNF form), one can for instance use
8968 ? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H))))
8970 [2, 1; 0, 1]
8971 [1, 0; 0, 2]
8972 [2, 0; 0, 1]
8973 [1, 0; 0, 1]
8974 Note that in this last representation, the index "[G:H]" is given
8976 by the determinant. See "galoissubcyclo" and "galoisfixedfield" for
8977 "nfsubfields" applications to Galois theory.
8978 Warning: the present implementation cannot treat a group "G", if
8980 one of its "p"-Sylow subgroups has a cyclic factor with more than
8981 "2^{31}", resp. "2^{63}" elements on a 32-bit, resp. 64-bit
8982 architecture.
8983 forvec"(X = v,seq,{flag = 0})"
8985 Let "v" be an "n"-component vector (where "n" is arbitrary) of two-
8986 component vectors "[a_i,b_i]" for "1 <= i <= n". This routine
8987 evaluates seq, where the formal variables "X[1],..., X[n]" go from
8988 "a_1" to "b_1",..., from "a_n" to "b_n", i.e. "X" goes from
8989 "[a_1,...,a_n]" to "[b_1,...,b_n]" with respect to the
8990 lexicographic ordering. (The formal variable with the highest index
8991 moves the fastest.) If "flag = 1", generate only nondecreasing
8992 vectors "X", and if "flag = 2", generate only strictly increasing
8993 vectors "X".
8994 if"(a,{seq1},{seq2})"
8996 evaluates the expression sequence seq1 if "a" is non-zero,
8997 otherwise the expression seq2. Of course, seq1 or seq2 may be
8998 empty:
8999 "if (a,seq)" evaluates seq if "a" is not equal to zero (you don't
9001 have to write the second comma), and does nothing otherwise,
9002 "if (a,,seq)" evaluates seq if "a" is equal to zero, and does
9004 nothing otherwise. You could get the same result using the "!"
9005 ("not") operator: "if (!a,seq)".
9006 Note that the boolean operators "&&" and "||" are evaluated
9008 according to operator precedence as explained in "Label
9009 se:operators", but that, contrary to other operators, the
9010 evaluation of the arguments is stopped as soon as the final truth
9011 value has been determined. For instance
9012 if (reallydoit && longcomplicatedfunction(), ...)%
9014 is a perfectly safe statement.
9016 Recall that functions such as "break" and "next" operate on
9018 \emph{loops} (such as "forxxx", "while", "until"). The "if"
9019 statement is \emph{not} a loop (obviously!).
9020 next"({n = 1})"
9022 interrupts execution of current "seq", resume the next iteration of
9023 the innermost enclosing loop, within the current function call (or
9024 top level loop). If "n" is specified, resume at the "n"-th
9025 enclosing loop. If "n" is bigger than the number of enclosing
9026 loops, all enclosing loops are exited.
9027 return"({x = 0})"
9029 returns from current subroutine, with result "x". If "x" is
9030 omitted, return the "(void)" value (return no result, like
9031 "print").
9032 until"(a,seq)"
9034 evaluates seq until "a" is not equal to 0 (i.e. until "a" is true).
9035 If "a" is initially not equal to 0, seq is evaluated once (more
9036 generally, the condition on "a" is tested \emph{after} execution of
9037 the seq, not before as in "while").
9038 while"(a,seq)"
9040 while "a" is non-zero, evaluates the expression sequence seq. The
9041 test is made \emph{before} evaluating the "seq", hence in
9042 particular if "a" is initially equal to zero the seq will not be
9043 evaluated at all.
9044 Specific functions used in GP programming
9046 In addition to the general PARI functions, it is necessary to have some
9047 functions which will be of use specifically for "gp", though a few of
9048 these can be accessed under library mode. Before we start describing
9049 these, we recall the difference between \emph{strings} and
9050 \emph{keywords} (see "Label se:strings"): the latter don't get expanded
9051 at all, and you can type them without any enclosing quotes. The former
9052 are dynamic objects, where everything outside quotes gets immediately
9053 expanded.
9054 addhelp"(S,str)"
9056 changes the help message for the symbol "S". The string str is
9057 expanded on the spot and stored as the online help for "S". If "S"
9058 is a function \emph{you} have defined, its definition will still be
9059 printed before the message str. It is recommended that you
9060 document global variables and user functions in this way. Of course
9061 "gp" will not protest if you skip this.
9062 Nothing prevents you from modifying the help of built-in PARI
9064 functions. (But if you do, we would like to hear why you needed to
9065 do it!)
9066 alias"(newkey,key)"
9068 defines the keyword newkey as an alias for keyword key. key must
9069 correspond to an existing \emph{function} name. This is different
9070 from the general user macros in that alias expansion takes place
9071 immediately upon execution, without having to look up any function
9072 code, and is thus much faster. A sample alias file "misc/gpalias"
9073 is provided with the standard distribution. Alias commands are
9074 meant to be read upon startup from the ".gprc" file, to cope with
9075 function names you are dissatisfied with, and should be useless in
9076 interactive usage.
9077 allocatemem"({x = 0})"
9079 this is a very special operation which allows the user to change
9080 the stack size \emph{after} initialization. "x" must be a non-
9081 negative integer. If "x ! = 0", a new stack of size
9082 "16*\ceil{x/16}" bytes is allocated, all the PARI data on the old
9083 stack is moved to the new one, and the old stack is discarded. If
9084 "x = 0", the size of the new stack is twice the size of the old
9085 one.
9086 Although it is a function, "allocatemem" cannot be used in loop-
9088 like constructs, or as part of a larger expression, e.g "2 +
9089 allocatemem()". Such an attempt will raise an error. The technical
9090 reason is that this routine usually moves the stack, so objects
9091 from the current expression may not be correct anymore, e.g. loop
9092 indexes.
9093 The library syntax is allocatemoremem"(x)", where "x" is an
9095 unsigned long, and the return type is void. "gp" uses a variant
9096 which makes sure it was not called within a loop.
9097 default"({key},{val})"
9099 returns the default corresponding to keyword key. If val is
9100 present, sets the default to val first (which is subject to string
9101 expansion first). Typing "default()" (or "\d") yields the complete
9102 default list as well as their current values. See "Label
9103 se:defaults" for a list of available defaults, and "Label se:meta"
9104 for some shortcut alternatives. Note that the shortcut are meant
9105 for interactive use and usually display more information than
9106 "default".
9107 The library syntax is gp_default"(key, val)", where key and val are
9109 "char *".
9110 error"({str}*)"
9112 outputs its argument list (each of them interpreted as a string),
9113 then interrupts the running "gp" program, returning to the input
9114 prompt. For instance
9115 error("n = ", n, " is not squarefree !")
9117 extern"(str)"
9119 the string str is the name of an external command (i.e. one you
9120 would type from your UNIX shell prompt). This command is
9121 immediately run and its input fed into "gp", just as if read from a
9122 file.
9123 The library syntax is extern0"(str)", where str is a "char *".
9125 getheap"()"
9127 returns a two-component row vector giving the number of objects on
9128 the heap and the amount of memory they occupy in long words. Useful
9129 mainly for debugging purposes.
9130 The library syntax is getheap"()".
9132 getrand"()"
9134 returns the current value of the random number seed. Useful mainly
9135 for debugging purposes.
9136 The library syntax is getrand"()", returns a C long.
9138 getstack"()"
9140 returns the current value of "top-avma", i.e. the number of bytes
9141 used up to now on the stack. Should be equal to 0 in between
9142 commands. Useful mainly for debugging purposes.
9143 The library syntax is getstack"()", returns a C long.
9145 gettime"()"
9147 returns the time (in milliseconds) elapsed since either the last
9148 call to "gettime", or to the beginning of the containing GP
9149 instruction (if inside "gp"), whichever came last.
9150 The library syntax is gettime"()", returns a C long.
9152 global"(list of variables)"
9154 declares the corresponding variables to be global. From now on, you
9156 will be forbidden to use them as formal parameters for function
9157 definitions or as loop indexes. This is especially useful when
9158 patching together various scripts, possibly written with different
9159 naming conventions. For instance the following situation is
9160 dangerous:
9161 p = 3 \\ fix characteristic
9163 ...
9164 forprime(p = 2, N, ...)
9165 f(p) = ...
9166 since within the loop or within the function's body (even worse: in
9168 the subroutines called in that scope), the true global value of "p"
9169 will be hidden. If the statement "global(p = 3)" appears at the
9170 beginning of the script, then both expressions will trigger syntax
9171 errors.
9172 Calling "global" without arguments prints the list of global
9174 variables in use. In particular, "eval(global)" will output the
9175 values of all global variables.
9176 input"()"
9178 reads a string, interpreted as a GP expression, from the input
9179 file, usually standard input (i.e. the keyboard). If a sequence of
9180 expressions is given, the result is the result of the last
9181 expression of the sequence. When using this instruction, it is
9182 useful to prompt for the string by using the "print1" function.
9183 Note that in the present version 2.19 of "pari.el", when using "gp"
9184 under GNU Emacs (see "Label se:emacs") one \emph{must} prompt for
9185 the string, with a string which ends with the same prompt as any of
9186 the previous ones (a "? " will do for instance).
9187 install"(name,code,{gpname},{lib})"
9189 loads from dynamic library lib the function name. Assigns to it the
9190 name gpname in this "gp" session, with argument code code (see the
9191 Libpari Manual for an explanation of those). If lib is omitted,
9192 uses "libpari.so". If gpname is omitted, uses name.
9193 This function is useful for adding custom functions to the "gp"
9195 interpreter, or picking useful functions from unrelated libraries.
9196 For instance, it makes the function "system" obsolete:
9197 ? install(system, vs, sys, "libc.so")
9199 ? sys("ls gp*")
9200 gp.c gp.h gp_rl.c
9201 But it also gives you access to all (non static) functions defined
9203 in the PARI library. For instance, the function "GEN addii(GEN x,
9204 GEN y)" adds two PARI integers, and is not directly accessible
9205 under "gp" (it's eventually called by the "+" operator of course):
9206 ? install("addii", "GG")
9208 ? addii(1, 2)
9209 %1 = 3
9210 Re-installing a function will print a Warning, and update the
9212 prototype code if needed, but will reload a symbol from the
9213 library, even it the latter has been recompiled.
9214 Caution: This function may not work on all systems, especially when
9216 "gp" has been compiled statically. In that case, the first use of
9217 an installed function will provoke a Segmentation Fault, i.e. a
9218 major internal blunder (this should never happen with a dynamically
9219 linked executable). Hence, if you intend to use this function,
9220 please check first on some harmless example such as the ones above
9221 that it works properly on your machine.
9222 kill"(s)"
9224 kills the present value of the variable, alias or user-defined
9225 function "s". The corresponding identifier can now be used to name
9226 any GP object (variable or function). This is the only way to
9227 replace a variable by a function having the same name (or the other
9228 way round), as in the following example:
9229 ? f = 1
9231 %1 = 1
9232 ? f(x) = 0
9233 *** unused characters: f(x)=0
9234 ^----
9235 ? kill(f)
9236 ? f(x) = 0
9237 ? f()
9238 %2 = 0
9239 When you kill a variable, all objects that used it become invalid.
9241 You can still display them, even though the killed variable will be
9242 printed in a funny way. For example:
9243 ? a^2 + 1
9245 %1 = a^2 + 1
9246 ? kill(a)
9247 ? %1
9248 %2 = #<1>^2 + 1
9249 If you simply want to restore a variable to its ``undefined'' value
9251 (monomial of degree one), use the quote operator: "a = 'a".
9252 Predefined symbols ("x" and GP function names) cannot be killed.
9253 print"({str}*)"
9255 outputs its (string) arguments in raw format, ending with a
9256 newline.
9257 print1"({str}*)"
9259 outputs its (string) arguments in raw format, without ending with a
9260 newline (note that you can still embed newlines within your
9261 strings, using the "\n" notation !).
9262 printp"({str}*)"
9264 outputs its (string) arguments in prettyprint (beautified) format,
9265 ending with a newline.
9266 printp1"({str}*)"
9268 outputs its (string) arguments in prettyprint (beautified) format,
9269 without ending with a newline.
9270 printtex"({str}*)"
9272 outputs its (string) arguments in TeX format. This output can then
9273 be used in a TeX manuscript. The printing is done on the standard
9274 output. If you want to print it to a file you should use "writetex"
9275 (see there).
9276 Another possibility is to enable the "log" default (see "Label
9278 se:defaults"). You could for instance do:
9279 default(logfile, "new.tex");
9281 default(log, 1);
9282 printtex(result);
9283 quit"()"
9285 exits "gp".
9286 read"({filename})"
9288 reads in the file filename (subject to string expansion). If
9289 filename is omitted, re-reads the last file that was fed into "gp".
9290 The return value is the result of the last expression evaluated.
9291 If a GP "binary file" is read using this command (see "Label
9293 se:writebin"), the file is loaded and the last object in the file
9294 is returned.
9295 readvec"({str})"
9297 reads in the file filename (subject to string expansion). If
9298 filename is omitted, re-reads the last file that was fed into "gp".
9299 The return value is a vector whose components are the evaluation of
9300 all sequences of instructions contained in the file. For instance,
9301 if file contains
9302 1
9304 2
9305 3
9306 then we will get:
9308 ? \r a
9310 %1 = 1
9311 %2 = 2
9312 %3 = 3
9313 ? read(a)
9314 %4 = 3
9315 ? readvec(a)
9316 %5 = [1, 2, 3]
9317 In general a sequence is just a single line, but as usual braces
9319 and "\\" may be used to enter multiline sequences.
9320 reorder"({x = []})"
9322 "x" must be a vector. If "x" is the empty vector, this gives the
9323 vector whose components are the existing variables in increasing
9324 order (i.e. in decreasing importance). Killed variables (see
9325 "kill") will be shown as 0. If "x" is non-empty, it must be a
9326 permutation of variable names, and this permutation gives a new
9327 order of importance of the variables, \emph{for output only}. For
9328 example, if the existing order is "[x,y,z]", then after
9329 "reorder([z,x])" the order of importance of the variables, with
9330 respect to output, will be "[z,y,x]". The internal representation
9331 is unaffected.
9332 setrand"(n)"
9334 reseeds the random number generator to the value "n". The initial
9335 seed is "n = 1".
9336 The library syntax is setrand"(n)", where "n" is a "long". Returns
9338 "n".
9339 system"(str)"
9341 str is a string representing a system command. This command is
9342 executed, its output written to the standard output (this won't get
9343 into your logfile), and control returns to the PARI system. This
9344 simply calls the C "system" command.
9345 trap"({e}, {rec}, {seq})"
9347 tries to evaluate seq, trapping error "e", that is effectively
9348 preventing it from aborting computations in the usual way; the
9349 recovery sequence rec is executed if the error occurs and the
9350 evaluation of rec becomes the result of the command. If "e" is
9351 omitted, all exceptions are trapped. Note in particular that
9352 hitting "^C" (Control-C) raises an exception. See "Label
9353 se:errorrec" for an introduction to error recovery under "gp".
9354 ? \\ trap division by 0
9356 ? inv(x) = trap (gdiver, INFINITY, 1/x)
9357 ? inv(2)
9358 %1 = 1/2
9359 ? inv(0)
9360 %2 = INFINITY
9361 If seq is omitted, defines rec as a default action when catching
9363 exception "e", provided no other trap as above intercepts it first.
9364 The error message is printed, as well as the result of the
9365 evaluation of rec, and control is given back to the "gp" prompt. In
9366 particular, current computation is then lost.
9367 The following error handler prints the list of all user variables,
9369 then stores in a file their name and their values:
9370 ? { trap( ,
9372 print(reorder);
9373 writebin("crash")) }
9374 If no recovery code is given (rec is omitted) a break loop will be
9376 started (see "Label se:breakloop"). In particular
9377 ? trap()
9379 by itself installs a default error handler, that will start a break
9381 loop whenever an exception is raised.
9382 If rec is the empty string "" the default handler (for that error
9384 if "e" is present) is disabled.
9385 Note: The interface is currently not adequate for trapping
9387 individual exceptions. In the current version /usr/share/libpari23,
9388 the following keywords are recognized, but the name list will be
9389 expanded and changed in the future (all library mode errors can be
9390 trapped: it's a matter of defining the keywords to "gp", and there
9391 are currently far too many useless ones):
9392 "accurer": accuracy problem
9394 "archer": not available on this architecture or operating system
9396 "errpile": the PARI stack overflows
9398 "gdiver": division by 0
9400 "invmoder": impossible inverse modulo
9402 "siginter": SIGINT received (usually from Control-C)
9404 "talker": miscellaneous error
9406 "typeer": wrong type
9408 "user": user error (from the "error" function)
9410 type"(x)"
9412 this is useful only under "gp". Returns the internal type name of
9413 the PARI object "x" as a string. Check out existing type names
9414 with the metacommand "\t". For example type(1) will return
9415 ""t_INT"".
9416 The library syntax is type0"(x)", though the macro "typ" is usually
9418 simpler to use since it return an integer that can easily be
9419 matched with the symbols "t_*". The name "type" was avoided due to
9420 the fact that "type" is a reserved identifier for some C(++)
9421 compilers.
9422 version"()"
9424 Returns the current version number as a "t_VEC" with three integer
9425 components: major version number, minor version number and
9426 patchlevel. To check against a particular version number, you can
9427 use:
9428 if (lex(version(), [2,2,0]) >= 0,
9430 \\ code to be executed if we are running 2.2.0 or more recent.
9431 ,
9432 \\ compatibility code
9433 );
9434 whatnow"(key)"
9436 if keyword key is the name of a function that was present in GP
9437 version 1.39.15 or lower, outputs the new function name and syntax,
9438 if it changed at all (387 out of 560 did).
9439 write"(filename,{str}*)"
9441 writes (appends) to filename the remaining arguments, and appends a
9442 newline (same output as "print").
9443 write1"(filename,{str}*)"
9445 writes (appends) to filename the remaining arguments without a
9446 trailing newline (same output as "print1").
9447 writebin"(filename,{x})"
9449 writes (appends) to filename the object "x" in binary format. This
9450 format is not human readable, but contains the exact internal
9451 structure of "x", and is much faster to save/load than a string
9452 expression, as would be produced by "write". The binary file format
9453 includes a magic number, so that such a file can be recognized and
9454 correctly input by the regular "read" or "\r" function. If saved
9455 objects refer to (polynomial) variables that are not defined in the
9456 new session, they will be displayed in a funny way (see "Label
9457 se:kill").
9458 If "x" is omitted, saves all user variables from the session,
9460 together with their names. Reading such a ``named object'' back in
9461 a "gp" session will set the corresponding user variable to the
9462 saved value. E.g after
9463 x = 1; writebin("log")
9465 reading "log" into a clean session will set "x" to 1. The relative
9467 variables priorities (see "Label se:priority") of new variables set
9468 in this way remain the same (preset variables retain their former
9469 priority, but are set to the new value). In particular, reading
9470 such a session log into a clean session will restore all variables
9471 exactly as they were in the original one.
9472 User functions, installed functions and history objects can not be
9474 saved via this function. Just as a regular input file, a binary
9475 file can be compressed using "gzip", provided the file name has the
9476 standard ".gz" extension.
9477 In the present implementation, the binary files are architecture
9479 dependent and compatibility with future versions of "gp" is not
9480 guaranteed. Hence binary files should not be used for long term
9481 storage (also, they are larger and harder to compress than text
9482 files).
9483 writetex"(filename,{str}*)"
9485 as "write", in TeX format.
9486
9488 Hey! The above document had some coding errors, which are explained
9489 below:
9490 Around line 9532:
9492 '=item' outside of any '=over'
9493 Around line 9723:
9495 You forgot a '=back' before '=head2'
9496 Around line 9734:
9498 '=item' outside of any '=over'
9499 =over without closing =back
9501perl v5.32.1 2021-01-27 libPARI(3)