1libPARI(3) User Contributed Perl Documentation libPARI(3)
2
6 libPARI - Functions and Operations Available in PARI and GP
7
9 The functions and operators available in PARI and in the GP/PARI calcu‐
10 lator are numerous and everexpanding. Here is a description of the ones
11 available in version 2.2.0. It should be noted that many of these func‐
12 tions accept quite different types as arguments, but others are more
13 restricted. The list of acceptable types will be given for each func‐
14 tion or class of functions. Except when stated otherwise, it is under‐
15 stood that a function or operation which should make natural sense is
16 legal. In this chapter, we will describe the functions according to a
17 rough classification. The general entry looks something like:
18 foo"(x,{flag = 0})": short description.
20 The library syntax is foo"(x,flag)".
22 This means that the GP function "foo" has one mandatory argument "x",
24 and an optional one, "flag", whose default value is 0 (the "{}" should
25 never be typed, it is just a convenient notation we will use throughout
26 to denote optional arguments). That is, you can type "foo(x,2)", or
27 foo(x), which is then understood to mean "foo(x,0)". As well, a comma
28 or closing parenthesis, where an optional argument should have been,
29 signals to GP it should use the default. Thus, the syntax "foo(x,)" is
30 also accepted as a synonym for our last expression. When a function has
31 more than one optional argument, the argument list is filled with user
32 supplied values, in order. And when none are left, the defaults are
33 used instead. Thus, assuming that "foo"'s prototype had been
34 " foo({x = 1},{y = 2},{z = 3}), "
36 typing in "foo(6,4)" would give you "foo(6,4,3)". In the rare case when
38 you want to set some far away flag, and leave the defaults in between
39 as they stand, you can use the ``empty arg'' trick alluded to above:
40 "foo(6,,1)" would yield "foo(6,2,1)". By the way, "foo()" by itself
41 yields "foo(1,2,3)" as was to be expected. In this rather special case
42 of a function having no mandatory argument, you can even omit the "()":
43 a standalone "foo" would be enough (though we don't really recommend it
44 for your scripts, for the sake of clarity). In defining GP syntax, we
45 strove to put optional arguments at the end of the argument list (of
46 course, since they would not make sense otherwise), and in order of
47 decreasing usefulness so that, most of the time, you will be able to
48 ignore them.
49 Binary Flags. For some of these optional flags, we adopted the custom‐
51 ary binary notation as a compact way to represent many toggles with
52 just one number. Letting "(p_0,...,p_n)" be a list of switches (i.e. of
53 properties which can be assumed to take either the value 0 or 1), the
54 number "2^3 + 2^5 = 40" means that "p_3" and "p_5" have been set (that
55 is, set to 1), and none of the others were (that is, they were set to
56 0). This will usually be announced as ``The binary digits of "flag"
57 mean 1: "p_0", 2: "p_1", 4: "p_2"'', and so on, using the available
58 consecutive powers of 2.
59 Pointers. If a parameter in the function prototype is prefixed with a &
61 sign, as in
62 foo"(x,&e)"
64 it means that, besides the normal return value, the variable named "e"
66 may be set as a side effect. When passing the argument, the & sign has
67 to be typed in explicitly. As of version 2.2.0, this "pointer" argument
68 is optional for all documented functions, hence the & will always
69 appear between brackets as in "issquare""(x,{&e})".
70 About library programming. To finish with our generic simple-minded
72 example, the library function "foo", as defined above, is seen to have
73 two mandatory arguments, "x" and flag (no PARI mathematical function
74 has been implemented so as to accept a variable number of arguments).
75 When not mentioned otherwise, the result and arguments of a function
76 are assumed implicitly to be of type "GEN". Most other functions
77 return an object of type "long" integer in C (see Chapter 4). The vari‐
78 able or parameter names prec and flag always denote "long" integers.
79 The "entree" type is used by the library to implement iterators (loops,
81 sums, integrals, etc.) when a formal variable has to successively
82 assume a number of values in a given set. When programming with the
83 library, it is easier and much more efficient to code loops and the
84 like directly. Hence this type is not documented, although it does
85 appear in a few library function prototypes below. See "Label se:sums"
86 for more details.
87
89 +"/"-
90 The expressions "+""x" and "-""x" refer to monadic operators (the first
92 does nothing, the second negates "x").
93 The library syntax is gneg"(x)" for "-""x".
95 +, "-"
97 The expression "x" "+" "y" is the sum and "x" "-" "y" is the difference
99 of "x" and "y". Among the prominent impossibilities are addition/sub‐
100 traction between a scalar type and a vector or a matrix, between vec‐
101 tor/matrices of incompatible sizes and between an integermod and a real
102 number.
103 The library syntax is gadd"(x,y)" "x" "+" "y", "gsub(x,y)" for "x" "-"
105 "y".
106 *
108 The expression "x" "*" "y" is the product of "x" and "y". Among the
110 prominent impossibilities are multiplication between vector/matrices of
111 incompatible sizes, between an integermod and a real number. Note that
112 because of vector and matrix operations, "*" is not necessarily commu‐
113 tative. Note also that since multiplication between two column or two
114 row vectors is not allowed, to obtain the scalar product of two vectors
115 of the same length, you must multiply a line vector by a column vector,
116 if necessary by transposing one of the vectors (using the operator "~"
117 or the function "mattranspose", see "Label se:linear_algebra").
118 If "x" and "y" are binary quadratic forms, compose them. See also "qfb‐
120 nucomp" and "qfbnupow".
121 The library syntax is gmul"(x,y)" for "x" "*" "y". Also available is
123 "gsqr(x)" for "x" "*" "x" (faster of course!).
124 /
126 The expression "x" "/" "y" is the quotient of "x" and "y". In addition
128 to the impossibilities for multiplication, note that if the divisor is
129 a matrix, it must be an invertible square matrix, and in that case the
130 result is "x*y^{-1}". Furthermore note that the result is as exact as
131 possible: in particular, division of two integers always gives a ratio‐
132 nal number (which may be an integer if the quotient is exact) and not
133 the Euclidean quotient (see "x" "\" "y" for that), and similarly the
134 quotient of two polynomials is a rational function in general. To
135 obtain the approximate real value of the quotient of two integers, add
136 0. to the result; to obtain the approximate "p"-adic value of the quo‐
137 tient of two integers, add "O(p^k)" to the result; finally, to obtain
138 the Taylor series expansion of the quotient of two polynomials, add
139 "O(X^k)" to the result or use the "taylor" function (see "Label se:tay‐
140 lor").
141 The library syntax is gdiv"(x,y)" for "x" "/" "y".
143 \
145 The expression "x" "\" "y" is the
147 Euclidean quotient of "x" and "y". The types must be either both inte‐
149 ger or both polynomials. The result is the Euclidean quotient. In the
150 case of integer division, the quotient is such that the corresponding
151 remainder is non-negative.
152 The library syntax is gdivent"(x,y)" for "x" "\" "y".
154 \/
156 The expression "x" "\/" "y" is the Euclidean quotient of "x" and "y".
158 The types must be either both integer or both polynomials. The result
159 is the rounded Euclidean quotient. In the case of integer division, the
160 quotient is such that the corresponding remainder is smallest in abso‐
161 lute value and in case of a tie the quotient closest to "+ oo " is cho‐
162 sen.
163 The library syntax is gdivround"(x,y)" for "x" "\/" "y".
165 %
167 The expression "x" "%" "y" is the
169 Euclidean remainder of "x" and "y". The modulus "y" must be of type
171 integer or polynomial. The result is the remainder, always non-negative
172 in the case of integers. Allowed dividend types are scalar exact types
173 when the modulus is an integer, and polynomials, polmods and rational
174 functions when the modulus is a polynomial.
175 The library syntax is gmod"(x,y)" for "x" "%" "y".
177 divrem"(x,y)"
179 creates a column vector with two components, the first being the
181 Euclidean quotient, the second the Euclidean remainder, of the division
182 of "x" by "y". This avoids the need to do two divisions if one needs
183 both the quotient and the remainder. The arguments must be both inte‐
184 gers or both polynomials; in the case of integers, the remainder is
185 non-negative.
186 The library syntax is gdiventres"(x,y)".
188 ^
190 The expression "x^n" is powering. If the exponent is an integer, then
192 exact operations are performed using binary (left-shift) powering tech‐
193 niques. In particular, in this case "x" cannot be a vector or matrix
194 unless it is a square matrix (and moreover invertible if the exponent
195 is negative). If "x" is a "p"-adic number, its precision will increase
196 if "v_p(n) > 0". PARI is able to rewrite the multiplication "x * x" of
197 two identical objects as "x^2", or sqr(x) (here, identical means the
198 operands are two different labels referencing the same chunk of memory;
199 no equality test is performed). This is no longer true when more than
200 two arguments are involved.
201 If the exponent is not of type integer, this is treated as a transcen‐
203 dental function (see "Label se:trans"), and in particular has the
204 effect of componentwise powering on vector or matrices.
205 As an exception, if the exponent is a rational number "p/q" and "x" an
207 integer modulo a prime, return a solution "y" of "y^q = x^p" if it
208 exists. Currently, "q" must not have large prime factors.
209 Beware that
211 ? Mod(7,19)^(1/2)
213 %1 = Mod(11, 19)/*is any square root*/
214 ? sqrt(Mod(7,19))
215 %2 = Mod(8, 19)/*is the smallest square root*/
216 ? Mod(7,19)^(3/5)
217 %3 = Mod(1, 19)
218 ? %3^(5/3)
219 %4 = Mod(1, 19)/*Mod(7,19) is just another cubic root*/
220 The library syntax is gpow"(x,n,prec)" for "x^n".
222 shift"(x,n)" or "x" "<< " "n" ( = "x" ">> " "(-n)")
224 shifts "x" componentwise left by "n" bits if "n >= 0" and right by
226 "⎪n⎪" bits if "n < 0". A left shift by "n" corresponds to multiplica‐
227 tion by "2^n". A right shift of an integer "x" by "⎪n⎪" corresponds to
228 a Euclidean division of "x" by "2^{⎪n⎪}" with a remainder of the same
229 sign as "x", hence is not the same (in general) as "x \ 2^n".
230 The library syntax is gshift"(x,n)" where "n" is a "long".
232 shiftmul"(x,n)"
234 multiplies "x" by "2^n". The difference with "shift" is that when "n <
236 0", ordinary division takes place, hence for example if "x" is an inte‐
237 ger the result may be a fraction, while for "shift" Euclidean division
238 takes place when "n < 0" hence if "x" is an integer the result is still
239 an integer.
240 The library syntax is gmul2n"(x,n)" where "n" is a "long".
242 Comparison and boolean operators
244 The six standard comparison operators "<= ", "< ", ">= ", "> ", " == ",
246 "! = " are available in GP, and in library mode under the names gle,
247 glt, gge, ggt, geq, gne respectively. The library syntax is "co(x,y)",
248 where co is the comparison operator. The result is 1 (as a "GEN") if
249 the comparison is true, 0 (as a "GEN") if it is false.
250 The standard boolean functions "⎪⎪" (inclusive or), "&&" (and) and "!"
252 (not) are also available, and the library syntax is "gor(x,y)",
253 "gand(x,y)" and "gnot(x)" respectively.
254 In library mode, it is in fact usually preferable to use the two basic
256 functions which are "gcmp(x,y)" which gives the sign (1, 0, or -1) of
257 "x-y", where "x" and "y" must be in R, and "gegal(x,y)" which can be
258 applied to any two PARI objects "x" and "y" and gives 1 (i.e. true) if
259 they are equal (but not necessarily identical), 0 (i.e. false) other‐
260 wise. Particular cases of gegal which should be used are "gcmp0(x)"
261 ("x == 0" ?), "gcmp1(x)" ("x == 1" ?), and "gcmp_1(x)" ("x == -1" ?).
262 Note that "gcmp0(x)" tests whether "x" is equal to zero, even if "x" is
264 not an exact object. To test whether "x" is an exact object which is
265 equal to zero, one must use "isexactzero".
266 Also note that the "gcmp" and "gegal" functions return a C-integer, and
268 not a "GEN" like "gle" etc.
269 GP accepts the following synonyms for some of the above functions:
271 since we thought it might easily lead to confusion, we don't use the
272 customary C operators for bitwise "and" or bitwise "or" (use "bitand"
273 or "bitor"), hence "⎪" and "&" are accepted as synonyms of "⎪⎪" and
274 "&&" respectively. Also, "< > " is accepted as a synonym for "! = ".
275 On the other hand, " = " is definitely not a synonym for " == " since
276 it is the assignment statement. and bitwise or"
277 lex"(x,y)"
279 gives the result of a lexicographic comparison between "x" and "y".
281 This is to be interpreted in quite a wide sense. For example, the vec‐
282 tor "[1,3]" will be considered smaller than the longer vector
283 "[1,3,-1]" (but of course larger than "[1,2,5]"), i.e. "lex([1,3],
284 [1,3,-1])" will return "-1".
285 The library syntax is lexcmp"(x,y)".
287 sign"(x)"
289 sign (0, 1 or "-1") of "x", which must be of type integer, real or
291 fraction.
292 The library syntax is gsigne"(x)". The result is a "long".
294 max"(x,y)" and min"(x,y)"
296 creates the maximum and minimum of "x" and "y" when they can be com‐
298 pared.
299 The library syntax is gmax"(x,y)" and "gmin(x,y)".
301 vecmax"(x)"
303 if "x" is a vector or a matrix, returns the maximum of the elements of
305 "x", otherwise returns a copy of "x". Returns "- oo " in the form of
306 "-(2^{31}-1)" (or "-(2^{63}-1)" for 64-bit machines) if "x" is empty.
307 The library syntax is vecmax"(x)".
309 vecmin"(x)"
311 if "x" is a vector or a matrix, returns the minimum of the elements of
313 "x", otherwise returns a copy of "x". Returns "+ oo " in the form of
314 "2^{31}-1" (or "2^{63}-1" for 64-bit machines) if "x" is empty.
315 The library syntax is vecmin"(x)".
317
319 Many of the conversion functions are rounding or truncating operations.
320 In this case, if the argument is a rational function, the result is the
321 Euclidean quotient of the numerator by the denominator, and if the
322 argument is a vector or a matrix, the operation is done componentwise.
323 This will not be restated for every function.
324 List"({x = []})"
326 transforms a (row or column) vector "x" into a list. The only other way
328 to create a "t_LIST" is to use the function "listcreate".
329 This is useless in library mode.
331 Mat"({x = []})"
333 transforms the object "x" into a matrix. If "x" is not a vector or a
335 matrix, this creates a "1 x 1" matrix. If "x" is a row (resp. column)
336 vector, this creates a 1-row (resp. 1-column) matrix. If "x" is
337 already a matrix, a copy of "x" is created.
338 This function can be useful in connection with the function "concat"
340 (see there).
341 The library syntax is gtomat"(x)".
343 Mod"(x,y,{flag = 0})"
345 creates the PARI object "(x mod y)", i.e. an integermod or a polmod.
347 "y" must be an integer or a polynomial. If "y" is an integer, "x" must
348 be an integer, a rational number, or a "p"-adic number compatible with
349 the modulus "y". If "y" is a polynomial, "x" must be a scalar (which is
350 not a polmod), a polynomial, a rational function, or a power series.
351 This function is not the same as "x" "%" "y", the result of which is an
353 integer or a polynomial.
354 If "flag" is equal to 1, the modulus of the created result is put on
356 the heap and not on the stack, and hence becomes a permanent copy which
357 cannot be erased later by garbage collecting (see "Label se:garbage").
358 Functions will operate faster on such objects and memory consumption
359 will be lower. On the other hand, care should be taken to avoid creat‐
360 ing too many such objects.
361 Under GP, the same effect can be obtained by assigning the object to a
363 GP variable (the value of which is a permanent object for the duration
364 of the relevant library function call, and is treated as such). This
365 value is subject to garbage collection, since it will be deleted when
366 the value changes. This is preferable and the above flag is only
367 retained for compatibility reasons (it can still be useful in library
368 mode).
369 The library syntax is Mod0"(x,y,flag)". Also available are
371 "*" for "flag = 1": "gmodulo(x,y)".
373 "*" for "flag = 0": "gmodulcp(x,y)".
375 Pol"(x,{v = x})"
377 transforms the object "x" into a polynomial with main variable "v". If
379 "x" is a scalar, this gives a constant polynomial. If "x" is a power
380 series, the effect is identical to "truncate" (see there), i.e. it
381 chops off the "O(X^k)". If "x" is a vector, this function creates the
382 polynomial whose coefficients are given in "x", with "x[1]" being the
383 leading coefficient (which can be zero).
384 Warning: this is not a substitution function. It is intended to be
386 quick and dirty. So if you try "Pol(a,y)" on the polynomial "a = x+y",
387 you will get "y+y", which is not a valid PARI object.
388 The library syntax is gtopoly"(x,v)", where "v" is a variable number.
390 Polrev"(x,{v = x})"
392 transform the object "x" into a polynomial with main variable "v". If
394 "x" is a scalar, this gives a constant polynomial. If "x" is a power
395 series, the effect is identical to "truncate" (see there), i.e. it
396 chops off the "O(X^k)". If "x" is a vector, this function creates the
397 polynomial whose coefficients are given in "x", with "x[1]" being the
398 constant term. Note that this is the reverse of "Pol" if "x" is a vec‐
399 tor, otherwise it is identical to "Pol".
400 The library syntax is gtopolyrev"(x,v)", where "v" is a variable num‐
402 ber.
403 Qfb"(a,b,c,{D = 0.})"
405 creates the binary quadratic form "ax^2+bxy+cy^2". If "b^2-4ac > 0",
407 initialize Shanks' distance function to "D".
408 The library syntax is Qfb0"(a,b,c,D,prec)". Also available are
410 "qfi(a,b,c)" (when "b^2-4ac < 0"), and "qfr(a,b,c,d)" (when "b^2-4ac >
411 0").
412 Ser"(x,{v = x})"
414 transforms the object "x" into a power series with main variable "v"
416 ("x" by default). If "x" is a scalar, this gives a constant power
417 series with precision given by the default "serieslength" (correspond‐
418 ing to the C global variable "precdl"). If "x" is a polynomial, the
419 precision is the greatest of "precdl" and the degree of the polynomial.
420 If "x" is a vector, the precision is similarly given, and the coeffi‐
421 cients of the vector are understood to be the coefficients of the power
422 series starting from the constant term (i.e. the reverse of the func‐
423 tion "Pol").
424 The warning given for "Pol" applies here: this is not a substitution
426 function.
427 The library syntax is gtoser"(x,v)", where "v" is a variable number
429 (i.e. a C integer).
430 Set"({x = []})"
432 converts "x" into a set, i.e. into a row vector with strictly increas‐
434 ing entries. "x" can be of any type, but is most useful when "x" is
435 already a vector. The components of "x" are put in canonical form (type
436 "t_STR") so as to be easily sorted. To recover an ordinary "GEN" from
437 such an element, you can apply "eval" to it.
438 The library syntax is gtoset"(x)".
440 Str"({x = ""},{flag = 0})"
442 converts "x" into a character string (type "t_STR", the empty string if
444 "x" is omitted). To recover an ordinary "GEN" from a string, apply
445 "eval" to it. The arguments of "Str" are evaluated in string context
446 (see "Label se:strings"). If flag is set, treat "x" as a filename and
447 perform environment expansion on the string. This feature can be used
448 to read environment variable values.
449 ? i = 1; Str("x" i)
451 %1 = "x1"
452 ? eval(%)
453 %2 = x1;
454 ? Str("$HOME", 1)
455 %3 = "/home/pari"
456 The library syntax is strtoGENstr"(x,flag)". This function is mostly
458 useless in library mode. Use the pair "strtoGEN"/"GENtostr" to convert
459 between "char*" and "GEN".
460 Vec"({x = []})"
462 transforms the object "x" into a row vector. The vector will be with
464 one component only, except when "x" is a vector/matrix or a quadratic
465 form (in which case the resulting vector is simply the initial object
466 considered as a row vector), but more importantly when "x" is a polyno‐
467 mial or a power series. In the case of a polynomial, the coefficients
468 of the vector start with the leading coefficient of the polynomial,
469 while for power series only the significant coefficients are taken into
470 account, but this time by increasing order of degree.
471 The library syntax is gtovec"(x)".
473 binary"(x)"
475 outputs the vector of the binary digits of "⎪x⎪". Here "x" can be an
477 integer, a real number (in which case the result has two components,
478 one for the integer part, one for the fractional part) or a vec‐
479 tor/matrix.
480 The library syntax is binaire"(x)".
482 bitand"(x,y)"
484 bitwise "and" of two integers "x" and "y", that is the integer
486 "sum (x_i and y_i) 2^i"
488 Negative numbers behave as if modulo a huge power of 2.
490 The library syntax is gbitand"(x,y)".
492 bitneg"(x,{n = -1})"
494 bitwise negation of an integer "x", truncated to "n" bits, that is the
496 integer
497 "sum_{i = 0}^n not(x_i) 2^i"
499 The special case "n = -1" means no truncation: an infinite sequence of
501 leading 1 is then represented as a negative number.
502 Negative numbers behave as if modulo a huge power of 2.
504 The library syntax is gbitneg"(x)".
506 bitnegimply"(x,y)"
508 bitwise negated imply of two integers "x" and "y" (or "not" "(x ==>
510 y)"), that is the integer
511 "sum (x_i and not(y_i)) 2^i"
513 Negative numbers behave as if modulo a huge power of 2.
515 The library syntax is gbitnegimply"(x,y)".
517 bitor"(x,y)"
519 bitwise (inclusive) "or" of two integers "x" and "y", that is the inte‐
521 ger inclusive or"
522 "sum (x_i or y_i) 2^i"
524 Negative numbers behave as if modulo a huge power of 2.
526 The library syntax is gbitor"(x,y)".
528 bittest"(x,n)"
530 outputs the "n^{th}" bit of "⎪x⎪" starting from the right (i.e. the
532 coefficient of "2^n" in the binary expansion of "x"). The result is 0
533 or 1. To extract several bits at once as a vector, pass a vector for
534 "n".
535 The library syntax is bittest"(x,n)", where "n" and the result are
537 "long"s.
538 bitxor"(x,y)"
540 bitwise (exclusive) "or" of two integers "x" and "y", that is the inte‐
542 ger exclusive or"
543 "sum (x_i xor y_i) 2^i"
545 Negative numbers behave as if modulo a huge power of 2.
547 The library syntax is gbitxor"(x,y)".
549 ceil"(x)"
551 ceiling of "x". When "x" is in R, the result is the smallest integer
553 greater than or equal to "x". Applied to a rational function, ceil(x)
554 returns the euclidian quotient of the numerator by the denominator.
555 The library syntax is gceil"(x)".
557 centerlift"(x,{v})"
559 lifts an element "x = a mod n" of "Z/nZ" to "a" in Z, and similarly
561 lifts a polmod to a polynomial. This is the same as "lift" except that
562 in the particular case of elements of "Z/nZ", the lift "y" is such that
563 "-n/2 < y <= n/2". If "x" is of type fraction, complex, quadratic,
564 polynomial, power series, rational function, vector or matrix, the lift
565 is done for each coefficient. Real and "p"-adics are forbidden.
566 The library syntax is centerlift0"(x,v)", where "v" is a "long" and an
568 omitted "v" is coded as "-1". Also available is centerlift"(x)" = "cen‐
569 terlift0(x,-1)".
570 changevar"(x,y)"
572 creates a copy of the object "x" where its variables are modified
574 according to the permutation specified by the vector "y". For example,
575 assume that the variables have been introduced in the order "x", "a",
576 "b", "c". Then, if "y" is the vector "[x,c,a,b]", the variable "a" will
577 be replaced by "c", "b" by "a", and "c" by "b", "x" being unchanged.
578 Note that the permutation must be completely specified, e.g. "[c,a,b]"
579 would not work, since this would replace "x" by "c", and leave "a" and
580 "b" unchanged (as well as "c" which is the fourth variable of the ini‐
581 tial list). In particular, the new variable names must be distinct.
582 The library syntax is changevar"(x,y)".
584 components of a PARI object
586 There are essentially three ways to extract the components from a PARI
588 object.
589 The first and most general, is the function "component(x,n)" which
591 extracts the "n^{th}"-component of "x". This is to be understood as
592 follows: every PARI type has one or two initial code words. The compo‐
593 nents are counted, starting at 1, after these code words. In particular
594 if "x" is a vector, this is indeed the "n^{th}"-component of "x", if
595 "x" is a matrix, the "n^{th}" column, if "x" is a polynomial, the
596 "n^{th}" coefficient (i.e. of degree "n-1"), and for power series, the
597 "n^{th}" significant coefficient. The use of the function "component"
598 implies the knowledge of the structure of the different PARI types,
599 which can be recalled by typing "\t" under GP.
600 The library syntax is compo"(x,n)", where "n" is a "long".
602 The two other methods are more natural but more restricted. The func‐
604 tion " polcoeff(x,n)" gives the coefficient of degree "n" of the poly‐
605 nomial or power series "x", with respect to the main variable of "x"
606 (to check variable ordering, or to change it, use the function
607 "reorder", see "Label se:reorder"). In particular if "n" is less than
608 the valuation of "x" or in the case of a polynomial, greater than the
609 degree, the result is zero (contrary to "compo" which would send an
610 error message). If "x" is a power series and "n" is greater than the
611 largest significant degree, then an error message is issued.
612 For greater flexibility, vector or matrix types are also accepted for
614 "x", and the meaning is then identical with that of "compo".
615 Finally note that a scalar type is considered by "polcoeff" as a poly‐
617 nomial of degree zero.
618 The library syntax is truecoeff"(x,n)".
620 The third method is specific to vectors or matrices under GP. If "x" is
622 a (row or column) vector, then "x[n]" represents the "n^{th}" component
623 of "x", i.e. "compo(x,n)". It is more natural and shorter to write. If
624 "x" is a matrix, "x[m,n]" represents the coefficient of row "m" and
625 column "n" of the matrix, "x[m,]" represents the "m^{th}" row of "x",
626 and "x[,n]" represents the "n^{th}" column of "x".
627 Finally note that in library mode, the macros coeff and mael are avail‐
629 able to deal with the non-recursivity of the "GEN" type from the com‐
630 piler's point of view. See the discussion on typecasts in Chapter 4.
631 conj"(x)"
633 conjugate of "x". The meaning of this is clear, except that for real
635 quadratic numbers, it means conjugation in the real quadratic field.
636 This function has no effect on integers, reals, integermods, fractions
637 or "p"-adics. The only forbidden type is polmod (see "conjvec" for
638 this).
639 The library syntax is gconj"(x)".
641 conjvec"(x)"
643 conjugate vector representation of "x". If "x" is a polmod, equal to
645 "Mod""(a,q)", this gives a vector of length degree(q) containing the
646 complex embeddings of the polmod if "q" has integral or rational coef‐
647 ficients, and the conjugates of the polmod if "q" has some integermod
648 coefficients. The order is the same as that of the "polroots" func‐
649 tions. If "x" is an integer or a rational number, the result is "x". If
650 "x" is a (row or column) vector, the result is a matrix whose columns
651 are the conjugate vectors of the individual elements of "x".
652 The library syntax is conjvec"(x,prec)".
654 denominator"(x)"
656 lowest denominator of "x". The meaning of this is clear when "x" is a
658 rational number or function. When "x" is an integer or a polynomial,
659 the result is equal to 1. When "x" is a vector or a matrix, the lowest
660 common denominator of the components of "x" is computed. All other
661 types are forbidden.
662 The library syntax is denom"(x)".
664 floor"(x)"
666 floor of "x". When "x" is in R, the result is the largest integer
668 smaller than or equal to "x". Applied to a rational function, floor(x)
669 returns the euclidian quotient of the numerator by the denominator.
670 The library syntax is gfloor"(x)".
672 frac"(x)"
674 fractional part of "x". Identical to "x-floor(x)". If "x" is real, the
676 result is in "[0,1[".
677 The library syntax is gfrac"(x)".
679 imag"(x)"
681 imaginary part of "x". When "x" is a quadratic number, this is the
683 coefficient of "omega" in the ``canonical'' integral basis "(1,omega)".
684 The library syntax is gimag"(x)".
686 length"(x)"
688 number of non-code words in "x" really used (i.e. the effective length
690 minus 2 for integers and polynomials). In particular, the degree of a
691 polynomial is equal to its length minus 1. If "x" has type "t_STR",
692 output number of letters.
693 The library syntax is glength"(x)" and the result is a C long.
695 lift"(x,{v})"
697 lifts an element "x = a mod n" of "Z/nZ" to "a" in Z, and similarly
699 lifts a polmod to a polynomial if "v" is omitted. Otherwise, lifts
700 only polmods with main variable "v" (if "v" does not occur in "x",
701 lifts only intmods). If "x" is of type fraction, complex, quadratic,
702 polynomial, power series, rational function, vector or matrix, the lift
703 is done for each coefficient. Forbidden types for "x" are reals and
704 "p"-adics.
705 The library syntax is lift0"(x,v)", where "v" is a "long" and an omit‐
707 ted "v" is coded as "-1". Also available is lift"(x)" = "lift0(x,-1)".
708 norm"(x)"
710 algebraic norm of "x", i.e. the product of "x" with its conjugate (no
712 square roots are taken), or conjugates for polmods. For vectors and
713 matrices, the norm is taken componentwise and hence is not the
714 "L^2"-norm (see "norml2"). Note that the norm of an element of R is its
715 square, so as to be compatible with the complex norm.
716 The library syntax is gnorm"(x)".
718 norml2"(x)"
720 square of the "L^2"-norm of "x". "x" must be a (row or column) vector.
722 The library syntax is gnorml2"(x)".
724 numerator"(x)"
726 numerator of "x". When "x" is a rational number or function, the mean‐
728 ing is clear. When "x" is an integer or a polynomial, the result is "x"
729 itself. When "x" is a vector or a matrix, then numerator(x) is defined
730 to be "denominator(x)*x". All other types are forbidden.
731 The library syntax is numer"(x)".
733 numtoperm"(n,k)"
735 generates the "k"-th permutation (as a row vector of length "n") of the
737 numbers 1 to "n". The number "k" is taken modulo "n!", i.e. inverse
738 function of "permtonum".
739 The library syntax is permute"(n,k)", where "n" is a "long".
741 padicprec"(x,p)"
743 absolute "p"-adic precision of the object "x". This is the minimum
745 precision of the components of "x". The result is "VERYBIGINT"
746 ("2^{31}-1" for 32-bit machines or "2^{63}-1" for 64-bit machines) if
747 "x" is an exact object.
748 The library syntax is padicprec"(x,p)" and the result is a "long" inte‐
750 ger.
751 permtonum"(x)"
753 given a permutation "x" on "n" elements, gives the number "k" such that
755 "x = numtoperm(n,k)", i.e. inverse function of "numtoperm".
756 The library syntax is permuteInv"(x)".
758 precision"(x,{n})"
760 gives the precision in decimal digits of the PARI object "x". If "x" is
762 an exact object, the largest single precision integer is returned. If
763 "n" is not omitted, creates a new object equal to "x" with a new preci‐
764 sion "n". This is to be understood as follows:
765 For exact types, no change. For "x" a vector or a matrix, the operation
767 is done componentwise.
768 For real "x", "n" is the number of desired significant decimal digits.
770 If "n" is smaller than the precision of "x", "x" is truncated, other‐
771 wise "x" is extended with zeros.
772 For "x" a "p"-adic or a power series, "n" is the desired number of sig‐
774 nificant "p"-adic or "X"-adic digits, where "X" is the main variable of
775 "x".
776 Note that the function "precision" never changes the type of the
778 result. In particular it is not possible to use it to obtain a polyno‐
779 mial from a power series. For that, see "truncate".
780 The library syntax is precision0"(x,n)", where "n" is a "long". Also
782 available are "ggprecision(x)" (result is a "GEN") and "gprec(x,n)",
783 where "n" is a "long".
784 random"({N = 2^{31}})"
786 gives a random integer between 0 and "N-1". "N" can be arbitrary large.
788 This is an internal PARI function and does not depend on the system's
789 random number generator. Note that the resulting integer is obtained by
790 means of linear congruences and will not be well distributed in arith‐
791 metic progressions.
792 The library syntax is genrand"(N)".
794 real"(x)"
796 real part of "x". In the case where "x" is a quadratic number, this is
798 the coefficient of 1 in the ``canonical'' integral basis "(1,omega)".
799 The library syntax is greal"(x)".
801 round"(x,{&e})"
803 If "x" is in R, rounds "x" to the nearest integer and sets "e" to the
805 number of error bits, that is the binary exponent of the difference
806 between the original and the rounded value (the ``fractional part'').
807 If the exponent of "x" is too large compared to its precision (i.e. "e
808 > 0"), the result is undefined and an error occurs if "e" was not
809 given.
810 Important remark: note that, contrary to the other truncation func‐
812 tions, this function operates on every coefficient at every level of a
813 PARI object. For example
814 "truncate((2.4*X^2-1.7)/(X)) = 2.4*X,"
816 whereas
818 "round((2.4*X^2-1.7)/(X)) = (2*X^2-2)/(X)."
820 An important use of "round" is to get exact results after a long
822 approximate computation, when theory tells you that the coefficients
823 must be integers.
824 The library syntax is grndtoi"(x,&e)", where "e" is a "long" integer.
826 Also available is "ground(x)".
827 simplify"(x)"
829 this function tries to simplify the object "x" as much as it can. The
831 simplifications do not concern rational functions (which PARI automati‐
832 cally tries to simplify), but type changes. Specifically, a complex or
833 quadratic number whose imaginary part is exactly equal to 0 (i.e. not a
834 real zero) is converted to its real part, and a polynomial of degree
835 zero is converted to its constant term. For all types, this of course
836 occurs recursively. This function is useful in any case, but in partic‐
837 ular before the use of arithmetic functions which expect integer argu‐
838 ments, and not for example a complex number of 0 imaginary part and
839 integer real part (which is however printed as an integer).
840 The library syntax is simplify"(x)".
842 sizebyte"(x)"
844 outputs the total number of bytes occupied by the tree representing the
846 PARI object "x".
847 The library syntax is taille2"(x)" which returns a "long". The function
849 taille returns the number of words instead.
850 sizedigit"(x)"
852 outputs a quick bound for the number of decimal digits of (the compo‐
854 nents of) "x", off by at most 1. If you want the exact value, you can
855 use "length(Str(x))", which is much slower.
856 The library syntax is sizedigit"(x)" which returns a "long".
858 truncate"(x,{&e})"
860 truncates "x" and sets "e" to the number of error bits. When "x" is in
862 R, this means that the part after the decimal point is chopped away,
863 "e" is the binary exponent of the difference between the original and
864 the truncated value (the ``fractional part''). If the exponent of "x"
865 is too large compared to its precision (i.e. "e > 0"), the result is
866 undefined and an error occurs if "e" was not given. The function
867 applies componentwise on rational functions and vector / matrices; "e"
868 is then the maximal number of error bits.
869 Note a very special use of "truncate": when applied to a power series,
871 it transforms it into a polynomial or a rational function with denomi‐
872 nator a power of "X", by chopping away the "O(X^k)". Similarly, when
873 applied to a "p"-adic number, it transforms it into an integer or a
874 rational number by chopping away the "O(p^k)".
875 The library syntax is gcvtoi"(x,&e)", where "e" is a "long" integer.
877 Also available is gtrunc"(x)".
878 valuation"(x,p)"
880 computes the highest exponent of "p" dividing "x". If "p" is of type
882 integer, "x" must be an integer, an integermod whose modulus is divisi‐
883 ble by "p", a fraction, a "q"-adic number with "q = p", or a polynomial
884 or power series in which case the valuation is the minimum of the valu‐
885 ation of the coefficients.
886 If "p" is of type polynomial, "x" must be of type polynomial or ratio‐
888 nal function, and also a power series if "x" is a monomial. Finally,
889 the valuation of a vector, complex or quadratic number is the minimum
890 of the component valuations.
891 If "x = 0", the result is "VERYBIGINT" ("2^{31}-1" for 32-bit machines
893 or "2^{63}-1" for 64-bit machines) if "x" is an exact object. If "x" is
894 a "p"-adic numbers or power series, the result is the exponent of the
895 zero. Any other type combinations gives an error.
896 The library syntax is ggval"(x,p)", and the result is a "long".
898 variable"(x)"
900 gives the main variable of the object "x", and "p" if "x" is a "p"-adic
902 number. Gives an error if "x" has no variable associated to it. Note
903 that this function is useful only in GP, since in library mode the
904 function "gvar" is more appropriate.
905 The library syntax is gpolvar"(x)". However, in library mode, this
907 function should not be used. Instead, test whether "x" is a "p"-adic
908 (type "t_PADIC"), in which case "p" is in "x[2]", or call the function
909 "gvar(x)" which returns the variable number of "x" if it exists, "BIG‐
910 INT" otherwise.
911
913 As a general rule, which of course in some cases may have exceptions,
914 transcendental functions operate in the following way:
915 "*" If the argument is either an integer, a real, a rational, a complex
917 or a quadratic number, it is, if necessary, first converted to a real
918 (or complex) number using the current precision held in the default
919 "realprecision". Note that only exact arguments are converted, while
920 inexact arguments such as reals are not.
921 Under GP this is transparent to the user, but when programming in
923 library mode, care must be taken to supply a meaningful parameter prec
924 as the last argument of the function if the first argument is an exact
925 object. This parameter is ignored if the argument is inexact.
926 Note that in library mode the precision argument prec is a word count
928 including codewords, i.e. represents the length in words of a real num‐
929 ber, while under GP the precision (which is changed by the metacommand
930 "\p" or using "default(realprecision,...)") is the number of signifi‐
931 cant decimal digits.
932 Note that some accuracies attainable on 32-bit machines cannot be
934 attained on 64-bit machines for parity reasons. For example the default
935 GP accuracy is 28 decimal digits on 32-bit machines, corresponding to
936 prec having the value 5, but this cannot be attained on 64-bit
937 machines.
938 After possible conversion, the function is computed. Note that even if
940 the argument is real, the result may be complex (e.g. "acos(2.0)" or
941 "acosh(0.0)"). Note also that the principal branch is always chosen.
942 "*" If the argument is an integermod or a "p"-adic, at present only a
944 few functions like "sqrt" (square root), "sqr" (square), "log", "exp",
945 powering, "teichmuller" (Teichmueller character) and "agm" (arith‐
946 metic-geometric mean) are implemented.
947 Note that in the case of a 2-adic number, sqr(x) may not be identical
949 to "x*x": for example if "x = 1+O(2^5)" and "y = 1+O(2^5)" then "x*y =
950 1+O(2^5)" while "sqr(x) = 1+O(2^6)". Here, "x * x" yields the same
951 result as sqr(x) since the two operands are known to be identical. The
952 same statement holds true for "p"-adics raised to the power "n", where
953 "v_p(n) > 0".
954 Remark: note that if we wanted to be strictly consistent with the PARI
956 philosophy, we should have "x*y = (4 mod 8)" and "sqr(x) = (4 mod 32)"
957 when both "x" and "y" are congruent to 2 modulo 4. However, since
958 integermod is an exact object, PARI assumes that the modulus must not
959 change, and the result is hence "(0 mod 4)" in both cases. On the other
960 hand, "p"-adics are not exact objects, hence are treated differently.
961 "*" If the argument is a polynomial, power series or rational function,
963 it is, if necessary, first converted to a power series using the cur‐
964 rent precision held in the variable "precdl". Under GP this again is
965 transparent to the user. When programming in library mode, however, the
966 global variable "precdl" must be set before calling the function if the
967 argument has an exact type (i.e. not a power series). Here "precdl" is
968 not an argument of the function, but a global variable.
969 Then the Taylor series expansion of the function around "X = 0" (where
971 "X" is the main variable) is computed to a number of terms depending on
972 the number of terms of the argument and the function being computed.
973 "*" If the argument is a vector or a matrix, the result is the compo‐
975 nentwise evaluation of the function. In particular, transcendental
976 functions on square matrices, which are not implemented in the present
977 version 2.2.0 (see Appendix B however), will have a slightly different
978 name if they are implemented some day.
979 ^
981 If "y" is not of type integer, "x^y" has the same effect as
983 "exp(y*ln(x))". It can be applied to "p"-adic numbers as well as to the
984 more usual types.
985 The library syntax is gpow"(x,y,prec)".
987 Euler
989 Euler's constant 0.57721.... Note that "Euler" is one of the few spe‐
991 cial reserved names which cannot be used for variables (the others are
992 "I" and "Pi", as well as all function names).
993 The library syntax is mpeuler"(prec)" where "prec" must be given. Note
995 that this creates "gamma" on the PARI stack, but a copy is also created
996 on the heap for quicker computations next time the function is called.
997 I
999 the complex number " sqrt {-1}".
1001 The library syntax is the global variable "gi" (of type "GEN").
1003 Pi
1005 the constant "Pi" (3.14159...).
1007 The library syntax is mppi"(prec)" where "prec" must be given. Note
1009 that this creates "Pi" on the PARI stack, but a copy is also created on
1010 the heap for quicker computations next time the function is called.
1011 abs"(x)"
1013 absolute value of "x" (modulus if "x" is complex). Power series and
1015 rational functions are not allowed. Contrary to most transcendental
1016 functions, an exact argument is not converted to a real number before
1017 applying "abs" and an exact result is returned if possible.
1018 ? abs(-1)
1020 %1 = 1
1021 ? abs(3/7 + 4/7*I)
1022 %2 = 5/7
1023 ? abs(1 + I)
1024 %3 = 1.414213562373095048801688724
1025 If "x" is a polynomial, returns "-x" if the leading coefficient is real
1027 and negative else returns "x". For a power series, the constant coeffi‐
1028 cient is considered instead.
1029 The library syntax is gabs"(x,prec)".
1031 acos"(x)"
1033 principal branch of "cos^{-1}(x)", i.e. such that "Re(acos(x)) belongs
1035 to [0,Pi]". If "x belongs to R" and "⎪x⎪ > 1", then acos(x) is complex.
1036 The library syntax is gacos"(x,prec)".
1038 acosh"(x)"
1040 principal branch of "cosh^{-1}(x)", i.e. such that "Im(acosh(x))
1042 belongs to [0,Pi]". If "x belongs to R" and "x < 1", then acosh(x) is
1043 complex.
1044 The library syntax is gach"(x,prec)".
1046 agm"(x,y)"
1048 arithmetic-geometric mean of "x" and "y". In the case of complex or
1050 negative numbers, the principal square root is always chosen. "p"-adic
1051 or power series arguments are also allowed. Note that a "p"-adic agm
1052 exists only if "x/y" is congruent to 1 modulo "p" (modulo 16 for "p =
1053 2"). "x" and "y" cannot both be vectors or matrices.
1054 The library syntax is agm"(x,y,prec)".
1056 arg"(x)"
1058 argument of the complex number "x", such that "-Pi < arg(x) <= Pi".
1060 The library syntax is garg"(x,prec)".
1062 asin"(x)"
1064 principal branch of "sin^{-1}(x)", i.e. such that "Re(asin(x)) belongs
1066 to [-Pi/2,Pi/2]". If "x belongs to R" and "⎪x⎪ > 1" then asin(x) is
1067 complex.
1068 The library syntax is gasin"(x,prec)".
1070 asinh"(x)"
1072 principal branch of "sinh^{-1}(x)", i.e. such that "Im(asinh(x))
1074 belongs to [-Pi/2,Pi/2]".
1075 The library syntax is gash"(x,prec)".
1077 atan"(x)"
1079 principal branch of "tan^{-1}(x)", i.e. such that "Re(atan(x)) belongs
1081 to ]-Pi/2,Pi/2[".
1082 The library syntax is gatan"(x,prec)".
1084 atanh"(x)"
1086 principal branch of "tanh^{-1}(x)", i.e. such that "Im(atanh(x))
1088 belongs to ]-Pi/2,Pi/2]". If "x belongs to R" and "⎪x⎪ > 1" then
1089 atanh(x) is complex.
1090 The library syntax is gath"(x,prec)".
1092 bernfrac"(x)"
1094 Bernoulli number "B_x", where "B_0 = 1", "B_1 = -1/2", "B_2 = 1/6",...,
1096 expressed as a rational number. The argument "x" should be of type
1097 integer.
1098 The library syntax is bernfrac"(x)".
1100 bernreal"(x)"
1102 Bernoulli number "B_x", as "bernfrac", but "B_x" is returned as a real
1104 number (with the current precision).
1105 The library syntax is bernreal"(x,prec)".
1107 bernvec"(x)"
1109 creates a vector containing, as rational numbers, the Bernoulli numbers
1111 "B_0", "B_2",..., "B_{2x}". These Bernoulli numbers can then be used as
1112 follows. Assume that this vector has been put into a variable, say
1113 "bernint". Then you can define under GP:
1114 bern(x) =
1116 {
1117 if (x == 1, return(-1/2));
1118 if (x < 0 ⎪⎪ x % 2, return(0));
1119 bernint[x/2+1]
1120 }
1121 and then bern(k) gives the Bernoulli number of index "k" as a rational
1123 number, exactly as bernreal(k) gives it as a real number. If you need
1124 only a few values, calling bernfrac(k) each time will be much more
1125 efficient than computing the huge vector above.
1126 The library syntax is bernvec"(x)".
1128 besseljh"(n,x)"
1130 "J"-Bessel function of half integral index. More precisely,
1132 "besseljh(n,x)" computes "J_{n+1/2}(x)" where "n" must be of type inte‐
1133 ger, and "x" is any element of C. In the present version 2.2.0, this
1134 function is not very accurate when "x" is small.
1135 The library syntax is jbesselh"(n,x,prec)".
1137 besselk"(nu,x,{flag = 0})"
1139 "K"-Bessel function of index nu (which can be complex) and argument
1141 "x". Only real and positive arguments "x" are allowed in the present
1142 version 2.2.0. If "flag" is equal to 1, uses another implementation of
1143 this function which is often faster.
1144 The library syntax is kbessel"(nu,x,prec)" and "kbessel2(nu,x,prec)"
1146 respectively.
1147 cos"(x)"
1149 cosine of "x".
1151 The library syntax is gcos"(x,prec)".
1153 cosh"(x)"
1155 hyperbolic cosine of "x".
1157 The library syntax is gch"(x,prec)".
1159 cotan"(x)"
1161 cotangent of "x".
1163 The library syntax is gcotan"(x,prec)".
1165 dilog"(x)"
1167 principal branch of the dilogarithm of "x", i.e. analytic continuation
1169 of the power series " log _2(x) = sum_{n >= 1}x^n/n^2".
1170 The library syntax is dilog"(x,prec)".
1172 eint1"(x,{n})"
1174 exponential integral "int_x^ oo (e^{-t})/(t)dt" ("x belongs to R")
1176 If "n" is present, outputs the "n"-dimensional vector
1178 "[eint1(x),...,eint1(nx)]" ("x >= 0"). This is faster than repeatedly
1179 calling "eint1(i * x)".
1180 The library syntax is veceint1"(x,n,prec)". Also available is
1182 "eint1(x,prec)".
1183 erfc"(x)"
1185 complementary error function "(2/ sqrt Pi)int_x^ oo e^{-t^2}dt".
1187 The library syntax is erfc"(x,prec)".
1189 eta"(x,{flag = 0})"
1191 Dedekind's "eta" function, without the "q^{1/24}". This means the fol‐
1193 lowing: if "x" is a complex number with positive imaginary part, the
1194 result is "prod_{n = 1}^ oo (1-q^n)", where "q = e^{2iPi x}". If "x" is
1195 a power series (or can be converted to a power series) with positive
1196 valuation, the result is "prod_{n = 1}^ oo (1-x^n)".
1197 If "flag = 1" and "x" can be converted to a complex number (i.e. is not
1199 a power series), computes the true "eta" function, including the lead‐
1200 ing "q^{1/24}".
1201 The library syntax is eta"(x,prec)".
1203 exp"(x)"
1205 exponential of "x". "p"-adic arguments with positive valuation are
1207 accepted.
1208 The library syntax is gexp"(x,prec)".
1210 gammah"(x)"
1212 gamma function evaluated at the argument "x+1/2". When "x" is an inte‐
1214 ger, this is much faster than using "gamma(x+1/2)".
1215 The library syntax is ggamd"(x,prec)".
1217 gamma"(x)"
1219 gamma function of "x". In the present version 2.2.0 the "p"-adic gamma
1221 function is not implemented.
1222 The library syntax is ggamma"(x,prec)".
1224 hyperu"(a,b,x)"
1226 "U"-confluent hypergeometric function with parameters "a" and "b". The
1228 parameters "a" and "b" can be complex but the present implementation
1229 requires "x" to be positive.
1230 The library syntax is hyperu"(a,b,x,prec)".
1232 incgam"(s,x,{y})"
1234 incomplete gamma function.
1236 "x" must be positive and "s" real. The result returned is "int_x^ oo
1238 e^{-t}t^{s-1}dt". When "y" is given, assume (of course without check‐
1239 ing!) that "y = Gamma(s)". For small "x", this will tremendously speed
1240 up the computation.
1241 The library syntax is incgam"(s,x,prec)" and "incgam4(s,x,y,prec)",
1243 respectively. There exist also the functions incgam1 and incgam2 which
1244 are used for internal purposes.
1245 incgamc"(s,x)"
1247 complementary incomplete gamma function.
1249 The arguments "s" and "x" must be positive. The result returned is
1251 "int_0^x e^{-t}t^{s-1}dt", when "x" is not too large.
1252 The library syntax is incgam3"(s,x,prec)".
1254 log"(x,{flag = 0})"
1256 principal branch of the natural logarithm of "x", i.e. such that
1258 "Im(ln(x)) belongs to ]-Pi,Pi]". The result is complex (with imaginary
1259 part equal to "Pi") if "x belongs to R" and "x < 0".
1260 "p"-adic arguments are also accepted for "x", with the convention that
1262 " ln (p) = 0". Hence in particular " exp ( ln (x))/x" will not in gen‐
1263 eral be equal to 1 but to a "(p-1)"-th root of unity (or "+-1" if "p =
1264 2") times a power of "p".
1265 If "flag" is equal to 1, use an agm formula suggested by Mestre, when
1267 "x" is real, otherwise identical to "log".
1268 The library syntax is glog"(x,prec)" or "glogagm(x,prec)".
1270 lngamma"(x)"
1272 principal branch of the logarithm of the gamma function of "x". Can
1274 have much larger arguments than "gamma" itself. In the present version
1275 2.2.0, the "p"-adic "lngamma" function is not implemented.
1276 The library syntax is glngamma"(x,prec)".
1278 polylog"(m,x,{flag = 0})"
1280 one of the different polylogarithms, depending on flag:
1282 If "flag = 0" or is omitted: "m^th" polylogarithm of "x", i.e. analytic
1284 continuation of the power series "Li_m(x) = sum_{n >= 1}x^n/n^m". The
1285 program uses the power series when "⎪x⎪^2 <= 1/2", and the power series
1286 expansion in " log (x)" otherwise. It is valid in a large domain (at
1287 least "⎪x⎪ < 230"), but should not be used too far away from the unit
1288 circle since it is then better to use the functional equation linking
1289 the value at "x" to the value at "1/x", which takes a trivial form for
1290 the variant below. Power series, polynomial, rational and vector/matrix
1291 arguments are allowed.
1292 For the variants to follow we need a notation: let " Re _m" denotes "
1294 Re " or " Im " depending whether "m" is odd or even.
1295 If "flag = 1": modified "m^th" polylogarithm of "x", called "~ D_m(x)"
1297 in Zagier, defined for "⎪x⎪ <= 1" by
1298 " Re _m(sum_{k = 0}^{m-1} ((- log ⎪x⎪)^k)/(k!)Li_{m-k}(x) +((- log
1300 ⎪x⎪)^{m-1})/(m!) log ⎪1-x⎪)."
1301 If "flag = 2": modified "m^th" polylogarithm of "x", called D_m(x) in
1303 Zagier, defined for "⎪x⎪ <= 1" by
1304 " Re _m(sum_{k = 0}^{m-1}((- log ⎪x⎪)^k)/(k!)Li_{m-k}(x) -(1)/(2)((-
1306 log ⎪x⎪)^m)/(m!))."
1307 If "flag = 3": another modified "m^th" polylogarithm of "x", called
1309 P_m(x) in Zagier, defined for "⎪x⎪ <= 1" by
1310 " Re _m(sum_{k = 0}^{m-1}(2^kB_k)/(k!)( log ⎪x⎪)^kLi_{m-k}(x)
1312 -(2^{m-1}B_m)/(m!)( log ⎪x⎪)^m)."
1313 These three functions satisfy the functional equation "f_m(1/x) =
1315 (-1)^{m-1}f_m(x)".
1316 The library syntax is polylog0"(m,x,flag,prec)".
1318 psi"(x)"
1320 the "psi"-function of "x", i.e. the logarithmic derivative
1322 "Gamma'(x)/Gamma(x)".
1323 The library syntax is gpsi"(x,prec)".
1325 sin"(x)"
1327 sine of "x".
1329 The library syntax is gsin"(x,prec)".
1331 sinh"(x)"
1333 hyperbolic sine of "x".
1335 The library syntax is gsh"(x,prec)".
1337 sqr"(x)"
1339 square of "x". This operation is not completely straightforward,
1341 i.e. identical to "x * x", since it can usually be computed more effi‐
1342 ciently (roughly one-half of the elementary multiplications can be
1343 saved). Also, squaring a 2-adic number increases its precision. For
1344 example,
1345 ? (1 + O(2^4))^2
1347 %1 = 1 + O(2^5)
1348 ? (1 + O(2^4)) * (1 + O(2^4))
1349 %2 = 1 + O(2^4)
1350 Note that this function is also called whenever one multiplies two
1352 objects which are known to be identical, e.g. they are the value of the
1353 same variable, or we are computing a power.
1354 ? x = (1 + O(2^4)); x * x
1356 %3 = 1 + O(2^5)
1357 ? (1 + O(2^4))^4
1358 %4 = 1 + O(2^6)
1359 (note the difference between %2 and %3 above).
1361 The library syntax is gsqr"(x)".
1363 sqrt"(x)"
1365 principal branch of the square root of "x", i.e. such that
1367 "Arg(sqrt(x)) belongs to ]-Pi/2, Pi/2]", or in other words such that "
1368 Re (sqrt(x)) > 0" or " Re (sqrt(x)) = 0" and " Im (sqrt(x)) >= 0". If
1369 "x belongs to R" and "x < 0", then the result is complex with positive
1370 imaginary part.
1371 Integermod a prime and "p"-adics are allowed as arguments. In that
1373 case, the square root (if it exists) which is returned is the one whose
1374 first "p"-adic digit (or its unique "p"-adic digit in the case of inte‐
1375 germods) is in the interval "[0,p/2]". When the argument is an inte‐
1376 germod a non-prime (or a non-prime-adic), the result is undefined.
1377 The library syntax is gsqrt"(x,prec)".
1379 sqrtn"(x,n,{&z})"
1381 principal branch of the "n"th root of "x", i.e. such that "Arg(sqrt(x))
1383 belongs to ]-Pi/n, Pi/n]".
1384 Integermod a prime and "p"-adics are allowed as arguments.
1386 If "z" is present, it is set to a suitable root of unity allowing to
1388 recover all the other roots. If it was not possible, z is set to zero.
1389 The following script computes all roots in all possible cases:
1391 sqrtnall(x,n)=
1393 {
1394 local(V,r,z,r2);
1395 r = sqrtn(x,n, &z);
1396 if (!z, error("Impossible case in sqrtn"));
1397 if (type(x) == "t_INTMOD" ⎪⎪ type(x)=="t_PADIC" ,
1398 r2 = r*z; n = 1;
1399 while (r2!=r, r2*=z;n++));
1400 V = vector(n); V[1] = r;
1401 for(i=2, n, V[i] = V[i-1]*z);
1402 V
1403 }
1404 addhelp(sqrtnall,"sqrtnall(x,n):compute the vector of nth-roots of x");
1405 The library syntax is gsqrtn"(x,n,&z,prec)".
1407 tan"(x)"
1409 tangent of "x".
1411 The library syntax is gtan"(x,prec)".
1413 tanh"(x)"
1415 hyperbolic tangent of "x".
1417 The library syntax is gth"(x,prec)".
1419 teichmuller"(x)"
1421 Teichmueller character of the "p"-adic number "x".
1423 The library syntax is teich"(x)".
1425 theta"(q,z)"
1427 Jacobi sine theta-function.
1429 The library syntax is theta"(q,z,prec)".
1431 thetanullk"(q,k)"
1433 "k"-th derivative at "z = 0" of "theta(q,z)".
1435 The library syntax is thetanullk"(q,k,prec)", where "k" is a "long".
1437 weber"(x,{flag = 0})"
1439 one of Weber's three "f" functions. If "flag = 0", returns
1441 "f(x) = exp (-iPi/24).eta((x+1)/2)/eta(x) such that j =
1443 (f^{24}-16)^3/f^{24},"
1444 where "j" is the elliptic "j"-invariant (see the function "ellj"). If
1446 "flag = 1", returns
1447 "f_1(x) = eta(x/2)/eta(x) such that j = (f_1^{24}+16)^3/f_1^{24}."
1449 Finally, if "flag = 2", returns
1451 "f_2(x) = sqrt {2}eta(2x)/eta(x) such that j =
1453 (f_2^{24}+16)^3/f_2^{24}."
1454 Note the identities "f^8 = f_1^8+f_2^8" and "ff_1f_2 = sqrt 2".
1456 The library syntax is weber0"(x,flag,prec)", or "wf(x,prec)",
1458 "wf1(x,prec)" or "wf2(x,prec)".
1459 zeta"(s)"
1461 Riemann's zeta function "zeta(s) = sum_{n >= 1}n^{-s}", computed using
1463 the Euler-Maclaurin summation formula, except when "s" is of type inte‐
1464 ger, in which case it is computed using Bernoulli numbers for "s <= 0"
1465 or "s > 0" and even, and using modular forms for "s > 0" and odd.
1466 The library syntax is gzeta"(s,prec)".
1468
1470 These functions are by definition functions whose natural domain of
1471 definition is either Z (or "Z_{ > 0}"), or sometimes polynomials over a
1472 base ring. Functions which concern polynomials exclusively will be
1473 explained in the next section. The way these functions are used is com‐
1474 pletely different from transcendental functions: in general only the
1475 types integer and polynomial are accepted as arguments. If a vector or
1476 matrix type is given, the function will be applied on each coefficient
1477 independently.
1478 In the present version 2.2.0, all arithmetic functions in the narrow
1480 sense of the word --- Euler's totient function, the Moebius function,
1481 the sums over divisors or powers of divisors etc.--- call, after trial
1482 division by small primes, the same versatile factoring machinery
1483 described under "factorint". It includes Shanks SQUFOF, Pollard Rho,
1484 ECM and MPQS stages, and has an early exit option for the functions
1485 moebius and (the integer function underlying) issquarefree. Note that
1486 it relies on a (fairly strong) probabilistic primality test: numbers
1487 found to be strong pseudo-primes after 10 successful trials of the
1488 Rabin-Miller test are declared primes.
1489 addprimes"({x = []})"
1491 adds the primes contained in the vector "x" (or the single integer "x")
1493 to the table computed upon GP initialization (by "pari_init" in library
1494 mode), and returns a row vector whose first entries contain all primes
1495 added by the user and whose last entries have been filled up with 1's.
1496 In total the returned row vector has 100 components. Whenever "factor"
1497 or "smallfact" is subsequently called, first the primes in the table
1498 computed by "pari_init" will be checked, and then the additional primes
1499 in this table. If "x" is empty or omitted, just returns the current
1500 list of extra primes.
1501 The entries in "x" are not checked for primality. They need only be
1503 positive integers not divisible by any of the pre-computed primes. It's
1504 in fact a nice trick to add composite numbers, which for example the
1505 function "factor(x,0)" was not able to factor. In case the message
1506 ``impossible inverse modulo "<"some integermod">"'' shows up after‐
1507 wards, you have just stumbled over a non-trivial factor. Note that the
1508 arithmetic functions in the narrow sense, like eulerphi, do not use
1509 this extra table.
1510 The present PARI version 2.2.0 allows up to 100 user-specified primes
1512 to be appended to the table. This limit may be changed by altering
1513 "NUMPRTBELT" in file "init.c". To remove primes from the list use
1514 "removeprimes".
1515 The library syntax is addprimes"(x)".
1517 bestappr"(x,k)"
1519 if "x belongs to R", finds the best rational approximation to "x" with
1521 denominator at most equal to "k" using continued fractions.
1522 The library syntax is bestappr"(x,k)".
1524 bezout"(x,y)"
1526 finds "u" and "v" minimal in a natural sense such that "x*u+y*v =
1528 gcd(x,y)". The arguments must be both integers or both polynomials, and
1529 the result is a row vector with three components "u", "v", and
1530 "gcd(x,y)".
1531 The library syntax is vecbezout"(x,y)" to get the vector, or "gbe‐
1533 zout(x,y, &u, &v)" which gives as result the address of the created
1534 gcd, and puts the addresses of the corresponding created objects into
1535 "u" and "v".
1536 bezoutres"(x,y)"
1538 as "bezout", with the resultant of "x" and "y" replacing the gcd.
1540 The library syntax is vecbezoutres"(x,y)" to get the vector, or "subre‐
1542 sext(x,y, &u, &v)" which gives as result the address of the created
1543 gcd, and puts the addresses of the corresponding created objects into
1544 "u" and "v".
1545 bigomega"(x)"
1547 number of prime divisors of "⎪x⎪" counted with multiplicity. "x" must
1549 be an integer.
1550 The library syntax is bigomega"(x)", the result is a "long".
1552 binomial"(x,y)"
1554 binomial coefficient "\binom x y". Here "y" must be an integer, but
1556 "x" can be any PARI object.
1557 The library syntax is binome"(x,y)", where "y" must be a "long".
1559 chinese"(x,y)"
1561 if "x" and "y" are both integermods or both polmods, creates (with the
1563 same type) a "z" in the same residue class as "x" and in the same
1564 residue class as "y", if it is possible.
1565 This function also allows vector and matrix arguments, in which case
1567 the operation is recursively applied to each component of the vector or
1568 matrix. For polynomial arguments, it is applied to each coefficient.
1569 Finally "chinese(x,x) = x" regardless of the type of "x"; this allows
1570 vector arguments to contain other data, so long as they are identical
1571 in both vectors.
1572 The library syntax is chinois"(x,y)".
1574 content"(x)"
1576 computes the gcd of all the coefficients of "x", when this gcd makes
1578 sense. If "x" is a scalar, this simply returns "x". If "x" is a polyno‐
1579 mial (and by extension a power series), it gives the usual content of
1580 "x". If "x" is a rational function, it gives the ratio of the contents
1581 of the numerator and the denominator. Finally, if "x" is a vector or a
1582 matrix, it gives the gcd of all the entries.
1583 The library syntax is content"(x)".
1585 contfrac"(x,{b},{lmax})"
1587 creates the row vector whose components are the partial quotients of
1589 the continued fraction expansion of "x", the number of partial quo‐
1590 tients being limited to "lmax". If "x" is a real number, the expansion
1591 stops at the last significant partial quotient if "lmax" is omitted.
1592 "x" can also be a rational function or a power series.
1593 If a vector "b" is supplied, the numerators will be equal to the coef‐
1595 ficients of "b". The length of the result is then equal to the length
1596 of "b", unless a partial remainder is encountered which is equal to
1597 zero. In which case the expansion stops. In the case of real numbers,
1598 the stopping criterion is thus different from the one mentioned above
1599 since, if "b" is too long, some partial quotients may not be signifi‐
1600 cant.
1601 If "b" is an integer, the command is understood as "contfrac(x,lmax)".
1603 The library syntax is contfrac0"(x,b,lmax)". Also available are
1605 "gboundcf(x,lmax)", "gcf(x)", or "gcf2(b,x)", where "lmax" is a C inte‐
1606 ger.
1607 contfracpnqn"(x)"
1609 when "x" is a vector or a one-row matrix, "x" is considered as the list
1611 of partial quotients "[a_0,a_1,...,a_n]" of a rational number, and the
1612 result is the 2 by 2 matrix "[p_n,p_{n-1};q_n,q_{n-1}]" in the standard
1613 notation of continued fractions, so "p_n/q_n =
1614 a_0+1/(a_1+...+1/a_n)...)". If "x" is a matrix with two rows
1615 "[b_0,b_1,...,b_n]" and "[a_0,a_1,...,a_n]", this is then considered as
1616 a generalized continued fraction and we have similarly "p_n/q_n =
1617 1/b_0(a_0+b_1/(a_1+...+b_n/a_n)...)". Note that in this case one usu‐
1618 ally has "b_0 = 1".
1619 The library syntax is pnqn"(x)".
1621 core"(n,{flag = 0})"
1623 if "n" is a non-zero integer written as "n = df^2" with "d" squarefree,
1625 returns "d". If "flag" is non-zero, returns the two-element row vector
1626 "[d,f]".
1627 The library syntax is core0"(n,flag)". Also available are "core(n)" (
1629 = core"(n,0)") and "core2(n)" ( = core"(n,1)").
1630 coredisc"(n,{flag})"
1632 if "n" is a non-zero integer written as "n = df^2" with "d" fundamental
1634 discriminant (including 1), returns "d". If "flag" is non-zero, returns
1635 the two-element row vector "[d,f]". Note that if "n" is not congruent
1636 to 0 or 1 modulo 4, "f" will be a half integer and not an integer.
1637 The library syntax is coredisc0"(n,flag)". Also available are "core‐
1639 disc(n)" ( = coredisc"(n,0)") and "coredisc2(n)" ( = coredisc"(n,1)").
1640 dirdiv"(x,y)"
1642 "x" and "y" being vectors of perhaps different lengths but with "y[1] !
1644 = 0" considered as Dirichlet series, computes the quotient of "x" by
1645 "y", again as a vector.
1646 The library syntax is dirdiv"(x,y)".
1648 direuler"(p = a,b,expr,{c})"
1650 computes the Dirichlet series to "b" terms of the Euler product of
1652 expression expr as "p" ranges through the primes from "a" to "b". expr
1653 must be a polynomial or rational function in another variable than "p"
1654 (say "X") and "expr(X)" is understood as the Dirichlet series (or more
1655 precisely the local factor) "expr(p^{-s})". If "c" is present, output
1656 only the first "c" coefficients in the series.
1657 The library syntax is direuler"(entree *ep, GEN a, GEN b, char *expr)"
1659 dirmul"(x,y)"
1661 "x" and "y" being vectors of perhaps different lengths considered as
1663 Dirichlet series, computes the product of "x" by "y", again as a vec‐
1664 tor.
1665 The library syntax is dirmul"(x,y)".
1667 divisors"(x)"
1669 creates a row vector whose components are the positive divisors of the
1671 integer "x" in increasing order. The factorization of "x" (as output by
1672 "factor") can be used instead.
1673 The library syntax is divisors"(x)".
1675 eulerphi"(x)"
1677 Euler's "phi" (totient) function of "⎪x⎪", in other words "⎪(Z/xZ)^*⎪".
1679 "x" must be of type integer.
1680 The library syntax is phi"(x)".
1682 factor"(x,{lim = -1})"
1684 general factorization function. If "x" is of type integer, rational,
1686 polynomial or rational function, the result is a two-column matrix, the
1687 first column being the irreducibles dividing "x" (prime numbers or
1688 polynomials), and the second the exponents. If "x" is a vector or a
1689 matrix, the factoring is done componentwise (hence the result is a vec‐
1690 tor or matrix of two-column matrices). By definition, 0 is factored as
1691 "0^1".
1692 If "x" is of type integer or rational, an argument lim can be added,
1694 meaning that we look only for factors up to lim, or to "primelimit",
1695 whichever is lowest (except when "lim = 0" where the effect is identi‐
1696 cal to setting "lim = primelimit"). Hence in this case, the remaining
1697 part is not necessarily prime. See factorint for more information about
1698 the algorithms used.
1699 The polynomials or rational functions to be factored must have scalar
1701 coefficients. In particular PARI does not know how to factor multivari‐
1702 ate polynomials.
1703 Note that PARI tries to guess in a sensible way over which ring you
1705 want to factor. Note also that factorization of polynomials is done up
1706 to multiplication by a constant. In particular, the factors of rational
1707 polynomials will have integer coefficients, and the content of a poly‐
1708 nomial or rational function is discarded and not included in the fac‐
1709 torization. If you need it, you can always ask for the content explic‐
1710 itly:
1711 ? factor(t^2 + 5/2*t + 1)
1713 %1 =
1714 [2*t + 1 1]
1715 [t + 2 1]
1717 ? content(t^2 + 5/2*t + 1)
1719 %2 = 1/2
1720 See also factornf.
1722 The library syntax is factor0"(x,lim)", where lim is a C integer. Also
1724 available are "factor(x)" ( = "factor0(x,-1)"), "smallfact(x)" ( =
1725 "factor0(x,0)").
1726 factorback"(f,{nf})"
1728 "f" being any factorization, gives back the factored object. If a sec‐
1730 ond argument "nf" is supplied, "f" is assumed to be a prime ideal fac‐
1731 torization in the number field "nf". The resulting ideal is given in
1732 HNF form.
1733 The library syntax is factorback"(f,nf)", where an omitted "nf" is
1735 entered as "NULL".
1736 factorcantor"(x,p)"
1738 factors the polynomial "x" modulo the prime "p", using distinct degree
1740 plus Cantor-Zassenhaus. The coefficients of "x" must be operation-com‐
1741 patible with "Z/pZ". The result is a two-column matrix, the first col‐
1742 umn being the irreducible polynomials dividing "x", and the second the
1743 exponents. If you want only the degrees of the irreducible polynomials
1744 (for example for computing an "L"-function), use "factormod(x,p,1)".
1745 Note that the "factormod" algorithm is usually faster than "factorcan‐
1746 tor".
1747 The library syntax is factcantor"(x,p)".
1749 factorff"(x,p,a)"
1751 factors the polynomial "x" in the field "F_q" defined by the irreduc‐
1753 ible polynomial "a" over "F_p". The coefficients of "x" must be opera‐
1754 tion-compatible with "Z/pZ". The result is a two-column matrix, the
1755 first column being the irreducible polynomials dividing "x", and the
1756 second the exponents. It is recommended to use for the variable of "a"
1757 (which will be used as variable of a polmod) a name distinct from the
1758 other variables used, so that a "lift()" of the result will be legible.
1759 If all the coefficients of "x" are in "F_p", a much faster algorithm is
1760 applied, using the computation of isomorphisms between finite fields.
1761 The library syntax is factmod9"(x,p,a)".
1763 factorial"(x)" or "x!"
1765 factorial of "x". The expression "x!" gives a result which is an inte‐
1767 ger, while factorial(x) gives a real number.
1768 The library syntax is mpfact"(x)" for "x!" and "mpfactr(x,prec)" for
1770 factorial(x). "x" must be a "long" integer and not a PARI integer.
1771 factorint"(n,{flag = 0})"
1773 factors the integer n using a combination of the Shanks SQUFOF and Pol‐
1775 lard Rho method (with modifications due to Brent), Lenstra's ECM (with
1776 modifications by Montgomery), and MPQS (the latter adapted from the
1777 LiDIA code with the kind permission of the LiDIA maintainers), as well
1778 as a search for pure powers with exponents" <= 10". The output is a
1779 two-column matrix as for "factor".
1780 This gives direct access to the integer factoring engine called by most
1782 arithmetical functions. flag is optional; its binary digits mean 1:
1783 avoid MPQS, 2: skip first stage ECM (we may still fall back to it
1784 later), 4: avoid Rho and SQUFOF, 8: don't run final ECM (as a result, a
1785 huge composite may be declared to be prime). Note that a (strong) prob‐
1786 abilistic primality test is used; thus composites might (very rarely)
1787 not be detected.
1788 The machinery underlying this function is still in a somewhat experi‐
1790 mental state, but should be much faster on average than pure ECM as
1791 used by all PARI versions up to 2.0.8, at the expense of heavier memory
1792 use. You are invited to play with the flag settings and watch the
1793 internals at work by using GP's "debuglevel" default parameter (level 3
1794 shows just the outline, 4 turns on time keeping, 5 and above show an
1795 increasing amount of internal details). If you see anything funny hap‐
1796 pening, please let us know.
1797 The library syntax is factorint"(n,flag)".
1799 factormod"(x,p,{flag = 0})"
1801 factors the polynomial "x" modulo the prime integer "p", using
1803 Berlekamp. The coefficients of "x" must be operation-compatible with
1804 "Z/pZ". The result is a two-column matrix, the first column being the
1805 irreducible polynomials dividing "x", and the second the exponents. If
1806 "flag" is non-zero, outputs only the degrees of the irreducible polyno‐
1807 mials (for example, for computing an "L"-function). A different algo‐
1808 rithm for computing the mod "p" factorization is "factorcantor" which
1809 is sometimes faster.
1810 The library syntax is factormod"(x,p,flag)". Also available are "fact‐
1812 mod(x,p)" (which is equivalent to "factormod(x,p,0)") and "simplefact‐
1813 mod(x,p)" ( = "factormod(x,p,1)").
1814 fibonacci"(x)"
1816 "x^{th}" Fibonacci number.
1818 The library syntax is fibo"(x)". "x" must be a "long".
1820 ffinit"(p,n,{v = x})"
1822 computes a monic polynomial of degree "n" which is irreducible over
1824 "F_p". For instance if "P = ffinit(3,2,y)", you can represent elements
1825 in "F_{3^2}" as polmods modulo "P".
1826 The library syntax is ffinit"(p,n,v)", where "v" is a variable number.
1828 gcd"(x,y,{flag = 0})"
1830 creates the greatest common divisor of "x" and "y". "x" and "y" can be
1832 of quite general types, for instance both rational numbers. Vec‐
1833 tor/matrix types are also accepted, in which case the GCD is taken
1834 recursively on each component. Note that for these types, "gcd" is not
1835 commutative.
1836 If "flag = 0", use Euclid's algorithm.
1838 If "flag = 1", use the modular gcd algorithm ("x" and "y" have to be
1840 polynomials, with integer coefficients).
1841 If "flag = 2", use the subresultant algorithm.
1843 The library syntax is gcd0"(x,y,flag)". Also available are "ggcd(x,y)",
1845 "modulargcd(x,y)", and "srgcd(x,y)" corresponding to "flag = 0", 1 and
1846 2 respectively.
1847 hilbert"(x,y,{p})"
1849 Hilbert symbol of "x" and "y" modulo "p". If "x" and "y" are of type
1851 integer or fraction, an explicit third parameter "p" must be supplied,
1852 "p = 0" meaning the place at infinity. Otherwise, "p" needs not be
1853 given, and "x" and "y" can be of compatible types integer, fraction,
1854 real, integermod a prime (result is undefined if the modulus is not
1855 prime), or "p"-adic.
1856 The library syntax is hil"(x,y,p)".
1858 isfundamental"(x)"
1860 true (1) if "x" is equal to 1 or to the discriminant of a quadratic
1862 field, false (0) otherwise.
1863 The library syntax is gisfundamental"(x)", but the simpler function
1865 "isfundamental(x)" which returns a "long" should be used if "x" is
1866 known to be of type integer.
1867 isprime"(x,{flag = 0})"
1869 if "flag = 0" (default), true (1) if "x" is a strong pseudo-prime for
1871 10 randomly chosen bases, false (0) otherwise.
1872 If "flag = 1", use Pocklington-Lehmer ``P-1'' test. true (1) if "x" is
1874 prime, false (0) otherwise.
1875 If "flag = 2", use Pocklington-Lehmer ``P-1'' test and output a primal‐
1877 ity certificate as follows: return 0 if "x" is composite, 1 if "x" is a
1878 small prime (currently strictly less than "341 550 071 728 321"), and a
1879 matrix if "x" is a large prime. The matrix has three columns. The
1880 first contains the prime factors "p", the second the corresponding ele‐
1881 ments "a_p" as in Proposition 8.3.1 in GTM 138, and the third the out‐
1882 put of isprime(p,2).
1883 In the two last cases, the algorithm fails if one of the (strong
1885 pseudo-)prime factors is not prime, but it should be exceedingly rare.
1886 The library syntax is gisprime"(x,flag)", but the simpler function
1888 "isprime(x)" which returns a "long" should be used if "x" is known to
1889 be of type integer. Also available is "plisprime(N,flag)", correspond‐
1890 ing to "gisprime(x,flag+1)" if "x" is known to be of type integer.
1891 ispseudoprime"(x)"
1893 true (1) if "x" is a strong pseudo-prime for a randomly chosen base,
1895 false (0) otherwise.
1896 The library syntax is gispsp"(x)", but the simpler function "ispsp(x)"
1898 which returns a "long" should be used if "x" is known to be of type
1899 integer.
1900 issquare"(x,{&n})"
1902 true (1) if "x" is square, false (0) if not. "x" can be of any type. If
1904 "n" is given and an exact square root had to be computed in the check‐
1905 ing process, puts that square root in "n". This is in particular the
1906 case when "x" is an integer or a polynomial. This is not the case for
1907 intmods (use quadratic reciprocity) or series (only check the leading
1908 coefficient).
1909 The library syntax is gcarrecomplet"(x,&n)". Also available is "gcar‐
1911 reparfait(x)".
1912 issquarefree"(x)"
1914 true (1) if "x" is squarefree, false (0) if not. Here "x" can be an
1916 integer or a polynomial.
1917 The library syntax is gissquarefree"(x)", but the simpler function
1919 "issquarefree(x)" which returns a "long" should be used if "x" is known
1920 to be of type integer. This issquarefree is just the square of the Moe‐
1921 bius function, and is computed as a multiplicative arithmetic function
1922 much like the latter.
1923 kronecker"(x,y)"
1925 Kronecker (i.e. generalized Legendre) symbol "((x)/(y))". "x" and "y"
1927 must be of type integer.
1928 The library syntax is kronecker"(x,y)", the result (0 or "+- 1") is a
1930 "long".
1931 lcm"(x,y)"
1933 least common multiple of "x" and "y", i.e. such that "lcm(x,y)*gcd(x,y)
1935 = abs(x*y)".
1936 The library syntax is glcm"(x,y)".
1938 moebius"(x)"
1940 Moebius "mu"-function of "⎪x⎪". "x" must be of type integer.
1942 The library syntax is mu"(x)", the result (0 or "+- 1") is a "long".
1944 nextprime"(x)"
1946 finds the smallest prime greater than or equal to "x". "x" can be of
1948 any real type. Note that if "x" is a prime, this function returns "x"
1949 and not the smallest prime strictly larger than "x".
1950 The library syntax is nextprime"(x)".
1952 numdiv"(x)"
1954 number of divisors of "⎪x⎪". "x" must be of type integer, and the
1956 result is a "long".
1957 The library syntax is numbdiv"(x)".
1959 omega"(x)"
1961 number of distinct prime divisors of "⎪x⎪". "x" must be of type inte‐
1963 ger.
1964 The library syntax is omega"(x)", the result is a "long".
1966 precprime"(x)"
1968 finds the largest prime less than or equal to "x". "x" can be of any
1970 real type. Returns 0 if "x <= 1". Note that if "x" is a prime, this
1971 function returns "x" and not the largest prime strictly smaller than
1972 "x".
1973 The library syntax is precprime"(x)".
1975 prime"(x)"
1977 the "x^{th}" prime number, which must be among the precalculated
1979 primes.
1980 The library syntax is prime"(x)". "x" must be a "long".
1982 primes"(x)"
1984 creates a row vector whose components are the first "x" prime numbers,
1986 which must be among the precalculated primes.
1987 The library syntax is primes"(x)". "x" must be a "long".
1989 qfbclassno"(x,{flag = 0})"
1991 class number of the quadratic field of discriminant "x". In the present
1993 version 2.2.0, a simple algorithm is used for "x > 0", so "x" should
1994 not be too large (say "x < 10^7") for the time to be reasonable. On the
1995 other hand, for "x < 0" one can reasonably compute classno("x") for
1996 "⎪x⎪ < 10^{25}", since the method used is Shanks' method which is in
1997 "O(⎪x⎪^{1/4})". For larger values of "⎪D⎪", see "quadclassunit".
1998 If "flag = 1", compute the class number using Euler products and the
2000 functional equation. However, it is in "O(⎪x⎪^{1/2})".
2001 Important warning. For "D < 0", this function often gives incorrect
2003 results when the class group is non-cyclic, because the authors were
2004 too lazy to implement Shanks' method completely. It is therefore
2005 strongly recommended to use either the version with "flag = 1", the
2006 function "qfbhclassno(-x)" if "x" is known to be a fundamental discrim‐
2007 inant, or the function "quadclassunit".
2008 The library syntax is qfbclassno0"(x,flag)". Also available are
2010 "classno(x)" ( = "qfbclassno(x)"), "classno2(x)" ( = "qfb‐
2011 classno(x,1)"), and finally there exists the function "hclassno(x)"
2012 which computes the class number of an imaginary quadratic field by
2013 counting reduced forms, an "O(⎪x⎪)" algorithm. See also "qfbhclassno".
2014 qfbcompraw"(x,y)"
2016 composition of the binary quadratic forms "x" and "y", without reduc‐
2018 tion of the result. This is useful e.g. to compute a generating element
2019 of an ideal.
2020 The library syntax is compraw"(x,y)".
2022 qfbhclassno"(x)"
2024 Hurwitz class number of "x", where "x" is non-negative and congruent to
2026 0 or 3 modulo 4. See also "qfbclassno".
2027 The library syntax is hclassno"(x)".
2029 qfbnucomp"(x,y,l)"
2031 composition of the primitive positive definite binary quadratic forms
2033 "x" and "y" using the NUCOMP and NUDUPL algorithms of Shanks (A la
2034 Atkin). "l" is any positive constant, but for optimal speed, one should
2035 take "l = ⎪D⎪^{1/4}", where "D" is the common discriminant of "x" and
2036 "y". When "x" and "y" do not have the same discriminant, the result is
2037 undefined.
2038 The library syntax is nucomp"(x,y,l)". The auxiliary function
2040 "nudupl(x,l)" should be used instead for speed when "x = y".
2041 qfbnupow"(x,n)"
2043 "n"-th power of the primitive positive definite binary quadratic form
2045 "x" using the NUCOMP and NUDUPL algorithms (see "qfbnucomp").
2046 The library syntax is nupow"(x,n)".
2048 qfbpowraw"(x,n)"
2050 "n"-th power of the binary quadratic form "x", computed without doing
2052 any reduction (i.e. using "qfbcompraw"). Here "n" must be non-negative
2053 and "n < 2^{31}".
2054 The library syntax is powraw"(x,n)" where "n" must be a "long" integer.
2056 qfbprimeform"(x,p)"
2058 prime binary quadratic form of discriminant "x" whose first coefficient
2060 is the prime number "p". By abuse of notation, "p = 1" is a valid spe‐
2061 cial case which returns the unit form. Returns an error if "x" is not a
2062 quadratic residue mod "p". In the case where "x > 0", the ``distance''
2063 component of the form is set equal to zero according to the current
2064 precision.
2065 The library syntax is primeform"(x,p,prec)", where the third variable
2067 "prec" is a "long", but is only taken into account when "x > 0".
2068 qfbred"(x,{flag = 0},{D},{isqrtD},{sqrtD})"
2070 reduces the binary quadratic form "x" (updating Shanks's distance func‐
2072 tion if "x" is indefinite). The binary digits of "flag" are toggles
2073 meaning
2074 1: perform a single reduction step
2076 2: don't update Shanks's distance
2078 "D", isqrtD, sqrtD, if present, supply the values of the discriminant,
2080 "\lfloor sqrt {D}\rfloor", and " sqrt {D}" respectively (no checking
2081 is done of these facts). If "D < 0" these values are useless, and all
2082 references to Shanks's distance are irrelevant.
2083 The library syntax is qfbred0"(x,flag,D,isqrtD,sqrtD)". Use "NULL" to
2085 omit any of "D", isqrtD, sqrtD.
2086 Also available are
2088 "redimag(x)" ( = "qfbred(x)" where "x" is definite),
2090 and for indefinite forms:
2092 "redreal(x)" ( = "qfbred(x)"),
2094 "rhoreal(x)" ( = "qfbred(x,1)"),
2096 "redrealnod(x,sq)" ( = "qfbred(x,2,,isqrtD)"),
2098 "rhorealnod(x,sq)" ( = "qfbred(x,3,,isqrtD)").
2100 quadclassunit"(D,{flag = 0},{tech = []})"
2102 Buchmann-McCurley's sub-exponential algorithm for computing the class
2104 group of a quadratic field of discriminant "D". If "D" is not fundamen‐
2105 tal, the function may or may not be defined, but usually is, and often
2106 gives the right answer (a warning is issued). The more general function
2107 "bnrinit" should be used to compute the class group of an order.
2108 This function should be used instead of "qfbclassno" or "quadregula"
2110 when "D < -10^{25}", "D > 10^{10}", or when the structure is wanted.
2111 If "flag" is non-zero and "D > 0", computes the narrow class group and
2113 regulator, instead of the ordinary (or wide) ones. In the current ver‐
2114 sion 2.2.0, this doesn't work at all : use the general function "bnf‐
2115 narrow".
2116 Optional parameter tech is a row vector of the form "[c_1,c_2]", where
2118 "c_1" and "c_2" are positive real numbers which control the execution
2119 time and the stack size. To get maximum speed, set "c_2 = c". To get a
2120 rigorous result (under GRH) you must take "c_2 = 6". Reasonable values
2121 for "c" are between 0.1 and 2.
2122 The result of this function is a vector "v" with 4 components if "D <
2124 0", and 5 otherwise. The correspond respectively to
2125 "*" "v[1]" : the class number
2127 "*" "v[2]" : a vector giving the structure of the class group as a
2129 product of cyclic groups;
2130 "*" "v[3]" : a vector giving generators of those cyclic groups (as
2132 binary quadratic forms).
2133 "*" "v[4]" : (omitted if "D < 0") the regulator, computed to an accu‐
2135 racy which is the maximum of an internal accuracy determined by the
2136 program and the current default (note that once the regulator is known
2137 to a small accuracy it is trivial to compute it to very high accuracy,
2138 see the tutorial).
2139 "*" "v[5]" : a measure of the correctness of the result. If it is close
2141 to 1, the result is correct (under GRH). If it is close to a larger
2142 integer, this shows that the class number is off by a factor equal to
2143 this integer, and you must start again with a larger value for "c_1" or
2144 a different random seed. In this case, a warning message is printed.
2145 The library syntax is quadclassunit0"(D,flag,tech)". Also available are
2147 "buchimag(D,c_1,c_2)" and "buchreal(D,flag,c_1,c_2)".
2148 quaddisc"(x)"
2150 discriminant of the quadratic field "Q( sqrt {x})", where "x belongs to
2152 Q".
2153 The library syntax is quaddisc"(x)".
2155 quadhilbert"(D,{flag = 0})"
2157 relative equation defining the Hilbert class field of the quadratic
2159 field of discriminant "D". If "flag" is non-zero and "D < 0", outputs
2160 "[form,root(form)]" (to be used for constructing subfields). If "flag"
2161 is non-zero and "D > 0", try hard to get the best modulus. Uses com‐
2162 plex multiplication in the imaginary case and Stark units in the real
2163 case.
2164 The library syntax is quadhilbert"(D,flag,prec)".
2166 quadgen"(x)"
2168 creates the quadratic number "omega = (a+ sqrt {x})/2" where "a = 0" if
2170 "x = 0 mod 4", "a = 1" if "x = 1 mod 4", so that "(1,omega)" is an
2171 integral basis for the quadratic order of discriminant "x". "x" must be
2172 an integer congruent to 0 or 1 modulo 4.
2173 The library syntax is quadgen"(x)".
2175 quadpoly"(D,{v = x})"
2177 creates the ``canonical'' quadratic polynomial (in the variable "v")
2179 corresponding to the discriminant "D", i.e. the minimal polynomial of
2180 quadgen(x). "D" must be an integer congruent to 0 or 1 modulo 4.
2181 The library syntax is quadpoly0"(x,v)".
2183 quadray"(D,f,{flag = 0})"
2185 relative equation for the ray class field of conductor "f" for the qua‐
2187 dratic field of discriminant "D" (which can also be a "bnf"), using
2188 analytic methods.
2189 For "D < 0", uses the "sigma" function. "flag" has the following mean‐
2191 ing: if it's an odd integer, outputs instead the vector of "[ideal,
2192 corresponding root]". It can also be a two-component vector
2193 "[lambda,flag]", where flag is as above and "lambda" is the technical
2194 element of "bnf" necessary for Schertz's method. In that case, returns
2195 0 if "lambda" is not suitable.
2196 For "D > 0", uses Stark's conjecture. If "flag" is non-zero, try hard
2198 to get the best modulus. The function may fail with the following mes‐
2199 sage
2200 "Cannot find a suitable modulus in FindModulus"
2202 See "bnrstark" for more details about the real case.
2204 The library syntax is quadray"(D,f,flag)".
2206 quadregulator"(x)"
2208 regulator of the quadratic field of positive discriminant "x". Returns
2210 an error if "x" is not a discriminant (fundamental or not) or if "x" is
2211 a square. See also "quadclassunit" if "x" is large.
2212 The library syntax is regula"(x,prec)".
2214 quadunit"(x)"
2216 fundamental unit of the real quadratic field "Q( sqrt x)" where "x"
2218 is the positive discriminant of the field. If "x" is not a fundamental
2219 discriminant, this probably gives the fundamental unit of the corre‐
2220 sponding order. "x" must be of type integer, and the result is a qua‐
2221 dratic number.
2222 The library syntax is fundunit"(x)".
2224 removeprimes"({x = []})"
2226 removes the primes listed in "x" from the prime number table. In par‐
2228 ticular "removeprimes(addprimes)" empties the extra prime table. "x"
2229 can also be a single integer. List the current extra primes if "x" is
2230 omitted.
2231 The library syntax is removeprimes"(x)".
2233 sigma"(x,{k = 1})"
2235 sum of the "k^{th}" powers of the positive divisors of "⎪x⎪". "x" must
2237 be of type integer.
2238 The library syntax is sumdiv"(x)" ( = "sigma(x)") or "gsumdivk(x,k)" (
2240 = "sigma(x,k)"), where "k" is a C long integer.
2241 sqrtint"(x)"
2243 integer square root of "x", which must be of PARI type integer. The
2245 result is non-negative and rounded towards zero. A negative "x" is
2246 allowed, and the result in that case is "I*sqrtint(-x)".
2247 The library syntax is racine"(x)".
2249 znlog"(x,g)"
2251 "g" must be a primitive root mod a prime "p", and the result is the
2253 discrete log of "x" in the multiplicative group "(Z/pZ)^*". This func‐
2254 tion using a simple-minded baby-step/giant-step approach and requires
2255 "O( sqrt {p})" storage, hence it cannot be used for "p" greater than
2256 about "10^{13}".
2257 The library syntax is znlog"(x,g)".
2259 znorder"(x)"
2261 "x" must be an integer mod "n", and the result is the order of "x" in
2263 the multiplicative group "(Z/nZ)^*". Returns an error if "x" is not
2264 invertible.
2265 The library syntax is order"(x)".
2267 znprimroot"(x)"
2269 returns a primitive root of "x", where "x" is a prime power.
2271 The library syntax is gener"(x)".
2273 znstar"(n)"
2275 gives the structure of the multiplicative group "(Z/nZ)^*" as a 3-com‐
2277 ponent row vector "v", where "v[1] = phi(n)" is the order of that
2278 group, "v[2]" is a "k"-component row-vector "d" of integers "d[i]" such
2279 that "d[i] > 1" and "d[i] ⎪ d[i-1]" for "i >= 2" and "(Z/nZ)^* ~
2280 prod_{i = 1}^k(Z/d[i]Z)", and "v[3]" is a "k"-component row vector giv‐
2281 ing generators of the image of the cyclic groups "Z/d[i]Z".
2282 The library syntax is znstar"(n)".
2284
2286 We have implemented a number of functions which are useful for number
2287 theorists working on elliptic curves. We always use Tate's notations.
2288 The functions assume that the curve is given by a general Weierstrass
2289 model
2290 " y^2+a_1xy+a_3y = x^3+a_2x^2+a_4x+a_6, "
2292 where a priori the "a_i" can be of any scalar type. This curve can be
2294 considered as a five-component vector "E = [a1,a2,a3,a4,a6]". Points on
2295 "E" are represented as two-component vectors "[x,y]", except for the
2296 point at infinity, i.e. the identity element of the group law, repre‐
2297 sented by the one-component vector "[0]".
2298 It is useful to have at one's disposal more information. This is given
2300 by the function "ellinit" (see there), which usually gives a 19 compo‐
2301 nent vector (which we will call a long vector in this section). If a
2302 specific flag is added, a vector with only 13 component will be output
2303 (which we will call a medium vector). A medium vector just gives the
2304 first 13 components of the long vector corresponding to the same curve,
2305 but is of course faster to compute. The following member functions are
2306 available to deal with the output of "ellinit":
2307 "a1"--"a6", "b2"--"b8", "c4"--"c6" : coefficients of the elliptic
2309 curve.
2310 "area" : volume of the complex lattice defining "E".
2312 "disc" : discriminant of the curve.
2314 "j" : "j"-invariant of the curve.
2316 "omega" : "[omega_1,omega_2]", periods forming a basis of the com‐
2318 plex lattice defining "E" ("omega_1" is the
2319 real period, and "omega_2/omega_1" belongs to Poin‐
2321 care's half-plane).
2322 "eta" : quasi-periods "[eta_1, eta_2]", such that
2324 "eta_1omega_2-eta_2omega_1 = iPi".
2325 "roots" : roots of the associated Weierstrass equation.
2327 "tate" : "[u^2,u,v]" in the notation of Tate.
2329 "w" : Mestre's "w" (this is technical).
2331 Their use is best described by an example: assume that "E" was output
2333 by "ellinit", then typing "E.disc" will retrieve the curve's discrimi‐
2334 nant. The member functions "area", "eta" and "omega" are only available
2335 for curves over Q. Conversely, "tate" and "w" are only available for
2336 curves defined over "Q_p".
2337 Some functions, in particular those relative to height computations
2339 (see "ellheight") require also that the curve be in minimal Weierstrass
2340 form. This is achieved by the function "ellglobalred".
2341 All functions related to elliptic curves share the prefix "ell", and
2343 the precise curve we are interested in is always the first argument, in
2344 either one of the three formats discussed above, unless otherwise spec‐
2345 ified. For instance, in functions which do not use the extra informa‐
2346 tion given by long vectors, the curve can be given either as a five-
2347 component vector, or by one of the longer vectors computed by
2348 "ellinit".
2349 elladd"(E,z1,z2)"
2351 sum of the points "z1" and "z2" on the elliptic curve corresponding to
2353 the vector "E".
2354 The library syntax is addell"(E,z1,z2)".
2356 ellak"(E,n)"
2358 computes the coefficient "a_n" of the "L"-function of the elliptic
2360 curve "E", i.e. in principle coefficients of a newform of weight 2
2361 assuming Taniyama-Weil conjecture (which is now known to hold in full
2362 generality thanks to the work of Breuil, Conrad, Diamond, Taylor and
2363 Wiles). "E" must be a medium or long vector of the type given by
2364 "ellinit". For this function to work for every "n" and not just those
2365 prime to the conductor, "E" must be a minimal Weierstrass equation. If
2366 this is not the case, use the function "ellglobalred" first before
2367 using "ellak".
2368 The library syntax is akell"(E,n)".
2370 ellan"(E,n)"
2372 computes the vector of the first "n" "a_k" corresponding to the ellip‐
2374 tic curve "E". All comments in "ellak" description remain valid.
2375 The library syntax is anell"(E,n)", where "n" is a C integer.
2377 ellap"(E,p,{flag = 0})"
2379 computes the "a_p" corresponding to the elliptic curve "E" and the
2381 prime number "p". These are defined by the equation "#E(F_p) = p+1 -
2382 a_p", where "#E(F_p)" stands for the number of points of the curve "E"
2383 over the finite field "F_p". When "flag" is 0, this uses the baby-step
2384 giant-step method and a trick due to Mestre. This runs in time
2385 "O(p^{1/4})" and requires "O(p^{1/4})" storage, hence becomes unreason‐
2386 able when "p" has about 30 digits.
2387 If "flag" is 1, computes the "a_p" as a sum of Legendre symbols. This
2389 is slower than the previous method as soon as "p" is greater than 100,
2390 say.
2391 No checking is done that "p" is indeed prime. "E" must be a medium or
2393 long vector of the type given by "ellinit", defined over Q, "F_p" or
2394 "Q_p". "E" must be given by a Weierstrass equation minimal at "p".
2395 The library syntax is ellap0"(E,p,flag)". Also available are
2397 "apell(E,p)", corresponding to "flag = 0", and "apell2(E,p)" ("flag =
2398 1").
2399 ellbil"(E,z1,z2)"
2401 if "z1" and "z2" are points on the elliptic curve "E", this function
2403 computes the value of the canonical bilinear form on "z1", "z2":
2404 " ellheight(E,z1+z2) - ellheight(E,z1) - ellheight(E,z2) "
2406 where "+" denotes of course addition on "E". In addition, "z1" or "z2"
2408 (but not both) can be vectors or matrices. Note that this is equal to
2409 twice some normalizations. "E" is assumed to be integral, given by a
2410 minimal model.
2411 The library syntax is bilhell"(E,z1,z2,prec)".
2413 ellchangecurve"(E,v)"
2415 changes the data for the elliptic curve "E" by changing the coordinates
2417 using the vector "v = [u,r,s,t]", i.e. if "x'" and "y'" are the new
2418 coordinates, then "x = u^2x'+r", "y = u^3y'+su^2x'+t". The vector "E"
2419 must be a medium or long vector of the type given by "ellinit".
2420 The library syntax is coordch"(E,v)".
2422 ellchangepoint"(x,v)"
2424 changes the coordinates of the point or vector of points "x" using the
2426 vector "v = [u,r,s,t]", i.e. if "x'" and "y'" are the new coordinates,
2427 then "x = u^2x'+r", "y = u^3y'+su^2x'+t" (see also "ellchangecurve").
2428 The library syntax is pointch"(x,v)".
2430 elleisnum"(E,k,{flag = 0})"
2432 "E" being an elliptic curve as output by "ellinit" (or, alternatively,
2434 given by a 2-component vector "[omega_1,omega_2]"), and "k" being an
2435 even positive integer, computes the numerical value of the Eisenstein
2436 series of weight "k" at "E". When flag is non-zero and "k = 4" or 6,
2437 returns "g_2" or "g_3" with the correct normalization.
2438 The library syntax is elleisnum"(E,k,flag)".
2440 elleta"(om)"
2442 returns the two-component row vector "[eta_1,eta_2]" of quasi-periods
2444 associated to "om = [omega_1, omega_2]"
2445 The library syntax is elleta"(om, prec)"
2447 ellglobalred"(E)"
2449 calculates the arithmetic conductor, the global minimal model of "E"
2451 and the global Tamagawa number "c". Here "E" is an elliptic curve given
2452 by a medium or long vector of the type given by "ellinit", and is sup‐
2453 posed to have all its coefficients "a_i" in Q. The result is a 3 compo‐
2454 nent vector "[N,v,c]". "N" is the arithmetic conductor of the curve,
2455 "v" is itself a vector "[u,r,s,t]" with rational components. It gives a
2456 coordinate change for "E" over Q such that the resulting model has
2457 integral coefficients, is everywhere minimal, "a_1" is 0 or 1, "a_2" is
2458 0, 1 or "-1" and "a_3" is 0 or 1. Such a model is unique, and the vec‐
2459 tor "v" is unique if we specify that "u" is positive. To get the new
2460 model, simply type "ellchangecurve(E,v)". Finally "c" is the product of
2461 the local Tamagawa numbers "c_p", a quantity which enters in the Birch
2462 and Swinnerton-Dyer conjecture.
2463 The library syntax is globalreduction"(E)".
2465 ellheight"(E,z,{flag = 0})"
2467 global Neron-Tate height of the point "z" on the elliptic curve "E".
2469 The vector "E" must be a long vector of the type given by "ellinit",
2470 with "flag = 1". If "flag = 0", this computation is done using sigma
2471 and theta-functions and a trick due to J. Silverman. If "flag = 1",
2472 use Tate's "4^n" algorithm, which is much slower. "E" is assumed to be
2473 integral, given by a minimal model.
2474 The library syntax is ellheight0"(E,z,flag,prec)". The Archimedean con‐
2476 tribution alone is given by the library function "hell(E,z,prec)".
2477 Also available are "ghell(E,z,prec)" ("flag = 0") and
2478 "ghell2(E,z,prec)" ("flag = 1").
2479 ellheightmatrix"(E,x)"
2481 "x" being a vector of points, this function outputs the Gram matrix of
2483 "x" with respect to the Neron-Tate height, in other words, the "(i,j)"
2484 component of the matrix is equal to "ellbil(E,x[i],x[j])". The rank of
2485 this matrix, at least in some approximate sense, gives the rank of the
2486 set of points, and if "x" is a basis of the Mordell-Weil group of "E",
2487 its determinant is equal to the regulator of "E". Note that this matrix
2488 should be divided by 2 to be in accordance with certain normalizations.
2489 "E" is assumed to be integral, given by a minimal model.
2490 The library syntax is mathell"(E,x,prec)".
2492 ellinit"(E,{flag = 0})"
2494 computes some fixed data concerning the elliptic curve given by the
2496 five-component vector "E", which will be essential for most further
2497 computations on the curve. The result is a 19-component vector E
2498 (called a long vector in this section), shortened to 13 components
2499 (medium vector) if "flag = 1". Both contain the following information
2500 in the first 13 components:
2501 " a_1,a_2,a_3,a_4,a_6,b_2,b_4,b_6,b_8,c_4,c_6,Delta,j."
2503 In particular, the discriminant is "E[12]" (or "E.disc"), and the
2505 "j"-invariant is "E[13]" (or "E.j").
2506 The other six components are only present if "flag" is 0 (or omitted!).
2508 Their content depends on whether the curve is defined over R or not:
2509 "*" When "E" is defined over R, "E[14]" ("E.roots") is a vector whose
2511 three components contain the roots of the associated Weierstrass equa‐
2512 tion. If the roots are all real, then they are ordered by decreasing
2513 value. If only one is real, it is the first component of "E[14]".
2514 "E[15]" ("E.omega[1]") is the real period of "E" (integral of
2516 "dx/(2y+a_1x+a_3)" over the connected component of the identity element
2517 of the real points of the curve), and "E[16]" ("E.omega[2]") is a com‐
2518 plex period. In other words, "omega_1 = E[15]" and "omega_2 = E[16]"
2519 form a basis of the complex lattice defining "E" ("E.omega"), with "tau
2520 = (omega_2)/(omega_1)" having positive imaginary part.
2521 "E[17]" and "E[18]" are the corresponding values "eta_1" and "eta_2"
2523 such that "eta_1omega_2-eta_2omega_1 = iPi", and both can be retrieved
2524 by typing "E.eta" (as a row vector whose components are the "eta_i").
2525 Finally, "E[19]" ("E.area") is the volume of the complex lattice defin‐
2527 ing "E".
2528 "*" When "E" is defined over "Q_p", the "p"-adic valuation of "j" must
2530 be negative. Then "E[14]" ("E.roots") is the vector with a single com‐
2531 ponent equal to the "p"-adic root of the associated Weierstrass equa‐
2532 tion corresponding to "-1" under the Tate parametrization.
2533 "E[15]" is equal to the square of the "u"-value, in the notation of
2535 Tate.
2536 "E[16]" is the "u"-value itself, if it belongs to "Q_p", otherwise
2538 zero.
2539 "E[17]" is the value of Tate's "q" for the curve "E".
2541 "E.tate" will yield the three-component vector "[u^2,u,q]".
2543 "E[18]" ("E.w") is the value of Mestre's "w" (this is technical), and
2545 "E[19]" is arbitrarily set equal to zero.
2546 For all other base fields or rings, the last six components are arbi‐
2548 trarily set equal to zero (see also the description of member functions
2549 related to elliptic curves at the beginning of this section).
2550 The library syntax is ellinit0"(E,flag,prec)". Also available are
2552 "initell(E,prec)" ("flag = 0") and "smallinitell(E,prec)" ("flag = 1").
2553 ellisoncurve"(E,z)"
2555 gives 1 (i.e. true) if the point "z" is on the elliptic curve "E", 0
2557 otherwise. If "E" or "z" have imprecise coefficients, an attempt is
2558 made to take this into account, i.e. an imprecise equality is checked,
2559 not a precise one.
2560 The library syntax is oncurve"(E,z)", and the result is a "long".
2562 ellj"(x)"
2564 elliptic "j"-invariant. "x" must be a complex number with positive
2566 imaginary part, or convertible into a power series or a "p"-adic number
2567 with positive valuation.
2568 The library syntax is jell"(x,prec)".
2570 elllocalred"(E,p)"
2572 calculates the Kodaira type of the local fiber of the elliptic curve
2574 "E" at the prime "p". "E" must be given by a medium or long vector of
2575 the type given by "ellinit", and is assumed to have all its coeffi‐
2576 cients "a_i" in Z. The result is a 4-component vector "[f,kod,v,c]".
2577 Here "f" is the exponent of "p" in the arithmetic conductor of "E", and
2578 "kod" is the Kodaira type which is coded as follows:
2579 1 means good reduction (type I"_0"), 2, 3 and 4 mean types II, III and
2581 IV respectively, "4+nu" with "nu > 0" means type I"_nu"; finally the
2582 opposite values "-1", "-2", etc. refer to the starred types I"_0^*",
2583 II"^*", etc. The third component "v" is itself a vector "[u,r,s,t]"
2584 giving the coordinate changes done during the local reduction. Nor‐
2585 mally, this has no use if "u" is 1, that is, if the given equation was
2586 already minimal. Finally, the last component "c" is the local Tamagawa
2587 number "c_p".
2588 The library syntax is localreduction"(E,p)".
2590 elllseries"(E,s,{A = 1})"
2592 "E" being a medium or long vector given by "ellinit", this computes the
2594 value of the L-series of "E" at "s". It is assumed that "E" is a mini‐
2595 mal model over Z and that the curve is a modular elliptic curve. The
2596 optional parameter "A" is a cutoff point for the integral, which must
2597 be chosen close to 1 for best speed. The result must be independent of
2598 "A", so this allows some internal checking of the function.
2599 Note that if the conductor of the curve is large, say greater than
2601 "10^{12}", this function will take an unreasonable amount of time since
2602 it uses an "O(N^{1/2})" algorithm.
2603 The library syntax is lseriesell"(E,s,A,prec)" where "prec" is a "long"
2605 and an omitted "A" is coded as "NULL".
2606 ellorder"(E,z)"
2608 gives the order of the point "z" on the elliptic curve "E" if it is a
2610 torsion point, zero otherwise. In the present version 2.2.0, this is
2611 implemented only for elliptic curves defined over Q.
2612 The library syntax is orderell"(E,z)".
2614 ellordinate"(E,x)"
2616 gives a 0, 1 or 2-component vector containing the "y"-coordinates of
2618 the points of the curve "E" having "x" as "x"-coordinate.
2619 The library syntax is ordell"(E,x)".
2621 ellpointtoz"(E,z)"
2623 if "E" is an elliptic curve with coefficients in R, this computes a
2625 complex number "t" (modulo the lattice defining "E") corresponding to
2626 the point "z", i.e. such that, in the standard Weierstrass model, " wp
2627 (t) = z[1], wp '(t) = z[2]". In other words, this is the inverse func‐
2628 tion of "ellztopoint".
2629 If "E" has coefficients in "Q_p", then either Tate's "u" is in "Q_p",
2631 in which case the output is a "p"-adic number "t" corresponding to the
2632 point "z" under the Tate parametrization, or only its square is, in
2633 which case the output is "t+1/t". "E" must be a long vector output by
2634 "ellinit".
2635 The library syntax is zell"(E,z,prec)".
2637 ellpow"(E,z,n)"
2639 computes "n" times the point "z" for the group law on the elliptic
2641 curve "E". Here, "n" can be in Z, or "n" can be a complex quadratic
2642 integer if the curve "E" has complex multiplication by "n" (if not, an
2643 error message is issued).
2644 The library syntax is powell"(E,z,n)".
2646 ellrootno"(E,{p = 1})"
2648 "E" being a medium or long vector given by "ellinit", this computes the
2650 local (if "p ! = 1") or global (if "p = 1") root number of the L-series
2651 of the elliptic curve "E". Note that the global root number is the sign
2652 of the functional equation and conjecturally is the parity of the rank
2653 of the Mordell-Weil group. The equation for "E" must have coefficients
2654 in Q but need not be minimal.
2655 The library syntax is ellrootno"(E,p)" and the result (equal to "+-1")
2657 is a "long".
2658 ellsigma"(E,z,{flag = 0})"
2660 value of the Weierstrass "sigma" function of the lattice associated to
2662 "E" as given by "ellinit" (alternatively, "E" can be given as a lattice
2663 "[omega_1,omega_2]").
2664 If "flag = 1", computes an (arbitrary) determination of " log
2666 (sigma(z))".
2667 If "flag = 2,3", same using the product expansion instead of theta
2669 series. The library syntax is ellsigma"(E,z,flag)"
2670 ellsub"(E,z1,z2)"
2672 difference of the points "z1" and "z2" on the elliptic curve corre‐
2674 sponding to the vector "E".
2675 The library syntax is subell"(E,z1,z2)".
2677 elltaniyama"(E)"
2679 computes the modular parametrization of the elliptic curve "E", where
2681 "E" is given in the (long or medium) format output by "ellinit", in the
2682 form of a two-component vector "[u,v]" of power series, given to the
2683 current default series precision. This vector is characterized by the
2684 following two properties. First the point "(x,y) = (u,v)" satisfies the
2685 equation of the elliptic curve. Second, the differential
2686 "du/(2v+a_1u+a_3)" is equal to "f(z)dz", a differential form on
2687 "H/Gamma_0(N)" where "N" is the conductor of the curve. The variable
2688 used in the power series for "u" and "v" is "x", which is implicitly
2689 understood to be equal to " exp (2iPi z)". It is assumed that the curve
2690 is a strong Weil curve, and the Manin constant is equal to 1. The equa‐
2691 tion of the curve "E" must be minimal (use "ellglobalred" to get a min‐
2692 imal equation).
2693 The library syntax is taniyama"(E)", and the precision of the result is
2695 determined by the global variable "precdl".
2696 elltors"(E,{flag = 0})"
2698 if "E" is an elliptic curve defined over Q, outputs the torsion sub‐
2700 group of "E" as a 3-component vector "[t,v1,v2]", where "t" is the
2701 order of the torsion group, "v1" gives the structure of the torsion
2702 group as a product of cyclic groups (sorted by decreasing order), and
2703 "v2" gives generators for these cyclic groups. "E" must be a long vec‐
2704 tor as output by "ellinit".
2705 ? E = ellinit([0,0,0,-1,0]);
2707 ? elltors(E)
2708 %1 = [4, [2, 2], [[0, 0], [1, 0]]]
2709 Here, the torsion subgroup is isomorphic to "Z/2Z x Z/2Z", with gener‐
2711 ators "[0,0]" and "[1,0]".
2712 If "flag = 0", use Doud's algorithm : bound torsion by computing
2714 "#E(F_p)" for small primes of good reduction, then look for torsion
2715 points using Weierstrass parametrization (and Mazur's classification).
2716 If "flag = 1", use Lutz--Nagell (much slower), "E" is allowed to be a
2718 medium vector.
2719 The library syntax is elltors0"(E,flag)".
2721 ellwp"(E,{z = x},{flag = 0})"
2723 Computes the value at "z" of the Weierstrass " wp " function attached
2725 to the elliptic curve "E" as given by "ellinit" (alternatively, "E" can
2726 be given as a lattice "[omega_1,omega_2]").
2727 If "z" is omitted or is a simple variable, computes the power series
2729 expansion in "z" (starting "z^{-2}+O(z^2)"). The number of terms to an
2730 even power in the expansion is the default serieslength in GP, and the
2731 second argument (C long integer) in library mode.
2732 Optional flag is (for now) only taken into account when "z" is numeric,
2734 and means 0: compute only " wp (z)", 1: compute "[ wp (z), wp '(z)]".
2735 The library syntax is ellwp0"(E,z,flag,prec,precdl)". Also available is
2737 weipell"(E,precdl)" for the power series (in "x = polx[0]").
2738 ellzeta"(E,z)"
2740 value of the Weierstrass "zeta" function of the lattice associated to
2742 "E" as given by "ellinit" (alternatively, "E" can be given as a lattice
2743 "[omega_1,omega_2]").
2744 The library syntax is ellzeta"(E,z)".
2746 ellztopoint"(E,z)"
2748 "E" being a long vector, computes the coordinates "[x,y]" on the curve
2750 "E" corresponding to the complex number "z". Hence this is the inverse
2751 function of "ellpointtoz". In other words, if the curve is put in
2752 Weierstrass form, "[x,y]" represents the Weierstrass " wp "-function
2753 and its derivative. If "z" is in the lattice defining "E" over C, the
2754 result is the point at infinity "[0]".
2755 The library syntax is pointell"(E,z,prec)".
2757
2759 In this section can be found functions which are used almost exclu‐
2760 sively for working in general number fields. Other less specific func‐
2761 tions can be found in the next section on polynomials. Functions
2762 related to quadratic number fields can be found in the section "Label
2763 se:arithmetic" (Arithmetic functions).
2764 We shall use the following conventions:
2766 "*" "nf" denotes a number field, i.e. a 9-component vector in the for‐
2768 mat output by "nfinit". This contains the basic arithmetic data associ‐
2769 ated to the number field: signature, maximal order, discriminant, etc.
2770 "*" "bnf" denotes a big number field, i.e. a 10-component vector in the
2772 format output by "bnfinit". This contains "nf" and the deeper invari‐
2773 ants of the field: units, class groups, as well as a lot of technical
2774 data necessary for some complex fonctions like "bnfisprincipal".
2775 "*" "bnr" denotes a big ``ray number field'', i.e. some data structure
2777 output by "bnrinit", even more complicated than "bnf", corresponding to
2778 the ray class group structure of the field, for some modulus.
2779 "*" "rnf" denotes a relative number field (see below).
2781 "*" "ideal" can mean any of the following:
2783 -- a Z-basis, in Hermite normal form (HNF) or not. In this case "x"
2785 is a square matrix.
2786 -- an idele, i.e. a 2-component vector, the first being an ideal
2788 given as a Z--basis, the second being a "r_1+r_2"-component row vector
2789 giving the complex logarithmic Archimedean information.
2790 -- a "Z_K"-generating system for an ideal.
2792 -- a column vector "x" expressing an element of the number field on
2794 the integral basis, in which case the ideal is treated as being the
2795 principal idele (or ideal) generated by "x".
2796 -- a prime ideal, i.e. a 5-component vector in the format output by
2798 "idealprimedec".
2799 -- a polmod "x", i.e. an algebraic integer, in which case the ideal
2801 is treated as being the principal idele generated by "x".
2802 -- an integer or a rational number, also treated as a principal
2804 idele.
2805 "*" a {character} on the Abelian group "\bigoplus (Z/N_iZ) g_i" is
2807 given by a row vector "chi = [a_1,...,a_n]" such that "chi(prod
2808 g_i^{n_i}) = exp(2iPisum a_i n_i / N_i)".
2809 Warnings:
2811 1) An element in "nf" can be expressed either as a polmod or as a vec‐
2813 tor of components on the integral basis "nf.zk". It is absolutely
2814 essential that all such vectors be column vectors.
2815 2) When giving an ideal by a "Z_K" generating system to a function
2817 expecting an ideal, it must be ensured that the function understands
2818 that it is a "Z_K"-generating system and not a Z-generating system.
2819 When the number of generators is strictly less than the degree of the
2820 field, there is no ambiguity and the program assumes that one is giving
2821 a "Z_K"-generating set. When the number of generators is greater than
2822 or equal to the degree of the field, however, the program assumes on
2823 the contrary that you are giving a Z-generating set. If this is not the
2824 case, you must absolutely change it into a Z-generating set, the sim‐
2825 plest manner being to use "idealhnf(nf,x)".
2826 Concerning relative extensions, some additional definitions are neces‐
2828 sary.
2829 "*" A {relative matrix} will be a matrix whose entries are elements of
2831 a (given) number field "nf", always expressed as column vectors on the
2832 integral basis "nf.zk". Hence it is a matrix of vectors.
2833 "*" An ideal list will be a row vector of (fractional) ideals of the
2835 number field "nf".
2836 "*" A pseudo-matrix will be a pair "(A,I)" where "A" is a relative
2838 matrix and "I" an ideal list whose length is the same as the number of
2839 columns of "A". This pair will be represented by a 2-component row vec‐
2840 tor.
2841 "*" The module generated by a pseudo-matrix "(A,I)" is the sum
2843 "sum_i{a}_jA_j" where the "{a}_j" are the ideals of "I" and "A_j" is
2844 the "j"-th column of "A".
2845 "*" A pseudo-matrix "(A,I)" is a pseudo-basis of the module it gener‐
2847 ates if "A" is a square matrix with non-zero determinant and all the
2848 ideals of "I" are non-zero. We say that it is in Hermite Normal Form
2849 (HNF) if it is upper triangular and all the elements of the diagonal
2850 are equal to 1.
2851 "*" The determinant of a pseudo-basis "(A,I)" is the ideal equal to the
2853 product of the determinant of "A" by all the ideals of "I". The deter‐
2854 minant of a pseudo-matrix is the determinant of any pseudo-basis of the
2855 module it generates.
2856 Finally, when defining a relative extension, the base field should be
2858 defined by a variable having a lower priority (i.e. a higher number)
2859 than the variable defining the extension. For example, under GP you can
2860 use the variable name "y" (or "t") to define the base field, and the
2861 variable name "x" to define the relative extension.
2862 Now a last set of definitions concerning the way big ray number fields
2864 (or bnr) are input, using class field theory. These are defined by a
2865 triple "a1", "a2", "a3", where the defining set "[a1,a2,a3]" can have
2866 any of the following forms: "[bnr]", "[bnr,subgroup]", "[bnf,module]",
2867 "[bnf,module,subgroup]", where:
2868 "*" "bnf" is as output by "bnfclassunit" or "bnfinit", where units are
2870 mandatory unless the ideal is trivial; bnr by "bnrclass" (with "flag >
2871 0") or "bnrinit". This is the ground field.
2872 "*" module is either an ideal in any form (see above) or a two-compo‐
2874 nent row vector containing an ideal and an "r_1"-component row vector
2875 of flags indicating which real Archimedean embeddings to take in the
2876 module.
2877 "*" subgroup is the HNF matrix of a subgroup of the ray class group of
2879 the ground field for the modulus module. This is input as a square
2880 matrix expressing generators of a subgroup of the ray class group
2881 "bnr.clgp" on the given generators.
2882 The corresponding bnr is then the subfield of the ray class field of
2884 the ground field for the given modulus, associated to the given sub‐
2885 group.
2886 All the functions which are specific to relative extensions, number
2888 fields, big number fields, big number rays, share the prefix "rnf",
2889 "nf", "bnf", "bnr" respectively. They are meant to take as first argu‐
2890 ment a number field of that precise type, respectively output by
2891 "rnfinit", "nfinit", "bnfinit", and "bnrinit".
2892 However, and even though it may not be specified in the descriptions of
2894 the functions below, it is permissible, if the function expects a "nf",
2895 to use a "bnf" instead (which contains much more information). The pro‐
2896 gram will make the effort of converting to what it needs. On the other
2897 hand, if the program requires a big number field, the program will not
2898 launch "bnfinit" for you, which can be a costly operation. Instead, it
2899 will give you a specific error message.
2900 The data types corresponding to the structures described above are
2902 rather complicated. Thus, as we already have seen it with elliptic
2903 curves, GP provides you with some ``member functions'' to retrieve the
2904 data you need from these structures (once they have been initialized of
2905 course). The relevant types of number fields are indicated between
2906 parentheses:
2907 "bnf" (bnr, bnf ) : big number field.
2909 "clgp" (bnr, bnf ) : classgroup. This one admits the following
2911 three subclasses:
2912 "cyc" : cyclic decomposition (SNF).
2914 "gen" : generators.
2916 "no" : number of elements.
2918 "diff" (bnr, bnf, nf ) : the different ideal.
2920 "codiff" (bnr, bnf, nf ) : the codifferent (inverse of the differ‐
2922 ent in the ideal group).
2923 "disc" (bnr, bnf, nf ) : discriminant.
2925 "fu" (bnr, bnf, nf ) : fundamental units.
2927 "futu" (bnr, bnf ) : "[u,w]", "u" is a vector of fundamental
2929 units, "w" generates the torsion.
2930 "nf" (bnr, bnf, nf ) : number field.
2932 "reg" (bnr, bnf, ) : regulator.
2934 "roots" (bnr, bnf, nf ) : roots of the polnomial generating the
2936 field.
2937 "sign" (bnr, bnf, nf ) : "[r_1,r_2]" the signature of the field.
2939 This means that the field has "r_1" real embeddings, "2r_2" com‐
2940 plex ones.
2941 "t2" (bnr, bnf, nf ) : the T2 matrix (see "nfinit").
2943 "tu" (bnr, bnf, ) : a generator for the torsion units.
2945 "tufu" (bnr, bnf, ) : as "futu", but outputs "[w,u]".
2947 "zk" (bnr, bnf, nf ) : integral basis, i.e. a Z-basis of the
2949 maximal order.
2950 "zkst" (bnr ) : structure of "(Z_K/m)^*" (can be
2952 extracted also from an idealstar).
2953 For instance, assume that "bnf = bnfinit(pol)", for some polynomial.
2955 Then "bnf.clgp" retrieves the class group, and "bnf.clgp.no" the class
2956 number. If we had set "bnf = nfinit(pol)", both would have output an
2957 error message. All these functions are completely recursive, thus for
2958 instance "bnr.bnf.nf.zk" will yield the maximal order of bnr (which you
2959 could get directly with a simple "bnr.zk" of course).
2960 The following functions, starting with "buch" in library mode, and with
2962 "bnf" under GP, are implementations of the sub-exponential algorithms
2963 for finding class and unit groups under GRH, due to Hafner-McCurley,
2964 Buchmann and Cohen-Diaz-Olivier.
2965 The general call to the functions concerning class groups of general
2967 number fields (i.e. excluding "quadclassunit") involves a polynomial
2968 "P" and a technical vector
2969 "tech = [c,c2,nrel,borne,nrpid,minsfb],"
2971 where the parameters are to be understood as follows:
2973 "P" is the defining polynomial for the number field, which must be in
2975 "Z[X]", irreducible and, preferably, monic. In fact, if you supply a
2976 non-monic polynomial at this point, GP will issue a warning, then
2977 transform your polynomial so that it becomes monic. Instead of the nor‐
2978 mal result, say "res", you then get a vector "[res,Mod(a,Q)]", where
2979 "Mod(a,Q) = Mod(X,P)" gives the change of variables.
2980 The numbers "c" and "c2" are positive real numbers which control the
2982 execution time and the stack size. To get maximum speed, set "c2 = c".
2983 To get a rigorous result (under GRH) you must take "c2 = 12" (or "c2 =
2984 6" in the quadratic case, but then you should use the much faster func‐
2985 tion "quadclassunit"). Reasonable values for "c" are between 0.1 and 2.
2986 (The defaults are "c = c2 = 0.3").
2987 "nrel" is the number of initial extra relations requested in computing
2989 the relation matrix. Reasonable values are between 5 and 20. (The
2990 default is 5).
2991 "borne" is a multiplicative coefficient of the Minkowski bound which
2993 controls the search for small norm relations. If this parameter is set
2994 equal to 0, the program does not search for small norm relations. Oth‐
2995 erwise reasonable values are between 0.5 and 2.0. (The default is 1.0).
2996 "nrpid" is the maximal number of small norm relations associated to
2998 each ideal in the factor base. Irrelevant when "borne = 0". Otherwise,
2999 reasonable values are between 4 and 20. (The default is 4).
3000 "minsfb" is the minimal number of elements in the ``sub-factorbase''.
3002 If the program does not seem to succeed in finding a full rank matrix
3003 (which you can see in GP by typing "\g 2"), increase this number. Rea‐
3004 sonable values are between 2 and 5. (The default is 3).
3005 Remarks.
3007 Apart from the polynomial "P", you don't need to supply any of the
3009 technical parameters (under the library you still need to send at least
3010 an empty vector, "cgetg(1,t_VEC)"). However, should you choose to set
3011 some of them, they must be given in the requested order. For example,
3012 if you want to specify a given value of "nrel", you must give some val‐
3013 ues as well for "c" and "c2", and provide a vector "[c,c2,nrel]".
3014 Note also that you can use an "nf" instead of "P", which avoids recom‐
3016 puting the integral basis and analogous quantities.
3017 bnfcertify"(bnf)"
3019 "bnf" being a big number field as output by "bnfinit" or "bnfclas‐
3021 sunit", checks whether the result is correct, i.e. whether it is possi‐
3022 ble to remove the assumption of the Generalized Riemann Hypothesis. If
3023 it is correct, the answer is 1. If not, the program may output some
3024 error message, but more probably will loop indefinitely. In no occasion
3025 can the program give a wrong answer (barring bugs of course): if the
3026 program answers 1, the answer is certified.
3027 The library syntax is certifybuchall"(bnf)", and the result is a C
3029 long.
3030 bnfclassunit"(P,{flag = 0},{tech = []})"
3032 Buchmann's sub-exponential algorithm for computing the class group, the
3034 regulator and a system of fundamental units of the general algebraic
3035 number field "K" defined by the irreducible polynomial "P" with integer
3036 coefficients.
3037 The result of this function is a vector "v" with 10 components (it is
3039 not a "bnf", you need "bnfinit" for that), which for ease of presenta‐
3040 tion is in fact output as a one column matrix. First we describe the
3041 default behaviour ("flag = 0"):
3042 "v[1]" is equal to the polynomial "P". Note that for optimum perfor‐
3044 mance, "P" should have gone through "polred" or "nfinit(x,2)".
3045 "v[2]" is the 2-component vector "[r1,r2]", where "r1" and "r2" are as
3047 usual the number of real and half the number of complex embeddings of
3048 the number field "K".
3049 "v[3]" is the 2-component vector containing the field discriminant and
3051 the index.
3052 "v[4]" is an integral basis in Hermite normal form.
3054 "v[5]" ("v.clgp") is a 3-component vector containing the class number
3056 ("v.clgp.no"), the structure of the class group as a product of cyclic
3057 groups of order "n_i" ("v.clgp.cyc"), and the corresponding generators
3058 of the class group of respective orders "n_i" ("v.clgp.gen").
3059 "v[6]" ("v.reg") is the regulator computed to an accuracy which is the
3061 maximum of an internally determined accuracy and of the default.
3062 "v[7]" is a measure of the correctness of the result. If it is close to
3064 1, the results are correct (under GRH). If it is close to a larger
3065 integer, this shows that the product of the class number by the regula‐
3066 tor is off by a factor equal to this integer, and you must start again
3067 with a larger value for "c" or a different random seed, i.e. use the
3068 function "setrand". (Since the computation involves a random process,
3069 starting again with exactly the same parameters may give the correct
3070 result.) In this case a warning message is printed.
3071 "v[8]" ("v.tu") a vector with 2 components, the first being the number
3073 "w" of roots of unity in "K" and the second a primitive "w"-th root of
3074 unity expressed as a polynomial.
3075 "v[9]" ("v.fu") is a system of fundamental units also expressed as
3077 polynomials.
3078 "v[10]" gives a measure of the correctness of the computations of the
3080 fundamental units (not of the regulator), expressed as a number of
3081 bits. If this number is greater than 20, say, everything is OK. If
3082 "v[10] <= 0", then we have lost all accuracy in computing the units
3083 (usually an error message will be printed and the units not given). In
3084 the intermediate cases, one must proceed with caution (for example by
3085 increasing the current precision).
3086 If "flag = 1", and the precision happens to be insufficient for obtain‐
3088 ing the fundamental units exactly, the internal precision is doubled
3089 and the computation redone, until the exact results are obtained. The
3090 user should be warned that this can take a very long time when the
3091 coefficients of the fundamental units on the integral basis are very
3092 large, for example in the case of large real quadratic fields. In that
3093 case, there are alternate methods for representing algebraic numbers
3094 which are not implemented in PARI.
3095 If "flag = 2", the fundamental units and roots of unity are not com‐
3097 puted. Hence the result has only 7 components, the first seven ones.
3098 "tech" is a technical vector (empty by default) containing "c", "c2",
3100 nrel, borne, nbpid, minsfb, in this order (see the beginning of the
3101 section or the keyword "bnf"). You can supply any number of these pro‐
3102 vided you give an actual value to each of them (the ``empty arg'' trick
3103 won't work here). Careful use of these parameters may speed up your
3104 computations considerably.
3105 The library syntax is bnfclassunit0"(P,flag,tech,prec)".
3107 bnfclgp"(P,{tech = []})"
3109 as "bnfclassunit", but only outputs "v[5]", i.e. the class group.
3111 The library syntax is bnfclassgrouponly"(P,tech,prec)", where tech is
3113 as described under "bnfclassunit".
3114 bnfdecodemodule"(nf,m)"
3116 if "m" is a module as output in the first component of an extension
3118 given by "bnrdisclist", outputs the true module.
3119 The library syntax is decodemodule"(nf,m)".
3121 bnfinit"(P,{flag = 0},{tech = []})"
3123 essentially identical to "bnfclassunit" except that the output contains
3125 a lot of technical data, and should not be printed out explicitly in
3126 general. The result of "bnfinit" is used in programs such as "bnfis‐
3127 principal", "bnfisunit" or "bnfnarrow". The result is a 10-component
3128 vector "bnf".
3129 "*" The first 6 and last 2 components are technical and in principle
3131 are not used by the casual user. However, for the sake of completeness,
3132 their description is as follows. We use the notations explained in the
3133 book by H. Cohen, A Course in Computational Algebraic Number Theory,
3134 Graduate Texts in Maths 138, Springer-Verlag, 1993, Section 6.5, and
3135 subsection 6.5.5 in particular.
3136 "bnf[1]" contains the matrix "W", i.e. the matrix in Hermite normal
3138 form giving relations for the class group on prime ideal generators
3139 "(p_i)_{1 <= i <= r}".
3140 "bnf[2]" contains the matrix "B", i.e. the matrix containing the
3142 expressions of the prime ideal factorbase in terms of the "p_i". It is
3143 an "r x c" matrix.
3144 "bnf[3]" contains the complex logarithmic embeddings of the system of
3146 fundamental units which has been found. It is an "(r_1+r_2) x
3147 (r_1+r_2-1)" matrix.
3148 "bnf[4]" contains the matrix "M''_C" of Archimedean components of the
3150 relations of the matrix "(W⎪B)".
3151 "bnf[5]" contains the prime factor base, i.e. the list of prime ideals
3153 used in finding the relations.
3154 "bnf[6]" contains the permutation of the prime factor base which was
3156 necessary to reduce the relation matrix to the form explained in sub‐
3157 section 6.5.5 of GTM 138 (i.e. with a big "c x c" identity matrix on
3158 the lower right). Note that in the above mentioned book, the need to
3159 permute the rows of the relation matrices which occur was not empha‐
3160 sized.
3161 "bnf[9]" is a 3-element row vector used in "bnfisprincipal" only and
3163 obtained as follows. Let "D = U W V" obtained by applying the Smith
3164 normal form algorithm to the matrix "W" ( = "bnf[1]") and let "U_r" be
3165 the reduction of "U" modulo "D". The first elements of the factorbase
3166 are given (in terms of "bnf.gen") by the columns of "U_r", with archi‐
3167 median component "g_a"; let also "GD_a" be the archimedian components
3168 of the generators of the (principal) ideals defined by the
3169 "bnf.gen[i]^bnf.cyc[i]". Then "bnf[9] = [U_r, g_a, GD_a]".
3170 Finally, "bnf[10]" is by default unused and set equal to 0. This field
3172 is used to store further information about the field as it becomes
3173 available (which is rarely needed, hence would be too expensive to com‐
3174 pute during the initial "bnfinit" call). For instance, the generators
3175 of the principal ideals "bnf.gen[i]^bnf.cyc[i]" (during a call to
3176 "bnrisprincipal"), or those corresponding to the relations in "W" and
3177 "B" (when the "bnf" internal precision needs to be increased).
3178 "*" The less technical components are as follows:
3180 "bnf[7]" or "bnf.nf" is equal to the number field data "nf" as would be
3182 given by "nfinit".
3183 "bnf[8]" is a vector containing the last 6 components of "bnfclas‐
3185 sunit[,1]", i.e. the classgroup "bnf.clgp", the regulator "bnf.reg",
3186 the general ``check'' number which should be close to 1, the number of
3187 roots of unity and a generator "bnf.tu", the fundamental units
3188 "bnf.fu", and finally the check on their computation. If the precision
3189 becomes insufficient, GP outputs a warning ("fundamental units too
3190 large, not given") and does not strive to compute the units by default
3191 ("flag = 0").
3192 When "flag = 1", GP insists on finding the fundamental units exactly,
3194 the internal precision being doubled and the computation redone, until
3195 the exact results are obtained. The user should be warned that this can
3196 take a very long time when the coefficients of the fundamental units on
3197 the integral basis are very large.
3198 When "flag = 2", on the contrary, it is initially agreed that GP will
3200 not compute units.
3201 When "flag = 3", computes a very small version of "bnfinit", a ``small
3203 big number field'' (or sbnf for short) which contains enough informa‐
3204 tion to recover the full "bnf" vector very rapidly, but which is much
3205 smaller and hence easy to store and print. It is supposed to be used in
3206 conjunction with "bnfmake". The output is a 12 component vector "v", as
3207 follows. Let "bnf" be the result of a full "bnfinit", complete with
3208 units. Then "v[1]" is the polynomial "P", "v[2]" is the number of real
3209 embeddings "r_1", "v[3]" is the field discriminant, "v[4]" is the inte‐
3210 gral basis, "v[5]" is the list of roots as in the sixth component of
3211 "nfinit", "v[6]" is the matrix "MD" of "nfinit" giving a Z-basis of the
3212 different, "v[7]" is the matrix "W = bnf[1]", "v[8]" is the matrix
3213 "matalpha = bnf[2]", "v[9]" is the prime ideal factor base "bnf[5]"
3214 coded in a compact way, and ordered according to the permutation
3215 "bnf[6]", "v[10]" is the 2-component vector giving the number of roots
3216 of unity and a generator, expressed on the integral basis, "v[11]" is
3217 the list of fundamental units, expressed on the integral basis, "v[12]"
3218 is a vector containing the algebraic numbers alpha corresponding to the
3219 columns of the matrix "matalpha", expressed on the integral basis.
3220 Note that all the components are exact (integral or rational), except
3222 for the roots in "v[5]". In practice, this is the only component which
3223 a user is allowed to modify, by recomputing the roots to a higher accu‐
3224 racy if desired. Note also that the member functions will not work on
3225 sbnf, you have to use "bnfmake" explicitly first.
3226 The library syntax is bnfinit0"(P,flag,tech,prec)".
3228 bnfisintnorm"(bnf,x)"
3230 computes a complete system of solutions (modulo units of positive norm)
3232 of the absolute norm equation "Norm(a) = x", where "a" is an integer in
3233 "bnf". If "bnf" has not been certified, the correctness of the result
3234 depends on the validity of GRH.
3235 The library syntax is bnfisintnorm"(bnf,x)".
3237 bnfisnorm"(bnf,x,{flag = 1})"
3239 tries to tell whether the rational number "x" is the norm of some ele‐
3241 ment y in "bnf". Returns a vector "[a,b]" where "x = Norm(a)*b". Looks
3242 for a solution which is an "S"-unit, with "S" a certain set of prime
3243 ideals containing (among others) all primes dividing "x". If "bnf" is
3244 known to be Galois, set "flag = 0" (in this case, "x" is a norm iff "b
3245 = 1"). If "flag" is non zero the program adds to "S" the following
3246 prime ideals, depending on the sign of "flag". If "flag > 0", the
3247 ideals of norm less than "flag". And if "flag < 0" the ideals dividing
3248 "flag".
3249 If you are willing to assume GRH, the answer is guaranteed (i.e. "x" is
3251 a norm iff "b = 1"), if "S" contains all primes less than "12 log
3252 (disc(Bnf))^2", where "Bnf" is the Galois closure of "bnf".
3253 The library syntax is bnfisnorm"(bnf,x,flag,prec)", where "flag" and
3255 "prec" are "long"s.
3256 bnfissunit"(bnf,sfu,x)"
3258 "bnf" being output by "bnfinit", sfu by "bnfsunit", gives the column
3260 vector of exponents of "x" on the fundamental "S"-units and the roots
3261 of unity. If "x" is not a unit, outputs an empty vector.
3262 The library syntax is bnfissunit"(bnf,sfu,x)".
3264 bnfisprincipal"(bnf,x,{flag = 1})"
3266 "bnf" being the number field data output by "bnfinit", and "x" being
3268 either a Z-basis of an ideal in the number field (not necessarily in
3269 HNF) or a prime ideal in the format output by the function "ideal‐
3270 primedec", this function tests whether the ideal is principal or not.
3271 The result is more complete than a simple true/false answer: it gives a
3272 row vector "[v_1,v_2,check]", where
3273 "v_1" is the vector of components "c_i" of the class of the ideal "x"
3275 in the class group, expressed on the generators "g_i" given by
3276 "bnfinit" (specifically "bnf.clgp.gen" which is the same as
3277 "bnf[8][1][3]"). The "c_i" are chosen so that "0 <= c_i < n_i" where
3278 "n_i" is the order of "g_i" (the vector of "n_i" being "bnf.clgp.cyc",
3279 that is "bnf[8][1][2]").
3280 "v_2" gives on the integral basis the components of "alpha" such that
3282 "x = alphaprod_ig_i^{c_i}". In particular, "x" is principal if and only
3283 if "v_1" is equal to the zero vector, and if this the case "x = alp‐
3284 haZ_K" where "alpha" is given by "v_2". Note that if "alpha" is too
3285 large to be given, a warning message will be printed and "v_2" will be
3286 set equal to the empty vector.
3287 Finally the third component check is analogous to the last component of
3289 "bnfclassunit": it gives a check on the accuracy of the result, in
3290 bits. check should be at least 10, and preferably much more. In any
3291 case, the result is checked for correctness.
3292 If "flag = 0", outputs only "v_1", which is much easier to compute.
3294 If "flag = 2", does as if "flag" were 0, but doubles the precision
3296 until a result is obtained.
3297 If "flag = 3", as in the default behaviour ("flag = 1"), but doubles
3299 the precision until a result is obtained.
3300 The user is warned that these two last setting may induce very lengthy
3302 computations.
3303 The library syntax is isprincipalall"(bnf,x,flag)".
3305 bnfisunit"(bnf,x)"
3307 "bnf" being the number field data output by "bnfinit" and "x" being an
3309 algebraic number (type integer, rational or polmod), this outputs the
3310 decomposition of "x" on the fundamental units and the roots of unity if
3311 "x" is a unit, the empty vector otherwise. More precisely, if
3312 "u_1",...,"u_r" are the fundamental units, and "zeta" is the generator
3313 of the group of roots of unity (found by "bnfclassunit" or "bnfinit"),
3314 the output is a vector "[x_1,...,x_r,x_{r+1}]" such that "x =
3315 u_1^{x_1}...u_r^{x_r}.zeta^{x_{r+1}}". The "x_i" are integers for "i <=
3316 r" and is an integer modulo the order of "zeta" for "i = r+1".
3317 The library syntax is isunit"(bnf,x)".
3319 bnfmake"(sbnf)"
3321 sbnf being a ``small "bnf"'' as output by "bnfinit""(x,3)", computes
3323 the complete "bnfinit" information. The result is not identical to what
3324 "bnfinit" would yield, but is functionally identical. The execution
3325 time is very small compared to a complete "bnfinit". Note that if the
3326 default precision in GP (or "prec" in library mode) is greater than the
3327 precision of the roots "sbnf[5]", these are recomputed so as to get a
3328 result with greater accuracy.
3329 Note that the member functions are not available for sbnf, you have to
3331 use "bnfmake" explicitly first.
3332 The library syntax is makebigbnf"(sbnf,prec)", where "prec" is a C long
3334 integer.
3335 bnfnarrow"(bnf)"
3337 "bnf" being a big number field as output by "bnfinit", computes the
3339 narrow class group of "bnf". The output is a 3-component row vector "v"
3340 analogous to the corresponding class group component "bnf.clgp"
3341 ("bnf[8][1]"): the first component is the narrow class number "v.no",
3342 the second component is a vector containing the SNF cyclic components
3343 "v.cyc" of the narrow class group, and the third is a vector giving the
3344 generators of the corresponding "v.gen" cyclic groups. Note that this
3345 function is a special case of "bnrclass".
3346 The library syntax is buchnarrow"(bnf)".
3348 bnfsignunit"(bnf)"
3350 "bnf" being a big number field output by "bnfinit", this computes an
3352 "r_1 x (r_1+r_2-1)" matrix having "+-1" components, giving the signs of
3353 the real embeddings of the fundamental units.
3354 The library syntax is signunits"(bnf)".
3356 bnfreg"(bnf)"
3358 "bnf" being a big number field output by "bnfinit", computes its regu‐
3360 lator.
3361 The library syntax is regulator"(bnf,tech,prec)", where tech is as in
3363 "bnfclassunit".
3364 bnfsunit"(bnf,S)"
3366 computes the fundamental "S"-units of the number field "bnf" (output by
3368 "bnfinit"), where "S" is a list of prime ideals (output by "ideal‐
3369 primedec"). The output is a vector "v" with 6 components.
3370 "v[1]" gives a minimal system of (integral) generators of the "S"-unit
3372 group modulo the unit group.
3373 "v[2]" contains technical data needed by "bnfissunit".
3375 "v[3]" is an empty vector (used to give the logarithmic embeddings of
3377 the generators in "v[1]" in version 2.0.16).
3378 "v[4]" is the "S"-regulator (this is the product of the regulator, the
3380 determinant of "v[2]" and the natural logarithms of the norms of the
3381 ideals in "S").
3382 "v[5]" gives the "S"-class group structure, in the usual format (a row
3384 vector whose three components give in order the "S"-class number, the
3385 cyclic components and the generators).
3386 "v[6]" is a copy of "S".
3388 The library syntax is bnfsunit"(bnf,S,prec)".
3390 bnfunit"(bnf)"
3392 "bnf" being a big number field as output by "bnfinit", outputs a two-
3394 component row vector giving in the first component the vector of funda‐
3395 mental units of the number field, and in the second component the num‐
3396 ber of bit of accuracy which remained in the computation (which is
3397 always correct, otherwise an error message is printed). This function
3398 is mainly for people who used the wrong flag in "bnfinit" and would
3399 like to skip part of a lengthy "bnfinit" computation.
3400 The library syntax is buchfu"(bnf)".
3402 bnrL1"(bnr,subgroup,{flag = 0})"
3404 bnr being the number field data which is output by "bnrinit(,,1)" and
3406 subgroup being a square matrix defining a congruence subgroup of the
3407 ray class group corresponding to bnr (or 0 for the trivial congruence
3408 subgroup), returns for each character "chi" of the ray class group
3409 which is trivial on this subgroup, the value at "s = 1" (or "s = 0") of
3410 the abelian "L"-function associated to "chi". For the value at "s = 0",
3411 the function returns in fact for each character "chi" a vector "[r_chi
3412 , c_chi]" where "r_chi" is the order of "L(s, chi)" at "s = 0" and
3413 "c_chi" the first non-zero term in the expansion of "L(s, chi)" at "s =
3414 0"; in other words
3415 "L(s, chi) = c_chi.s^{r_chi} + O(s^{r_chi + 1})"
3417 near 0. flag is optional, default value is 0; its binary digits mean 1:
3419 compute at "s = 1" if set to 1 or "s = 0" if set to 0, 2: compute the
3420 primitive "L"-functions associated to "chi" if set to 0 or the
3421 "L"-function with Euler factors at prime ideals dividing the modulus of
3422 bnr removed if set to 1 (this is the so-called "L_S(s, chi)" function
3423 where "S" is the set of infinite places of the number field together
3424 with the finite prime ideals dividing the modulus of bnr, see the exam‐
3425 ple below), 3: returns also the character.
3426 Example:
3428 bnf = bnfinit(x^2 - 229);
3430 bnr = bnrinit(bnf,1,1);
3431 bnrL1(bnr, 0)
3432 returns the order and the first non-zero term of the abelian "L"-func‐
3434 tions "L(s, chi)" at "s = 0" where "chi" runs through the characters of
3435 the class group of "Q( sqrt {229})". Then
3436 bnr2 = bnrinit(bnf,2,1);
3438 bnrL1(bnr2,0,2)
3439 returns the order and the first non-zero terms of the abelian "L"-func‐
3441 tions "L_S(s, chi)" at "s = 0" where "chi" runs through the characters
3442 of the class group of "Q( sqrt {229})" and "S" is the set of infinite
3443 places of "Q( sqrt {229})" together with the finite prime 2 (note that
3444 the ray class group modulo 2 is in fact the class group, so
3445 "bnrL1(bnr2,0)" returns exactly the same answer as "bnrL1(bnr,0)"!).
3446 The library syntax is bnrL1"(bnr,subgroup,flag,prec)"
3448 bnrclass"(bnf,ideal,{flag = 0})"
3450 "bnf" being a big number field as output by "bnfinit" (the units are
3452 mandatory unless the ideal is trivial), and ideal being either an ideal
3453 in any form or a two-component row vector containing an ideal and an
3454 "r_1"-component row vector of flags indicating which real Archimedean
3455 embeddings to take in the module, computes the ray class group of the
3456 number field for the module ideal, as a 3-component vector as all other
3457 finite Abelian groups (cardinality, vector of cyclic components, corre‐
3458 sponding generators).
3459 If "flag = 2", the output is different. It is a 6-component vector "w".
3461 "w[1]" is "bnf". "w[2]" is the result of applying "idealstar(bnf,I,2)".
3462 "w[3]", "w[4]" and "w[6]" are technical components used only by the
3463 function "bnrisprincipal". "w[5]" is the structure of the ray class
3464 group as would have been output with "flag = 0".
3465 If "flag = 1", as above, except that the generators of the ray class
3467 group are not computed, which saves time.
3468 The library syntax is bnrclass0"(bnf,ideal,flag,prec)".
3470 bnrclassno"(bnf,I)"
3472 "bnf" being a big number field as output by "bnfinit" (units are manda‐
3474 tory unless the ideal is trivial), and "I" being either an ideal in any
3475 form or a two-component row vector containing an ideal and an
3476 "r_1"-component row vector of flags indicating which real Archimedean
3477 embeddings to take in the modulus, computes the ray class number of the
3478 number field for the modulus "I". This is faster than "bnrclass" and
3479 should be used if only the ray class number is desired.
3480 The library syntax is rayclassno"(bnf,I)".
3482 bnrclassnolist"(bnf,list)"
3484 "bnf" being a big number field as output by "bnfinit" (units are manda‐
3486 tory unless the ideal is trivial), and list being a list of modules as
3487 output by "ideallist" of "ideallistarch", outputs the list of the class
3488 numbers of the corresponding ray class groups.
3489 The library syntax is rayclassnolist"(bnf,list)".
3491 bnrconductor"(a_1,{a_2},{a_3}, {flag = 0})"
3493 conductor of the subfield of a ray class field as defined by
3495 "[a_1,a_2,a_3]" (see "bnr" at the beginning of this section).
3496 The library syntax is bnrconductor"(a_1,a_2,a_3,flag,prec)", where an
3498 omitted argument among the "a_i" is input as "gzero", and "flag" is a C
3499 long.
3500 bnrconductorofchar"(bnr,chi)"
3502 bnr being a big ray number field as output by "bnrclass", and chi being
3504 a row vector representing a character as expressed on the generators of
3505 the ray class group, gives the conductor of this character as a modu‐
3506 lus.
3507 The library syntax is bnrconductorofchar"(bnr,chi,prec)" where "prec"
3509 is a "long".
3510 bnrdisc"(a1,{a2},{a3},{flag = 0})"
3512 "a1", "a2", "a3" defining a big ray number field "L" over a groud field
3514 "K" (see "bnr" at the beginning of this section for the meaning of
3515 "a1", "a2", "a3"), outputs a 3-component row vector "[N,R_1,D]", where
3516 "N" is the (absolute) degree of "L", "R_1" the number of real places of
3517 "L", and "D" the discriminant of "L/Q", including sign (if "flag = 0").
3518 If "flag = 1", as above but outputs relative data. "N" is now the
3520 degree of "L/K", "R_1" is the number of real places of "K" unramified
3521 in "L" (so that the number of real places of "L" is equal to "R_1"
3522 times the relative degree "N"), and "D" is the relative discriminant
3523 ideal of "L/K".
3524 If "flag = 2", does as in case 0, except that if the modulus is not the
3526 exact conductor corresponding to the "L", no data is computed and the
3527 result is 0 ("gzero").
3528 If "flag = 3", as case 2, outputting relative data.
3530 The library syntax is bnrdisc0"(a1,a2,a3,flag,prec)".
3532 bnrdisclist"(bnf,bound,{arch},{flag = 0})"
3534 "bnf" being a big number field as output by "bnfinit" (the units are
3536 mandatory), computes a list of discriminants of Abelian extensions of
3537 the number field by increasing modulus norm up to bound bound, where
3538 the ramified Archimedean places are given by arch (unramified at infin‐
3539 ity if arch is void or omitted). If flag is non-zero, give arch all the
3540 possible values. (See "bnr" at the beginning of this section for the
3541 meaning of "a1", "a2", "a3".)
3542 The alternative syntax "bnrdisclist(bnf,list)" is supported, where list
3544 is as output by "ideallist" or "ideallistarch" (with units).
3545 The output format is as follows. The output "v" is a row vector of row
3547 vectors, allowing the bound to be greater than "2^{16}" for 32-bit
3548 machines, and "v[i][j]" is understood to be in fact "V[2^{15}(i-1)+j]"
3549 of a unique big vector "V" (note that "2^{15}" is hardwired and can be
3550 increased in the source code only on 64-bit machines and higher).
3551 Such a component "V[k]" is itself a vector "W" (maybe of length 0)
3553 whose components correspond to each possible ideal of norm "k". Each
3554 component "W[i]" corresponds to an Abelian extension "L" of "bnf" whose
3555 modulus is an ideal of norm "k" and no Archimedean components (hence
3556 the extension is unramified at infinity). The extension "W[i]" is rep‐
3557 resented by a 4-component row vector "[m,d,r,D]" with the following
3558 meaning. "m" is the prime ideal factorization of the modulus, "d =
3559 [L:Q]" is the absolute degree of "L", "r" is the number of real places
3560 of "L", and "D" is the factorization of the absolute discriminant. Each
3561 prime ideal "pr = [p,alpha,e,f,beta]" in the prime factorization "m" is
3562 coded as "p.n^2+(f-1).n+(j-1)", where "n" is the degree of the base
3563 field and "j" is such that
3564 "pr = idealprimedec(nf,p)[j]".
3566 "m" can be decoded using "bnfdecodemodule".
3568 The library syntax is bnrdisclist0"(a1,a2,a3,bound,arch,flag)".
3570 bnrinit"(bnf,ideal,{flag = 0})"
3572 "bnf" is as output by "bnfinit", ideal is a valid ideal (or a module),
3574 initializes data linked to the ray class group structure corresponding
3575 to this module. This is the same as "bnrclass(bnf,ideal,flag+1)".
3576 The library syntax is bnrinit0"(bnf,ideal,flag,prec)".
3578 bnrisconductor"(a1,{a2},{a3})"
3580 "a1", "a2", "a3" represent an extension of the base field, given by
3582 class field theory for some modulus encoded in the parameters. Outputs
3583 1 if this modulus is the conductor, and 0 otherwise. This is slightly
3584 faster than "bnrconductor".
3585 The library syntax is bnrisconductor"(a1,a2,a3)" and the result is a
3587 "long".
3588 bnrisprincipal"(bnr,x,{flag = 1})"
3590 bnr being the number field data which is output by "bnrinit""(,,1)" and
3592 "x" being an ideal in any form, outputs the components of "x" on the
3593 ray class group generators in a way similar to "bnfisprincipal". That
3594 is a 3-component vector "v" where "v[1]" is the vector of components of
3595 "x" on the ray class group generators, "v[2]" gives on the integral
3596 basis an element "alpha" such that "x = alphaprod_ig_i^{x_i}". Finally
3597 "v[3]" indicates the number of bits of accuracy left in the result. In
3598 any case the result is checked for correctness, but "v[3]" is included
3599 to see if it is necessary to increase the accuracy in other computa‐
3600 tions.
3601 If "flag = 0", outputs only "v_1". In that case, bnr need not contain
3603 the ray class group generators, i.e. it may be created with
3604 "bnrinit""(,,0)"
3605 The library syntax is isprincipalrayall"(bnr,x,flag)".
3607 bnrrootnumber"(bnr,chi,{flag = 0})"
3609 if "chi = chi" is a (not necessarily primitive) character over bnr, let
3611 "L(s,chi) = sum_{id} chi(id) N(id)^{-s}" be the associated Artin
3612 L-function. Returns the so-called Artin root number, i.e. the complex
3613 number "W(chi)" of modulus 1 such that
3614 "Lambda(1-s,chi) = W(chi) Lambda(s,\overline{chi})"
3616 where "Lambda(s,chi) = A(chi)^{s/2}gamma_chi(s) L(s,chi)" is the
3618 enlarged L-function associated to "L".
3619 The generators of the ray class group are needed, and you can set "flag
3621 = 1" if the character is known to be primitive. Example:
3622 bnf = bnfinit(x^2 - 145);
3624 bnr = bnrinit(bnf,7,1);
3625 bnrrootnumber(bnr, [5])
3626 returns the root number of the character "chi" of "Cl_7(Q( sqrt
3628 {145}))" such that "chi(g) = zeta^5", where "g" is the generator of the
3629 ray-class field and "zeta = e^{2iPi/N}" where "N" is the order of "g"
3630 ("N = 12" as "bnr.cyc" readily tells us).
3631 The library syntax is bnrrootnumber"(bnf,chi,flag)"
3633 bnrstark"{(bnr,subgroup,{flag = 0})}"
3635 bnr being as output by "bnrinit(,,1)", finds a relative equation for
3637 the class field corresponding to the modulus in bnr and the given con‐
3638 gruence subgroup using Stark units (set "subgroup = 0" if you want the
3639 whole ray class group). The main variable of bnr must not be "x", and
3640 the ground field and the class field must be totally real and not iso‐
3641 morphic to Q (over the rationnals, use "polsubcyclo" or "galoissubcy‐
3642 clo"). flag is optional and may be set to 0 to obtain a reduced rela‐
3643 tive polynomial, 1 to be satisfied with any relative polynomial, 2 to
3644 obtain an absolute polynomial and 3 to obtain the irreducible relative
3645 polynomial of the Stark unit, 0 being default. Example:
3646 bnf = bnfinit(y^2 - 3);
3648 bnr = bnrinit(bnf, 5, 1);
3649 bnrstark(bnr, 0)
3650 returns the ray class field of "Q( sqrt {3})" modulo 5.
3652 Remark. The result of the computation depends on the choice of a modu‐
3654 lus verifying special conditions. By default the function will try few
3655 moduli, choosing the one giving the smallest result. In some cases
3656 where the result is however very large, you can tell the function to
3657 try more moduli by adding 4 to the value of flag. Whether this flag is
3658 set or not, the function may fail in some extreme cases, returning the
3659 error message
3660 "Cannot find a suitable modulus in FindModule".
3662 In this case, the corresponding congruence group is a product of cyclic
3664 groups and, for the time being, the class field has to be obtained by
3665 splitting this group into its cyclic components.
3666 The library syntax is bnrstark"(bnr,subgroup,flag)".
3668 dirzetak"(nf,b)"
3670 gives as a vector the first "b" coefficients of the Dedekind zeta func‐
3672 tion of the number field "nf" considered as a Dirichlet series.
3673 The library syntax is dirzetak"(nf,b)".
3675 factornf"(x,t)"
3677 factorization of the univariate polynomial "x" over the number field
3679 defined by the (univariate) polynomial "t". "x" may have coefficients
3680 in Q or in the number field. The main variable of "t" must be of lower
3681 priority than that of "x" (in other words the variable number of "t"
3682 must be greater than that of "x"). However if the coefficients of the
3683 number field occur explicitly (as polmods) as coefficients of "x", the
3684 variable of these polmods must be the same as the main variable of "t".
3685 For example
3686 ? factornf(x^2 + Mod(y, y^2+1), y^2+1);
3688 ? factornf(x^2 + 1, y^2+1); \\ these two are OK
3689 ? factornf(x^2 + Mod(z,z^2+1), y^2+1)
3690 *** incorrect type in gmulsg
3691 The library syntax is polfnf"(x,t)".
3693 galoisfixedfield"(gal,perm,{fl = 0},{v = y}))"
3695 gal being be a Galois field as output by "galoisinit" and perm an ele‐
3697 ment of "gal.group" or a vector of such elements, computes the fixed
3698 field of gal by the automorphism defined by the permutations perm of
3699 the roots "gal.roots". "P" is guaranteed to be squarefree modulo
3700 "gal.p".
3701 If no flags or "flag = 0", output format is the same as for "nfsub‐
3703 field", returning "[P,x]" such that "P" is a polynomial defining the
3704 fixed field, and "x" is a root of "P" expressed as a polmod in
3705 "gal.pol".
3706 If "flag = 1" return only the polynomial "P".
3708 If "flag = 2" return "[P,x,F]" where "P" and "x" are as above and "F"
3710 is the factorization of "gal.pol" over the field defined by "P", where
3711 variable "v" ("y" by default) stands for a root of "P". The priority of
3712 "v" must be less than the priority of the variable of "gal.pol".
3713 Example:
3715 G = galoisinit(x^4+1);
3717 galoisfixedfield(G,G.group[2],2)
3718 [x^2 + 2, Mod(x^3 + x, x^4 + 1), [x^2 - y*x - 1, x^2 + y*x - 1]]
3719 computes the factorization "x^4+1 = (x^2- sqrt {-2}x-1)(x^2+ sqrt
3721 {-2}x-1)"
3722 The library syntax is galoisfixedfield"(gal,perm,p)".
3724 galoisinit"(pol,{den})"
3726 computes the Galois group and all neccessary information for computing
3728 the fixed fields of the Galois extension "K/Q" where "K" is the number
3729 field defined by "pol" (monic irreducible polynomial in "Z[X]" or a
3730 number field as output by "nfinit"). The extension "K/Q" must be Galois
3731 with Galois group ``weakly'' super-solvable (see "nfgaloisconj")
3732 Warning: The interface of this function is experimental, so the
3734 described output can be subject to important changes in the near
3735 future. However the function itself should work as described. For any
3736 remarks about this interface, please mail "allomber@math.u-bor‐
3737 deaux.fr".
3738 The output is an 8-component vector gal.
3740 "gal[1]" contains the polynomial pol ("gal.pol").
3742 "gal[2]" is a three--components vector "[p,e,q]" where "p" is a prime
3744 number ("gal.p") such that pol totally split modulo "p" , "e" is an
3745 integer and "q = p^e" ("gal.mod") is the modulus of the roots in
3746 "gal.roots".
3747 "gal[3]" is a vector "L" containing the "p"-adic roots of pol as inte‐
3749 gers implicitly modulo "gal.mod". ("gal.roots").
3750 "gal[4]" is the inverse of the Van der Monde matrix of the "p"-adic
3752 roots of pol, multiplied by "gal[5]".
3753 "gal[5]" is a multiple of the least common denominator of the automor‐
3755 phisms expressed as polynomial in a root of pol.
3756 "gal[6]" is the Galois group "G" expressed as a vector of permutations
3758 of "L" ("gal.group").
3759 "gal[7]" is a generating subset "S = [s_1,...,s_g]" of "G" expressed as
3761 a vector of permutations of "L" ("gal.gen").
3762 "gal[8]" contains the relative orders "[o_1,...,o_g]" of the generators
3764 of "S" ("gal.orders").
3765 Let "H" be the maximal normal supersolvable subgroup of "G", we have
3767 the following properties:
3768 "*" if "G/H ~ A_4" then "[o_1,...,o_g]" ends by "[2,2,3]".
3770 "*" if "G/H ~ S_4" then "[o_1,...,o_g]" ends by "[2,2,3,2]".
3772 "*" else "G" is super-solvable.
3774 "*" for "1 <= i <= g" the subgroup of "G" generated by
3776 "[s_1,...,s_g]" is normal, with the exception of "i = g-2" in the sec‐
3777 ond case and of "i = g-3" in the third.
3778 "*" the relative order "o_i" of "s_i" is its order in the quotient
3780 group "G/<s_1,...,s_{i-1}>", with the same exceptions.
3781 "*" for any "x belongs to G" there exists a unique family
3783 "[e_1,...,e_g]" such that (no exceptions):
3784 -- for "1 <= i <= g" we have "0 <= e_i < o_i"
3786 -- "x = g_1^{e_1}g_2^{e_2}...g_n^{e_n}"
3788 If present "den" must be a suitable value for "gal[5]".
3790 The library syntax is galoisinit"(gal,den)".
3792 galoispermtopol"(gal,perm)"
3794 gal being a galois field as output by "galoisinit" and perm a element
3796 of "gal.group", return the polynomial defining the Galois automorphism,
3797 as output by "nfgaloisconj", associated with the permutation perm of
3798 the roots "gal.roots". perm can also be a vector or matrix, in this
3799 case, "galoispermtopol" is applied to all components recursively.
3800 Note that
3802 G = galoisinit(pol);
3804 galoispermtopol(G, G[6])~
3805 is equivalent to "nfgaloisconj(pol)", if degree of pol is greater or
3807 equal to 2.
3808 The library syntax is galoispermtopol"(gal,perm)".
3810 galoissubcyclo"(n,H,{Z},{v})"
3812 compute a polynomial defining the subfield of "Q(zeta_n)" fixed by the
3814 subgroup H of "Z/nZ". The subgroup H can be given by a generator, a set
3815 of generators given by a vector or a HNF matrix. If present "Z" must be
3816 znstar(n), and is currently only used when H is a HNF matrix. If v is
3817 given, the polynomial is given in the variable v.
3818 The following function can be used to compute all subfields of
3820 "Q(zeta_n)" (of order less than "d", if "d" is set):
3821 subcyclo(n, d = -1)=
3823 {
3824 local(Z,G,S);
3825 if (d < 0, d = n);
3826 Z = znstar(n);
3827 G = matdiagonal(Z[2]);
3828 S = [];
3829 forsubgroup(H = G, d,
3830 S = concat(S, galoissubcyclo(n, mathnf(concat(G,H)),Z));
3831 );
3832 S
3833 }
3834 The library syntax is galoissubcyclo"(n,H,Z,v)" where n is a C long
3836 integer.
3837 idealadd"(nf,x,y)"
3839 sum of the two ideals "x" and "y" in the number field "nf". When "x"
3841 and "y" are given by Z-bases, this does not depend on "nf" and can be
3842 used to compute the sum of any two Z-modules. The result is given in
3843 HNF.
3844 The library syntax is idealadd"(nf,x,y)".
3846 idealaddtoone"(nf,x,{y})"
3848 "x" and "y" being two co-prime integral ideals (given in any form),
3850 this gives a two-component row vector "[a,b]" such that "a belongs to
3851 x", "b belongs to y" and "a+b = 1".
3852 The alternative syntax "idealaddtoone(nf,v)", is supported, where "v"
3854 is a "k"-component vector of ideals (given in any form) which sum to
3855 "Z_K". This outputs a "k"-component vector "e" such that "e[i] belongs
3856 to x[i]" for "1 <= i <= k" and "sum_{1 <= i <= k}e[i] = 1".
3857 The library syntax is idealaddtoone0"(nf,x,y)", where an omitted "y" is
3859 coded as "NULL".
3860 idealappr"(nf,x,{flag = 0})"
3862 if "x" is a fractional ideal (given in any form), gives an element
3864 "alpha" in "nf" such that for all prime ideals "p" such that the valua‐
3865 tion of "x" at "p" is non-zero, we have "v_{p}(alpha) = v_{p}(x)", and.
3866 "v_{p}(alpha) >= 0" for all other "{p}".
3867 If "flag" is non-zero, "x" must be given as a prime ideal factoriza‐
3869 tion, as output by "idealfactor", but possibly with zero or negative
3870 exponents. This yields an element "alpha" such that for all prime
3871 ideals "p" occurring in "x", "v_{p}(alpha)" is equal to the exponent of
3872 "p" in "x", and for all other prime ideals, "v_{p}(alpha) >= 0". This
3873 generalizes "idealappr(nf,x,0)" since zero exponents are allowed. Note
3874 that the algorithm used is slightly different, so that "ide‐
3875 alapp(nf,idealfactor(nf,x))" may not be the same as "ide‐
3876 alappr(nf,x,1)".
3877 The library syntax is idealappr0"(nf,x,flag)".
3879 idealchinese"(nf,x,y)"
3881 "x" being a prime ideal factorization (i.e. a 2 by 2 matrix whose first
3883 column contain prime ideals, and the second column integral exponents),
3884 "y" a vector of elements in "nf" indexed by the ideals in "x", computes
3885 an element "b" such that
3886 "v_p(b - y_p) >= v_p(x)" for all prime ideals in "x" and "v_p(b) >= 0"
3888 for all other "p".
3889 The library syntax is idealchinese"(nf,x,y)".
3891 idealcoprime"(nf,x,y)"
3893 given two integral ideals "x" and "y" in the number field "nf", finds a
3895 "beta" in the field, expressed on the integral basis "nf[7]", such that
3896 "beta.y" is an integral ideal coprime to "x".
3897 The library syntax is idealcoprime"(nf,x)".
3899 idealdiv"(nf,x,y,{flag = 0})"
3901 quotient "x.y^{-1}" of the two ideals "x" and "y" in the number field
3903 "nf". The result is given in HNF.
3904 If "flag" is non-zero, the quotient "x.y^{-1}" is assumed to be an
3906 integral ideal. This can be much faster when the norm of the quotient
3907 is small even though the norms of "x" and "y" are large.
3908 The library syntax is idealdiv0"(nf,x,y,flag)". Also available are
3910 "idealdiv(nf,x,y)" ("flag = 0") and "idealdivexact(nf,x,y)" ("flag =
3911 1").
3912 idealfactor"(nf,x)"
3914 factors into prime ideal powers the ideal "x" in the number field "nf".
3916 The output format is similar to the "factor" function, and the prime
3917 ideals are represented in the form output by the "idealprimedec" func‐
3918 tion, i.e. as 5-element vectors.
3919 The library syntax is idealfactor"(nf,x)".
3921 idealhnf"(nf,a,{b})"
3923 gives the Hermite normal form matrix of the ideal "a". The ideal can be
3925 given in any form whatsoever (typically by an algebraic number if it is
3926 principal, by a "Z_K"-system of generators, as a prime ideal as given
3927 by "idealprimedec", or by a Z-basis).
3928 If "b" is not omitted, assume the ideal given was "aZ_K+bZ_K", where
3930 "a" and "b" are elements of "K" given either as vectors on the integral
3931 basis "nf[7]" or as algebraic numbers.
3932 The library syntax is idealhnf0"(nf,a,b)" where an omitted "b" is coded
3934 as "NULL". Also available is "idealhermite(nf,a)" ("b" omitted).
3935 idealintersect"(nf,x,y)"
3937 intersection of the two ideals "x" and "y" in the number field "nf".
3939 When "x" and "y" are given by Z-bases, this does not depend on "nf" and
3940 can be used to compute the intersection of any two Z-modules. The
3941 result is given in HNF.
3942 The library syntax is idealintersect"(nf,x,y)".
3944 idealinv"(nf,x)"
3946 inverse of the ideal "x" in the number field "nf". The result is the
3948 Hermite normal form of the inverse of the ideal, together with the
3949 opposite of the Archimedean information if it is given.
3950 The library syntax is idealinv"(nf,x)".
3952 ideallist"(nf,bound,{flag = 4})"
3954 computes the list of all ideals of norm less or equal to bound in the
3956 number field nf. The result is a row vector with exactly bound compo‐
3957 nents. Each component is itself a row vector containing the informa‐
3958 tion about ideals of a given norm, in no specific order. This informa‐
3959 tion can be either the HNF of the ideal or the "idealstar" with possi‐
3960 bly some additional information.
3961 If "flag" is present, its binary digits are toggles meaning
3963 1: give also the generators in the "idealstar".
3965 2: output "[L,U]", where "L" is as before and "U" is a vector of
3967 "zinternallog"s of the units.
3968 4: give only the ideals and not the "idealstar" or the "ideallog" of
3970 the units.
3971 The library syntax is ideallist0"(nf,bound,flag)", where bound must be
3973 a C long integer. Also available is "ideallist(nf,bound)", correspond‐
3974 ing to the case "flag = 0".
3975 ideallistarch"(nf,list,{arch = []},{flag = 0})"
3977 vector of vectors of all "idealstarinit" (see "idealstar") of all mod‐
3979 ules in list, with Archimedean part arch added (void if omitted). list
3980 is a vector of big ideals, as output by "ideallist""(..., flag)" for
3981 instance. "flag" is optional; its binary digits are toggles meaning: 1:
3982 give generators as well, 2: list format is "[L,U]" (see "ideallist").
3983 The library syntax is ideallistarch0"(nf,list,arch,flag)", where an
3985 omitted arch is coded as "NULL".
3986 ideallog"(nf,x,bid)"
3988 "nf" being a number field, bid being a ``big ideal'' as output by "ide‐
3990 alstar" and "x" being a non-necessarily integral element of nf which
3991 must have valuation equal to 0 at all prime ideals dividing "I =
3992 bid[1]", computes the ``discrete logarithm'' of "x" on the generators
3993 given in "bid[2]". In other words, if "g_i" are these generators, of
3994 orders "d_i" respectively, the result is a column vector of integers
3995 "(x_i)" such that "0 <= x_i < d_i" and
3996 "x = prod_ig_i^{x_i} (mod ^*I) ."
3998 Note that when "I" is a module, this implies also sign conditions on
4000 the embeddings.
4001 The library syntax is zideallog"(nf,x,bid)".
4003 idealmin"(nf,x,{vdir})"
4005 computes a minimum of the ideal "x" in the direction vdir in the number
4007 field nf.
4008 The library syntax is minideal"(nf,x,vdir,prec)", where an omitted vdir
4010 is coded as "NULL".
4011 idealmul"(nf,x,y,{flag = 0})"
4013 ideal multiplication of the ideals "x" and "y" in the number field nf.
4015 The result is a generating set for the ideal product with at most "n"
4016 elements, and is in Hermite normal form if either "x" or "y" is in HNF
4017 or is a prime ideal as output by "idealprimedec", and this is given
4018 together with the sum of the Archimedean information in "x" and "y" if
4019 both are given.
4020 If "flag" is non-zero, reduce the result using "idealred".
4022 The library syntax is idealmul"(nf,x,y)" ("flag = 0") or "ideal‐
4024 mulred(nf,x,y,prec)" ("flag ! = 0"), where as usual, "prec" is a C long
4025 integer representing the precision.
4026 idealnorm"(nf,x)"
4028 computes the norm of the ideal "x" in the number field "nf".
4030 The library syntax is idealnorm"(nf, x)".
4032 idealpow"(nf,x,k,{flag = 0})"
4034 computes the "k"-th power of the ideal "x" in the number field "nf".
4036 "k" can be positive, negative or zero. The result is NOT reduced, it is
4037 really the "k"-th ideal power, and is given in HNF.
4038 If "flag" is non-zero, reduce the result using "idealred". Note however
4040 that this is NOT the same as as "idealpow(nf,x,k)" followed by reduc‐
4041 tion, since the reduction is performed throughout the powering process.
4042 The library syntax corresponding to "flag = 0" is "idealpow(nf,x,k)".
4044 If "k" is a "long", you can use "idealpows(nf,x,k)". Corresponding to
4045 "flag = 1" is "idealpowred(nf,vp,k,prec)", where "prec" is a "long".
4046 idealprimedec"(nf,p)"
4048 computes the prime ideal decomposition of the prime number "p" in the
4050 number field "nf". "p" must be a (positive) prime number. Note that the
4051 fact that "p" is prime is not checked, so if a non-prime number "p" is
4052 given it may lead to unpredictable results.
4053 The result is a vector of 5-component vectors, each representing one of
4055 the prime ideals above "p" in the number field "nf". The representation
4056 "vp = [p,a,e,f,b]" of a prime ideal means the following. The prime
4057 ideal is equal to "pZ_K+alphaZ_K" where "Z_K" is the ring of integers
4058 of the field and "alpha = sum_i a_iomega_i" where the "omega_i" form
4059 the integral basis "nf.zk", "e" is the ramification index, "f" is the
4060 residual index, and "b" is an "n"-component column vector representing
4061 a "beta belongs to Z_K" such that "vp^{-1} = Z_K+beta/pZ_K" which will
4062 be useful for computing valuations, but which the user can ignore. The
4063 number "alpha" is guaranteed to have a valuation equal to 1 at the
4064 prime ideal (this is automatic if "e > 1").
4065 The library syntax is idealprimedec"(nf,p)".
4067 idealprincipal"(nf,x)"
4069 creates the principal ideal generated by the algebraic number "x"
4071 (which must be of type integer, rational or polmod) in the number field
4072 "nf". The result is a one-column matrix.
4073 The library syntax is principalideal"(nf,x)".
4075 idealred"(nf,I,{vdir = 0})"
4077 LLL reduction of the ideal "I" in the number field nf, along the direc‐
4079 tion vdir. If vdir is present, it must be an "r1+r2"-component vector
4080 ("r1" and "r2" number of real and complex places of nf as usual).
4081 This function finds a ``small'' "a" in "I" (it is an LLL pseudo-minimum
4083 along direction vdir). The result is the Hermite normal form of the
4084 LLL-reduced ideal "r I/a", where "r" is a rational number such that the
4085 resulting ideal is integral and primitive. This is often, but not
4086 always, a reduced ideal in the sense of Buchmann. If "I" is an idele,
4087 the logarithmic embeddings of "a" are subtracted to the Archimedean
4088 part.
4089 More often than not, a principal ideal will yield the identity matrix.
4091 This is a quick and dirty way to check if ideals are principal without
4092 computing a full "bnf" structure, but it's not a necessary condition;
4093 hence, a non-trivial result doesn't prove the ideal is non-trivial in
4094 the class group.
4095 Note that this is not the same as the LLL reduction of the lattice "I"
4097 since ideal operations are involved.
4098 The library syntax is ideallllred"(nf,x,vdir,prec)", where an omitted
4100 vdir is coded as "NULL".
4101 idealstar"(nf,I,{flag = 1})"
4103 nf being a number field, and "I" either and ideal in any form, or a row
4105 vector whose first component is an ideal and whose second component is
4106 a row vector of "r_1" 0 or 1, outputs necessary data for computing in
4107 the group "(Z_K/I)^*".
4108 If "flag = 2", the result is a 5-component vector "w". "w[1]" is the
4110 ideal or module "I" itself. "w[2]" is the structure of the group. The
4111 other components are difficult to describe and are used only in con‐
4112 junction with the function "ideallog".
4113 If "flag = 1" (default), as "flag = 2", but do not compute explicit
4115 generators for the cyclic components, which saves time.
4116 If "flag = 0", computes the structure of "(Z_K/I)^*" as a 3-component
4118 vector "v". "v[1]" is the order, "v[2]" is the vector of SNF cyclic
4119 components and "v[3]" the corresponding generators. When the row vector
4120 is explicitly included, the non-zero elements of this vector are con‐
4121 sidered as real embeddings of nf in the order given by "polroots",
4122 i.e. in nf[6] ("nf.roots"), and then "I" is a module with components at
4123 infinity.
4124 To solve discrete logarithms (using "ideallog"), you have to choose
4126 "flag = 2".
4127 The library syntax is idealstar0"(nf,I,flag)".
4129 idealtwoelt"(nf,x,{a})"
4131 computes a two-element representation of the ideal "x" in the number
4133 field "nf", using a straightforward (exponential time) search. "x" can
4134 be an ideal in any form, (including perhaps an Archimedean part, which
4135 is ignored) and the result is a row vector "[a,alpha]" with two compo‐
4136 nents such that "x = aZ_K+alphaZ_K" and "a belongs to Z", where "a" is
4137 the one passed as argument if any. If "x" is given by at least two gen‐
4138 erators, "a" is chosen to be the positive generator of "x cap Z".
4139 Note that when an explicit "a" is given, we use an asymptotically
4141 faster method, however in practice it is usually slower.
4142 The library syntax is ideal_two_elt0"(nf,x,a)", where an omitted "a" is
4144 entered as "NULL".
4145 idealval"(nf,x,vp)"
4147 gives the valuation of the ideal "x" at the prime ideal vp in the num‐
4149 ber field "nf", where vp must be a 5-component vector as given by "ide‐
4150 alprimedec".
4151 The library syntax is idealval"(nf,x,vp)", and the result is a "long"
4153 integer.
4154 ideleprincipal"(nf,x)"
4156 creates the principal idele generated by the algebraic number "x"
4158 (which must be of type integer, rational or polmod) in the number field
4159 "nf". The result is a two-component vector, the first being a one-col‐
4160 umn matrix representing the corresponding principal ideal, and the sec‐
4161 ond being the vector with "r_1+r_2" components giving the complex loga‐
4162 rithmic embedding of "x".
4163 The library syntax is principalidele"(nf,x)".
4165 matalgtobasis"(nf,x)"
4167 "nf" being a number field in "nfinit" format, and "x" a matrix whose
4169 coefficients are expressed as polmods in "nf", transforms this matrix
4170 into a matrix whose coefficients are expressed on the integral basis of
4171 "nf". This is the same as applying "nfalgtobasis" to each entry, but it
4172 would be dangerous to use the same name.
4173 The library syntax is matalgtobasis"(nf,x)".
4175 matbasistoalg"(nf,x)"
4177 "nf" being a number field in "nfinit" format, and "x" a matrix whose
4179 coefficients are expressed as column vectors on the integral basis of
4180 "nf", transforms this matrix into a matrix whose coefficients are alge‐
4181 braic numbers expressed as polmods. This is the same as applying "nfba‐
4182 sistoalg" to each entry, but it would be dangerous to use the same
4183 name.
4184 The library syntax is matbasistoalg"(nf,x)".
4186 modreverse"(a)"
4188 "a" being a polmod A(X) modulo T(X), finds the ``reverse polmod'' B(X)
4190 modulo Q(X), where "Q" is the minimal polynomial of "a", which must be
4191 equal to the degree of "T", and such that if "theta" is a root of "T"
4192 then "theta = B(alpha)" for a certain root "alpha" of "Q".
4193 This is very useful when one changes the generating element in alge‐
4195 braic extensions.
4196 The library syntax is polmodrecip"(x)".
4198 newtonpoly"(x,p)"
4200 gives the vector of the slopes of the Newton polygon of the polynomial
4202 "x" with respect to the prime number "p". The "n" components of the
4203 vector are in decreasing order, where "n" is equal to the degree of
4204 "x". Vertical slopes occur iff the constant coefficient of "x" is zero
4205 and are denoted by "VERYBIGINT", the biggest single precision integer
4206 representable on the machine ("2^{31}-1" (resp. "2^{63}-1") on 32-bit
4207 (resp. 64-bit) machines), see "Label se:valuation".
4208 The library syntax is newtonpoly"(x,p)".
4210 nfalgtobasis"(nf,x)"
4212 this is the inverse function of "nfbasistoalg". Given an object "x"
4214 whose entries are expressed as algebraic numbers in the number field
4215 "nf", transforms it so that the entries are expressed as a column vec‐
4216 tor on the integral basis "nf.zk".
4217 The library syntax is algtobasis"(nf,x)".
4219 nfbasis"(x,{flag = 0},{p})"
4221 integral basis of the number field defined by the irreducible, prefer‐
4223 ably monic, polynomial "x", using a modified version of the round 4
4224 algorithm by default. The binary digits of "flag" have the following
4225 meaning:
4226 1: assume that no square of a prime greater than the default "prime‐
4228 limit" divides the discriminant of "x", i.e. that the index of "x" has
4229 only small prime divisors.
4230 2: use round 2 algorithm. For small degrees and coefficient size, this
4232 is sometimes a little faster. (This program is the translation into C
4233 of a program written by David Ford in Algeb.)
4234 Thus for instance, if "flag = 3", this uses the round 2 algorithm and
4236 outputs an order which will be maximal at all the small primes.
4237 If "p" is present, we assume (without checking!) that it is the two-
4239 column matrix of the factorization of the discriminant of the polyno‐
4240 mial "x". Note that it does not have to be a complete factorization.
4241 This is especially useful if only a local integral basis for some small
4242 set of places is desired: only factors with exponents greater or equal
4243 to 2 will be considered.
4244 The library syntax is nfbasis0"(x,flag,p)". An extended version is
4246 "nfbasis(x,&d,flag,p)", where "d" will receive the discriminant of the
4247 number field (not of the polynomial "x"), and an omitted "p" should be
4248 input as "gzero". Also available are "base(x,&d)" ("flag = 0"),
4249 "base2(x,&d)" ("flag = 2") and "factoredbase(x,p,&d)".
4250 nfbasistoalg"(nf,x)"
4252 this is the inverse function of "nfalgtobasis". Given an object "x"
4254 whose entries are expressed on the integral basis "nf.zk", transforms
4255 it into an object whose entries are algebraic numbers (i.e. polmods).
4256 The library syntax is basistoalg"(nf,x)".
4258 nfdetint"(nf,x)"
4260 given a pseudo-matrix "x", computes a non-zero ideal contained in
4262 (i.e. multiple of) the determinant of "x". This is particularly useful
4263 in conjunction with "nfhnfmod".
4264 The library syntax is nfdetint"(nf,x)".
4266 nfdisc"(x,{flag = 0},{p})"
4268 field discriminant of the number field defined by the integral, prefer‐
4270 ably monic, irreducible polynomial "x". "flag" and "p" are exactly as
4271 in "nfbasis". That is, "p" provides the matrix of a partial factoriza‐
4272 tion of the discriminant of "x", and binary digits of "flag" are as
4273 follows:
4274 1: assume that no square of a prime greater than "primelimit" divides
4276 the discriminant.
4277 2: use the round 2 algorithm, instead of the default round 4. This
4279 should be slower except maybe for polynomials of small degree and coef‐
4280 ficients.
4281 The library syntax is nfdiscf0"(x,flag,p)" where, to omit "p", you
4283 should input "gzero". You can also use "discf(x)" ("flag = 0").
4284 nfeltdiv"(nf,x,y)"
4286 given two elements "x" and "y" in nf, computes their quotient "x/y" in
4288 the number field "nf".
4289 The library syntax is element_div"(nf,x,y)".
4291 nfeltdiveuc"(nf,x,y)"
4293 given two elements "x" and "y" in nf, computes an algebraic integer "q"
4295 in the number field "nf" such that the components of "x-qy" are reason‐
4296 ably small. In fact, this is functionally identical to "round(nfelt‐
4297 div(nf,x,y))".
4298 The library syntax is nfdiveuc"(nf,x,y)".
4300 nfeltdivmodpr"(nf,x,y,pr)"
4302 given two elements "x" and "y" in nf and pr a prime ideal in "modpr"
4304 format (see "nfmodprinit"), computes their quotient "x / y" modulo the
4305 prime ideal pr.
4306 The library syntax is element_divmodpr"(nf,x,y,pr)".
4308 nfeltdivrem"(nf,x,y)"
4310 given two elements "x" and "y" in nf, gives a two-element row vector
4312 "[q,r]" such that "x = qy+r", "q" is an algebraic integer in "nf", and
4313 the components of "r" are reasonably small.
4314 The library syntax is nfdivres"(nf,x,y)".
4316 nfeltmod"(nf,x,y)"
4318 given two elements "x" and "y" in nf, computes an element "r" of "nf"
4320 of the form "r = x-qy" with "q" and algebraic integer, and such that
4321 "r" is small. This is functionally identical to
4322 "x - nfeltmul(nf,round(nfeltdiv(nf,x,y)),y)."
4324 The library syntax is nfmod"(nf,x,y)".
4326 nfeltmul"(nf,x,y)"
4328 given two elements "x" and "y" in nf, computes their product "x*y" in
4330 the number field "nf".
4331 The library syntax is element_mul"(nf,x,y)".
4333 nfeltmulmodpr"(nf,x,y,pr)"
4335 given two elements "x" and "y" in nf and pr a prime ideal in "modpr"
4337 format (see "nfmodprinit"), computes their product "x*y" modulo the
4338 prime ideal pr.
4339 The library syntax is element_mulmodpr"(nf,x,y,pr)".
4341 nfeltpow"(nf,x,k)"
4343 given an element "x" in nf, and a positive or negative integer "k",
4345 computes "x^k" in the number field "nf".
4346 The library syntax is element_pow"(nf,x,k)".
4348 nfeltpowmodpr"(nf,x,k,pr)"
4350 given an element "x" in nf, an integer "k" and a prime ideal pr in
4352 "modpr" format (see "nfmodprinit"), computes "x^k" modulo the prime
4353 ideal pr.
4354 The library syntax is element_powmodpr"(nf,x,k,pr)".
4356 nfeltreduce"(nf,x,ideal)"
4358 given an ideal in Hermite normal form and an element "x" of the number
4360 field "nf", finds an element "r" in "nf" such that "x-r" belongs to the
4361 ideal and "r" is small.
4362 The library syntax is element_reduce"(nf,x,ideal)".
4364 nfeltreducemodpr"(nf,x,pr)"
4366 given an element "x" of the number field "nf" and a prime ideal pr in
4368 "modpr" format compute a canonical representative for the class of "x"
4369 modulo pr.
4370 The library syntax is nfreducemodpr2"(nf,x,pr)".
4372 nfeltval"(nf,x,pr)"
4374 given an element "x" in nf and a prime ideal pr in the format output by
4376 "idealprimedec", computes their the valuation at pr of the element "x".
4377 The same result could be obtained using "idealval(nf,x,pr)" (since "x"
4378 would then be converted to a principal ideal), but it would be less
4379 efficient.
4380 The library syntax is element_val"(nf,x,pr)", and the result is a
4382 "long".
4383 nffactor"(nf,x)"
4385 factorization of the univariate polynomial "x" over the number field
4387 "nf" given by "nfinit". "x" has coefficients in "nf" (i.e. either
4388 scalar, polmod, polynomial or column vector). The main variable of "nf"
4389 must be of lower priority than that of "x" (in other words, the vari‐
4390 able number of "nf" must be greater than that of "x"). However if the
4391 polynomial defining the number field occurs explicitly in the coeffi‐
4392 cients of "x" (as modulus of a "t_POLMOD"), its main variable must be
4393 the same as the main variable of "x". For example,
4394 ? nf = nfinit(y^2 + 1);
4396 ? nffactor(nf, x^2 + y); \\ OK
4397 ? nffactor(nf, x^2 + Mod(y, y^2+1)); \\ OK
4398 ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ WRONG
4399 The library syntax is nffactor"(nf,x)".
4401 nffactormod"(nf,x,pr)"
4403 factorization of the univariate polynomial "x" modulo the prime ideal
4405 pr in the number field "nf". "x" can have coefficients in the number
4406 field (scalar, polmod, polynomial, column vector) or modulo the prime
4407 ideal (integermod modulo the rational prime under pr, polmod or polyno‐
4408 mial with integermod coefficients, column vector of integermod). The
4409 prime ideal pr must be in the format output by "idealprimedec". The
4410 main variable of "nf" must be of lower priority than that of "x" (in
4411 other words the variable number of "nf" must be greater than that of
4412 "x"). However if the coefficients of the number field occur explicitly
4413 (as polmods) as coefficients of "x", the variable of these polmods must
4414 be the same as the main variable of "t" (see "nffactor").
4415 The library syntax is nffactormod"(nf,x,pr)".
4417 nfgaloisapply"(nf,aut,x)"
4419 "nf" being a number field as output by "nfinit", and aut being a Galois
4421 automorphism of "nf" expressed either as a polynomial or a polmod (such
4422 automorphisms being found using for example one of the variants of
4423 "nfgaloisconj"), computes the action of the automorphism aut on the
4424 object "x" in the number field. "x" can be an element (scalar, polmod,
4425 polynomial or column vector) of the number field, an ideal (either
4426 given by "Z_K"-generators or by a Z-basis), a prime ideal (given as a
4427 5-element row vector) or an idele (given as a 2-element row vector).
4428 Because of possible confusion with elements and ideals, other vector or
4429 matrix arguments are forbidden.
4430 The library syntax is galoisapply"(nf,aut,x)".
4432 nfgaloisconj"(nf,{flag = 0},{d})"
4434 "nf" being a number field as output by "nfinit", computes the conju‐
4436 gates of a root "r" of the non-constant polynomial "x = nf[1]"
4437 expressed as polynomials in "r". This can be used even if the number
4438 field "nf" is not Galois since some conjugates may lie in the field. As
4439 a note to old-timers of PARI, starting with version 2.0.17 this func‐
4440 tion works much better than in earlier versions.
4441 "nf" can simply be a polynomial if "flag ! = 1".
4443 If no flags or "flag = 0", if "nf" is a number field use a combination
4445 of flag 4 and 1 and the result is always complete, else use a combina‐
4446 tion of flag 4 and 2 and the result is subject to the restriction of
4447 "flag = 2", but a warning is issued when it is not proven complete.
4448 If "flag = 1", use "nfroots" (require a number field).
4450 If "flag = 2", use complex approximations to the roots and an integral
4452 LLL. The result is not guaranteed to be complete: some conjugates may
4453 be missing (no warning issued), especially so if the corresponding
4454 polynomial has a huge index. In that case, increasing the default pre‐
4455 cision may help.
4456 If "flag = 4", use Allombert's algorithm and permutation testing. If
4458 the field is Galois with ``weakly'' super solvable Galois group, return
4459 the complete list of automorphisms, else only the identity element. If
4460 present, "d" is assumed to be a multiple of the least common denomina‐
4461 tor of the conjugates expressed as polynomial in a root of pol.
4462 A group G is ``weakly'' super solvable if it contains a super solvable
4464 normal subgroup "H" such that "G = H" , or "G/H ~ A_4" , or "G/H ~
4465 S_4". Abelian and nilpotent groups are ``weakly'' super solvable. In
4466 practice, almost all groups of small order are ``weakly'' super solv‐
4467 able, the exceptions having order 36(1 exception), 48(2), 56(1), 60(1),
4468 72(5), 75(1), 80(1), 96(10) and " >= 108".
4469 Hence "flag = 4" permits to quickly check whether a polynomial of order
4471 strictly less than 36 is Galois or not. This method is much faster than
4472 "nfroots" and can be applied to polynomials of degree larger than 50.
4473 The library syntax is galoisconj0"(nf,flag,d,prec)". Also available are
4475 "galoisconj(nf)" for "flag = 0", "galoisconj2(nf,n,prec)" for "flag =
4476 2" where "n" is a bound on the number of conjugates, and "galois‐
4477 conj4(nf,d)" corresponding to "flag = 4".
4478 nfhilbert"(nf,a,b,{pr})"
4480 if pr is omitted, compute the global Hilbert symbol "(a,b)" in "nf",
4482 that is 1 if "x^2 - a y^2 - b z^2" has a non trivial solution "(x,y,z)"
4483 in "nf", and "-1" otherwise. Otherwise compute the local symbol modulo
4484 the prime ideal pr (as output by "idealprimedec").
4485 The library syntax is nfhilbert"(nf,a,b,pr)", where an omitted pr is
4487 coded as "NULL".
4488 nfhnf"(nf,x)"
4490 given a pseudo-matrix "(A,I)", finds a pseudo-basis in Hermite normal
4492 form of the module it generates.
4493 The library syntax is nfhermite"(nf,x)".
4495 nfhnfmod"(nf,x,detx)"
4497 given a pseudo-matrix "(A,I)" and an ideal detx which is contained in
4499 (read integral multiple of) the determinant of "(A,I)", finds a pseudo-
4500 basis in Hermite normal form of the module generated by "(A,I)". This
4501 avoids coefficient explosion. detx can be computed using the function
4502 "nfdetint".
4503 The library syntax is nfhermitemod"(nf,x,detx)".
4505 nfinit"(pol,{flag = 0})"
4507 pol being a non-constant, preferably monic, irreducible polynomial in
4509 "Z[X]", initializes a number field structure ("nf") associated to the
4510 field "K" defined by pol. As such, it's a technical object passed as
4511 the first argument to most "nf"xxx functions, but it contains some
4512 information which may be directly useful. Access to this information
4513 via member functions is prefered since the specific data organization
4514 specified below may change in the future. Currently, "nf" is a row vec‐
4515 tor with 9 components:
4516 "nf[1]" contains the polynomial pol ("nf.pol").
4518 "nf[2]" contains "[r1,r2]" ("nf.sign"), the number of real and complex
4520 places of "K".
4521 "nf[3]" contains the discriminant d(K) ("nf.disc") of "K".
4523 "nf[4]" contains the index of "nf[1]", i.e. "[Z_K : Z[theta]]", where
4525 "theta" is any root of "nf[1]".
4526 "nf[5]" is a vector containing 7 matrices "M", "MC", "T2", "T", "MD",
4528 "TI", "MDI" useful for certain computations in the number field "K".
4529 "*" "M" is the "(r1+r2) x n" matrix whose columns represent the
4531 numerical values of the conjugates of the elements of the integral
4532 basis.
4533 "*" "MC" is essentially the conjugate of the transpose of "M", except
4535 that the last "r2" columns are also multiplied by 2.
4536 "*" "T2" is an "n x n" matrix equal to the real part of the product
4538 "MC.M" (which is a real positive definite symmetric matrix), the so-
4539 called "T_2"-matrix ("nf.t2").
4540 "*" "T" is the "n x n" matrix whose coefficients are
4542 "Tr(omega_iomega_j)" where the "omega_i" are the elements of the inte‐
4543 gral basis. Note that "T = \overline{MC}.M" and in particular that "T =
4544 T_2" if the field is totally real (in practice "T_2" will have real
4545 approximate entries and "T" will have integer entries). Note also that
4546 " det (T)" is equal to the discriminant of the field "K".
4547 "*" The columns of "MD" ("nf.diff") express a Z-basis of the differ‐
4549 ent of "K" on the integral basis.
4550 "*" "TI" is equal to "d(K)T^{-1}", which has integral coefficients.
4552 Note that, understood as as ideal, the matrix "T^{-1}" generates the
4553 codifferent ideal.
4554 "*" Finally, "MDI" is a two-element representation (for faster ideal
4556 product) of d(K) times the codifferent ideal ("nf.disc*nf.codiff",
4557 which is an integral ideal). "MDI" is only used in "idealinv".
4558 "nf[6]" is the vector containing the "r1+r2" roots ("nf.roots") of
4560 "nf[1]" corresponding to the "r1+r2" embeddings of the number field
4561 into C (the first "r1" components are real, the next "r2" have positive
4562 imaginary part).
4563 "nf[7]" is an integral basis in Hermite normal form for "Z_K" ("nf.zk")
4565 expressed on the powers of "theta".
4566 "nf[8]" is the "n x n" integral matrix expressing the power basis in
4568 terms of the integral basis, and finally
4569 "nf[9]" is the "n x n^2" matrix giving the multiplication table of the
4571 integral basis.
4572 If a non monic polynomial is input, "nfinit" will transform it into a
4574 monic one, then reduce it (see "flag = 3"). It is allowed, though not
4575 very useful given the existence of nfnewprec, to input a "nf" or a
4576 "bnf" instead of a polynomial.
4577 The special input format "[x,B]" is also accepted where "x" is a poly‐
4579 nomial as above and "B" is the integer basis, as computed by "nfbasis".
4580 This can be useful since "nfinit" uses the round 4 algorithm by
4581 default, which can be very slow in pathological cases where round 2
4582 ("nfbasis(x,2)") would succeed very quickly.
4583 If "flag = 2": pol is changed into another polynomial "P" defining the
4585 same number field, which is as simple as can easily be found using the
4586 "polred" algorithm, and all the subsequent computations are done using
4587 this new polynomial. In particular, the first component of the result
4588 is the modified polynomial.
4589 If "flag = 3", does a "polred" as in case 2, but outputs
4591 "[nf,Mod(a,P)]", where "nf" is as before and "Mod(a,P) = Mod(x,pol)"
4592 gives the change of variables. This is implicit when pol is not monic:
4593 first a linear change of variables is performed, to get a monic polyno‐
4594 mial, then a "polred" reduction.
4595 If "flag = 4", as 2 but uses a partial "polred".
4597 If "flag = 5", as 3 using a partial "polred".
4599 The library syntax is nfinit0"(x,flag,prec)".
4601 nfisideal"(nf,x)"
4603 returns 1 if "x" is an ideal in the number field "nf", 0 otherwise.
4605 The library syntax is isideal"(x)".
4607 nfisincl"(x,y)"
4609 tests whether the number field "K" defined by the polynomial "x" is
4611 conjugate to a subfield of the field "L" defined by "y" (where "x" and
4612 "y" must be in "Q[X]"). If they are not, the output is the number 0. If
4613 they are, the output is a vector of polynomials, each polynomial "a"
4614 representing an embedding of "K" into "L", i.e. being such that "y ⎪ x
4615 o a".
4616 If "y" is a number field (nf), a much faster algorithm is used (factor‐
4618 ing "x" over "y" using "nffactor"). Before version 2.0.14, this wasn't
4619 guaranteed to return all the embeddings, hence was triggered by a spe‐
4620 cial flag. This is no more the case.
4621 The library syntax is nfisincl"(x,y,flag)".
4623 nfisisom"(x,y)"
4625 as "nfisincl", but tests for isomorphism. If either "x" or "y" is a
4627 number field, a much faster algorithm will be used.
4628 The library syntax is nfisisom"(x,y,flag)".
4630 nfnewprec"(nf)"
4632 transforms the number field "nf" into the corresponding data using cur‐
4634 rent (usually larger) precision. This function works as expected if
4635 "nf" is in fact a "bnf" (update "bnf" to current precision) but may be
4636 quite slow (many generators of principal ideals have to be computed).
4637 The library syntax is nfnewprec"(nf,prec)".
4639 nfkermodpr"(nf,a,pr)"
4641 kernel of the matrix "a" in "Z_K/pr", where pr is in modpr format (see
4643 "nfmodprinit").
4644 The library syntax is nfkermodpr"(nf,a,pr)".
4646 nfmodprinit"(nf,pr)"
4648 transforms the prime ideal pr into "modpr" format necessary for all
4650 operations modulo pr in the number field nf. Returns a two-component
4651 vector "[P,a]", where "P" is the Hermite normal form of pr, and "a" is
4652 an integral element congruent to 1 modulo pr, and congruent to 0 modulo
4653 "p / pr^e". Here "p = Z cap pr" and "e" is the absolute ramification
4654 index.
4655 The library syntax is nfmodprinit"(nf,pr)".
4657 nfsubfields"(nf,{d = 0})"
4659 finds all subfields of degree "d" of the number field "nf" (all sub‐
4661 fields if "d" is null or omitted). The result is a vector of sub‐
4662 fields, each being given by "[g,h]", where "g" is an absolute equation
4663 and "h" expresses one of the roots of "g" in terms of the root "x" of
4664 the polynomial defining "nf". This is a crude implementation by
4665 M. Olivier of an algorithm due to J. Klueners.
4666 The library syntax is subfields"(nf,d)".
4668 nfroots"(nf,x)"
4670 roots of the polynomial "x" in the number field "nf" given by "nfinit"
4672 without multiplicity. "x" has coefficients in the number field (scalar,
4673 polmod, polynomial, column vector). The main variable of "nf" must be
4674 of lower priority than that of "x" (in other words the variable number
4675 of "nf" must be greater than that of "x"). However if the coefficients
4676 of the number field occur explicitly (as polmods) as coefficients of
4677 "x", the variable of these polmods must be the same as the main vari‐
4678 able of "t" (see "nffactor").
4679 The library syntax is nfroots"(nf,x)".
4681 nfrootsof1"(nf)"
4683 computes the number of roots of unity "w" and a primitive "w"-th root
4685 of unity (expressed on the integral basis) belonging to the number
4686 field "nf". The result is a two-component vector "[w,z]" where "z" is a
4687 column vector expressing a primitive "w"-th root of unity on the inte‐
4688 gral basis "nf.zk".
4689 The library syntax is rootsof1"(nf)".
4691 nfsnf"(nf,x)"
4693 given a torsion module "x" as a 3-component row vector "[A,I,J]" where
4695 "A" is a square invertible "n x n" matrix, "I" and "J" are two ideal
4696 lists, outputs an ideal list "d_1,...,d_n" which is the Smith normal
4697 form of "x". In other words, "x" is isomorphic to "Z_K/d_1 oplus ...
4698 oplus Z_K/d_n" and "d_i" divides "d_{i-1}" for "i >= 2". The link
4699 between "x" and "[A,I,J]" is as follows: if "e_i" is the canonical
4700 basis of "K^n", "I = [b_1,...,b_n]" and "J = [a_1,...,a_n]", then "x"
4701 is isomorphic to
4702 " (b_1e_1 oplus ... oplus b_ne_n) / (a_1A_1 oplus ... oplus a_nA_n)
4704 , "
4705 where the "A_j" are the columns of the matrix "A". Note that every fi‐
4707 nitely generated torsion module can be given in this way, and even with
4708 "b_i = Z_K" for all "i".
4709 The library syntax is nfsmith"(nf,x)".
4711 nfsolvemodpr"(nf,a,b,pr)"
4713 solution of "a.x = b" in "Z_K/pr", where "a" is a matrix and "b" a col‐
4715 umn vector, and where pr is in modpr format (see "nfmodprinit").
4716 The library syntax is nfsolvemodpr"(nf,a,b,pr)".
4718 polcompositum"(x,y,{flag = 0})"
4720 "x" and "y" being polynomials in "Z[X]" in the same variable, outputs a
4722 vector giving the list of all possible composita of the number fields
4723 defined by "x" and "y", if "x" and "y" are irreducible, or of the cor‐
4724 responding etale algebras, if they are only squarefree. Returns an
4725 error if one of the polynomials is not squarefree. When one of the
4726 polynomials is irreducible (say "x"), it is often much faster to use
4727 "nffactor(nfinit(x), y)" then "rnfequation".
4728 If "flag = 1", outputs a vector of 4-component vectors "[z,a,b,k]",
4730 where "z" ranges through the list of all possible compositums as above,
4731 and "a" (resp. "b") expresses the root of "x" (resp. "y") as a polmod
4732 in a root of "z", and "k" is a small integer k such that "a+kb" is the
4733 chosen root of "z".
4734 The compositum will quite often be defined by a complicated polynomial,
4736 which it is advisable to reduce before further work. Here is a simple
4737 example involving the field "Q(zeta_5, 5^{1/5})":
4738 ? z = polcompositum(x^5 - 5, polcyclo(5), 1)[1];
4740 ? pol = z[1] \\ pol defines the compositum
4741 %2 = x^20 + 5*x^19 + 15*x^18 + 35*x^17 + 70*x^16 + 141*x^15 + 260*x^14 \
4742 + 355*x^13 + 95*x^12 - 1460*x^11 - 3279*x^10 - 3660*x^9 - 2005*x^8 \
4743 + 705*x^7 + 9210*x^6 + 13506*x^5 + 7145*x^4 - 2740*x^3 + 1040*x^2 \
4744 - 320*x + 256
4745 ? a = z[2]; a^5 - 5 \\ a is a fifth root of 5
4746 %3 = 0
4747 ? z = polredabs(pol, 1); \\ look for a simpler polynomial
4748 ? pol = z[1]
4749 %5 = x^20 + 25*x^10 + 5
4750 ? a = subst(a.pol, x, z[2]) \\ a in the new coordinates
4751 %6 = Mod(-5/22*x^19 + 1/22*x^14 - 123/22*x^9 + 9/11*x^4, x^20 + 25*x^10 + 5)
4752 The library syntax is polcompositum0"(x,y,flag)".
4754 polgalois"(x)"
4756 Galois group of the non-constant polynomial "x belongs to Q[X]". In the
4758 present version 2.2.0, "x" must be irreducible and the degree of "x"
4759 must be less than or equal to 7. On certain versions for which the data
4760 file of Galois resolvents has been installed (available in the Unix
4761 distribution as a separate package), degrees 8, 9, 10 and 11 are also
4762 implemented.
4763 The output is a 3-component vector "[n,s,k]" with the following mean‐
4765 ing: "n" is the cardinality of the group, "s" is its signature ("s = 1"
4766 if the group is a subgroup of the alternating group "A_n", "s = -1"
4767 otherwise), and "k" is the number of the group corresponding to a given
4768 pair "(n,s)" ("k = 1" except in 2 cases). Specifically, the groups are
4769 coded as follows, using standard notations (see GTM 138, quoted at the
4770 beginning of this section; see also ``The transitive groups of degree
4771 up to eleven'', by G. Butler and J. McKay in Communications in Algebra,
4772 vol. 11, 1983, pp. 863--911):
4773 In degree 1: "S_1 = [1,-1,1]".
4775 In degree 2: "S_2 = [2,-1,1]".
4777 In degree 3: "A_3 = C_3 = [3,1,1]", "S_3 = [6,-1,1]".
4779 In degree 4: "C_4 = [4,-1,1]", "V_4 = [4,1,1]", "D_4 = [8,-1,1]", "A_4
4781 = [12,1,1]", "S_4 = [24,-1,1]".
4782 In degree 5: "C_5 = [5,1,1]", "D_5 = [10,1,1]", "M_{20} = [20,-1,1]",
4784 "A_5 = [60,1,1]", "S_5 = [120,-1,1]".
4785 In degree 6: "C_6 = [6,-1,1]", "S_3 = [6,-1,2]", "D_6 = [12,-1,1]",
4787 "A_4 = [12,1,1]", "G_{18} = [18,-1,1]", "S_4^ -= [24,-1,1]", "A_4 x C_2
4788 = [24,-1,2]", "S_4^ += [24,1,1]", "G_{36}^ -= [36,-1,1]", "G_{36}^ +=
4789 [36,1,1]", "S_4 x C_2 = [48,-1,1]", "A_5 = PSL_2(5) = [60,1,1]",
4790 "G_{72} = [72,-1,1]", "S_5 = PGL_2(5) = [120,-1,1]", "A_6 = [360,1,1]",
4791 "S_6 = [720,-1,1]".
4792 In degree 7: "C_7 = [7,1,1]", "D_7 = [14,-1,1]", "M_{21} = [21,1,1]",
4794 "M_{42} = [42,-1,1]", "PSL_2(7) = PSL_3(2) = [168,1,1]", "A_7 =
4795 [2520,1,1]", "S_7 = [5040,-1,1]".
4796 The method used is that of resolvent polynomials and is sensitive to
4798 the current precision. The precision is updated internally but, in very
4799 rare cases, a wrong result may be returned if the initial precision was
4800 not sufficient.
4801 The library syntax is galois"(x,prec)".
4803 polred"(x,{flag = 0},{p})"
4805 finds polynomials with reasonably small coefficients defining subfields
4807 of the number field defined by "x". One of the polynomials always
4808 defines Q (hence is equal to "x-1"), and another always defines the
4809 same number field as "x" if "x" is irreducible. All "x" accepted by
4810 "nfinit" are also allowed here (e.g. non-monic polynomials, "nf",
4811 "bnf", "[x,Z_K_basis]").
4812 The following binary digits of "flag" are significant:
4814 1: does a partial reduction only. This means that only a suborder of
4816 the maximal order may be used.
4817 2: gives also elements. The result is a two-column matrix, the first
4819 column giving the elements defining these subfields, the second giving
4820 the corresponding minimal polynomials.
4821 If "p" is given, it is assumed that it is the two-column matrix of the
4823 factorization of the discriminant of the polynomial "x".
4824 The library syntax is polred0"(x,flag,p,prec)", where an omitted "p" is
4826 coded by "gzero". Also available are "polred(x,prec)" and "factored‐
4827 polred(x,p,prec)", both corresponding to "flag = 0".
4828 polredabs"(x,{flag = 0})"
4830 finds one of the polynomial defining the same number field as the one
4832 defined by "x", and such that the sum of the squares of the modulus of
4833 the roots (i.e. the "T_2"-norm) is minimal. All "x" accepted by
4834 "nfinit" are also allowed here (e.g. non-monic polynomials, "nf",
4835 "bnf", "[x,Z_K_basis]").
4836 The binary digits of "flag" mean
4838 1: outputs a two-component row vector "[P,a]", where "P" is the default
4840 output and "a" is an element expressed on a root of the polynomial "P",
4841 whose minimal polynomial is equal to "x".
4842 4: gives all polynomials of minimal "T_2" norm (of the two polynomials
4844 P(x) and "P(-x)", only one is given).
4845 The library syntax is polredabs0"(x,flag,prec)".
4847 polredord"(x)"
4849 finds polynomials with reasonably small coefficients and of the same
4851 degree as that of "x" defining suborders of the order defined by "x".
4852 One of the polynomials always defines Q (hence is equal to "(x-1)^n",
4853 where "n" is the degree), and another always defines the same order as
4854 "x" if "x" is irreducible.
4855 The library syntax is ordred"(x)".
4857 poltschirnhaus"(x)"
4859 applies a random Tschirnhausen transformation to the polynomial "x",
4861 which is assumed to be non-constant and separable, so as to obtain a
4862 new equation for the etale algebra defined by "x". This is for instance
4863 useful when computing resolvents, hence is used by the "polgalois"
4864 function.
4865 The library syntax is tschirnhaus"(x)".
4867 rnfalgtobasis"(rnf,x)"
4869 "rnf" being a relative number field extension "L/K" as output by
4871 "rnfinit" and "x" being an element of "L" expressed as a polynomial or
4872 polmod with polmod coefficients, expresses "x" on the relative integral
4873 basis.
4874 The library syntax is rnfalgtobasis"(rnf,x)".
4876 rnfbasis"(bnf,x)"
4878 given a big number field "bnf" as output by "bnfinit", and either a
4880 polynomial "x" with coefficients in "bnf" defining a relative extension
4881 "L" of "bnf", or a pseudo-basis "x" of such an extension, gives either
4882 a true "bnf"-basis of "L" if it exists, or an "n+1"-element generating
4883 set of "L" if not, where "n" is the rank of "L" over "bnf".
4884 The library syntax is rnfbasis"(bnf,x)".
4886 rnfbasistoalg"(rnf,x)"
4888 "rnf" being a relative number field extension "L/K" as output by
4890 "rnfinit" and "x" being an element of "L" expressed on the relative
4891 integral basis, computes the representation of "x" as a polmod with
4892 polmods coefficients.
4893 The library syntax is rnfbasistoalg"(rnf,x)".
4895 rnfcharpoly"(nf,T,a,{v = x})"
4897 characteristic polynomial of "a" over "nf", where "a" belongs to the
4899 algebra defined by "T" over "nf", i.e. "nf[X]/(T)". Returns a polyno‐
4900 mial in variable "v" ("x" by default).
4901 The library syntax is rnfcharpoly"(nf,T,a,v)", where "v" is a variable
4903 number.
4904 rnfconductor"(bnf,pol)"
4906 "bnf" being a big number field as output by "bnfinit", and pol a rela‐
4908 tive polynomial defining an Abelian extension, computes the class field
4909 theory conductor of this Abelian extension. The result is a 3-component
4910 vector "[conductor,rayclgp,subgroup]", where conductor is the conductor
4911 of the extension given as a 2-component row vector "[f_0,f_ oo ]", ray‐
4912 clgp is the full ray class group corresponding to the conductor given
4913 as a 3-component vector [h,cyc,gen] as usual for a group, and subgroup
4914 is a matrix in HNF defining the subgroup of the ray class group on the
4915 given generators gen.
4916 The library syntax is rnfconductor"(rnf,pol,prec)".
4918 rnfdedekind"(nf,pol,pr)"
4920 given a number field "nf" as output by "nfinit" and a polynomial pol
4922 with coefficients in "nf" defining a relative extension "L" of "nf",
4923 evaluates the relative Dedekind criterion over the order defined by a
4924 root of pol for the prime ideal pr and outputs a 3-component vector as
4925 the result. The first component is a flag equal to 1 if the enlarged
4926 order could be proven to be pr-maximal and to 0 otherwise (it may be
4927 maximal in the latter case if pr is ramified in "L"), the second compo‐
4928 nent is a pseudo-basis of the enlarged order and the third component is
4929 the valuation at pr of the order discriminant.
4930 The library syntax is rnfdedekind"(nf,pol,pr)".
4932 rnfdet"(nf,M)"
4934 given a pseudomatrix "M" over the maximal order of "nf", computes its
4936 pseudodeterminant.
4937 The library syntax is rnfdet"(nf,M)".
4939 rnfdisc"(nf,pol)"
4941 given a number field "nf" as output by "nfinit" and a polynomial pol
4943 with coefficients in "nf" defining a relative extension "L" of "nf",
4944 computes the relative discriminant of "L". This is a two-element row
4945 vector "[D,d]", where "D" is the relative ideal discriminant and "d" is
4946 the relative discriminant considered as an element of "nf^*/{nf^*}^2".
4947 The main variable of "nf" must be of lower priority than that of pol.
4948 Note: As usual, "nf" can be a "bnf" as output by "nfinit".
4950 The library syntax is rnfdiscf"(bnf,pol)".
4952 rnfeltabstorel"(rnf,x)"
4954 "rnf" being a relative number field extension "L/K" as output by
4956 "rnfinit" and "x" being an element of "L" expressed as a polynomial
4957 modulo the absolute equation "rnf[11][1]", computes "x" as an element
4958 of the relative extension "L/K" as a polmod with polmod coefficients.
4959 The library syntax is rnfelementabstorel"(rnf,x)".
4961 rnfeltdown"(rnf,x)"
4963 "rnf" being a relative number field extension "L/K" as output by
4965 "rnfinit" and "x" being an element of "L" expressed as a polynomial or
4966 polmod with polmod coefficients, computes "x" as an element of "K" as a
4967 polmod, assuming "x" is in "K" (otherwise an error will occur). If "x"
4968 is given on the relative integral basis, apply "rnfbasistoalg" first,
4969 otherwise PARI will believe you are dealing with a vector.
4970 The library syntax is rnfelementdown"(rnf,x)".
4972 rnfeltreltoabs"(rnf,x)"
4974 "rnf" being a relative number field extension "L/K" as output by
4976 "rnfinit" and "x" being an element of "L" expressed as a polynomial or
4977 polmod with polmod coefficients, computes "x" as an element of the
4978 absolute extension "L/Q" as a polynomial modulo the absolute equation
4979 "rnf[11][1]". If "x" is given on the relative integral basis, apply
4980 "rnfbasistoalg" first, otherwise PARI will believe you are dealing with
4981 a vector.
4982 The library syntax is rnfelementreltoabs"(rnf,x)".
4984 rnfeltup"(rnf,x)"
4986 "rnf" being a relative number field extension "L/K" as output by
4988 "rnfinit" and "x" being an element of "K" expressed as a polynomial or
4989 polmod, computes "x" as an element of the absolute extension "L/Q" as a
4990 polynomial modulo the absolute equation "rnf[11][1]". Note that it is
4991 unnecessary to compute "x" as an element of the relative extension
4992 "L/K" (its expression would be identical to itself). If "x" is given on
4993 the integral basis of "K", apply "nfbasistoalg" first, otherwise PARI
4994 will believe you are dealing with a vector.
4995 The library syntax is rnfelementup"(rnf,x)".
4997 rnfequation"(nf,pol,{flag = 0})"
4999 given a number field "nf" as output by "nfinit" (or simply a polyno‐
5001 mial) and a polynomial pol with coefficients in "nf" defining a rela‐
5002 tive extension "L" of "nf", computes the absolute equation of "L" over
5003 Q.
5004 If "flag" is non-zero, outputs a 3-component row vector "[z,a,k]",
5006 where "z" is the absolute equation of "L" over Q, as in the default be‐
5007 haviour, "a" expresses as an element of "L" a root "alpha" of the poly‐
5008 nomial defining the base field "nf", and "k" is a small integer such
5009 that "theta = beta+kalpha" where "theta" is a root of "z" and "beta" a
5010 root of "pol".
5011 The main variable of "nf" must be of lower priority than that of pol.
5013 Note that for efficiency, this does not check whether the relative
5014 equation is irreducible over "nf", but only if it is squarefree. If it
5015 is reducible but squarefree, the result will be the absolute equation
5016 of the etale algebra defined by pol. If pol is not squarefree, an error
5017 message will be issued.
5018 The library syntax is rnfequation0"(nf,pol,flag)".
5020 rnfhnfbasis"(bnf,x)"
5022 given a big number field "bnf" as output by "bnfinit", and either a
5024 polynomial "x" with coefficients in "bnf" defining a relative extension
5025 "L" of "bnf", or a pseudo-basis "x" of such an extension, gives either
5026 a true "bnf"-basis of "L" in upper triangular Hermite normal form, if
5027 it exists, zero otherwise.
5028 The library syntax is rnfhermitebasis"(nf,x)".
5030 rnfidealabstorel"(rnf,x)"
5032 "rnf" being a relative number field extension "L/K" as output by
5034 "rnfinit" and "x" being an ideal of the absolute extension "L/Q" given
5035 in HNF (if it is not, apply "idealhnf" first), computes the relative
5036 pseudomatrix in HNF giving the ideal "x" considered as an ideal of the
5037 relative extension "L/K".
5038 The library syntax is rnfidealabstorel"(rnf,x)".
5040 rnfidealdown"(rnf,x)"
5042 "rnf" being a relative number field extension "L/K" as output by
5044 "rnfinit" and "x" being an ideal of the absolute extension "L/Q" given
5045 in HNF (if it is not, apply "idealhnf" first), gives the ideal of "K"
5046 below "x", i.e. the intersection of "x" with "K". Note that, if "x" is
5047 given as a relative ideal (i.e. a pseudomatrix in HNF), then it is not
5048 necessary to use this function since the result is simply the first
5049 ideal of the ideal list of the pseudomatrix.
5050 The library syntax is rnfidealdown"(rnf,x)".
5052 rnfidealhnf"(rnf,x)"
5054 "rnf" being a relative number field extension "L/K" as output by
5056 "rnfinit" and "x" being a relative ideal (which can be, as in the abso‐
5057 lute case, of many different types, including of course elements), com‐
5058 putes as a 2-component row vector the relative Hermite normal form of
5059 "x", the first component being the HNF matrix (with entries on the
5060 integral basis), and the second component the ideals.
5061 The library syntax is rnfidealhermite"(rnf,x)".
5063 rnfidealmul"(rnf,x,y)"
5065 "rnf" being a relative number field extension "L/K" as output by
5067 "rnfinit" and "x" and "y" being ideals of the relative extension "L/K"
5068 given by pseudo-matrices, outputs the ideal product, again as a rela‐
5069 tive ideal.
5070 The library syntax is rnfidealmul"(rnf,x,y)".
5072 rnfidealnormabs"(rnf,x)"
5074 "rnf" being a relative number field extension "L/K" as output by
5076 "rnfinit" and "x" being a relative ideal (which can be, as in the abso‐
5077 lute case, of many different types, including of course elements), com‐
5078 putes the norm of the ideal "x" considered as an ideal of the absolute
5079 extension "L/Q". This is identical to "idealnorm(rnfidealnorm‐
5080 rel(rnf,x))", only faster.
5081 The library syntax is rnfidealnormabs"(rnf,x)".
5083 rnfidealnormrel"(rnf,x)"
5085 "rnf" being a relative number field extension "L/K" as output by
5087 "rnfinit" and "x" being a relative ideal (which can be, as in the abso‐
5088 lute case, of many different types, including of course elements), com‐
5089 putes the relative norm of "x" as a ideal of "K" in HNF.
5090 The library syntax is rnfidealnormrel"(rnf,x)".
5092 rnfidealreltoabs"(rnf,x)"
5094 "rnf" being a relative number field extension "L/K" as output by
5096 "rnfinit" and "x" being a relative ideal (which can be, as in the abso‐
5097 lute case, of many different types, including of course elements), com‐
5098 putes the HNF matrix of the ideal "x" considered as an ideal of the
5099 absolute extension "L/Q".
5100 The library syntax is rnfidealreltoabs"(rnf,x)".
5102 rnfidealtwoelt"(rnf,x)"
5104 "rnf" being a relative number field extension "L/K" as output by
5106 "rnfinit" and "x" being an ideal of the relative extension "L/K" given
5107 by a pseudo-matrix, gives a vector of two generators of "x" over "Z_L"
5108 expressed as polmods with polmod coefficients.
5109 The library syntax is rnfidealtwoelement"(rnf,x)".
5111 rnfidealup"(rnf,x)"
5113 "rnf" being a relative number field extension "L/K" as output by
5115 "rnfinit" and "x" being an ideal of "K", gives the ideal "xZ_L" as an
5116 absolute ideal of "L/Q" (the relative ideal representation is trivial:
5117 the matrix is the identity matrix, and the ideal list starts with "x",
5118 all the other ideals being "Z_K").
5119 The library syntax is rnfidealup"(rnf,x)".
5121 rnfinit"(nf,pol)"
5123 "nf" being a number field in "nfinit" format considered as base field,
5125 and pol a polynomial defining a relative extension over "nf", this com‐
5126 putes all the necessary data to work in the relative extension. The
5127 main variable of pol must be of higher priority (i.e. lower number)
5128 than that of "nf", and the coefficients of pol must be in "nf".
5129 The result is an 11-component row vector as follows (most of the compo‐
5131 nents are technical), the numbering being very close to that of
5132 "nfinit". In the following description, we let "K" be the base field
5133 defined by "nf", "m" the degree of the base field, "n" the relative
5134 degree, "L" the large field (of relative degree "n" or absolute degree
5135 "nm"), "r_1" and "r_2" the number of real and complex places of "K".
5136 "rnf[1]" contains the relative polynomial pol.
5138 "rnf[2]" is a row vector with "r_1+r_2" entries, entry "j" being a
5140 2-component row vector "[r_{j,1},r_{j,2}]" where "r_{j,1}" and
5141 "r_{j,2}" are the number of real and complex places of "L" above the
5142 "j"-th place of "K" so that "r_{j,1} = 0" and "r_{j,2} = n" if "j" is a
5143 complex place, while if "j" is a real place we have "r_{j,1}+2r_{j,2} =
5144 n".
5145 "rnf[3]" is a two-component row vector "[d(L/K),s]" where "d(L/K)" is
5147 the relative ideal discriminant of "L/K" and "s" is the discriminant of
5148 "L/K" viewed as an element of "K^*/(K^*)^2", in other words it is the
5149 output of "rnfdisc".
5150 "rnf[4]" is the ideal index "f", i.e. such that "d(pol)Z_K =
5152 f^2d(L/K)".
5153 "rnf[5]" is a vector vm with 7 entries useful for certain computations
5155 in the relative extension "L/K". "vm[1]" is a vector of "r_1+r_2"
5156 matrices, the "j"-th matrix being an "(r_{1,j}+r_{2,j}) x n" matrix
5157 "M_j" representing the numerical values of the conjugates of the "j"-th
5158 embedding of the elements of the integral basis, where "r_{i,j}" is as
5159 in "rnf[2]". "vm[2]" is a vector of "r_1+r_2" matrices, the "j"-th
5160 matrix "MC_j" being essentially the conjugate of the matrix "M_j"
5161 except that the last "r_{2,j}" columns are also multiplied by 2.
5162 "vm[3]" is a vector of "r_1+r_2" matrices "T2_j", where "T2_j" is an "n
5163 x n" matrix equal to the real part of the product "MC_j.M_j" (which is
5164 a real positive definite matrix). "vm[4]" is the "n x n" matrix "T"
5165 whose entries are the relative traces of "omega_iomega_j" expressed as
5166 polmods in "nf", where the "omega_i" are the elements of the relative
5167 integral basis. Note that the "j"-th embedding of "T" is equal to
5168 "\overline{MC_j}.M_j", and in particular will be equal to "T2_j" if
5169 "r_{2,j} = 0". Note also that the relative ideal discriminant of "L/K"
5170 is equal to " det (T)" times the square of the product of the ideals in
5171 the relative pseudo-basis (in "rnf[7][2]"). The last 3 entries "vm[5]",
5172 "vm[6]" and "vm[7]" are linked to the different as in "nfinit", but
5173 have not yet been implemented.
5174 "rnf[6]" is a row vector with "r_1+r_2" entries, the "j"-th entry being
5176 the row vector with "r_{1,j}+r_{2,j}" entries of the roots of the
5177 "j"-th embedding of the relative polynomial pol.
5178 "rnf[7]" is a two-component row vector, where the first component is
5180 the relative integral pseudo basis expressed as polynomials (in the
5181 variable of "pol") with polmod coefficients in "nf", and the second
5182 component is the ideal list of the pseudobasis in HNF.
5183 "rnf[8]" is the inverse matrix of the integral basis matrix, with coef‐
5185 ficients polmods in "nf".
5186 "rnf[9]" may be the multiplication table of the integral basis, but is
5188 not implemented at present.
5189 "rnf[10]" is "nf".
5191 "rnf[11]" is a vector vabs with 5 entries describing the absolute
5193 extension "L/Q". "vabs[1]" is an absolute equation. "vabs[2]"
5194 expresses the generator "alpha" of the number field "nf" as a polyno‐
5195 mial modulo the absolute equation "vabs[1]". "vabs[3]" is a small
5196 integer "k" such that, if "beta" is an abstract root of pol and "alpha"
5197 the generator of "nf", the generator whose root is vabs will be "beta +
5198 k alpha". Note that one must be very careful if "k ! = 0" when dealing
5199 simultaneously with absolute and relative quantities since the genera‐
5200 tor chosen for the absolute extension is not the same as for the rela‐
5201 tive one. If this happens, one can of course go on working, but we
5202 strongly advise to change the relative polynomial so that its root will
5203 be "beta + k alpha". Typically, the GP instruction would be
5204 "pol = subst(pol, x, x - k*Mod(y,nf.pol))"
5206 Finally, "vabs[4]" is the absolute integral basis of "L" expressed in
5208 HNF (hence as would be output by "nfinit(vabs[1])"), and "vabs[5]" the
5209 inverse matrix of the integral basis, allowing to go from polmod to
5210 integral basis representation.
5211 The library syntax is rnfinitalg"(nf,pol,prec)".
5213 rnfisfree"(bnf,x)"
5215 given a big number field "bnf" as output by "bnfinit", and either a
5217 polynomial "x" with coefficients in "bnf" defining a relative extension
5218 "L" of "bnf", or a pseudo-basis "x" of such an extension, returns true
5219 (1) if "L/bnf" is free, false (0) if not.
5220 The library syntax is rnfisfree"(bnf,x)", and the result is a "long".
5222 rnfisnorm"(bnf,ext,el,{flag = 1})"
5224 similar to "bnfisnorm" but in the relative case. This tries to decide
5226 whether the element el in bnf is the norm of some "y" in ext. "bnf" is
5227 as output by "bnfinit".
5228 "ext" is a relative extension which has to be a row vector whose compo‐
5230 nents are:
5231 "ext[1]": a relative equation of the number field ext over bnf. As
5233 usual, the priority of the variable of the polynomial defining the
5234 ground field bnf (say "y") must be lower than the main variable of
5235 "ext[1]", say "x".
5236 "ext[2]": the generator "y" of the base field as a polynomial in "x"
5238 (as given by "rnfequation" with "flag = 1").
5239 "ext[3]": is the "bnfinit" of the absolute extension "ext/Q".
5241 This returns a vector "[a,b]", where "el = Norm(a)*b". It looks for a
5243 solution which is an "S"-integer, with "S" a list of places (of bnf)
5244 containing the ramified primes, the generators of the class group of
5245 ext, as well as those primes dividing el. If "ext/bnf" is known to be
5246 Galois, set "flag = 0" (here el is a norm iff "b = 1"). If "flag" is
5247 non zero add to "S" all the places above the primes which: divide
5248 "flag" if "flag < 0", or are less than "flag" if "flag > 0". The answer
5249 is guaranteed (i.e. el is a norm iff "b = 1") under GRH, if "S" con‐
5250 tains all primes less than "12 log ^2⎪disc(Ext)⎪", where Ext is the
5251 normal closure of "ext / bnf". Example:
5252 bnf = bnfinit(y^3 + y^2 - 2*y - 1);
5254 p = x^2 + Mod(y^2 + 2*y + 1, bnf.pol);
5255 rnf = rnfequation(bnf,p,1);
5256 ext = [p, rnf[2], bnfinit(rnf[1])];
5257 rnfisnorm(bnf,ext,17, 1)
5258 checks whether 17 is a norm in the Galois extension "Q(beta) /
5260 Q(alpha)", where "alpha^3 + alpha^2 - 2alpha - 1 = 0" and "beta^2 +
5261 alpha^2 + 2*alpha + 1 = 0" (it is).
5262 The library syntax is rnfisnorm"(bnf,ext,x,flag,prec)".
5264 rnfkummer"(bnr,subgroup,{deg = 0})"
5266 bnr being as output by "bnrinit", finds a relative equation for the
5268 class field corresponding to the module in bnr and the given congruence
5269 subgroup. If deg is positive, outputs the list of all relative equa‐
5270 tions of degree deg contained in the ray class field defined by bnr.
5271 (THIS PROGRAM IS STILL IN DEVELOPMENT STAGE)
5273 The library syntax is rnfkummer"(bnr,subgroup,deg,prec)", where deg is
5275 a "long".
5276 rnflllgram"(nf,pol,order)"
5278 given a polynomial pol with coefficients in nf and an order order as
5280 output by "rnfpseudobasis" or similar, gives "[[neworder],U]", where
5281 neworder is a reduced order and "U" is the unimodular transformation
5282 matrix.
5283 The library syntax is rnflllgram"(nf,pol,order,prec)".
5285 rnfnormgroup"(bnr,pol)"
5287 bnr being a big ray class field as output by "bnrinit" and pol a rela‐
5289 tive polynomial defining an Abelian extension, computes the norm group
5290 (alias Artin or Takagi group) corresponding to the Abelian extension of
5291 "bnf = bnr[1]" defined by pol, where the module corresponding to bnr is
5292 assumed to be a multiple of the conductor (i.e. polrel defines a subex‐
5293 tension of bnr). The result is the HNF defining the norm group on the
5294 given generators of "bnr[5][3]". Note that neither the fact that pol
5295 defines an Abelian extension nor the fact that the module is a multiple
5296 of the conductor is checked. The result is undefined if the assumption
5297 is not correct.
5298 The library syntax is rnfnormgroup"(bnr,pol)".
5300 rnfpolred"(nf,pol)"
5302 relative version of "polred". Given a monic polynomial pol with coef‐
5304 ficients in "nf", finds a list of relative polynomials defining some
5305 subfields, hopefully simpler and containing the original field. In the
5306 present version 2.2.0, this is slower than "rnfpolredabs".
5307 The library syntax is rnfpolred"(nf,pol,prec)".
5309 rnfpolredabs"(nf,pol,{flag = 0})"
5311 relative version of "polredabs". Given a monic polynomial pol with
5313 coefficients in "nf", finds a simpler relative polynomial defining the
5314 same field. If "flag = 1", returns "[P,a]" where "P" is the default
5315 output and "a" is an element expressed on a root of "P" whose charac‐
5316 teristic polynomial is pol, if "flag = 2", returns an absolute polyno‐
5317 mial (same as
5318 "rnfequation(nf,rnfpolredabs(nf,pol))"
5320 but faster).
5322 Remark. In the present implementation, this is both faster and much
5324 more efficient than "rnfpolred", the difference being more dramatic
5325 than in the absolute case. This is because the implementation of "rnf‐
5326 polred" is based on (a partial implementation of) an incomplete reduc‐
5327 tion theory of lattices over number fields (i.e. the function "rnflll‐
5328 gram") which deserves to be improved.
5329 The library syntax is rnfpolredabs"(nf,pol,flag,prec)".
5331 rnfpseudobasis"(nf,pol)"
5333 given a number field "nf" as output by "nfinit" and a polynomial pol
5335 with coefficients in "nf" defining a relative extension "L" of "nf",
5336 computes a pseudo-basis "(A,I)" and the relative discriminant of "L".
5337 This is output as a four-element row vector "[A,I,D,d]", where "D" is
5338 the relative ideal discriminant and "d" is the relative discriminant
5339 considered as an element of "nf^*/{nf^*}^2".
5340 Note: As usual, "nf" can be a "bnf" as output by "bnfinit".
5342 The library syntax is rnfpseudobasis"(nf,pol)".
5344 rnfsteinitz"(nf,x)"
5346 given a number field "nf" as output by "nfinit" and either a polynomial
5348 "x" with coefficients in "nf" defining a relative extension "L" of
5349 "nf", or a pseudo-basis "x" of such an extension as output for example
5350 by "rnfpseudobasis", computes another pseudo-basis "(A,I)" (not in HNF
5351 in general) such that all the ideals of "I" except perhaps the last one
5352 are equal to the ring of integers of "nf", and outputs the four-compo‐
5353 nent row vector "[A,I,D,d]" as in "rnfpseudobasis". The name of this
5354 function comes from the fact that the ideal class of the last ideal of
5355 "I" (which is well defined) is called the Steinitz class of the module
5356 "Z_L".
5357 Note: "nf" can be a "bnf" as output by "bnfinit".
5359 The library syntax is rnfsteinitz"(nf,x)".
5361 subgrouplist"(bnr,{bound},{flag = 0})"
5363 bnr being as output by "bnrinit" or a list of cyclic components of a
5365 finite Abelian group "G", outputs the list of subgroups of "G" (of
5366 index bounded by bound, if not omitted). Subgroups are given as HNF
5367 left divisors of the SNF matrix corresponding to "G". If "flag = 0"
5368 (default) and bnr is as output by "bnrinit", gives only the subgroups
5369 whose modulus is the conductor.
5370 The library syntax is subgrouplist0"(bnr,bound,flag,prec)", where
5372 bound, "flag" and "prec" are long integers.
5373 zetak"(znf,x,{flag = 0})"
5375 znf being a number field initialized by "zetakinit" (not by "nfinit"),
5377 computes the value of the Dedekind zeta function of the number field at
5378 the complex number "x". If "flag = 1" computes Dedekind "Lambda" func‐
5379 tion instead (i.e. the product of the Dedekind zeta function by its
5380 gamma and exponential factors).
5381 The accuracy of the result depends in an essential way on the accuracy
5383 of both the "zetakinit" program and the current accuracy, but even so
5384 the result may be off by up to 5 or 10 decimal digits.
5385 The library syntax is glambdak"(znf,x,prec)" or "gzetak(znf,x,prec)".
5387 zetakinit"(x)"
5389 computes a number of initialization data concerning the number field
5391 defined by the polynomial "x" so as to be able to compute the Dedekind
5392 zeta and lambda functions (respectively zetak(x) and "zetak(x,1)").
5393 This function calls in particular the "bnfinit" program. The result is
5394 a 9-component vector "v" whose components are very technical and cannot
5395 really be used by the user except through the "zetak" function. The
5396 only component which can be used if it has not been computed already is
5397 "v[1][4]" which is the result of the "bnfinit" call.
5398 This function is very inefficient and should be rewritten. It needs to
5400 computes millions of coefficients of the corresponding Dirichlet series
5401 if the precision is big. Unless the discriminant is small it will not
5402 be able to handle more than 9 digits of relative precision
5403 (e.g "zetakinit(x^8 - 2)" needs 440MB of memory at default precision).
5404 The library syntax is initzeta"(x)".
5406
5408 We group here all functions which are specific to polynomials or power
5409 series. Many other functions which can be applied on these objects are
5410 described in the other sections. Also, some of the functions described
5411 here can be applied to other types.
5412 O"(a""^""b)"
5414 "p"-adic (if "a" is an integer greater or equal to 2) or power series
5416 zero (in all other cases), with precision given by "b".
5417 The library syntax is ggrandocp"(a,b)", where "b" is a "long".
5419 deriv"(x,{v})"
5421 derivative of "x" with respect to the main variable if "v" is omitted,
5423 and with respect to "v" otherwise. "x" can be any type except polmod.
5424 The derivative of a scalar type is zero, and the derivative of a vector
5425 or matrix is done componentwise. One can use "x'" as a shortcut if the
5426 derivative is with respect to the main variable of "x".
5427 The library syntax is deriv"(x,v)", where "v" is a "long", and an omit‐
5429 ted "v" is coded as "-1".
5430 eval"(x)"
5432 replaces in "x" the formal variables by the values that have been
5434 assigned to them after the creation of "x". This is mainly useful in
5435 GP, and not in library mode. Do not confuse this with substitution (see
5436 "subst"). Applying this function to a character string yields the out‐
5437 put from the corresponding GP command, as if directly input from the
5438 keyboard (see "Label se:strings").
5439 The library syntax is geval"(x)". The more basic functions "pole‐
5441 val(q,x)", "qfeval(q,x)", and "hqfeval(q,x)" evaluate "q" at "x", where
5442 "q" is respectively assumed to be a polynomial, a quadratic form (a
5443 symmetric matrix), or an Hermitian form (an Hermitian complex matrix).
5444 factorpadic"(pol,p,r,{flag = 0})"
5446 "p"-adic factorization of the polynomial pol to precision "r", the
5448 result being a two-column matrix as in "factor". The factors are nor‐
5449 malized so that their leading coefficient is a power of "p". "r" must
5450 be strictly larger than the "p"-adic valuation of the discriminant of
5451 pol for the result to make any sense. The method used is a modified
5452 version of the round 4 algorithm of Zassenhaus.
5453 If "flag = 1", use an algorithm due to Buchmann and Lenstra, which is
5455 usually less efficient.
5456 The library syntax is factorpadic4"(pol,p,r)", where "r" is a "long"
5458 integer.
5459 intformal"(x,{v})"
5461 formal integration of "x" with respect to the main variable if "v" is
5463 omitted, with respect to the variable "v" otherwise. Since PARI does
5464 not know about ``abstract'' logarithms (they are immediately evaluated,
5465 if only to a power series), logarithmic terms in the result will yield
5466 an error. "x" can be of any type. When "x" is a rational function, it
5467 is assumed that the base ring is an integral domain of characteristic
5468 zero.
5469 The library syntax is integ"(x,v)", where "v" is a "long" and an omit‐
5471 ted "v" is coded as "-1".
5472 padicappr"(pol,a)"
5474 vector of "p"-adic roots of the polynomial "pol" congruent to the
5476 "p"-adic number "a" modulo "p" (or modulo 4 if "p = 2"), and with the
5477 same "p"-adic precision as "a". The number "a" can be an ordinary
5478 "p"-adic number (type "t_PADIC", i.e. an element of "Q_p") or can be an
5479 element of a finite extension of "Q_p", in which case it is of type
5480 "t_POLMOD", where at least one of the coefficients of the polmod is a
5481 "p"-adic number. In this case, the result is the vector of roots
5482 belonging to the same extension of "Q_p" as "a".
5483 The library syntax is apprgen9"(pol,a)", but if "a" is known to be sim‐
5485 ply a "p"-adic number (type "t_PADIC"), the syntax "apprgen(pol,a)" can
5486 be used.
5487 polcoeff"(x,s,{v})"
5489 coefficient of degree "s" of the polynomial "x", with respect to the
5491 main variable if "v" is omitted, with respect to "v" otherwise.
5492 The library syntax is polcoeff0"(x,s,v)", where "v" is a "long" and an
5494 omitted "v" is coded as "-1". Also available is truecoeff"(x,v)".
5495 poldegree"(x,{v})"
5497 degree of the polynomial "x" in the main variable if "v" is omitted, in
5499 the variable "v" otherwise. This is to be understood as follows. When
5500 "x" is a polynomial or a rational function, it gives the degree of "x",
5501 the degree of 0 being "-1" by convention. When "x" is a non-zero
5502 scalar, it gives 0, and when "x" is a zero scalar, it gives "-1".
5503 Return an error otherwise.
5504 The library syntax is poldegree"(x,v)", where "v" and the result are
5506 "long"s (and an omitted "v" is coded as "-1"). Also available is
5507 degree"(x)", which is equivalent to "poldegree(x,-1)".
5508 polcyclo"(n,{v = x})"
5510 "n"-th cyclotomic polynomial, in variable "v" ("x" by default). The
5512 integer "n" must be positive.
5513 The library syntax is cyclo"(n,v)", where "n" and "v" are "long" inte‐
5515 gers ("v" is a variable number, usually obtained through "varn").
5516 poldisc"(pol,{v})"
5518 discriminant of the polynomial pol in the main variable is "v" is omit‐
5520 ted, in "v" otherwise. The algorithm used is the subresultant algo‐
5521 rithm.
5522 The library syntax is poldisc0"(x,v)". Also available is discsr"(x)",
5524 equivalent to "poldisc0(x,-1)".
5525 poldiscreduced"(f)"
5527 reduced discriminant vector of the (integral, monic) polynomial "f".
5529 This is the vector of elementary divisors of
5530 "Z[alpha]/f'(alpha)Z[alpha]", where "alpha" is a root of the polynomial
5531 "f". The components of the result are all positive, and their product
5532 is equal to the absolute value of the discriminant of "f".
5533 The library syntax is reduceddiscsmith"(x)".
5535 polhensellift"(x, y, p, e)"
5537 given a vector "y" of polynomials that are pairwise relatively prime
5539 modulo the prime "p", and whose product is congruent to "x" modulo "p",
5540 lift the elements of "y" to polynomials whose product is congruent to
5541 "x" modulo "p^e".
5542 The library syntax is polhensellift"(x,y,p,e)" where "e" must be a
5544 "long".
5545 polinterpolate"(xa,{ya},{v = x},{&e})"
5547 given the data vectors "xa" and "ya" of the same length "n" ("xa" con‐
5549 taining the "x"-coordinates, and "ya" the corresponding "y"-coordi‐
5550 nates), this function finds the interpolating polynomial passing
5551 through these points and evaluates it at "v". If "ya" is omitted,
5552 return the polynomial interpolating the "(i,xa[i])". If present, "e"
5553 will contain an error estimate on the returned value.
5554 The library syntax is polint"(xa,ya,v,&e)", where "e" will contain an
5556 error estimate on the returned value.
5557 polisirreducible"(pol)"
5559 pol being a polynomial (univariate in the present version 2.2.0),
5561 returns 1 if pol is non-constant and irreducible, 0 otherwise. Irre‐
5562 ducibility is checked over the smallest base field over which pol seems
5563 to be defined.
5564 The library syntax is gisirreducible"(pol)".
5566 pollead"(x,{v})"
5568 leading coefficient of the polynomial or power series "x". This is com‐
5570 puted with respect to the main variable of "x" if "v" is omitted, with
5571 respect to the variable "v" otherwise.
5572 The library syntax is pollead"(x,v)", where "v" is a "long" and an
5574 omitted "v" is coded as "-1". Also available is leadingcoeff"(x)".
5575 pollegendre"(n,{v = x})"
5577 creates the "n^{th}" Legendre polynomial, in variable "v".
5579 The library syntax is legendre"(n)", where "x" is a "long".
5581 polrecip"(pol)"
5583 reciprocal polynomial of pol, i.e. the coefficients are in reverse
5585 order. pol must be a polynomial.
5586 The library syntax is polrecip"(x)".
5588 polresultant"(x,y,{v},{flag = 0})"
5590 resultant of the two polynomials "x" and "y" with exact entries, with
5592 respect to the main variables of "x" and "y" if "v" is omitted, with
5593 respect to the variable "v" otherwise. The algorithm used is the subre‐
5594 sultant algorithm by default.
5595 If "flag = 1", uses the determinant of Sylvester's matrix instead (here
5597 "x" and "y" may have non-exact coefficients).
5598 If "flag = 2", uses Ducos's modified subresultant algorithm. It should
5600 be much faster than the default if the coefficient ring is complicated
5601 (e.g multivariate polynomials or huge coefficients), and slightly
5602 slower otherwise.
5603 The library syntax is polresultant0"(x,y,v,flag)", where "v" is a
5605 "long" and an omitted "v" is coded as "-1". Also available are "sub‐
5606 res(x,y)" ("flag = 0") and "resultant2(x,y)" ("flag = 1").
5607 polroots"(pol,{flag = 0})"
5609 complex roots of the polynomial pol, given as a column vector where
5611 each root is repeated according to its multiplicity. The precision is
5612 given as for transcendental functions: under GP it is kept in the vari‐
5613 able "realprecision" and is transparent to the user, but it must be
5614 explicitly given as a second argument in library mode.
5615 The algorithm used is a modification of A. Schoenhage's remarkable
5617 root-finding algorithm, due to and implemented by X. Gourdon. Barring
5618 bugs, it is guaranteed to converge and to give the roots to the
5619 required accuracy.
5620 If "flag = 1", use a variant of the Newton-Raphson method, which is not
5622 guaranteed to converge, but is rather fast. If you get the messages
5623 ``too many iterations in roots'' or ``INTERNAL ERROR: incorrect result
5624 in roots'', use the default function (i.e. no flag or "flag = 0"). This
5625 used to be the default root-finding function in PARI until version
5626 1.39.06.
5627 The library syntax is roots"(pol,prec)" or "rootsold(pol,prec)".
5629 polrootsmod"(pol,p,{flag = 0})"
5631 row vector of roots modulo "p" of the polynomial pol. The particular
5633 non-prime value "p = 4" is accepted, mainly for 2-adic computations.
5634 Multiple roots are not repeated.
5635 If "p < 100", you may try setting "flag = 1", which uses a naive
5637 search. In this case, multiple roots are repeated with their order of
5638 multiplicity.
5639 The library syntax is rootmod"(pol,p)" ("flag = 0") or "root‐
5641 mod2(pol,p)" ("flag = 1").
5642 polrootspadic"(pol,p,r)"
5644 row vector of "p"-adic roots of the polynomial pol with "p"-adic preci‐
5646 sion equal to "r". Multiple roots are not repeated. "p" is assumed to
5647 be a prime.
5648 The library syntax is rootpadic"(pol,p,r)", where "r" is a "long".
5650 polsturm"(pol,{a},{b})"
5652 number of real roots of the real polynomial pol in the interval
5654 "]a,b]", using Sturm's algorithm. "a" (resp. "b") is taken to be "- oo
5655 " (resp. "+ oo ") if omitted.
5656 The library syntax is sturmpart"(pol,a,b)". Use "NULL" to omit an argu‐
5658 ment. sturm"(pol)" is equivalent to sturmpart"(pol,NULL,NULL)". The
5659 result is a "long".
5660 polsubcyclo"(n,d,{v = x})"
5662 gives a polynomial (in variable "v") defining the sub-Abelian extension
5664 of degree "d" of the cyclotomic field "Q(zeta_n)", where "d ⎪ phi(n)".
5665 "(Z/nZ)^*" has to be cyclic (i.e. "n = 2", 4, "p^k" or "2p^k" for an
5666 odd prime "p"). The function "galoissubcyclo" covers the general case.
5667 The library syntax is subcyclo"(n,d,v)", where "v" is a variable num‐
5669 ber.
5670 polsylvestermatrix"(x,y)"
5672 forms the Sylvester matrix corresponding to the two polynomials "x" and
5674 "y", where the coefficients of the polynomials are put in the columns
5675 of the matrix (which is the natural direction for solving equations
5676 afterwards). The use of this matrix can be essential when dealing with
5677 polynomials with inexact entries, since polynomial Euclidean division
5678 doesn't make much sense in this case.
5679 The library syntax is sylvestermatrix"(x,y)".
5681 polsym"(x,n)"
5683 creates the vector of the symmetric powers of the roots of the polyno‐
5685 mial "x" up to power "n", using Newton's formula.
5686 The library syntax is polsym"(x)".
5688 poltchebi"(n,{v = x})"
5690 creates the "n^{th}" Chebyshev polynomial, in variable "v".
5692 The library syntax is tchebi"(n,v)", where "n" and "v" are "long" inte‐
5694 gers ("v" is a variable number).
5695 polzagier"(n,m)"
5697 creates Zagier's polynomial "P_{n,m}" used in the functions "sumalt"
5699 and "sumpos" (with "flag = 1"). The exact definition can be found in a
5700 forthcoming paper. One must have "m <= n".
5701 The library syntax is polzagreel"(n,m,prec)" if the result is only
5703 wanted as a polynomial with real coefficients to the precision "prec",
5704 or "polzag(n,m)" if the result is wanted exactly, where "n" and "m" are
5705 "long"s.
5706 serconvol"(x,y)"
5708 convolution (or Hadamard product) of the two power series "x" and "y";
5710 in other words if "x = sum a_k*X^k" and "y = sum b_k*X^k" then "sercon‐
5711 vol(x,y) = sum a_k*b_k*X^k".
5712 The library syntax is convol"(x,y)".
5714 serlaplace"(x)"
5716 "x" must be a power series with only non-negative exponents. If "x =
5718 sum (a_k/k!)*X^k" then the result is "sum a_k*X^k".
5719 The library syntax is laplace"(x)".
5721 serreverse"(x)"
5723 reverse power series (i.e. "x^{-1}", not "1/x") of "x". "x" must be a
5725 power series whose valuation is exactly equal to one.
5726 The library syntax is recip"(x)".
5728 subst"(x,y,z)"
5730 replace the simple variable "y" by the argument "z" in the ``polyno‐
5732 mial'' expression "x". Every type is allowed for "x", but if it is not
5733 a genuine polynomial (or power series, or rational function), the sub‐
5734 stitution will be done as if the scalar components were polynomials of
5735 degree one. In particular, beware that:
5736 ? subst(1, x, [1,2; 3,4])
5738 %1 =
5739 [1 0]
5740 [0 1]
5742 ? subst(1, x, Mat([0,1]))
5744 *** forbidden substitution by a non square matrix
5745 If "x" is a power series, "z" must be either a polynomial, a power
5747 series, or a rational function. "y" must be a simple variable name.
5748 The library syntax is gsubst"(x,v,z)", where "v" is the number of the
5750 variable "y".
5751 taylor"(x,y)"
5753 Taylor expansion around 0 of "x" with respect to the simple variable
5755 "y". "x" can be of any reasonable type, for example a rational func‐
5756 tion. The number of terms of the expansion is transparent to the user
5757 under GP, but must be given as a second argument in library mode.
5758 The library syntax is tayl"(x,y,n)", where the "long" integer "n" is
5760 the desired number of terms in the expansion.
5761 thue"(tnf,a,{sol})"
5763 solves the equation "P(x,y) = a" in integers "x" and "y", where tnf was
5765 created with thueinit(P). sol, if present, contains the solutions of
5766 "Norm(x) = a" modulo units of positive norm in the number field defined
5767 by "P" (as computed by "bnfisintnorm"). If tnf was computed without
5768 assuming GRH ("flag = 1" in "thueinit"), the result is unconditional.
5769 For instance, here's how to solve the Thue equation "x^{13} - 5y^{13} =
5770 - 4":
5771 ? tnf = thueinit(x^13 - 5);
5773 ? thue(tnf, -4)
5774 %1 = [[1, 1]]
5775 Hence, assuming GRH, the only solution is "x = 1", "y = 1".
5777 The library syntax is thue"(tnf,a,sol)", where an omitted sol is coded
5779 as "NULL".
5780 thueinit"(P,{flag = 0})"
5782 initializes the tnf corresponding to "P". It is meant to be used in
5784 conjunction with "thue" to solve Thue equations "P(x,y) = a", where "a"
5785 is an integer. If "flag" is non-zero, certify the result uncondition‐
5786 naly, Otherwise, assume GRH, this being much faster of course.
5787 The library syntax is thueinit"(P,flag,prec)".
5789
5791 Note that most linear algebra functions operating on subspaces defined
5792 by generating sets (such as "mathnf", "qflll", etc.) take matrices as
5793 arguments. As usual, the generating vectors are taken to be the columns
5794 of the given matrix.
5795 algdep"(x,k,{flag = 0})"
5797 "x" being real, complex, or "p"-adic, finds a polynomial of degree at
5799 most "k" with integer coefficients having "x" as approximate root. Note
5800 that the polynomial which is obtained is not necessarily the ``cor‐
5801 rect'' one (it's not even guaranteed to be irreducible!). One can check
5802 the closeness either by a polynomial evaluation or substitution, or by
5803 computing the roots of the polynomial given by algdep.
5804 If "x" is padic, "flag" is meaningless and the algorithm LLL-reduces
5806 the ``dual lattice'' corresponding to the powers of "x".
5807 Otherwise, if "flag" is zero, the algorithm used is a variant of the
5809 LLL algorithm due to Hastad, Lagarias and Schnorr (STACS 1986). If the
5810 precision is too low, the routine may enter an infinite loop.
5811 If "flag" is non-zero, use a standard LLL. "flag" then indicates a pre‐
5813 cision, which should be between 0.5 and 1.0 times the number of decimal
5814 digits to which "x" was computed.
5815 The library syntax is algdep0"(x,k,flag,prec)", where "k" and "flag"
5817 are "long"s. Also available is "algdep(x,k,prec)" ("flag = 0").
5818 charpoly"(A,{v = x},{flag = 0})"
5820 characteristic polynomial of "A" with respect to the variable "v",
5822 i.e. determinant of "v*I-A" if "A" is a square matrix, determinant of
5823 the map ``multiplication by "A"'' if "A" is a scalar, in particular a
5824 polmod (e.g. "charpoly(I,x) = x^2+1"). Note that in the latter case,
5825 the minimal polynomial can be obtained as
5826 minpoly(A)=
5828 {
5829 local(y);
5830 y = charpoly(A);
5831 y / gcd(y,y')
5832 }
5833 The value of "flag" is only significant for matrices.
5835 If "flag = 0", the method used is essentially the same as for computing
5837 the adjoint matrix, i.e. computing the traces of the powers of "A".
5838 If "flag = 1", uses Lagrange interpolation which is almost always
5840 slower.
5841 If "flag = 2", uses the Hessenberg form. This is faster than the
5843 default when the coefficients are integermod a prime or real numbers,
5844 but is usually slower in other base rings.
5845 The library syntax is charpoly0"(A,v,flag)", where "v" is the variable
5847 number. Also available are the functions "caract(A,v)" ("flag = 1"),
5848 "carhess(A,v)" ("flag = 2"), and "caradj(A,v,pt)" where, in this last
5849 case, pt is a "GEN*" which, if not equal to "NULL", will receive the
5850 address of the adjoint matrix of "A" (see "matadjoint"), so both can be
5851 obtained at once.
5852 concat"(x,{y})"
5854 concatenation of "x" and "y". If "x" or "y" is not a vector or matrix,
5856 it is considered as a one-dimensional vector. All types are allowed for
5857 "x" and "y", but the sizes must be compatible. Note that matrices are
5858 concatenated horizontally, i.e. the number of rows stays the same.
5859 Using transpositions, it is easy to concatenate them vertically.
5860 To concatenate vectors sideways (i.e. to obtain a two-row or two-column
5862 matrix), first transform the vector into a one-row or one-column matrix
5863 using the function "Mat". Concatenating a row vector to a matrix having
5864 the same number of columns will add the row to the matrix (top row if
5865 the vector is "x", i.e. comes first, and bottom row otherwise).
5866 The empty matrix "[;]" is considered to have a number of rows compati‐
5868 ble with any operation, in particular concatenation. (Note that this is
5869 definitely not the case for empty vectors "[ ]" or "[ ]~".)
5870 If "y" is omitted, "x" has to be a row vector or a list, in which case
5872 its elements are concatenated, from left to right, using the above
5873 rules.
5874 ? concat([1,2], [3,4])
5876 %1 = [1, 2, 3, 4]
5877 ? a = [[1,2]~, [3,4]~]; concat(a)
5878 %2 = [1, 2, 3, 4]~
5879 ? a[1] = Mat(a[1]); concat(a)
5880 %3 =
5881 [1 3]
5882 [2 4]
5884 ? concat([1,2; 3,4], [5,6]~)
5886 %4 =
5887 [1 2 5]
5888 [3 4 6]
5890 ? concat([%, [7,8]~, [1,2,3,4]])
5891 %5 =
5892 [1 2 5 7]
5893 [3 4 6 8]
5895 [1 2 3 4]
5897 The library syntax is concat"(x,y)".
5899 lindep"(x,{flag = 0})"
5901 "x" being a vector with real or complex coefficients, finds a small
5903 integral linear combination among these coefficients.
5904 If "flag = 0", uses a variant of the LLL algorithm due to Hastad,
5906 Lagarias and Schnorr (STACS 1986).
5907 If "flag > 0", uses the LLL algorithm. "flag" is a parameter which
5909 should be between one half the number of decimal digits of precision
5910 and that number (see "algdep").
5911 If "flag < 0", returns as soon as one relation has been found.
5913 The library syntax is lindep0"(x,flag,prec)". Also available is "lin‐
5915 dep(x,prec)" ("flag = 0").
5916 listcreate"(n)"
5918 creates an empty list of maximal length "n".
5920 This function is useless in library mode.
5922 listinsert"(list,x,n)"
5924 inserts the object "x" at position "n" in list (which must be of type
5926 "t_LIST"). All the remaining elements of list (from position "n+1"
5927 onwards) are shifted to the right. This and "listput" are the only com‐
5928 mands which enable you to increase a list's effective length (as long
5929 as it remains under the maximal length specified at the time of the
5930 "listcreate").
5931 This function is useless in library mode.
5933 listkill"(list)"
5935 kill list. This deletes all elements from list and sets its effective
5937 length to 0. The maximal length is not affected.
5938 This function is useless in library mode.
5940 listput"(list,x,{n})"
5942 sets the "n"-th element of the list list (which must be of type
5944 "t_LIST") equal to "x". If "n" is omitted, or greater than the list
5945 current effective length, just appends "x". This and "listinsert" are
5946 the only commands which enable you to increase a list's effective
5947 length (as long as it remains under the maximal length specified at the
5948 time of the "listcreate").
5949 If you want to put an element into an occupied cell, i.e. if you don't
5951 want to change the effective length, you can consider the list as a
5952 vector and use the usual "list[n] = x" construct.
5953 This function is useless in library mode.
5955 listsort"(list,{flag = 0})"
5957 sorts list (which must be of type "t_LIST") in place. If "flag" is
5959 non-zero, suppresses all repeated coefficients. This is much faster
5960 than the "vecsort" command since no copy has to be made.
5961 This function is useless in library mode.
5963 matadjoint"(x)"
5965 adjoint matrix of "x", i.e. the matrix "y" of cofactors of "x", satis‐
5967 fying "x*y = det (x)*Id". "x" must be a (non-necessarily invertible)
5968 square matrix.
5969 The library syntax is adj"(x)".
5971 matcompanion"(x)"
5973 the left companion matrix to the polynomial "x".
5975 The library syntax is assmat"(x)".
5977 matdet"(x,{flag = 0})"
5979 determinant of "x". "x" must be a square matrix.
5981 If "flag = 0", uses Gauss-Bareiss.
5983 If "flag = 1", uses classical Gaussian elimination, which is better
5985 when the entries of the matrix are reals or integers for example, but
5986 usually much worse for more complicated entries like multivariate poly‐
5987 nomials.
5988 The library syntax is det"(x)" ("flag = 0") and "det2(x)" ("flag = 1").
5990 matdetint"(x)"
5992 "x" being an "m x n" matrix with integer coefficients, this function
5994 computes a multiple of the determinant of the lattice generated by the
5995 columns of "x" if it is of rank "m", and returns zero otherwise. This
5996 function can be useful in conjunction with the function "mathnfmod"
5997 which needs to know such a multiple. Other ways to obtain this determi‐
5998 nant (assuming the rank is maximal) is "matdet(qflll(x,4)[2]*x)" or
5999 more simply "matdet(mathnf(x))". Experiment to see which is faster for
6000 your applications.
6001 The library syntax is detint"(x)".
6003 matdiagonal"(x)"
6005 "x" being a vector, creates the diagonal matrix whose diagonal entries
6007 are those of "x".
6008 The library syntax is diagonal"(x)".
6010 mateigen"(x)"
6012 gives the eigenvectors of "x" as columns of a matrix.
6014 The library syntax is eigen"(x)".
6016 mathess"(x)"
6018 Hessenberg form of the square matrix "x".
6020 The library syntax is hess"(x)".
6022 mathilbert"(x)"
6024 "x" being a "long", creates the Hilbert matrix of order "x", i.e. the
6026 matrix whose coefficient ("i","j") is "1/ (i+j-1)". matrix"
6027 The library syntax is mathilbert"(x)".
6029 mathnf"(x,{flag = 0})"
6031 if "x" is a (not necessarily square) matrix of maximal rank, finds the
6033 upper triangular Hermite normal form of "x". If the rank of "x" is
6034 equal to its number of rows, the result is a square matrix. In general,
6035 the columns of the result form a basis of the lattice spanned by the
6036 columns of "x".
6037 If "flag = 0", uses the naive algorithm. If the Z-module generated by
6039 the columns is a lattice, it is recommanded to use "mathnfmod(x, mat‐
6040 detint(x))" instead (much faster).
6041 If "flag = 1", uses Batut's algorithm. Outputs a two-component row vec‐
6043 tor "[H,U]", where "H" is the upper triangular Hermite normal form of
6044 "x" (i.e. the default result) and "U" is the unimodular transformation
6045 matrix such that "xU = [0⎪H]". If the rank of "x" is equal to its num‐
6046 ber of rows, "H" is a square matrix. In general, the columns of "H"
6047 form a basis of the lattice spanned by the columns of "x".
6048 If "flag = 2", uses Havas's algorithm. Outputs "[H,U,P]", such that "H"
6050 and "U" are as before and "P" is a permutation of the rows such that
6051 "P" applied to "xU" gives "H". This does not work very well in present
6052 version 2.2.0.
6053 If "flag = 3", uses Batut's algorithm, and outputs "[H,U,P]" as in the
6055 previous case.
6056 If "flag = 4", as in case 1 above, but uses LLL reduction along the
6058 way.
6059 The library syntax is mathnf0"(x,flag)". Also available are "hnf(x)"
6061 ("flag = 0") and "hnfall(x)" ("flag = 1"). To reduce huge (say "400 x
6062 400" and more) relation matrices (sparse with small entries), you can
6063 use the pair "hnfspec" / "hnfadd". Since this is rather technical and
6064 the calling interface may change, they are not documented yet. Look at
6065 the code in "basemath/alglin1.c".
6066 mathnfmod"(x,d)"
6068 if "x" is a (not necessarily square) matrix of maximal rank with inte‐
6070 ger entries, and "d" is a multiple of the (non-zero) determinant of the
6071 lattice spanned by the columns of "x", finds the upper triangular Her‐
6072 mite normal form of "x".
6073 If the rank of "x" is equal to its number of rows, the result is a
6075 square matrix. In general, the columns of the result form a basis of
6076 the lattice spanned by the columns of "x". This is much faster than
6077 "mathnf" when "d" is known.
6078 The library syntax is hnfmod"(x,d)".
6080 mathnfmodid"(x,d)"
6082 outputs the (upper triangular) Hermite normal form of "x" concatenated
6084 with "d" times the identity matrix.
6085 The library syntax is hnfmodid"(x,d)".
6087 matid"(n)"
6089 creates the "n x n" identity matrix.
6091 The library syntax is idmat"(n)" where "n" is a "long".
6093 Related functions are "gscalmat(x,n)", which creates "x" times the
6095 identity matrix ("x" being a "GEN" and "n" a "long"), and "gscals‐
6096 mat(x,n)" which is the same when "x" is a "long".
6097 matimage"(x,{flag = 0})"
6099 gives a basis for the image of the matrix "x" as columns of a matrix. A
6101 priori the matrix can have entries of any type. If "flag = 0", use
6102 standard Gauss pivot. If "flag = 1", use "matsupplement".
6103 The library syntax is matimage0"(x,flag)". Also available is "image(x)"
6105 ("flag = 0").
6106 matimagecompl"(x)"
6108 gives the vector of the column indices which are not extracted by the
6110 function "matimage". Hence the number of components of matimagecompl(x)
6111 plus the number of columns of matimage(x) is equal to the number of
6112 columns of the matrix "x".
6113 The library syntax is imagecompl"(x)".
6115 matindexrank"(x)"
6117 "x" being a matrix of rank "r", gives two vectors "y" and "z" of length
6119 "r" giving a list of rows and columns respectively (starting from 1)
6120 such that the extracted matrix obtained from these two vectors using
6121 "vecextract(x,y,z)" is invertible.
6122 The library syntax is indexrank"(x)".
6124 matintersect"(x,y)"
6126 "x" and "y" being two matrices with the same number of rows each of
6128 whose columns are independent, finds a basis of the Q-vector space
6129 equal to the intersection of the spaces spanned by the columns of "x"
6130 and "y" respectively. See also the function "idealintersect", which
6131 does the same for free Z-modules.
6132 The library syntax is intersect"(x,y)".
6134 matinverseimage"(x,y)"
6136 gives a column vector belonging to the inverse image of the column vec‐
6138 tor "y" by the matrix "x" if one exists, the empty vector otherwise. To
6139 get the complete inverse image, it suffices to add to the result any
6140 element of the kernel of "x" obtained for example by "matker".
6141 The library syntax is inverseimage"(x,y)".
6143 matisdiagonal"(x)"
6145 returns true (1) if "x" is a diagonal matrix, false (0) if not.
6147 The library syntax is isdiagonal"(x)", and this returns a "long" inte‐
6149 ger.
6150 matker"(x,{flag = 0})"
6152 gives a basis for the kernel of the matrix "x" as columns of a matrix.
6154 A priori the matrix can have entries of any type.
6155 If "x" is known to have integral entries, set "flag = 1".
6157 Note: The library function "ker_mod_p(x, p)", where "x" has integer
6159 entries and "p" is prime, which is equivalent to but many orders of
6160 magnitude faster than "matker(x*Mod(1,p))" and needs much less stack
6161 space. To use it under GP, type "install(ker_mod_p, GG)" first.
6162 The library syntax is matker0"(x,flag)". Also available are "ker(x)"
6164 ("flag = 0"), "keri(x)" ("flag = 1") and "ker_mod_p(x,p)".
6165 matkerint"(x,{flag = 0})"
6167 gives an LLL-reduced Z-basis for the lattice equal to the kernel of the
6169 matrix "x" as columns of the matrix "x" with integer entries (rational
6170 entries are not permitted).
6171 If "flag = 0", uses a modified integer LLL algorithm.
6173 If "flag = 1", uses "matrixqz(x,-2)". If LLL reduction of the final
6175 result is not desired, you can save time using "matrixqz(matker(x),-2)"
6176 instead.
6177 If "flag = 2", uses another modified LLL. In the present version 2.2.0,
6179 only independent rows are allowed in this case.
6180 The library syntax is matkerint0"(x,flag)". Also available is
6182 "kerint(x)" ("flag = 0").
6183 matmuldiagonal"(x,d)"
6185 product of the matrix "x" by the diagonal matrix whose diagonal entries
6187 are those of the vector "d". Equivalent to, but much faster than
6188 "x*matdiagonal(d)".
6189 The library syntax is matmuldiagonal"(x,d)".
6191 matmultodiagonal"(x,y)"
6193 product of the matrices "x" and "y" knowing that the result is a diago‐
6195 nal matrix. Much faster than "x*y" in that case.
6196 The library syntax is matmultodiagonal"(x,y)".
6198 matpascal"(x,{q})"
6200 creates as a matrix the lower triangular Pascal triangle of order "x+1"
6202 (i.e. with binomial coefficients up to "x"). If "q" is given, compute
6203 the "q"-Pascal triangle (i.e. using "q"-binomial coefficients).
6204 The library syntax is matqpascal"(x,q)", where "x" is a "long" and "q =
6206 NULL" is used to omit "q". Also available is matpascal{x}.
6207 matrank"(x)"
6209 rank of the matrix "x".
6211 The library syntax is rank"(x)", and the result is a "long".
6213 matrix"(m,n,{X},{Y},{expr = 0})"
6215 creation of the "m x n" matrix whose coefficients are given by the
6217 expression expr. There are two formal parameters in expr, the first one
6218 ("X") corresponding to the rows, the second ("Y") to the columns, and
6219 "X" goes from 1 to "m", "Y" goes from 1 to "n". If one of the last 3
6220 parameters is omitted, fill the matrix with zeroes.
6221 The library syntax is matrice"(GEN nlig,GEN ncol,entree *e1,entree
6223 *e2,char *expr)".
6224 matrixqz"(x,p)"
6226 "x" being an "m x n" matrix with "m >= n" with rational or integer
6228 entries, this function has varying behaviour depending on the sign of
6229 "p":
6230 If "p >= 0", "x" is assumed to be of maximal rank. This function
6232 returns a matrix having only integral entries, having the same image as
6233 "x", such that the GCD of all its "n x n" subdeterminants is equal to 1
6234 when "p" is equal to 0, or not divisible by "p" otherwise. Here "p"
6235 must be a prime number (when it is non-zero). However, if the function
6236 is used when "p" has no small prime factors, it will either work or
6237 give the message ``impossible inverse modulo'' and a non-trivial divi‐
6238 sor of "p".
6239 If "p = -1", this function returns a matrix whose columns form a basis
6241 of the lattice equal to "Z^n" intersected with the lattice generated by
6242 the columns of "x".
6243 If "p = -2", returns a matrix whose columns form a basis of the lattice
6245 equal to "Z^n" intersected with the Q-vector space generated by the
6246 columns of "x".
6247 The library syntax is matrixqz0"(x,p)".
6249 matsize"(x)"
6251 "x" being a vector or matrix, returns a row vector with two components,
6253 the first being the number of rows (1 for a row vector), the second the
6254 number of columns (1 for a column vector).
6255 The library syntax is matsize"(x)".
6257 matsnf"(X,{flag = 0})"
6259 if "X" is a (singular or non-singular) square matrix outputs the vector
6261 of elementary divisors of "X" (i.e. the diagonal of the Smith normal
6262 form of "X").
6263 The binary digits of flag mean:
6265 1 (complete output): if set, outputs "[U,V,D]", where "U" and "V" are
6267 two unimodular matrices such that "UXV" is the diagonal matrix "D".
6268 Otherwise output only the diagonal of "D".
6269 2 (generic input): if set, allows polynomial entries. Otherwise, assume
6271 that "X" has integer coefficients.
6272 4 (cleanup): if set, cleans up the output. This means that elementary
6274 divisors equal to 1 will be deleted, i.e. outputs a shortened vector
6275 "D'" instead of "D". If complete output was required, returns
6276 "[U',V',D']" so that "U'XV' = D'" holds. If this flag is set, "X" is
6277 allowed to be of the form "D" or "[U,V,D]" as would normally be output
6278 with the cleanup flag unset.
6279 The library syntax is matsnf0"(X,flag)". Also available is "smith(X)"
6281 ("flag = 0").
6282 matsolve"(x,y)"
6284 "x" being an invertible matrix and "y" a column vector, finds the solu‐
6286 tion "u" of "x*u = y", using Gaussian elimination. This has the same
6287 effect as, but is a bit faster, than "x^{-1}*y".
6288 The library syntax is gauss"(x,y)".
6290 matsolvemod"(m,d,y,{flag = 0})"
6292 "m" being any integral matrix, "d" a vector of positive integer moduli,
6294 and "y" an integral column vector, gives a small integer solution to
6295 the system of congruences "sum_i m_{i,j}x_j = y_i (mod d_i)" if one
6296 exists, otherwise returns zero. Shorthand notation: "y" (resp. "d") can
6297 be given as a single integer, in which case all the "y_i" (resp. "d_i")
6298 above are taken to be equal to "y" (resp. "d").
6299 If "flag = 1", all solutions are returned in the form of a two-compo‐
6301 nent row vector "[x,u]", where "x" is a small integer solution to the
6302 system of congruences and "u" is a matrix whose columns give a basis of
6303 the homogeneous system (so that all solutions can be obtained by adding
6304 "x" to any linear combination of columns of "u"). If no solution
6305 exists, returns zero.
6306 The library syntax is matsolvemod0"(m,d,y,flag)". Also available are
6308 "gaussmodulo(m,d,y)" ("flag = 0") and "gaussmodulo2(m,d,y)" ("flag =
6309 1").
6310 matsupplement"(x)"
6312 assuming that the columns of the matrix "x" are linearly independent
6314 (if they are not, an error message is issued), finds a square invert‐
6315 ible matrix whose first columns are the columns of "x", i.e. supplement
6316 the columns of "x" to a basis of the whole space.
6317 The library syntax is suppl"(x)".
6319 mattranspose"(x)" or "x~"
6321 transpose of "x". This has an effect only on vectors and matrices.
6323 The library syntax is gtrans"(x)".
6325 qfgaussred"(q)"
6327 decomposition into squares of the quadratic form represented by the
6329 symmetric matrix "q". The result is a matrix whose diagonal entries are
6330 the coefficients of the squares, and the non-diagonal entries represent
6331 the bilinear forms. More precisely, if "(a_{ij})" denotes the output,
6332 one has
6333 " q(x) = sum_i a_{ii} (x_i + sum_{j > i} a_{ij} x_j)^2 "
6335 The library syntax is sqred"(x)".
6337 qfjacobi"(x)"
6339 "x" being a real symmetric matrix, this gives a vector having two com‐
6341 ponents: the first one is the vector of eigenvalues of "x", the second
6342 is the corresponding orthogonal matrix of eigenvectors of "x". The
6343 method used is Jacobi's method for symmetric matrices.
6344 The library syntax is jacobi"(x)".
6346 qflll"(x,{flag = 0})"
6348 LLL algorithm applied to the columns of the (not necessarily square)
6350 matrix "x". The columns of "x" must however be linearly independent,
6351 unless specified otherwise below. The result is a transformation matrix
6352 "T" such that "x.T" is an LLL-reduced basis of the lattice generated by
6353 the column vectors of "x".
6354 If "flag = 0" (default), the computations are done with real numbers
6356 (i.e. not with rational numbers) hence are fast but as presently pro‐
6357 grammed (version 2.2.0) are numerically unstable.
6358 If "flag = 1", it is assumed that the corresponding Gram matrix is
6360 integral. The computation is done entirely with integers and the algo‐
6361 rithm is both accurate and quite fast. In this case, "x" needs not be
6362 of maximal rank, but if it is not, "T" will not be square.
6363 If "flag = 2", similar to case 1, except "x" should be an integer
6365 matrix whose columns are linearly independent. The lattice generated by
6366 the columns of "x" is first partially reduced before applying the LLL
6367 algorithm. [A basis is said to be partially reduced if "⎪v_i +- v_j⎪ >=
6368 ⎪v_i⎪" for any two distinct basis vectors "v_i, v_j".]
6369 This can be significantly faster than "flag = 1" when one row is huge
6371 compared to the other rows.
6372 If "flag = 3", all computations are done in rational numbers. This does
6374 not incur numerical instability, but is extremely slow. This function
6375 is essentially superseded by case 1, so will soon disappear.
6376 If "flag = 4", "x" is assumed to have integral entries, but needs not
6378 be of maximal rank. The result is a two-component vector of matrices :
6379 the columns of the first matrix represent a basis of the integer kernel
6380 of "x" (not necessarily LLL-reduced) and the second matrix is the
6381 transformation matrix "T" such that "x.T" is an LLL-reduced Z-basis of
6382 the image of the matrix "x".
6383 If "flag = 5", case as case 4, but "x" may have polynomial coeffi‐
6385 cients.
6386 If "flag = 7", uses an older version of case 0 above.
6388 If "flag = 8", same as case 0, where "x" may have polynomial coeffi‐
6390 cients.
6391 If "flag = 9", variation on case 1, using content.
6393 The library syntax is qflll0"(x,flag,prec)". Also available are
6395 "lll(x,prec)" ("flag = 0"), "lllint(x)" ("flag = 1"), and "lllkerim(x)"
6396 ("flag = 4").
6397 qflllgram"(x,{flag = 0})"
6399 same as "qflll" except that the matrix "x" which must now be a square
6401 symmetric real matrix is the Gram matrix of the lattice vectors, and
6402 not the coordinates of the vectors themselves. The result is again the
6403 transformation matrix "T" which gives (as columns) the coefficients
6404 with respect to the initial basis vectors. The flags have more or less
6405 the same meaning, but some are missing. In brief:
6406 "flag = 0": numerically unstable in the present version 2.2.0.
6408 "flag = 1": "x" has integer entries, the computations are all done in
6410 integers.
6411 "flag = 4": "x" has integer entries, gives the kernel and reduced
6413 image.
6414 "flag = 5": same as 4 for generic "x".
6416 "flag = 7": an older version of case 0.
6418 The library syntax is qflllgram0"(x,flag,prec)". Also available are
6420 "lllgram(x,prec)" ("flag = 0"), "lllgramint(x)" ("flag = 1"), and "lll‐
6421 gramkerim(x)" ("flag = 4").
6422 qfminim"(x,b,m,{flag = 0})"
6424 "x" being a square and symmetric matrix representing a positive defi‐
6426 nite quadratic form, this function deals with the minimal vectors of
6427 "x", depending on "flag".
6428 If "flag = 0" (default), seeks vectors of square norm less than or
6430 equal to "b" (for the norm defined by "x"), and at most "2m" of these
6431 vectors. The result is a three-component vector, the first component
6432 being the number of vectors, the second being the maximum norm found,
6433 and the last vector is a matrix whose columns are the vectors found,
6434 only one being given for each pair "+- v" (at most "m" such pairs).
6435 If "flag = 1", ignores "m" and returns the first vector whose norm is
6437 less than "b".
6438 In both these cases, "x" is assumed to have integral entries, and the
6440 function searches for the minimal non-zero vectors whenever "b = 0".
6441 If "flag = 2", "x" can have non integral real entries, but "b = 0" is
6443 now meaningless (uses Fincke-Pohst algorithm).
6444 The library syntax is qfminim0"(x,b,m,flag,prec)", also available are "
6446 minim(x,b,m)" ("flag = 0"), " minim2(x,b,m)" ("flag = 1"), and finally
6447 " fincke_pohst(x,b,m,prec)" ("flag = 2").
6448 qfperfection"(x)"
6450 "x" being a square and symmetric matrix with integer entries represent‐
6452 ing a positive definite quadratic form, outputs the perfection rank of
6453 the form. That is, gives the rank of the family of the "s" symmetric
6454 matrices "v_iv_i^t", where "s" is half the number of minimal vectors
6455 and the "v_i" ("1 <= i <= s") are the minimal vectors.
6456 As a side note to old-timers, this used to fail bluntly when "x" had
6458 more than 5000 minimal vectors. Beware that the computations can now be
6459 very lengthy when "x" has many minimal vectors.
6460 The library syntax is perf"(x)".
6462 qfsign"(x)"
6464 signature of the quadratic form represented by the symmetric matrix
6466 "x". The result is a two-component vector.
6467 The library syntax is signat"(x)".
6469 setintersect"(x,y)"
6471 intersection of the two sets "x" and "y".
6473 The library syntax is setintersect"(x,y)".
6475 setisset"(x)"
6477 returns true (1) if "x" is a set, false (0) if not. In PARI, a set is
6479 simply a row vector whose entries are strictly increasing. To convert
6480 any vector (and other objects) into a set, use the function "Set".
6481 The library syntax is setisset"(x)", and this returns a "long".
6483 setminus"(x,y)"
6485 difference of the two sets "x" and "y", i.e. set of elements of "x"
6487 which do not belong to "y".
6488 The library syntax is setminus"(x,y)".
6490 setsearch"(x,y,{flag = 0})"
6492 searches if "y" belongs to the set "x". If it does and "flag" is zero
6494 or omitted, returns the index "j" such that "x[j] = y", otherwise
6495 returns 0. If "flag" is non-zero returns the index "j" where "y" should
6496 be inserted, and 0 if it already belongs to "x" (this is meant to be
6497 used in conjunction with "listinsert").
6498 This function works also if "x" is a sorted list (see "listsort").
6500 The library syntax is setsearch"(x,y,flag)" which returns a "long"
6502 integer.
6503 setunion"(x,y)"
6505 union of the two sets "x" and "y".
6507 The library syntax is setunion"(x,y)".
6509 trace"(x)"
6511 this applies to quite general "x". If "x" is not a matrix, it is equal
6513 to the sum of "x" and its conjugate, except for polmods where it is the
6514 trace as an algebraic number.
6515 For "x" a square matrix, it is the ordinary trace. If "x" is a non-
6517 square matrix (but not a vector), an error occurs.
6518 The library syntax is gtrace"(x)".
6520 vecextract"(x,y,{z})"
6522 extraction of components of the vector or matrix "x" according to "y".
6524 In case "x" is a matrix, its components are as usual the columns of
6525 "x". The parameter "y" is a component specifier, which is either an
6526 integer, a string describing a range, or a vector.
6527 If "y" is an integer, it is considered as a mask: the binary bits of
6529 "y" are read from right to left, but correspond to taking the compo‐
6530 nents from left to right. For example, if "y = 13 = (1101)_2" then the
6531 components 1,3 and 4 are extracted.
6532 If "y" is a vector, which must have integer entries, these entries cor‐
6534 respond to the component numbers to be extracted, in the order speci‐
6535 fied.
6536 If "y" is a string, it can be
6538 "*" a single (non-zero) index giving a component number (a negative
6540 index means we start counting from the end).
6541 "*" a range of the form "a..b", where "a" and "b" are indexes as above.
6543 Any of "a" and "b" can be omitted; in this case, we take as default
6544 values "a = 1" and "b = -1", i.e. the first and last components respec‐
6545 tively. We then extract all components in the interval "[a,b]", in
6546 reverse order if "b < a".
6547 In addition, if the first character in the string is "^", the comple‐
6549 ment of the given set of indices is taken.
6550 If "z" is not omitted, "x" must be a matrix. "y" is then the line spec‐
6552 ifier, and "z" the column specifier, where the component specifier is
6553 as explained above.
6554 ? v = [a, b, c, d, e];
6556 ? vecextract(v, 5) \\ mask
6557 %1 = [a, c]
6558 ? vecextract(v, [4, 2, 1]) \\ component list
6559 %2 = [d, b, a]
6560 ? vecextract(v, "2..4") \\ interval
6561 %3 = [b, c, d]
6562 ? vecextract(v, "-1..-3") \\ interval + reverse order
6563 %4 = [e, d, c]
6564 ? vecextract([1,2,3], "^2") \\ complement
6565 %5 = [1, 3]
6566 ? vecextract(matid(3), "2..", "..")
6567 %6 =
6568 [0 1 0]
6569 [0 0 1]
6571 The library syntax is extract"(x,y)" or "matextract(x,y,z)".
6573 vecsort"(x,{k},{flag = 0})"
6575 sorts the vector "x" in ascending order, using the heapsort method. "x"
6577 must be a vector, and its components integers, reals, or fractions.
6578 If "k" is present and is an integer, sorts according to the value of
6580 the "k"-th subcomponents of the components of "x". "k" can also be a
6581 vector, in which case the sorting is done lexicographically according
6582 to the components listed in the vector "k". For example, if "k =
6583 [2,1,3]", sorting will be done with respect to the second component,
6584 and when these are equal, with respect to the first, and when these are
6585 equal, with respect to the third.
6586 The binary digits of flag mean:
6588 "*" 1: indirect sorting of the vector "x", i.e. if "x" is an "n"-compo‐
6590 nent vector, returns a permutation of "[1,2,...,n]" which applied to
6591 the components of "x" sorts "x" in increasing order. For example,
6592 "vecextract(x, vecsort(x,,1))" is equivalent to vecsort(x).
6593 "*" 2: sorts "x" by ascending lexicographic order (as per the "lex"
6595 comparison function).
6596 "*" 4: use decreasing instead of ascending order.
6598 The library syntax is vecsort0"(x,k,flag)". To omit "k", use "NULL"
6600 instead. You can also use the simpler functions
6601 "sort(x)" ( = "vecsort0(x,NULL,0)").
6603 "indexsort(x)" ( = "vecsort0(x,NULL,1)").
6605 "lexsort(x)" ( = "vecsort0(x,NULL,2)").
6607 Also available are sindexsort and sindexlexsort which return a vector
6609 of C-long integers (private type "t_VECSMALL") "v", where "v[1]...v[n]"
6610 contain the indices. Note that the resulting "v" is not a generic PARI
6611 object, but is in general easier to use in C programs!
6612 vector"(n,{X},{expr = 0})"
6614 creates a row vector (type "t_VEC") with "n" components whose compo‐
6616 nents are the expression expr evaluated at the integer points between 1
6617 and "n". If one of the last two arguments is omitted, fill the vector
6618 with zeroes.
6619 The library syntax is vecteur"(GEN nmax, entree *ep, char *expr)".
6621 vectorv"(n,X,expr)"
6623 as vector, but returns a column vector (type "t_COL").
6625 The library syntax is vvecteur"(GEN nmax, entree *ep, char *expr)".
6627
6629 Although the GP calculator is programmable, it is useful to have pre‐
6630 programmed a number of loops, including sums, products, and a certain
6631 number of recursions. Also, a number of functions from numerical analy‐
6632 sis like numerical integration and summation of series will be
6633 described here.
6634 One of the parameters in these loops must be the control variable,
6636 hence a simple variable name. The last parameter can be any legal PARI
6637 expression, including of course expressions using loops. Since it is
6638 much easier to program directly the loops in library mode, these func‐
6639 tions are mainly useful for GP programming. The use of these functions
6640 in library mode is a little tricky and its explanation will be mostly
6641 omitted, although the reader can try and figure it out by himself by
6642 checking the example given for the "sum" function. In this section we
6643 only give the library syntax, with no semantic explanation.
6644 The letter "X" will always denote any simple variable name, and repre‐
6646 sents the formal parameter used in the function.
6647 (numerical) integration: A number of Romberg-like integration methods
6649 are implemented (see "intnum" as opposed to "intformal" which we
6650 already described). The user should not require too much accuracy: 18
6651 or 28 decimal digits is OK, but not much more. In addition, analytical
6652 cleanup of the integral must have been done: there must be no singular‐
6653 ities in the interval or at the boundaries. In practice this can be
6654 accomplished with a simple change of variable. Furthermore, for
6655 improper integrals, where one or both of the limits of integration are
6656 plus or minus infinity, the function must decrease sufficiently rapidly
6657 at infinity. This can often be accomplished through integration by
6658 parts. Finally, the function to be integrated should not be very small
6659 (compared to the current precision) on the entire interval. This can of
6660 course be accomplished by just multiplying by an appropriate constant.
6661 Note that infinity can be represented with essentially no loss of accu‐
6663 racy by 1e4000. However beware of real underflow when dealing with
6664 rapidly decreasing functions. For example, if one wants to compute the
6665 "int_0^ oo e^{-x^2}dx" to 28 decimal digits, then one should set infin‐
6666 ity equal to 10 for example, and certainly not to 1e4000.
6667 The integrand may have values belonging to a vector space over the real
6669 numbers; in particular, it can be complex-valued or vector-valued.
6670 See also the discrete summation methods below (sharing the prefix
6672 "sum").
6673 intnum"(X = a,b,expr,{flag = 0})"
6675 numerical integration of expr (smooth in "]a,b["), with respect to "X".
6677 Set "flag = 0" (or omit it altogether) when "a" and "b" are not too
6679 large, the function is smooth, and can be evaluated exactly everywhere
6680 on the interval "[a,b]".
6681 If "flag = 1", uses a general driver routine for doing numerical inte‐
6683 gration, making no particular assumption (slow).
6684 "flag = 2" is tailored for being used when "a" or "b" are infinite. One
6686 must have "ab > 0", and in fact if for example "b = + oo ", then it is
6687 preferable to have "a" as large as possible, at least "a >= 1".
6688 If "flag = 3", the function is allowed to be undefined (but continuous)
6690 at "a" or "b", for example the function " sin (x)/x" at "x = 0".
6691 The library syntax is intnum0"(entree*e,GEN a,GEN b,char*expr,long
6693 flag,long prec)".
6694 prod"(X = a,b,expr,{x = 1})"
6696 product of expression expr, initialized at "x", the formal parameter
6698 "X" going from "a" to "b". As for "sum", the main purpose of the ini‐
6699 tialization parameter "x" is to force the type of the operations being
6700 performed. For example if it is set equal to the integer 1, operations
6701 will start being done exactly. If it is set equal to the real 1., they
6702 will be done using real numbers having the default precision. If it is
6703 set equal to the power series "1+O(X^k)" for a certain "k", they will
6704 be done using power series of precision at most "k". These are the
6705 three most common initializations.
6706 As an extreme example, compare
6708 ? prod(i=1, 100, 1 - X^i); \\ this has degree 5050 !!
6710 time = 3,335 ms.
6711 ? prod(i=1, 100, 1 - X^i, 1 + O(X^101))
6712 time = 43 ms.
6713 %2 = 1 - X - X^2 + X^5 + X^7 - X^12 - X^15 + X^22 + X^26 - X^35 - X^40 + \
6714 X^51 + X^57 - X^70 - X^77 + X^92 + X^100 + O(X^101)
6715 The library syntax is produit"(entree *ep, GEN a, GEN b, char *expr,
6717 GEN x)".
6718 prodeuler"(X = a,b,expr)"
6720 product of expression expr, initialized at 1. (i.e. to a real number
6722 equal to 1 to the current "realprecision"), the formal parameter "X"
6723 ranging over the prime numbers between "a" and "b".
6724 The library syntax is prodeuler"(entree *ep, GEN a, GEN b, char *expr,
6726 long prec)".
6727 prodinf"(X = a,expr,{flag = 0})"
6729 infinite product of expression expr, the formal parameter "X" starting
6731 at "a". The evaluation stops when the relative error of the expression
6732 minus 1 is less than the default precision. The expressions must always
6733 evaluate to an element of C.
6734 If "flag = 1", do the product of the ("1+expr") instead.
6736 The library syntax is prodinf"(entree *ep, GEN a, char *expr, long
6738 prec)" ("flag = 0"), or prodinf1 with the same arguments ("flag = 1").
6739 solve"(X = a,b,expr)"
6741 find a real root of expression expr between "a" and "b", under the con‐
6743 dition "expr(X = a) * expr(X = b) <= 0". This routine uses Brent's
6744 method and can fail miserably if expr is not defined in the whole of
6745 "[a,b]" (try "solve(x = 1, 2, tan(x)").
6746 The library syntax is zbrent"(entree *ep, GEN a, GEN b, char *expr,
6748 long prec)".
6749 sum"(X = a,b,expr,{x = 0})"
6751 sum of expression expr, initialized at "x", the formal parameter going
6753 from "a" to "b". As for "prod", the initialization parameter "x" may be
6754 given to force the type of the operations being performed.
6755 As an extreme example, compare
6757 ? sum(i=1, 5000, 1/i); \\ rational number: denominator has 2166 digits.
6759 time = 1,241 ms.
6760 ? sum(i=1, 5000, 1/i, 0.)
6761 time = 158 ms.
6762 %2 = 9.094508852984436967261245533
6763 The library syntax is somme"(entree *ep, GEN a, GEN b, char *expr, GEN
6765 x)". This is to be used as follows: "ep" represents the dummy variable
6766 used in the expression "expr"
6767 /* compute a^2 + ... + b^2 */
6769 {
6770 /* define the dummy variable "i" */
6771 entree *ep = is_entry("i");
6772 /* sum for a <= i <= b */
6773 return somme(ep, a, b, "i^2", gzero);
6774 }
6775 sumalt"(X = a,expr,{flag = 0})"
6777 numerical summation of the series expr, which should be an alternating
6779 series, the formal variable "X" starting at "a".
6780 If "flag = 0", use an algorithm of F. Villegas as modified by
6782 D. Zagier. This is much better than Euler-Van Wijngaarden's method
6783 which was used formerly. Beware that the stopping criterion is that
6784 the term gets small enough, hence terms which are equal to 0 will cre‐
6785 ate problems and should be removed.
6786 If "flag = 1", use a variant with slightly different polynomials. Some‐
6788 times faster.
6789 Divergent alternating series can sometimes be summed by this method, as
6791 well as series which are not exactly alternating (see for example
6792 "Label se:user_defined").
6793 Important hint: a significant speed gain can be obtained by writing the
6795 "(-1)^X" which may occur in the expression as "(1. - X%2*2)".
6796 The library syntax is sumalt"(entree *ep, GEN a, char *expr, long flag,
6798 long prec)".
6799 sumdiv"(n,X,expr)"
6801 sum of expression expr over the positive divisors of "n".
6803 Arithmetic functions like sigma use the multiplicativity of the under‐
6805 lying expression to speed up the computation. In the present version
6806 2.2.0, there is no way to indicate that expr is multiplicative in "n",
6807 hence specialized functions should be prefered whenever possible.
6808 The library syntax is divsum"(entree *ep, GEN num, char *expr)".
6810 suminf"(X = a,expr)"
6812 infinite sum of expression expr, the formal parameter "X" starting at
6814 "a". The evaluation stops when the relative error of the expression is
6815 less than the default precision. The expressions must always evaluate
6816 to a complex number.
6817 The library syntax is suminf"(entree *ep, GEN a, char *expr, long
6819 prec)".
6820 sumpos"(X = a,expr,{flag = 0})"
6822 numerical summation of the series expr, which must be a series of terms
6824 having the same sign, the formal variable "X" starting at "a". The
6825 algorithm used is Van Wijngaarden's trick for converting such a series
6826 into an alternating one, and is quite slow. Beware that the stopping
6827 criterion is that the term gets small enough, hence terms which are
6828 equal to 0 will create problems and should be removed.
6829 If "flag = 1", use slightly different polynomials. Sometimes faster.
6831 The library syntax is sumpos"(entree *ep, GEN a, char *expr, long flag,
6833 long prec)".
6834
6836 Although plotting is not even a side purpose of PARI, a number of plot‐
6837 ting functions are provided. Moreover, a lot of people felt like sug‐
6838 gesting ideas or submitting huge patches for this section of the code.
6839 Among these, special thanks go to Klaus-Peter Nischke who suggested the
6840 recursive plotting and the forking/resizing stuff under X11, and Ilya
6841 Zakharevich who undertook a complete rewrite of the graphic code, so
6842 that most of it is now platform-independent and should be relatively
6843 easy to port or expand.
6844 These graphic functions are either
6846 "*" high-level plotting functions (all the functions starting with
6848 "ploth") in which the user has little to do but explain what type of
6849 plot he wants, and whose syntax is similar to the one used in the pre‐
6850 ceding section (with somewhat more complicated flags).
6851 "*" low-level plotting functions, where every drawing primitive (point,
6853 line, box, etc.) must be specified by the user. These low-level func‐
6854 tions (called rectplot functions, sharing the prefix "plot") work as
6855 follows. You have at your disposal 16 virtual windows which are filled
6856 independently, and can then be physically ORed on a single window at
6857 user-defined positions. These windows are numbered from 0 to 15, and
6858 must be initialized before being used by the function "plotinit", which
6859 specifies the height and width of the virtual window (called a rectwin‐
6860 dow in the sequel). At all times, a virtual cursor (initialized at
6861 "[0,0]") is associated to the window, and its current value can be
6862 obtained using the function "plotcursor".
6863 A number of primitive graphic objects (called rect objects) can then be
6865 drawn in these windows, using a default color associated to that window
6866 (which can be changed under X11, using the "plotcolor" function, black
6867 otherwise) and only the part of the object which is inside the window
6868 will be drawn, with the exception of polygons and strings which are
6869 drawn entirely (but the virtual cursor can move outside of the window).
6870 The ones sharing the prefix "plotr" draw relatively to the current
6871 position of the virtual cursor, the others use absolute coordinates.
6872 Those having the prefix "plotrecth" put in the rectwindow a large batch
6873 of rect objects corresponding to the output of the related "ploth"
6874 function.
6875 Finally, the actual physical drawing is done using the function "plot‐
6877 draw". Note that the windows are preserved so that further drawings
6878 using the same windows at different positions or different windows can
6879 be done without extra work. If you want to erase a window (and free the
6880 corresponding memory), use the function "plotkill". It is not possible
6881 to partially erase a window. Erase it completely, initialize it again
6882 and then fill it with the graphic objects that you want to keep.
6883 In addition to initializing the window, you may want to have a scaled
6885 window to avoid unnecessary conversions. For this, use the function
6886 "plotscale" below. As long as this function is not called, the scaling
6887 is simply the number of pixels, the origin being at the upper left and
6888 the "y"-coordinates going downwards.
6889 Note that in the present version 2.2.0 all these plotting functions
6891 (both low and high level) have been written for the X11-window system
6892 (hence also for GUI's based on X11 such as Openwindows and Motif) only,
6893 though very little code remains which is actually platform-dependent. A
6894 Suntools/Sunview, Macintosh, and an Atari/Gem port were provided for
6895 previous versions. These may be adapted in future releases.
6896 Under X11/Suntools, the physical window (opened by "plotdraw" or any of
6898 the "ploth*" functions) is completely separated from GP (technically, a
6899 "fork" is done, and the non-graphical memory is immediately freed in
6900 the child process), which means you can go on working in the current GP
6901 session, without having to kill the window first. Under X11, this win‐
6902 dow can be closed, enlarged or reduced using the standard window man‐
6903 ager functions. No zooming procedure is implemented though (yet).
6904 "*" Finally, note that in the same way that "printtex" allows you to
6906 have a TeX output corresponding to printed results, the functions
6907 starting with "ps" allow you to have "PostScript" output of the plots.
6908 This will not be absolutely identical with the screen output, but will
6909 be sufficiently close. Note that you can use PostScript output even if
6910 you do not have the plotting routines enabled. The PostScript output is
6911 written in a file whose name is derived from the "psfile" default
6912 ("./pari.ps" if you did not tamper with it). Each time a new PostScript
6913 output is asked for, the PostScript output is appended to that file.
6914 Hence the user must remove this file, or change the value of "psfile",
6915 first if he does not want unnecessary drawings from preceding sessions
6916 to appear. On the other hand, in this manner as many plots as desired
6917 can be kept in a single file.
6918 None of the graphic functions are available within the PARI library,
6920 you must be under GP to use them. The reason for that is that you
6921 really should not use PARI for heavy-duty graphical work, there are
6922 much better specialized alternatives around. This whole set of routines
6923 was only meant as a convenient, but simple-minded, visual aid. If you
6924 really insist on using these in your program (we warned you), the
6925 source ("plot*.c") should be readable enough for you to achieve some‐
6926 thing.
6927 plot"(X = a,b,expr,{Ymin},{Ymax})"
6929 crude (ASCII) plot of the function represented by expression expr from
6931 "a" to "b", with Y ranging from Ymin to Ymax. If Ymin (resp. Ymax) is
6932 not given, the minima (resp. the maxima) of the computed values of the
6933 expression is used instead.
6934 plotbox"(w,x2,y2)"
6936 let "(x1,y1)" be the current position of the virtual cursor. Draw in
6938 the rectwindow "w" the outline of the rectangle which is such that the
6939 points "(x1,y1)" and "(x2,y2)" are opposite corners. Only the part of
6940 the rectangle which is in "w" is drawn. The virtual cursor does not
6941 move.
6942 plotclip"(w)"
6944 `clips' the content of rectwindow "w", i.e remove all parts of the
6946 drawing that would not be visible on the screen. Together with "plot‐
6947 copy" this function enables you to draw on a scratchpad before commit‐
6948 ing the part you're interested in to the final picture.
6949 plotcolor"(w,c)"
6951 set default color to "c" in rectwindow "w". In present version 2.2.0,
6953 this is only implemented for X11 window system, and you only have the
6954 following palette to choose from:
6955 1 = black, 2 = blue, 3 = sienna, 4 = red, 5 = cornsilk, 6 = grey, 7 =
6957 gainsborough.
6958 Note that it should be fairly easy for you to hardwire some more colors
6960 by tweaking the files "rect.h" and "plotX.c". User-defined colormaps
6961 would be nice, and may be available in future versions.
6962 plotcopy"(w1,w2,dx,dy)"
6964 copy the contents of rectwindow "w1" to rectwindow "w2", with offset
6966 "(dx,dy)".
6967 plotcursor"(w)"
6969 give as a 2-component vector the current (scaled) position of the vir‐
6971 tual cursor corresponding to the rectwindow "w".
6972 plotdraw"(list)"
6974 physically draw the rectwindows given in "list" which must be a vector
6976 whose number of components is divisible by 3. If "list =
6977 [w1,x1,y1,w2,x2,y2,...]", the windows "w1", "w2", etc. are physically
6978 placed with their upper left corner at physical position "(x1,y1)",
6979 "(x2,y2)",...respectively, and are then drawn together. Overlapping
6980 regions will thus be drawn twice, and the windows are considered trans‐
6981 parent. Then display the whole drawing in a special window on your
6982 screen.
6983 plotfile"(s)"
6985 set the output file for plotting output. Special filename "-" redirects
6987 to the same place as PARI output.
6988 ploth"(X = a,b,expr,{flag = 0},{n = 0})"
6990 high precision plot of the function "y = f(x)" represented by the
6992 expression expr, "x" going from "a" to "b". This opens a specific win‐
6993 dow (which is killed whenever you click on it), and returns a four-com‐
6994 ponent vector giving the coordinates of the bounding box in the form
6995 "[xmin,xmax,ymin,ymax]".
6996 Important note: Since this may involve a lot of function calls, it is
6998 advised to keep the current precision to a minimum (e.g. 9) before
6999 calling this function.
7000 "n" specifies the number of reference point on the graph (0 means use
7002 the hardwired default values, that is: 1000 for general plot, 1500 for
7003 parametric plot, and 15 for recursive plot).
7004 If no "flag" is given, expr is either a scalar expression f(X), in
7006 which case the plane curve "y = f(X)" will be drawn, or a vector
7007 "[f_1(X),...,f_k(X)]", and then all the curves "y = f_i(X)" will be
7008 drawn in the same window.
7009 The binary digits of "flag" mean:
7011 "*" 1: parametric plot. Here expr must be a vector with an even number
7013 of components. Successive pairs are then understood as the parametric
7014 coordinates of a plane curve. Each of these are then drawn.
7015 For instance:
7017 "ploth(X = 0,2*Pi,[sin(X),cos(X)],1)" will draw a circle.
7019 "ploth(X = 0,2*Pi,[sin(X),cos(X)])" will draw two entwined sinusoidal
7021 curves.
7022 "ploth(X = 0,2*Pi,[X,X,sin(X),cos(X)],1)" will draw a circle and the
7024 line "y = x".
7025 "*" 2: recursive plot. If this flag is set, only one curve can be drawn
7027 at time, i.e. expr must be either a two-component vector (for a single
7028 parametric curve, and the parametric flag has to be set), or a scalar
7029 function. The idea is to choose pairs of successive reference points,
7030 and if their middle point is not too far away from the segment joining
7031 them, draw this as a local approximation to the curve. Otherwise, add
7032 the middle point to the reference points. This is very fast, and usu‐
7033 ally more precise than usual plot. Compare the results of
7034 "ploth(X = -1,1,sin(1/X),2) and ploth(X = -1,1,sin(1/X))"
7036 for instance. But beware that if you are extremely unlucky, or choose
7038 too few reference points, you may draw some nice polygon bearing little
7039 resemblance to the original curve. For instance you should never plot
7040 recursively an odd function in a symmetric interval around 0. Try
7041 ploth(x = -20, 20, sin(x), 2)
7043 to see why. Hence, it's usually a good idea to try and plot the same
7045 curve with slightly different parameters.
7046 The other values toggle various display options:
7048 "*" 4: do not rescale plot according to the computed extrema. This is
7050 meant to be used when graphing multiple functions on a rectwindow (as a
7051 "plotrecth" call), in conjuction with "plotscale".
7052 "*" 8: do not print the "x"-axis.
7054 "*" 16: do not print the "y"-axis.
7056 "*" 32: do not print frame.
7058 "*" 64: only plot reference points, do not join them.
7060 "*" 256: use splines to interpolate the points.
7062 "*" 512: plot no "x"-ticks.
7064 "*" 1024: plot no "y"-ticks.
7066 "*" 2048: plot all ticks with the same length.
7068 plothraw"(listx,listy,{flag = 0})"
7070 given listx and listy two vectors of equal length, plots (in high pre‐
7072 cision) the points whose "(x,y)"-coordinates are given in listx and
7073 listy. Automatic positioning and scaling is done, but with the same
7074 scaling factor on "x" and "y". If "flag" is 1, join points, other non-0
7075 flags toggle display options and should be combinations of bits "2^k",
7076 "k
7077 >= 3" as in "ploth".
7078 plothsizes"()"
7080 return data corresponding to the output window in the form of a 6-com‐
7082 ponent vector: window width and height, sizes for ticks in horizontal
7083 and vertical directions (this is intended for the "gnuplot" interface
7084 and is currently not significant), width and height of characters.
7085 plotinit"(w,x,y)"
7087 initialize the rectwindow "w" to width "x" and height "y", and position
7089 the virtual cursor at "(0,0)". This destroys any rect objects you may
7090 have already drawn in "w".
7091 The plotting device imposes an upper bound for "x" and "y", for
7093 instance the number of pixels for screen output. These bounds are
7094 available through the "plothsizes" function. The following sequence
7095 initializes in a portable way (i.e independant of the output device) a
7096 window of maximal size, accessed through coordinates in the "[0,1000]
7097 x [0,1000]" range :
7098 s = plothsizes();
7100 plotinit(0, s[1]-1, s[2]-1);
7101 plotscale(0, 0,1000, 0,1000);
7102 plotkill"(w)"
7104 erase rectwindow "w" and free the corresponding memory. Note that if
7106 you want to use the rectwindow "w" again, you have to use "initrect"
7107 first to specify the new size. So it's better in this case to use "ini‐
7108 trect" directly as this throws away any previous work in the given
7109 rectwindow.
7110 plotlines"(w,X,Y,{flag = 0})"
7112 draw on the rectwindow "w" the polygon such that the (x,y)-coordinates
7114 of the vertices are in the vectors of equal length "X" and "Y". For
7115 simplicity, the whole polygon is drawn, not only the part of the poly‐
7116 gon which is inside the rectwindow. If "flag" is non-zero, close the
7117 polygon. In any case, the virtual cursor does not move.
7118 "X" and "Y" are allowed to be scalars (in this case, both have to).
7120 There, a single segment will be drawn, between the virtual cursor cur‐
7121 rent position and the point "(X,Y)". And only the part thereof which
7122 actually lies within the boundary of "w". Then move the virtual cursor
7123 to "(X,Y)", even if it is outside the window. If you want to draw a
7124 line from "(x1,y1)" to "(x2,y2)" where "(x1,y1)" is not necessarily the
7125 position of the virtual cursor, use "plotmove(w,x1,y1)" before using
7126 this function.
7127 plotlinetype"(w,type)"
7129 change the type of lines subsequently plotted in rectwindow "w". type
7131 "-2" corresponds to frames, "-1" to axes, larger values may correspond
7132 to something else. "w = -1" changes highlevel plotting. This is only
7133 taken into account by the "gnuplot" interface.
7134 plotmove"(w,x,y)"
7136 move the virtual cursor of the rectwindow "w" to position "(x,y)".
7138 plotpoints"(w,X,Y)"
7140 draw on the rectwindow "w" the points whose "(x,y)"-coordinates are in
7142 the vectors of equal length "X" and "Y" and which are inside "w". The
7143 virtual cursor does not move. This is basically the same function as
7144 "plothraw", but either with no scaling factor or with a scale chosen
7145 using the function "plotscale".
7146 As was the case with the "plotlines" function, "X" and "Y" are allowed
7148 to be (simultaneously) scalar. In this case, draw the single point
7149 "(X,Y)" on the rectwindow "w" (if it is actually inside "w"), and in
7150 any case move the virtual cursor to position "(x,y)".
7151 plotpointsize"(w,size)"
7153 changes the ``size'' of following points in rectwindow "w". If "w =
7155 -1", change it in all rectwindows. This only works in the "gnuplot"
7156 interface.
7157 plotpointtype"(w,type)"
7159 change the type of points subsequently plotted in rectwindow "w". "type
7161 = -1" corresponds to a dot, larger values may correspond to something
7162 else. "w = -1" changes highlevel plotting. This is only taken into
7163 account by the "gnuplot" interface.
7164 plotrbox"(w,dx,dy)"
7166 draw in the rectwindow "w" the outline of the rectangle which is such
7168 that the points "(x1,y1)" and "(x1+dx,y1+dy)" are opposite corners,
7169 where "(x1,y1)" is the current position of the cursor. Only the part
7170 of the rectangle which is in "w" is drawn. The virtual cursor does not
7171 move.
7172 plotrecth"(w,X = a,b,expr,{flag = 0},{n = 0})"
7174 writes to rectwindow "w" the curve output of "ploth""(w,X =
7176 a,b,expr,flag,n)".
7177 plotrecthraw"(w,data,{flag = 0})"
7179 plot graph(s) for data in rectwindow "w". "flag" has the same signifi‐
7181 cance here as in "ploth", though recursive plot is no more significant.
7182 data is a vector of vectors, each corresponding to a list a coordi‐
7184 nates. If parametric plot is set, there must be an even number of vec‐
7185 tors, each successive pair corresponding to a curve. Otherwise, the
7186 first one containe the "x" coordinates, and the other ones contain the
7187 "y"-coordinates of curves to plot.
7188 plotrline"(w,dx,dy)"
7190 draw in the rectwindow "w" the part of the segment
7192 "(x1,y1)-(x1+dx,y1+dy)" which is inside "w", where "(x1,y1)" is the
7193 current position of the virtual cursor, and move the virtual cursor to
7194 "(x1+dx,y1+dy)" (even if it is outside the window).
7195 plotrmove"(w,dx,dy)"
7197 move the virtual cursor of the rectwindow "w" to position
7199 "(x1+dx,y1+dy)", where "(x1,y1)" is the initial position of the cursor
7200 (i.e. to position "(dx,dy)" relative to the initial cursor).
7201 plotrpoint"(w,dx,dy)"
7203 draw the point "(x1+dx,y1+dy)" on the rectwindow "w" (if it is inside
7205 "w"), where "(x1,y1)" is the current position of the cursor, and in any
7206 case move the virtual cursor to position "(x1+dx,y1+dy)".
7207 plotscale"(w,x1,x2,y1,y2)"
7209 scale the local coordinates of the rectwindow "w" so that "x" goes from
7211 "x1" to "x2" and "y" goes from "y1" to "y2" ("x2 < x1" and "y2 < y1"
7212 being allowed). Initially, after the initialization of the rectwindow
7213 "w" using the function "plotinit", the default scaling is the graphic
7214 pixel count, and in particular the "y" axis is oriented downwards since
7215 the origin is at the upper left. The function "plotscale" allows to
7216 change all these defaults and should be used whenever functions are
7217 graphed.
7218 plotstring"(w,x,{flag = 0})"
7220 draw on the rectwindow "w" the String "x" (see "Label se:strings"), at
7222 the current position of the cursor.
7223 flag is used for justification: bits 1 and 2 regulate horizontal align‐
7225 ment: left if 0, right if 2, center if 1. Bits 4 and 8 regulate verti‐
7226 cal alignment: bottom if 0, top if 8, v-center if 4. Can insert addi‐
7227 tional small gap between point and string: horizontal if bit 16 is set,
7228 vertical if bit 32 is set (see the tutorial for an example).
7229 plotterm"(term)"
7231 sets terminal where high resolution plots go (this is currently only
7233 taken into account by the "gnuplot" graphical driver). Using the "gnu‐
7234 plot" driver, possible terminals are the same as in gnuplot. If term is
7235 "?", lists possible values.
7236 Terminal options can be appended to the terminal name and space; termi‐
7238 nal size can be put immediately after the name, as in "gif = 300,200".
7239 Positive return value means success.
7240 psdraw"(list)"
7242 same as "plotdraw", except that the output is a PostScript program
7244 appended to the "psfile".
7245 psploth"(X = a,b,expr)"
7247 same as "ploth", except that the output is a PostScript program
7249 appended to the "psfile".
7250 psplothraw"(listx,listy)"
7252 same as "plothraw", except that the output is a PostScript program
7254 appended to the "psfile".
7255
7257 =head2 Control statements.
7258 A number of control statements are available under GP. They are simpler
7260 and have a syntax slightly different from their C counterparts, but are
7261 quite powerful enough to write any kind of program. Some of them are
7262 specific to GP, since they are made for number theorists. As usual, "X"
7263 will denote any simple variable name, and seq will always denote a
7264 sequence of expressions, including the empty sequence.
7265break"({n = 1})"
7267interrupts execution of current seq, and immediately exits from the "n" inner‐
7268most enclosing loops, within the current function call (or the top level
7269loop). "n" must be bigger than 1. If "n" is greater than the number of
7270enclosing loops, all enclosing loops are exited.
7271for"(X = a,b,seq)"
7273the formal variable "X" going from "a" to "b", the seq is evaluated. Nothing
7274is done if "a > b". "a" and "b" must be in R.
7275fordiv"(n,X,seq)"
7277the formal variable "X" ranging through the positive divisors of "n", the
7278sequence seq is evaluated. "n" must be of type integer.
7279forprime"(X = a,b,seq)"
7281the formal variable "X" ranging over the prime numbers between "a" to "b"
7282(including "a" and "b" if they are prime), the seq is evaluated. More pre‐
7283cisely, the value of "X" is incremented to the smallest prime strictly larger
7284than "X" at the end of each iteration. Nothing is done if "a > b". Note that
7285"a" and "b" must be in R.
7286 ? { forprime(p = 2, 12,
7288 print(p);
7289 if (p == 3, p = 6);
7290 )
7291 }
7292 2
7293 3
7294 7
7295 11
7296forstep"(X = a,b,s,seq)"
7298the formal variable "X" going from "a" to "b", in increments of "s", the seq
7299is evaluated. Nothing is done if "s > 0" and "a > b" or if "s < 0" and "a <
7300b". "s" must be in "R^*" or a vector of steps "[s_1,...,s_n]". In the latter
7301case, the successive steps are used in the order they appear in "s".
7302 ? forstep(x=5, 20, [2,4], print(x))
7304 5
7305 7
7306 11
7307 13
7308 17
7309 19
7310forsubgroup"(H = G,{B},seq)"
7312executes seq for each subgroup "H" of the abelian group "G" (given in SNF form
7313or as a vector of elementary divisors), whose index is bounded by bound. The
7314subgroups are not ordered in any obvious way, unless "G" is a "p"-group in
7315which case Birkhoff's algorithm produces them by decreasing index. A subgroup
7316is given as a matrix whose columns give its generators on the implicit genera‐
7317tors of "G". For example, the following prints all subgroups of index less
7318than 2 in "G = Z/2Z g_1 x Z/2Z g_2" :
7319 ? G = [2,2]; forsubgroup(H=G, 2, print(H))
7321 [1; 1]
7322 [1; 2]
7323 [2; 1]
7324 [1, 0; 1, 1]
7325The last one, for instance is generated by "(g_1, g_1 + g_2)". This routine is
7327intended to treat huge groups, when subgrouplist is not an option due to the
7328sheer size of the output.
7329For maximal speed the subgroups have been left as produced by the algorithm.
7331To print them in canonical form (as left divisors of "G" in HNF form), one can
7332for instance use
7333 ? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H))))
7335 [2, 1; 0, 1]
7336 [1, 0; 0, 2]
7337 [2, 0; 0, 1]
7338 [1, 0; 0, 1]
7339Note that in this last representation, the index "[G:H]" is given by the
7341determinant.
7342forvec"(X = v,seq,{flag = 0})"
7344"v" being an "n"-component vector (where "n" is arbitrary) of two-component
7345vectors "[a_i,b_i]" for "1 <= i <= n", the seq is evaluated with the formal
7346variable "X[1]" going from "a_1" to "b_1",...,"X[n]" going from "a_n" to
7347"b_n". The formal variable with the highest index moves the fastest. If "flag
7349only strictly increasing vectors "X".
7350if"(a,{seq1},{seq2})"
7352if "a" is non-zero, the expression sequence seq1 is evaluated, otherwise the
7353expression seq2 is evaluated. Of course, seq1 or seq2 may be empty, so "if
7354(a,seq)" evaluates seq if "a" is not equal to zero (you don't have to write
7355the second comma), and does nothing otherwise, whereas "if (a,,seq)" evaluates
7357same result using the "!" ("not") operator: "if (!a,seq)".
7358Note that the boolean operators "&&" and "⎪⎪" are evaluated according to oper‐
7360ator precedence as explained in "Label se:operators", but that, contrary to
7361other operators, the evaluation of the arguments is stopped as soon as the
7362final truth value has been determined. For instance
7363 if (reallydoit && longcomplicatedfunction(), ...)%
7365is a perfectly safe statement.
7367Recall that functions such as "break" and "next" operate on loops (such as
7369"forxxx", "while", "until"). The "if" statement is not a loop (obviously!).
7370next"({n = 1})"
7372interrupts execution of current "seq", resume the next iteration of the inner‐
7373most enclosing loop, within the current fonction call (or top level loop). If
7374"n" is specified, resume at the "n"-th enclosing loop. If "n" is bigger than
7375the number of enclosing loops, all enclosing loops are exited.
7376return"({x = 0})"
7378returns from current subroutine, with result "x".
7379until"(a,seq)"
7381evaluates expression sequence seq until "a" is not equal to 0 (i.e. until "a"
7382is true). If "a" is initially not equal to 0, seq is evaluated once (more gen‐
7383erally, the condition on "a" is tested after execution of the seq, not before
7384as in "while").
7385while"(a,seq)"
7387while "a" is non-zero evaluate the expression sequence seq. The test is made
7389zero the seq will not be evaluated at all.
7390
7392In addition to the general PARI functions, it is necessary to have some func‐
7394tions which will be of use specifically for GP, though a few of these can be
7395accessed under library mode. Before we start describing these, we recall the
7396difference between strings and keywords (see "Label se:strings"): the latter
7397don't get expanded at all, and you can type them without any enclosing quotes.
7398The former are dynamic objects, where everything outside quotes gets immedi‐
7399ately expanded.
7400We need an additional notation for this chapter. An argument between braces,
7402followed by a star, like "{str}*", means that any number of such arguments
7403(possibly none) can be given.
7404addhelp"(S,str)"
7406 changes the help message for the symbol "S". The string str is expanded on
7407the spot and stored as the online help for "S". If "S" is a function you have
7408defined, its definition will still be printed before the message str. It is
7409recommended that you document global variables and user functions in this way.
7410Of course GP won't protest if you don't do it.
7411There's nothing to prevent you from modifying the help of built-in PARI func‐
7413tions (but if you do, we'd like to hear why you needed to do it!).
7414alias"(newkey,key)"
7416defines the keyword newkey as an alias for keyword key. key must correspond to
7417an existing function name. This is different from the general user macros in
7418that alias expansion takes place immediately upon execution, without having to
7419look up any function code, and is thus much faster. A sample alias file
7420"misc/gpalias" is provided with the standard distribution. Alias commands are
7421meant to be read upon startup from the ".gprc" file, to cope with function
7422names you are dissatisfied with, and should be useless in interactive usage.
7423allocatemem"({x = 0})"
7425this is a very special operation which allows the user to change the stack
7426size after initialization. "x" must be a non-negative integer. If "x! = 0", a
7427new stack of size "16*\lceil x/16\rceil" bytes will be allocated, all the PARI
7428data on the old stack will be moved to the new one, and the old stack will be
7429discarded. If "x = 0", the size of the new stack will be twice the size of the
7430old one.
7431Although it is a function, this must be the last instruction in any GP
7433sequence. The technical reason is that this routine usually moves the stack,
7434so objects from the current sequence might not be correct anymore. Hence, to
7435prevent such problems, this routine terminates by a "longjmp" (just as an
7436error would) and not by a return.
7437The library syntax is allocatemoremem"(x)", where "x" is an unsigned long, and
7439the return type is void. GP uses a variant which ends by a "longjmp".
7440default"({key},{val},{flag})"
7442sets the default corresponding to keyword key to value val. val is a string
7443(which of course accepts numeric arguments without adverse effects, due to the
7444expansion mechanism). See "Label se:defaults" for a list of available
7445defaults, and "Label se:meta" for some shortcut alternatives. Typing
7446"default()" (or "\d") yields the complete default list as well as their cur‐
7447rent values.
7448If val is omitted, prints the current value of default key. If "flag" is set,
7450returns the result instead of printing it.
7451error"({str}*)"
7453outputs its argument list (each of them interpreted as a string), then inter‐
7454rupts the running GP program, returning to the input prompt.
7455Example: "error("n = ", n, " is not squarefree !")".
7457Note that, due to the automatic concatenation of strings, you could in fact
7459use only one argument, just by suppressing the commas.
7460extern"(str)"
7462the string str is the name of an external command (i.e. one you would type
7463from your UNIX shell prompt). This command is immediately run and its input
7464fed into GP, just as if read from a file.
7465getheap"()"
7467returns a two-component row vector giving the number of objects on the heap
7468and the amount of memory they occupy in long words. Useful mainly for debug‐
7469ging purposes.
7470The library syntax is getheap"()".
7472getrand"()"
7474returns the current value of the random number seed. Useful mainly for debug‐
7475ging purposes.
7476The library syntax is getrand"()", returns a C long.
7478getstack"()"
7480returns the current value of "top-avma", i.e. the number of bytes used up to
7481now on the stack. Should be equal to 0 in between commands. Useful mainly for
7482debugging purposes.
7483The library syntax is getstack"()", returns a C long.
7485gettime"()"
7487returns the time (in milliseconds) elapsed since either the last call to "get‐
7488time", or to the beginning of the containing GP instruction (if inside GP),
7489whichever came last.
7490The library syntax is gettime"()", returns a C long.
7492global"({list of variables})"
7494declares the corresponding variables to be global. From now on, you will be
7496forbidden to use them as formal parameters for function definitions or as loop
7497indexes. This is especially useful when patching together various scripts,
7498possibly written with different naming conventions. For instance the following
7499situation is dangerous:
7500 p = 3 \\ fix characteristic
7502 ...
7503 forprime(p = 2, N, ...)
7504 f(p) = ...
7505since within the loop or within the function's body (even worse: in the sub‐
7507routines called in that scope), the true global value of "p" will be hidden.
7508If the statement "global(p = 3)" appears at the beginning of the script, then
7509both expressions will trigger syntax errors.
7510Calling "global" without arguments prints the list of global variables in use.
7512In particular, "eval(global)" will output the values of all local variables.
7513input"()"
7515reads a string, interpreted as a GP expression, from the input file, usually
7516standard input (i.e. the keyboard). If a sequence of expressions is given, the
7517result is the result of the last expression of the sequence. When using this
7518instruction, it is useful to prompt for the string by using the "print1" func‐
7519tion. Note that in the present version 2.19 of "pari.el", when using GP under
7520GNU Emacs (see "Label se:emacs") one must prompt for the string, with a string
7521which ends with the same prompt as any of the previous ones (a "? " will do
7522for instance).
7523install"(name,code,{gpname},{lib})"
7525loads from dynamic library lib the function name. Assigns to it the name
7527face" for an explanation of those). If lib is omitted, uses "libpari.so". If
7529This function is useful for adding custom functions to the GP interpreter, or
7531picking useful functions from unrelated libraries. For instance, it makes the
7532function "system" obsolete:
7533 ? install(system, vs, sys, "libc.so")
7535 ? sys("ls gp*")
7536 gp.c gp.h gp_rl.c
7537But it also gives you access to all (non static) functions defined in the PARI
7539library. For instance, the function "GEN addii(GEN x, GEN y)" adds two PARI
7540integers, and is not directly accessible under GP (it's eventually called by
7541the "+" operator of course):
7542 ? install("addii", "GG")
7544 ? addii(1, 2)
7545 %1 = 3
7546
7548been compiled statically. In that case, the first use of an installed function
7549will provoke a Segmentation Fault, i.e. a major internal blunder (this should
7550never happen with a dynamically linked executable). Hence, if you intend to
7551use this function, please check first on some harmless example such as the
7552ones above that it works properly on your machine.
7553kill"(s)"
7555 kills the present value of the variable, alias or user-defined function "s".
7556The corresponding identifier can now be used to name any GP object (variable
7557or function). This is the only way to replace a variable by a function having
7558the same name (or the other way round), as in the following example:
7559 ? f = 1
7561 %1 = 1
7562 ? f(x) = 0
7563 *** unused characters: f(x)=0
7564 ^----
7565 ? kill(f)
7566 ? f(x) = 0
7567 ? f()
7568 %2 = 0
7569When you kill a variable, all objects that used it become invalid. You can
7571still display them, even though the killed variable will be printed in a funny
7572way (following the same convention as used by the library function
7573"fetch_var", see "Label se:vars"). For example:
7574 ? a^2 + 1
7576 %1 = a^2 + 1
7577 ? kill(a)
7578 ? %1
7579 %2 = #<1>^2 + 1
7580If you simply want to restore a variable to its ``undefined'' value (monomial
7582of degree one), use the quote operator: "a = 'a". Predefined symbols ("x" and
7583GP function names) cannot be killed.
7584print"({str}*)"
7586outputs its (string) arguments in raw format, ending with a newline.
7587print1"({str}*)"
7589outputs its (string) arguments in raw format, without ending with a newline
7590(note that you can still embed newlines within your strings, using the "\n"
7591notation !).
7592printp"({str}*)"
7594outputs its (string) arguments in prettyprint (beautified) format, ending with
7595a newline.
7596printp1"({str}*)"
7598outputs its (string) arguments in prettyprint (beautified) format, without
7599ending with a newline.
7600printtex"({str}*)"
7602outputs its (string) arguments in TeX format. This output can then be used in
7603a TeX manuscript. The printing is done on the standard output. If you want to
7604print it to a file you should use "writetex" (see there).
7605Another possibility is to enable the "log" default (see "Label se:defaults").
7607You could for instance do:
7608 default(logfile, "new.tex");
7610 default(log, 1);
7611 printtex(result);
7612(You can use the automatic string expansion/concatenation process to have
7614dynamic file names if you wish).
7615quit"()"
7617exits GP.
7618read"({str})"
7620reads in the file whose name results from the expansion of the string str. If
7622is the result of the last expression evaluated.
7623reorder"({x = []})"
7625"x" must be a vector. If "x" is the empty vector, this gives the vector whose
7626components are the existing variables in increasing order (i.e. in decreasing
7627importance). Killed variables (see "kill") will be shown as 0. If "x" is
7628non-empty, it must be a permutation of variable names, and this permutation
7629gives a new order of importance of the variables, for output only. For exam‐
7630ple, if the existing order is "[x,y,z]", then after "reorder([z,x])" the order
7631of importance of the variables, with respect to output, will be "[z,y,x]". The
7632internal representation is unaffected.
7633setrand"(n)"
7635reseeds the random number generator to the value "n". The initial seed is "n =
76361".
7637The library syntax is setrand"(n)", where "n" is a "long". Returns "n".
7639system"(str)"
7642output written to the standard output (this won't get into your logfile), and
7643control returns to the PARI system. This simply calls the C "system" command.
7644trap"({e}, {rec}, {seq})"
7646tries to execute seq, trapping error "e", that is effectively preventing it
7647from aborting computations in the usual way; the recovery sequence rec is exe‐
7648cuted if the error occurs and the evaluation of rec becomes the result of the
7649command. If "e" is omitted, all exceptions are trapped. Note in particular
7650that hitting "^C" (Control-C) raises an exception.
7651 ? \\ trap division by 0
7653 ? inv(x) = trap (gdiver2, INFINITY, 1/x)
7654 ? inv(2)
7655 %1 = 1/2
7656 ? inv(0)
7657 %2 = INFINITY
7658If seq is omitted, defines rec as a default action when encountering exception
7660"e". The error message is printed, as well as the result of the evaluation of
7662computation is then lost.
7663The following error handler prints the list of all user variables, then stores
7665in a file their name and their values:
7666 ? { trap( ,
7668 print(reorder);
7669 write("crash", reorder);
7670 write("crash", eval(reorder))) }
7671If no recovery code is given (rec is omitted) a so-called break loop will be
7673started. During a break loop, all commands are read and evaluated as during
7674the main GP loop (except that no history of results is kept).
7675To get out of the break loop, you can use "next", "break" or "return"; reading
7677in a file by "\r" will also terminate the loop once the file has been read
7678("read" will remain in the break loop). If the error is not fatal ("^C" is the
7679only non-fatal error), "next" will continue the computation as if nothing had
7680happened (except of course, you may have changed GP state during the break
7681loop); otherwise control will come back to the GP prompt. After a user inter‐
7682rupt ("^C"), entering an empty input line (i.e hitting the return key) has the
7683same effect as "next".
7684Break loops are useful as a debugging tool to inspect the values of GP vari‐
7686ables to understand why a problem occurred, or to change GP behaviour
7687(increase debugging level, start storing results in a logfile, modify parame‐
7688ters...) in the middle of a long computation (hit "^C", type in your modifica‐
7689tions, then type "next").
7690If rec is the empty string "" the last default handler is popped out, and
7692replaced by the previous one for that error.
7693
7695tions. In the current version 2.2.0, the following keywords are recognized,
7696but the name list will be expanded and changed in the future (all library mode
7697errors can be trapped: it's a matter of defining the keywords to GP, and there
7698are currently far too many useless ones):
7699"accurer": accuracy problem
7701"gdiver2": division by 0
7703"archer": not available on this architecture or operating system
7705"typeer": wrong type
7707"errpile": the PARI stack overflows
7709type"(x,{t})"
7711this is useful only under GP. If "t" is not present, returns the internal type
7712number of the PARI object "x". Otherwise, makes a copy of "x" and sets its
7713type equal to type "t", which can be either a number or, preferably since
7714internal codes may eventually change, a symbolic name such as "t_FRACN" (you
7715can skip the "t_" part here, so that "FRACN" by itself would also be all
7716right). Check out existing type names with the metacommand "\t".
7717GP won't let you create meaningless objects in this way where the internal
7719structure doesn't match the type. This function can be useful to create reduc‐
7720ible rationals (type "t_FRACN") or rational functions (type "t_RFRACN"). In
7721fact it's the only way to do so in GP. In this case, the created object, as
7722well as the objects created from it, will not be reduced automatically, making
7723some operations a bit faster.
7724There is no equivalent library syntax, since the internal functions "typ" and
7726"settyp" are available. Note that "settyp" does not create a copy of "x", con‐
7727trary to most PARI functions. It also doesn't check for consistency. "settyp"
7728just changes the type in place and returns nothing. "typ" returns a C long
7729integer. Note also the different spellings of the internal functions
7730("set")"typ" and of the GP function "type", which is due to the fact that
7731"type" is a reserved identifier for some C compilers.
7732whatnow"(key)"
7734if keyword key is the name of a function that was present in GP version
77351.39.15 or lower, outputs the new function name and syntax, if it changed at
7736all (387 out of 560 did).
7737write"(filename,{str*})"
7739writes (appends) to filename the remaining arguments, and appends a newline
7740(same output as "print").
7741write1"(filename,{str*})"
7743writes (appends) to filename the remaining arguments without a trailing new‐
7744line (same output as "print1").
7745writetex"(filename,{str*})"
7747as "write", in TeX format.
7748perl v5.8.8 2007-04-18 libPARI(3)