1libPARI(3) User Contributed Perl Documentation libPARI(3)
2
6 libPARI - Functions and Operations Available in PARI and GP
7
9 The functions and operators available in PARI and in the GP/PARI
10 calculator are numerous and everexpanding. Here is a description of the
11 ones available in version 2.2.0. It should be noted that many of these
12 functions accept quite different types as arguments, but others are
13 more restricted. The list of acceptable types will be given for each
14 function or class of functions. Except when stated otherwise, it is
15 understood that a function or operation which should make natural sense
16 is legal. In this chapter, we will describe the functions according to
17 a rough classification. The general entry looks something like:
18 foo"(x,{flag = 0})": short description.
20 The library syntax is foo"(x,flag)".
22 This means that the GP function "foo" has one mandatory argument "x",
24 and an optional one, "flag", whose default value is 0. (The "{}" should
25 not be typed, it is just a convenient notation we will use throughout
26 to denote optional arguments.) That is, you can type "foo(x,2)", or
27 foo(x), which is then understood to mean "foo(x,0)". As well, a comma
28 or closing parenthesis, where an optional argument should have been,
29 signals to GP it should use the default. Thus, the syntax "foo(x,)" is
30 also accepted as a synonym for our last expression. When a function has
31 more than one optional argument, the argument list is filled with user
32 supplied values, in order. When none are left, the defaults are used
33 instead. Thus, assuming that "foo"'s prototype had been
34 " foo({x = 1},{y = 2},{z = 3}), "
36 typing in "foo(6,4)" would give you "foo(6,4,3)". In the rare case when
38 you want to set some far away argument, and leave the defaults in
39 between as they stand, you can use the ``empty arg'' trick alluded to
40 above: "foo(6,,1)" would yield "foo(6,2,1)". By the way, "foo()" by
41 itself yields "foo(1,2,3)" as was to be expected.
42 In this rather special case of a function having no mandatory argument,
44 you can even omit the "()": a standalone "foo" would be enough (though
45 we do not recommend it for your scripts, for the sake of clarity). In
46 defining GP syntax, we strove to put optional arguments at the end of
47 the argument list (of course, since they would not make sense
48 otherwise), and in order of decreasing usefulness so that, most of the
49 time, you will be able to ignore them.
50 Finally, an optional argument (between braces) followed by a star, like
52 "{x}*", means that any number of such arguments (possibly none) can be
53 given. This is in particular used by the various "print" routines.
54 Flags. A flag is an argument which, rather than conveying actual
56 information to the routine, intructs it to change its default
57 behaviour, e.g. return more or less information. All such flags are
58 optional, and will be called flag in the function descriptions to
59 follow. There are two different kind of flags
60 \item generic: all valid values for the flag are individually described
62 (``If flag is equal to 1, then...'').
63 \item binary: use customary binary notation as a compact way to
65 represent many toggles with just one integer. Let "(p_0,...,p_n)" be a
66 list of switches (i.e. of properties which take either the value 0
67 or 1), the number "2^3 + 2^5 = 40" means that "p_3" and "p_5" are set
68 (that is, set to 1), and none of the others are (that is, they are set
69 to 0). This is announced as ``The binary digits of "flag" mean 1:
70 "p_0", 2: "p_1", 4: "p_2"'', and so on, using the available consecutive
71 powers of 2.
72 Mnemonics for flags. Numeric flags as mentionned above are obscure,
74 error-prone, and quite rigid: should the authors want to adopt a new
75 flag numbering scheme (for instance when noticing flags with the same
76 meaning but different numeric values across a set of routines), it
77 would break backward compatibility. The only advantage of explicit
78 numeric values is that they are fast to type, so their use is only
79 advised when using the calculator "gp".
80 As an alternative, one can replace a numeric flag by a character string
82 containing symbolic identifiers. For a generic flag, the mnemonic
83 corresponding to the numeric identifier is given after it as in
84 fun(x, {flag = 0} ):
86 If flag is equal to 1 = AGM, use an agm formula\dots
88 which means that one can use indifferently "fun(x, 1)" or "fun(x,
90 AGM)".
91 For a binary flag, mnemonics corresponding to the various toggles are
93 given after each of them. They can be negated by prepending "no_" to
94 the mnemonic, or by removing such a prefix. These toggles are grouped
95 together using any punctuation character (such as ',' or ';'). For
96 instance (taken from description of "ploth(X = a,b,expr,{flag = 0},{n =
97 0})")
98 Binary digits of flags mean: C<1 = Parametric>,
100 C<2 = Recursive>,...
101 so that, instead of 1, one could use the mnemonic "Parametric;
103 no_Recursive", or simply "Parametric" since "Recursive" is unset by
104 default (default value of "flag" is 0, i.e. everything unset).
105 Pointers.\varsidx{pointer} If a parameter in the function prototype is
107 prefixed with a & sign, as in
108 foo"(x,&e)"
110 it means that, besides the normal return value, the function may assign
112 a value to "e" as a side effect. When passing the argument, the & sign
113 has to be typed in explicitly. As of version 2.2.0, this pointer
114 argument is optional for all documented functions, hence the & will
115 always appear between brackets as in "Z_issquare""(x,{&e})".
116 About library programming. the library function "foo", as defined at
118 the beginning of this section, is seen to have two mandatory arguments,
119 "x" and flag: no PARI mathematical function has been implemented so as
120 to accept a variable number of arguments, so all arguments are
121 mandatory when programming with the library (often, variants are
122 provided corresponding to the various flag values). When not mentioned
123 otherwise, the result and arguments of a function are assumed
124 implicitly to be of type "GEN". Most other functions return an object
125 of type "long" integer in C (see Chapter 4). The variable or parameter
126 names prec and flag always denote "long" integers.
127 The "entree" type is used by the library to implement iterators (loops,
129 sums, integrals, etc.) when a formal variable has to successively
130 assume a number of values in a given set. When programming with the
131 library, it is easier and much more efficient to code loops and the
132 like directly. Hence this type is not documented, although it does
133 appear in a few library function prototypes below. See "Label se:sums"
134 for more details.
135
137 +"/"-
138 The expressions "+""x" and "-""x" refer to monadic operators (the first
139 does nothing, the second negates "x").
140 The library syntax is gneg"(x)" for "-""x".
142 +, "-"
144 The expression "x" "+" "y" is the sum and "x" "-" "y" is the difference
145 of "x" and "y". Among the prominent impossibilities are
146 addition/subtraction between a scalar type and a vector or a matrix,
147 between vector/matrices of incompatible sizes and between an intmod and
148 a real number.
149 The library syntax is gadd"(x,y)" "x" "+" "y", " gsub(x,y)" for "x" "-"
151 "y".
152 *
154 The expression "x" "*" "y" is the product of "x" and "y". Among the
155 prominent impossibilities are multiplication between vector/matrices of
156 incompatible sizes, between an intmod and a real number. Note that
157 because of vector and matrix operations, "*" is not necessarily
158 commutative. Note also that since multiplication between two column or
159 two row vectors is not allowed, to obtain the scalar product of two
160 vectors of the same length, you must multiply a line vector by a column
161 vector, if necessary by transposing one of the vectors (using the
162 operator "~" or the function "mattranspose", see "Label
163 se:linear_algebra").
164 If "x" and "y" are binary quadratic forms, compose them. See also
166 "qfbnucomp" and "qfbnupow".
167 The library syntax is gmul"(x,y)" for "x" "*" "y". Also available is "
169 gsqr(x)" for "x" "*" "x" (faster of course!).
170 /
172 The expression "x" "/" "y" is the quotient of "x" and "y". In addition
173 to the impossibilities for multiplication, note that if the divisor is
174 a matrix, it must be an invertible square matrix, and in that case the
175 result is "x*y^{-1}". Furthermore note that the result is as exact as
176 possible: in particular, division of two integers always gives a
177 rational number (which may be an integer if the quotient is exact) and
178 \emph{not} the Euclidean quotient (see "x" "\" "y" for that), and
179 similarly the quotient of two polynomials is a rational function in
180 general. To obtain the approximate real value of the quotient of two
181 integers, add 0. to the result; to obtain the approximate "p"-adic
182 value of the quotient of two integers, add "O(p^k)" to the result;
183 finally, to obtain the Taylor series expansion of the quotient of two
184 polynomials, add "O(X^k)" to the result or use the "taylor" function
185 (see "Label se:taylor").
186 The library syntax is gdiv"(x,y)" for "x" "/" "y".
188 \
190 The expression "x \y" is the Euclidean quotient of "x" and "y". If "y"
191 is a real scalar, this is defined as "floor(x/y)" if "y > 0", and
192 "ceil(x/y)" if "y < 0" and the division is not exact. Hence the
193 remainder "x - (x\y)*y" is in "[0, |y|[".
194 Note that when "y" is an integer and "x" a polynomial, "y" is first
196 promoted to a polynomial of degree 0. When "x" is a vector or matrix,
197 the operator is applied componentwise.
198 The library syntax is gdivent"(x,y)" for "x" "\" "y".
200 \/
202 The expression "x" "\/" "y" evaluates to the rounded Euclidean quotient
203 of "x" and "y". This is the same as "x \y" except for scalar division:
204 the quotient is such that the corresponding remainder is smallest in
205 absolute value and in case of a tie the quotient closest to "+ oo " is
206 chosen (hence the remainder would belong to "]-|y|/2, |y|/2]").
207 When "x" is a vector or matrix, the operator is applied componentwise.
209 The library syntax is gdivround"(x,y)" for "x" "\/" "y".
211 %
213 The expression "x % y" evaluates to the modular Euclidean remainder of
214 "x" and "y", which we now define. If "y" is an integer, this is the
215 smallest non-negative integer congruent to "x" modulo "y". If "y" is a
216 polynomial, this is the polynomial of smallest degree congruent to "x"
217 modulo "y". When "y" is a non-integral real number, "x%y" is defined as
218 "x - (x\y)*y". This coincides with the definition for "y" integer if
219 and only if "x" is an integer, but still belongs to "[0, |y|[". For
220 instance:
221 ? (1/2) % 3
223 %1 = 2
224 ? 0.5 % 3
225 *** forbidden division t_REAL % t_INT.
226 ? (1/2) % 3.0
227 %2 = 1/2
228 Note that when "y" is an integer and "x" a polynomial, "y" is first
230 promoted to a polynomial of degree 0. When "x" is a vector or matrix,
231 the operator is applied componentwise.
232 The library syntax is gmod"(x,y)" for "x" "%" "y".
234 divrem"(x,y,{v})"
236 creates a column vector with two components, the first being the
237 Euclidean quotient ("x \y"), the second the Euclidean remainder ("x -
238 (x\y)*y"), of the division of "x" by "y". This avoids the need to do
239 two divisions if one needs both the quotient and the remainder. If "v"
240 is present, and "x", "y" are multivariate polynomials, divide with
241 respect to the variable "v".
242 Beware that "divrem(x,y)[2]" is in general not the same as "x % y";
244 there is no operator to obtain it in GP:
245 ? divrem(1/2, 3)[2]
247 %1 = 1/2
248 ? (1/2) % 3
249 %2 = 2
250 ? divrem(Mod(2,9), 3)[2]
251 *** forbidden division t_INTMOD \ t_INT.
252 ? Mod(2,9) % 6
253 %3 = Mod(2,3)
254 The library syntax is divrem"(x,y,v)",where "v" is a "long". Also
256 available as " gdiventres(x,y)" when "v" is not needed.
257 ^
259 The expression "x^n" is powering. If the exponent is an integer, then
260 exact operations are performed using binary (left-shift) powering
261 techniques. In particular, in this case "x" cannot be a vector or
262 matrix unless it is a square matrix (invertible if the exponent is
263 negative). If "x" is a "p"-adic number, its precision will increase if
264 "v_p(n) > 0". Powering a binary quadratic form (types "t_QFI" and
265 "t_QFR") returns a reduced representative of the class, provided the
266 input is reduced. In particular, "x^1" is identical to "x".
267 PARI is able to rewrite the multiplication "x * x" of two
269 \emph{identical} objects as "x^2", or sqr(x). Here, identical means the
270 operands are two different labels referencing the same chunk of memory;
271 no equality test is performed. This is no longer true when more than
272 two arguments are involved.
273 If the exponent is not of type integer, this is treated as a
275 transcendental function (see "Label se:trans"), and in particular has
276 the effect of componentwise powering on vector or matrices.
277 As an exception, if the exponent is a rational number "p/q" and "x" an
279 integer modulo a prime or a "p"-adic number, return a solution "y" of
280 "y^q = x^p" if it exists. Currently, "q" must not have large prime
281 factors. Beware that
282 ? Mod(7,19)^(1/2)
284 %1 = Mod(11, 19) /* is any square root */
285 ? sqrt(Mod(7,19))
286 %2 = Mod(8, 19) /* is the smallest square root */
287 ? Mod(7,19)^(3/5)
288 %3 = Mod(1, 19)
289 ? %3^(5/3)
290 %4 = Mod(1, 19) /* Mod(7,19) is just another cubic root */
291 If the exponent is a negative integer, an inverse must be computed.
293 For non-invertible "t_INTMOD", this will fail and implicitly exhibit a
294 non trivial factor of the modulus:
295 ? Mod(4,6)^(-1)
297 *** impossible inverse modulo: Mod(2, 6).
298 (Here, a factor 2 is obtained directly. In general, take the gcd of the
300 representative and the modulus.) This is most useful when performing
301 complicated operations modulo an integer "N" whose factorization is
302 unknown. Either the computation succeeds and all is well, or a factor
303 "d" is discovered and the computation may be restarted modulo "d" or
304 "N/d".
305 For non-invertible "t_POLMOD", this will fail without exhibiting a
307 factor.
308 ? Mod(x^2, x^3-x)^(-1)
310 *** non-invertible polynomial in RgXQ_inv.
311 ? a = Mod(3,4)*y^3 + Mod(1,4); b = y^6+y^5+y^4+y^3+y^2+y+1;
313 ? Mod(a, b)^(-1);
314 *** non-invertible polynomial in RgXQ_inv.
315 In fact the latter polynomial is invertible, but the algorithm used
317 (subresultant) assumes the base ring is a domain. If it is not the
318 case, as here for "Z/4Z", a result will be correct but chances are an
319 error will occur first. In this specific case, one should work with
320 2-adics. In general, one can try the following approach
321 ? inversemod(a, b) =
323 { local(m);
324 m = polsylvestermatrix(polrecip(a), polrecip(b));
325 m = matinverseimage(m, matid(#m)[,1]);
326 Polrev( vecextract(m, Str("..", poldegree(b))), variable(b) )
327 }
328 ? inversemod(a,b)
329 %2 = Mod(2,4)*y^5 + Mod(3,4)*y^3 + Mod(1,4)*y^2 + Mod(3,4)*y + Mod(2,4)
330 This is not guaranteed to work either since it must invert pivots. See
332 "Label se:linear_algebra".
333 The library syntax is gpow"(x,n,prec)" for "x^n".
335 bittest"(x,n)"
337 outputs the "n^{th}" bit of "x" starting from the right (i.e. the
338 coefficient of "2^n" in the binary expansion of "x"). The result is 0
339 or 1. To extract several bits at once as a vector, pass a vector for
340 "n".
341 See "Label se:bitand" for the behaviour at negative arguments.
343 The library syntax is bittest"(x,n)", where "n" and the result are
345 "long"s.
346 shift"(x,n)" or "x" "<< " "n" ( = "x" ">> " "(-n)")
348 shifts "x" componentwise left by "n" bits if "n >= 0" and right by
349 "|n|" bits if "n < 0". A left shift by "n" corresponds to
350 multiplication by "2^n". A right shift of an integer "x" by "|n|"
351 corresponds to a Euclidean division of "x" by "2^{|n|}" with a
352 remainder of the same sign as "x", hence is not the same (in general)
353 as "x \ 2^n".
354 The library syntax is gshift"(x,n)" where "n" is a "long".
356 shiftmul"(x,n)"
358 multiplies "x" by "2^n". The difference with "shift" is that when "n <
359 0", ordinary division takes place, hence for example if "x" is an
360 integer the result may be a fraction, while for shifts Euclidean
361 division takes place when "n < 0" hence if "x" is an integer the result
362 is still an integer.
363 The library syntax is gmul2n"(x,n)" where "n" is a "long".
365 Comparison and boolean operators
367 The six standard comparison operators "<= ", "< ", ">= ", "> ", " == ",
368 "! = " are available in GP, and in library mode under the names "gle",
369 "glt", "gge", "ggt", "geq", "gne" respectively. The library syntax is
370 "co(x,y)", where co is the comparison operator. The result is 1 (as a
371 "GEN") if the comparison is true, 0 (as a "GEN") if it is false. For
372 the purpose of comparison, "t_STR" objects are strictly larger than any
373 other non-string type; two "t_STR" objects are compared using the
374 standard lexicographic order.
375 The standard boolean functions "||" (inclusive or), "&&" (and) and "!"
377 (not) are also available, and the library syntax is " gor(x,y)", "
378 gand(x,y)" and " gnot(x)" respectively.
379 In library mode, it is in fact usually preferable to use the two basic
381 functions which are " gcmp(x,y)" which gives the sign (1, 0, or -1) of
382 "x-y", where "x" and "y" must be in R, and " gequal(x,y)" which can be
383 applied to any two PARI objects "x" and "y" and gives 1 (i.e. true) if
384 they are equal (but not necessarily identical), 0 (i.e. false)
385 otherwise. Comparisons to special constants are implemented and should
386 be used instead of "gequal": " gcmp0(x)" ("x == 0" ?), " gcmp1(x)" ("x
387 == 1" ?), and " gcmp_1(x)" ("x == -1" ?).
388 Note that gcmp0(x) tests whether "x" is equal to zero, even if "x" is
390 not an exact object. To test whether "x" is an exact object which is
391 equal to zero, one must use " isexactzero(x)".
392 Also note that the "gcmp" and "gequal" functions return a C-integer,
394 and \emph{not} a "GEN" like "gle" etc.
395 GP accepts the following synonyms for some of the above functions:
397 since we thought it might easily lead to confusion, we don't use the
398 customary C operators for bitwise "and" or bitwise "or" (use "bitand"
399 or "bitor"), hence "|" and "&" are accepted as synonyms of "||" and
400 "&&" respectively. Also, "< > " is accepted as a synonym for "! = ".
401 On the other hand, " = " is definitely \emph{not} a synonym for " == "
402 since it is the assignment statement.
403 lex"(x,y)"
405 gives the result of a lexicographic comparison between "x" and "y" (as
406 "-1", 0 or 1). This is to be interpreted in quite a wide sense: It is
407 admissible to compare objects of different types (scalars, vectors,
408 matrices), provided the scalars can be compared, as well as
409 vectors/matrices of different lengths. The comparison is recursive.
410 In case all components are equal up to the smallest length of the
412 operands, the more complex is considered to be larger. More precisely,
413 the longest is the largest; when lengths are equal, we have matrix " >
414 " vector " > " scalar. For example:
415 ? lex([1,3], [1,2,5])
417 %1 = 1
418 ? lex([1,3], [1,3,-1])
419 %2 = -1
420 ? lex([1], [[1]])
421 %3 = -1
422 ? lex([1], [1]~)
423 %4 = 0
424 The library syntax is lexcmp"(x,y)".
426 sign"(x)"
428 sign (0, 1 or "-1") of "x", which must be of type integer, real or
429 fraction.
430 The library syntax is gsigne"(x)". The result is a "long".
432 max"(x,y)" and " min(x,y)"
434 creates the maximum and minimum of "x" and "y" when they can be
435 compared.
436 The library syntax is gmax"(x,y)" and " gmin(x,y)".
438 vecmax"(x)"
440 if "x" is a vector or a matrix, returns the maximum of the elements of
441 "x", otherwise returns a copy of "x". Error if "x" is empty.
442 The library syntax is vecmax"(x)".
444 vecmin"(x)"
446 if "x" is a vector or a matrix, returns the minimum of the elements of
447 "x", otherwise returns a copy of "x". Error if "x" is empty.
448 The library syntax is vecmin"(x)".
450
452 Many of the conversion functions are rounding or truncating operations.
453 In this case, if the argument is a rational function, the result is the
454 Euclidean quotient of the numerator by the denominator, and if the
455 argument is a vector or a matrix, the operation is done componentwise.
456 This will not be restated for every function.
457 Col"({x = []})"
459 transforms the object "x" into a column vector. The vector will be
460 with one component only, except when "x" is a vector or a quadratic
461 form (in which case the resulting vector is simply the initial object
462 considered as a column vector), a matrix (the column of row vectors
463 comprising the matrix is returned), a character string (a column of
464 individual characters is returned), but more importantly when "x" is a
465 polynomial or a power series. In the case of a polynomial, the
466 coefficients of the vector start with the leading coefficient of the
467 polynomial, while for power series only the significant coefficients
468 are taken into account, but this time by increasing order of degree.
469 The library syntax is gtocol"(x)".
471 List"({x = []})"
473 transforms a (row or column) vector "x" into a list. The only other way
474 to create a "t_LIST" is to use the function "listcreate".
475 This is useless in library mode.
477 Mat"({x = []})"
479 transforms the object "x" into a matrix. If "x" is already a matrix, a
480 copy of "x" is created. If "x" is not a vector or a matrix, this
481 creates a "1 x 1" matrix. If "x" is a row (resp. column) vector, this
482 creates a 1-row (resp. 1-column) matrix, \emph{unless} all elements
483 are column (resp. row) vectors of the same length, in which case the
484 vectors are concatenated sideways and the associated big matrix is
485 returned.
486 ? Mat(x + 1)
488 %1 =
489 [x + 1]
490 ? Vec( matid(3) )
491 %2 = [[1, 0, 0]~, [0, 1, 0]~, [0, 0, 1]~]
492 ? Mat(%)
493 %3 =
494 [1 0 0]
495 [0 1 0]
497 [0 0 1]
499 ? Col( [1,2; 3,4] )
500 %4 = [[1, 2], [3, 4]]~
501 ? Mat(%)
502 %5 =
503 [1 2]
504 [3 4]
506 The library syntax is gtomat"(x)".
508 Mod"(x,y,{flag = 0})"
510 creates the PARI object "(x mod y)", i.e. an intmod or a polmod. "y"
511 must be an integer or a polynomial. If "y" is an integer, "x" must be
512 an integer, a rational number, or a "p"-adic number compatible with the
513 modulus "y". If "y" is a polynomial, "x" must be a scalar (which is not
514 a polmod), a polynomial, a rational function, or a power series.
515 This function is not the same as "x" "%" "y", the result of which is an
517 integer or a polynomial.
518 "flag" is obsolete and should not be used.
520 The library syntax is gmodulo"(x,y)".
522 Pol"(x,{v = x})"
524 transforms the object "x" into a polynomial with main variable "v". If
525 "x" is a scalar, this gives a constant polynomial. If "x" is a power
526 series, the effect is identical to "truncate" (see there), i.e. it
527 chops off the "O(X^k)". If "x" is a vector, this function creates the
528 polynomial whose coefficients are given in "x", with "x[1]" being the
529 leading coefficient (which can be zero).
530 Warning: this is \emph{not} a substitution function. It will not
532 transform an object containing variables of higher priority than "v".
533 ? Pol(x + y, y)
535 *** Pol: variable must have higher priority in gtopoly.
536 The library syntax is gtopoly"(x,v)", where "v" is a variable number.
538 Polrev"(x,{v = x})"
540 transform the object "x" into a polynomial with main variable "v". If
541 "x" is a scalar, this gives a constant polynomial. If "x" is a power
542 series, the effect is identical to "truncate" (see there), i.e. it
543 chops off the "O(X^k)". If "x" is a vector, this function creates the
544 polynomial whose coefficients are given in "x", with "x[1]" being the
545 constant term. Note that this is the reverse of "Pol" if "x" is a
546 vector, otherwise it is identical to "Pol".
547 The library syntax is gtopolyrev"(x,v)", where "v" is a variable
549 number.
550 Qfb"(a,b,c,{D = 0.})"
552 creates the binary quadratic form "ax^2+bxy+cy^2". If "b^2-4ac > 0",
553 initialize Shanks' distance function to "D". Negative definite forms
554 are not implemented, use their positive definite counterpart instead.
555 The library syntax is Qfb0"(a,b,c,D,prec)". Also available are "
557 qfi(a,b,c)" (when "b^2-4ac < 0"), and " qfr(a,b,c,d)" (when "b^2-4ac >
558 0").
559 Ser"(x,{v = x})"
561 transforms the object "x" into a power series with main variable "v"
562 ("x" by default). If "x" is a scalar, this gives a constant power
563 series with precision given by the default "serieslength"
564 (corresponding to the C global variable "precdl"). If "x" is a
565 polynomial, the precision is the greatest of "precdl" and the degree of
566 the polynomial. If "x" is a vector, the precision is similarly given,
567 and the coefficients of the vector are understood to be the
568 coefficients of the power series starting from the constant term
569 (i.e. the reverse of the function "Pol").
570 The warning given for "Pol" also applies here: this is not a
572 substitution function.
573 The library syntax is gtoser"(x,v)", where "v" is a variable number
575 (i.e. a C integer).
576 Set"({x = []})"
578 converts "x" into a set, i.e. into a row vector of character strings,
579 with strictly increasing entries with respect to lexicographic
580 ordering. The components of "x" are put in canonical form (type
581 "t_STR") so as to be easily sorted. To recover an ordinary "GEN" from
582 such an element, you can apply "eval" to it.
583 The library syntax is gtoset"(x)".
585 Str"({x}*)"
587 converts its argument list into a single character string (type
588 "t_STR", the empty string if "x" is omitted). To recover an ordinary
589 "GEN" from a string, apply "eval" to it. The arguments of "Str" are
590 evaluated in string context, see "Label se:strings".
591 ? x2 = 0; i = 2; Str(x, i)
593 %1 = "x2"
594 ? eval(%)
595 %2 = 0
596 This function is mostly useless in library mode. Use the pair
598 "strtoGEN"/"GENtostr" to convert between "GEN" and "char*". The latter
599 returns a malloced string, which should be freed after usage.
600 Strchr"(x)"
602 converts "x" to a string, translating each integer into a character.
603 ? Strchr(97)
605 %1 = "a"
606 ? Vecsmall("hello world")
607 %2 = Vecsmall([104, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100])
608 ? Strchr(%)
609 %3 = "hello world"
610 Strexpand"({x}*)"
612 converts its argument list into a single character string (type
613 "t_STR", the empty string if "x" is omitted). Then performe
614 environment expansion, see "Label se:envir". This feature can be used
615 to read environment variable values.
616 ? Strexpand("$HOME/doc")
618 %1 = "/home/pari/doc"
619 The individual arguments are read in string context, see "Label
621 se:strings".
622 Strtex"({x}*)"
624 translates its arguments to TeX format, and concatenates the results
625 into a single character string (type "t_STR", the empty string if "x"
626 is omitted).
627 The individual arguments are read in string context, see "Label
629 se:strings".
630 Vec"({x = []})"
632 transforms the object "x" into a row vector. The vector will be with
633 one component only, except when "x" is a vector or a quadratic form (in
634 which case the resulting vector is simply the initial object considered
635 as a row vector), a matrix (the vector of columns comprising the matrix
636 is return), a character string (a vector of individual characters is
637 returned), but more importantly when "x" is a polynomial or a power
638 series. In the case of a polynomial, the coefficients of the vector
639 start with the leading coefficient of the polynomial, while for power
640 series only the significant coefficients are taken into account, but
641 this time by increasing order of degree.
642 The library syntax is gtovec"(x)".
644 Vecsmall"({x = []})"
646 transforms the object "x" into a row vector of type "t_VECSMALL". This
647 acts as "Vec", but only on a limited set of objects (the result must be
648 representable as a vector of small integers). In particular,
649 polynomials and power series are forbidden. If "x" is a character
650 string, a vector of individual characters in ASCII encoding is returned
651 ("Strchr" yields back the character string).
652 The library syntax is gtovecsmall"(x)".
654 binary"(x)"
656 outputs the vector of the binary digits of "|x|". Here "x" can be an
657 integer, a real number (in which case the result has two components,
658 one for the integer part, one for the fractional part) or a
659 vector/matrix.
660 The library syntax is binaire"(x)".
662 bitand"(x,y)"
664 bitwise "and" of two integers "x" and "y", that is the integer
665 "sum_i (x_i and y_i) 2^i"
667 Negative numbers behave 2-adically, i.e. the result is the 2-adic limit
669 of "bitand""(x_n,y_n)", where "x_n" and "y_n" are non-negative integers
670 tending to "x" and "y" respectively. (The result is an ordinary
671 integer, possibly negative.)
672 ? bitand(5, 3)
674 %1 = 1
675 ? bitand(-5, 3)
676 %2 = 3
677 ? bitand(-5, -3)
678 %3 = -7
679 The library syntax is gbitand"(x,y)".
681 bitneg"(x,{n = -1})"
683 bitwise negation of an integer "x", truncated to "n" bits, that is the
684 integer
685 "sum_{i = 0}^{n-1} not(x_i) 2^i"
687 The special case "n = -1" means no truncation: an infinite sequence of
689 leading 1 is then represented as a negative number.
690 See "Label se:bitand" for the behaviour for negative arguments.
692 The library syntax is gbitneg"(x)".
694 bitnegimply"(x,y)"
696 bitwise negated imply of two integers "x" and "y" (or "not" "(x ==>
697 y)"), that is the integer
698 "sum (x_i and not(y_i)) 2^i"
700 See "Label se:bitand" for the behaviour for negative arguments.
702 The library syntax is gbitnegimply"(x,y)".
704 bitor"(x,y)"
706 bitwise (inclusive) "or" of two integers "x" and "y", that is the
707 integer
708 "sum (x_i or y_i) 2^i"
710 See "Label se:bitand" for the behaviour for negative arguments.
712 The library syntax is gbitor"(x,y)".
714 bittest"(x,n)"
716 outputs the "n^{th}" bit of "|x|" starting from the right (i.e. the
717 coefficient of "2^n" in the binary expansion of "x"). The result is 0
718 or 1. To extract several bits at once as a vector, pass a vector for
719 "n".
720 The library syntax is bittest"(x,n)", where "n" and the result are
722 "long"s.
723 bitxor"(x,y)"
725 bitwise (exclusive) "or" of two integers "x" and "y", that is the
726 integer
727 "sum (x_i xor y_i) 2^i"
729 See "Label se:bitand" for the behaviour for negative arguments.
731 The library syntax is gbitxor"(x,y)".
733 ceil"(x)"
735 ceiling of "x". When "x" is in R, the result is the smallest integer
736 greater than or equal to "x". Applied to a rational function, ceil(x)
737 returns the euclidian quotient of the numerator by the denominator.
738 The library syntax is gceil"(x)".
740 centerlift"(x,{v})"
742 lifts an element "x = a mod n" of "Z/nZ" to "a" in Z, and similarly
743 lifts a polmod to a polynomial. This is the same as "lift" except that
744 in the particular case of elements of "Z/nZ", the lift "y" is such that
745 "-n/2 < y <= n/2". If "x" is of type fraction, complex, quadratic,
746 polynomial, power series, rational function, vector or matrix, the lift
747 is done for each coefficient. Reals are forbidden.
748 The library syntax is centerlift0"(x,v)", where "v" is a "long" and an
750 omitted "v" is coded as "-1". Also available is " centerlift(x)" =
751 "centerlift0(x,-1)".
752 changevar"(x,y)"
754 creates a copy of the object "x" where its variables are modified
755 according to the permutation specified by the vector "y". For example,
756 assume that the variables have been introduced in the order "x", "a",
757 "b", "c". Then, if "y" is the vector "[x,c,a,b]", the variable "a" will
758 be replaced by "c", "b" by "a", and "c" by "b", "x" being unchanged.
759 Note that the permutation must be completely specified, e.g. "[c,a,b]"
760 would not work, since this would replace "x" by "c", and leave "a" and
761 "b" unchanged (as well as "c" which is the fourth variable of the
762 initial list). In particular, the new variable names must be distinct.
763 The library syntax is changevar"(x,y)".
765 components of a PARI object
767 There are essentially three ways to extract the components from a PARI
768 object.
769 The first and most general, is the function " component(x,n)" which
771 extracts the "n^{th}"-component of "x". This is to be understood as
772 follows: every PARI type has one or two initial code words. The
773 components are counted, starting at 1, after these code words. In
774 particular if "x" is a vector, this is indeed the "n^{th}"-component of
775 "x", if "x" is a matrix, the "n^{th}" column, if "x" is a polynomial,
776 the "n^{th}" coefficient (i.e. of degree "n-1"), and for power series,
777 the "n^{th}" significant coefficient. The use of the function
778 "component" implies the knowledge of the structure of the different
779 PARI types, which can be recalled by typing "\t" under "gp".
780 The library syntax is compo"(x,n)", where "n" is a "long".
782 The two other methods are more natural but more restricted. The
784 function " polcoeff(x,n)" gives the coefficient of degree "n" of the
785 polynomial or power series "x", with respect to the main variable of
786 "x" (to check variable ordering, or to change it, use the function
787 "reorder", see "Label se:reorder"). In particular if "n" is less than
788 the valuation of "x" or in the case of a polynomial, greater than the
789 degree, the result is zero (contrary to "compo" which would send an
790 error message). If "x" is a power series and "n" is greater than the
791 largest significant degree, then an error message is issued.
792 For greater flexibility, vector or matrix types are also accepted for
794 "x", and the meaning is then identical with that of "compo".
795 Finally note that a scalar type is considered by "polcoeff" as a
797 polynomial of degree zero.
798 The library syntax is truecoeff"(x,n)".
800 The third method is specific to vectors or matrices in GP. If "x" is a
802 (row or column) vector, then "x[n]" represents the "n^{th}" component
803 of "x", i.e. "compo(x,n)". It is more natural and shorter to write. If
804 "x" is a matrix, "x[m,n]" represents the coefficient of row "m" and
805 column "n" of the matrix, "x[m,]" represents the "m^{th}" \emph{row} of
806 "x", and "x[,n]" represents the "n^{th}" \emph{column} of "x".
807 Finally note that in library mode, the macros gcoeff and gmael are
809 available as direct accessors to a "GEN component". See Chapter 4 for
810 details.
811 conj"(x)"
813 conjugate of "x". The meaning of this is clear, except that for real
814 quadratic numbers, it means conjugation in the real quadratic field.
815 This function has no effect on integers, reals, intmods, fractions or
816 "p"-adics. The only forbidden type is polmod (see "conjvec" for this).
817 The library syntax is gconj"(x)".
819 conjvec"(x)"
821 conjugate vector representation of "x". If "x" is a polmod, equal to
822 "Mod""(a,q)", this gives a vector of length degree(q) containing the
823 complex embeddings of the polmod if "q" has integral or rational
824 coefficients, and the conjugates of the polmod if "q" has some intmod
825 coefficients. The order is the same as that of the "polroots"
826 functions. If "x" is an integer or a rational number, the result
827 is "x". If "x" is a (row or column) vector, the result is a matrix
828 whose columns are the conjugate vectors of the individual elements of
829 "x".
830 The library syntax is conjvec"(x,prec)".
832 denominator"(x)"
834 denominator of "x". The meaning of this is clear when "x" is a rational
835 number or function. If "x" is an integer or a polynomial, it is treated
836 as a rational number of function, respectively, and the result is equal
837 to 1. For polynomials, you probably want to use
838 denominator( content(x) )
840 instead. As for modular objects, "t_INTMOD" and "t_PADIC" have
842 denominator 1, and the denominator of a "t_POLMOD" is the denominator
843 of its (minimal degree) polynomial representative.
844 If "x" is a recursive structure, for instance a vector or matrix, the
846 lcm of the denominators of its components (a common denominator) is
847 computed. This also applies for "t_COMPLEX"s and "t_QUAD"s.
848 Warning: multivariate objects are created according to variable
850 priorities, with possibly surprising side effects ("x/y" is a
851 polynomial, but "y/x" is a rational function). See "Label se:priority".
852 The library syntax is denom"(x)".
854 floor"(x)"
856 floor of "x". When "x" is in R, the result is the largest integer
857 smaller than or equal to "x". Applied to a rational function, floor(x)
858 returns the euclidian quotient of the numerator by the denominator.
859 The library syntax is gfloor"(x)".
861 frac"(x)"
863 fractional part of "x". Identical to "x-floor(x)". If "x" is real, the
864 result is in "[0,1[".
865 The library syntax is gfrac"(x)".
867 imag"(x)"
869 imaginary part of "x". When "x" is a quadratic number, this is the
870 coefficient of "omega" in the ``canonical'' integral basis "(1,omega)".
871 The library syntax is gimag"(x)". This returns a copy of the imaginary
873 part. The internal routine "imag_i" is faster, since it returns the
874 pointer and skips the copy.
875 length"(x)"
877 number of non-code words in "x" really used (i.e. the effective length
878 minus 2 for integers and polynomials). In particular, the degree of a
879 polynomial is equal to its length minus 1. If "x" has type "t_STR",
880 output number of letters.
881 The library syntax is glength"(x)" and the result is a C long.
883 lift"(x,{v})"
885 lifts an element "x = a mod n" of "Z/nZ" to "a" in Z, and similarly
886 lifts a polmod to a polynomial if "v" is omitted. Otherwise, lifts
887 only polmods whose modulus has main variable "v" (if "v" does not occur
888 in "x", lifts only intmods). If "x" is of recursive (non modular) type,
889 the lift is done coefficientwise. For "p"-adics, this routine acts as
890 "truncate". It is not allowed to have "x" of type "t_REAL".
891 ? lift(Mod(5,3))
893 %1 = 2
894 ? lift(3 + O(3^9))
895 %2 = 3
896 ? lift(Mod(x,x^2+1))
897 %3 = x
898 ? lift(x * Mod(1,3) + Mod(2,3))
899 %4 = x + 2
900 ? lift(x * Mod(y,y^2+1) + Mod(2,3))
901 %5 = y*x + Mod(2, 3) \\ do you understand this one ?
902 ? lift(x * Mod(y,y^2+1) + Mod(2,3), x)
903 %6 = Mod(y, y^2+1) * x + Mod(2, y^2+1)
904 The library syntax is lift0"(x,v)", where "v" is a "long" and an
906 omitted "v" is coded as "-1". Also available is " lift(x)" =
907 "lift0(x,-1)".
908 norm"(x)"
910 algebraic norm of "x", i.e. the product of "x" with its conjugate (no
911 square roots are taken), or conjugates for polmods. For vectors and
912 matrices, the norm is taken componentwise and hence is not the
913 "L^2"-norm (see "norml2"). Note that the norm of an element of R is its
914 square, so as to be compatible with the complex norm.
915 The library syntax is gnorm"(x)".
917 norml2"(x)"
919 square of the "L^2"-norm of "x". More precisely, if "x" is a scalar,
920 norml2(x) is defined to be "x * conj(x)". If "x" is a (row or column)
921 vector or a matrix, norml2(x) is defined recursively as "sum_i
922 norml2(x_i)", where "(x_i)" run through the components of "x". In
923 particular, this yields the usual "sum |x_i|^2" (resp. "sum
924 |x_{i,j}|^2") if "x" is a vector (resp. matrix) with complex
925 components.
926 ? norml2( [ 1, 2, 3 ] ) \\ vector
928 %1 = 14
929 ? norml2( [ 1, 2; 3, 4] ) \\ matrix
930 %1 = 30
931 ? norml2( I + x )
932 %3 = x^2 + 1
933 ? norml2( [ [1,2], [3,4], 5, 6 ] ) \\ recursively defined
934 %4 = 91
935 The library syntax is gnorml2"(x)".
937 numerator"(x)"
939 numerator of "x". The meaning of this is clear when "x" is a rational
940 number or function. If "x" is an integer or a polynomial, it is treated
941 as a rational number of function, respectively, and the result is "x"
942 itself. For polynomials, you probably want to use
943 numerator( content(x) )
945 instead.
947 In other cases, numerator(x) is defined to be "denominator(x)*x". This
949 is the case when "x" is a vector or a matrix, but also for "t_COMPLEX"
950 or "t_QUAD". In particular since a "t_PADIC" or "t_INTMOD" has
951 denominator 1, its numerator is itself.
952 Warning: multivariate objects are created according to variable
954 priorities, with possibly surprising side effects ("x/y" is a
955 polynomial, but "y/x" is a rational function). See "Label se:priority".
956 The library syntax is numer"(x)".
958 numtoperm"(n,k)"
960 generates the "k"-th permutation (as a row vector of length "n") of the
961 numbers 1 to "n". The number "k" is taken modulo "n!", i.e. inverse
962 function of "permtonum".
963 The library syntax is numtoperm"(n,k)", where "n" is a "long".
965 padicprec"(x,p)"
967 absolute "p"-adic precision of the object "x". This is the minimum
968 precision of the components of "x". The result is "VERYBIGINT"
969 ("2^{31}-1" for 32-bit machines or "2^{63}-1" for 64-bit machines) if
970 "x" is an exact object.
971 The library syntax is padicprec"(x,p)" and the result is a "long"
973 integer.
974 permtonum"(x)"
976 given a permutation "x" on "n" elements, gives the number "k" such that
977 "x = numtoperm(n,k)", i.e. inverse function of "numtoperm".
978 The library syntax is permtonum"(x)".
980 precision"(x,{n})"
982 gives the precision in decimal digits of the PARI object "x". If "x" is
983 an exact object, the largest single precision integer is returned. If
984 "n" is not omitted, creates a new object equal to "x" with a new
985 precision "n". This is to be understood as follows:
986 For exact types, no change. For "x" a vector or a matrix, the operation
988 is done componentwise.
989 For real "x", "n" is the number of desired significant \emph{decimal}
991 digits. If "n" is smaller than the precision of "x", "x" is truncated,
992 otherwise "x" is extended with zeros.
993 For "x" a "p"-adic or a power series, "n" is the desired number of
995 significant "p"-adic or "X"-adic digits, where "X" is the main variable
996 of "x".
997 Note that the function "precision" never changes the type of the
999 result. In particular it is not possible to use it to obtain a
1000 polynomial from a power series. For that, see "truncate".
1001 The library syntax is precision0"(x,n)", where "n" is a "long". Also
1003 available are " ggprecision(x)" (result is a "GEN") and " gprec(x,n)",
1004 where "n" is a "long".
1005 random"({N = 2^{31}})"
1007 returns a random integer between 0 and "N-1". "N" is an integer, which
1008 can be arbitrary large. This is an internal PARI function and does not
1009 depend on the system's random number generator.
1010 The resulting integer is obtained by means of linear congruences and
1012 will not be well distributed in arithmetic progressions. The random
1013 seed may be obtained via "getrand", and reset using "setrand".
1014 Note that "random(2^31)" is \emph{not} equivalent to "random()",
1016 although both return an integer between 0 and "2^{31}-1". In fact,
1017 calling "random" with an argument generates a number of random words
1018 (32bit or 64bit depending on the architecture), rescaled to the desired
1019 interval. The default uses directly a 31-bit generator.
1020 Important technical note: the implementation of this function is
1022 incorrect unless "N" is a power of 2 (integers less than the bound are
1023 not equally likely, some may not even occur). It is kept for backward
1024 compatibility only, and has been rewritten from scratch in the 2.4.x
1025 unstable series. Use the following script for a correct version:
1026 RANDOM(N) =
1028 { local(n, L);
1029 L = 1; while (L < N, L <<= 1;);
1031 /* L/2 < N <= L, L power of 2 */
1032 until(n < N, n = random(L)); n
1033 }
1034 The library syntax is genrand"(N)". Also available are "pari_rand""()"
1036 which returns a random "unsigned long" (32bit or 64bit depending on the
1037 architecture), and "pari_rand31""()" which returns a 31bit "long"
1038 integer.
1039 real"(x)"
1041 real part of "x". In the case where "x" is a quadratic number, this is
1042 the coefficient of 1 in the ``canonical'' integral basis "(1,omega)".
1043 The library syntax is greal"(x)". This returns a copy of the real part.
1045 The internal routine "real_i" is faster, since it returns the pointer
1046 and skips the copy.
1047 round"(x,{&e})"
1049 If "x" is in R, rounds "x" to the nearest integer and sets "e" to the
1050 number of error bits, that is the binary exponent of the difference
1051 between the original and the rounded value (the ``fractional part'').
1052 If the exponent of "x" is too large compared to its precision (i.e. "e
1053 > 0"), the result is undefined and an error occurs if "e" was not
1054 given.
1055 Important remark: note that, contrary to the other truncation
1057 functions, this function operates on every coefficient at every level
1058 of a PARI object. For example
1059 "truncate((2.4*X^2-1.7)/(X)) = 2.4*X,"
1061 whereas
1063 "round((2.4*X^2-1.7)/(X)) = (2*X^2-2)/(X)."
1065 An important use of "round" is to get exact results after a long
1067 approximate computation, when theory tells you that the coefficients
1068 must be integers.
1069 The library syntax is grndtoi"(x,&e)", where "e" is a "long" integer.
1071 Also available is " ground(x)".
1072 simplify"(x)"
1074 this function simplifies "x" as much as it can. Specifically, a
1075 complex or quadratic number whose imaginary part is an exact 0
1076 (i.e. not an approximate one as a O(3) or "0.E-28") is converted to its
1077 real part, and a polynomial of degree 0 is converted to its constant
1078 term. Simplifications occur recursively.
1079 This function is especially useful before using arithmetic functions,
1081 which expect integer arguments:
1082 ? x = 1 + y - y
1084 %1 = 1
1085 ? divisors(x)
1086 *** divisors: not an integer argument in an arithmetic function
1087 ? type(x)
1088 %2 = "t_POL"
1089 ? type(simplify(x))
1090 %3 = "t_INT"
1091 Note that GP results are simplified as above before they are stored in
1093 the history. (Unless you disable automatic simplification with "\y",
1094 that is.) In particular
1095 ? type(%1)
1097 %4 = "t_INT"
1098 The library syntax is simplify"(x)".
1100 sizebyte"(x)"
1102 outputs the total number of bytes occupied by the tree representing the
1103 PARI object "x".
1104 The library syntax is taille2"(x)" which returns a "long"; " taille(x)"
1106 returns the number of \emph{words} instead.
1107 sizedigit"(x)"
1109 outputs a quick bound for the number of decimal digits of (the
1110 components of) "x", off by at most 1. If you want the exact value, you
1111 can use "#Str(x)", which is slower.
1112 The library syntax is sizedigit"(x)" which returns a "long".
1114 truncate"(x,{&e})"
1116 truncates "x" and sets "e" to the number of error bits. When "x" is in
1117 R, this means that the part after the decimal point is chopped away,
1118 "e" is the binary exponent of the difference between the original and
1119 the truncated value (the ``fractional part''). If the exponent of "x"
1120 is too large compared to its precision (i.e. "e > 0"), the result is
1121 undefined and an error occurs if "e" was not given. The function
1122 applies componentwise on vector / matrices; "e" is then the maximal
1123 number of error bits. If "x" is a rational function, the result is the
1124 ``integer part'' (Euclidean quotient of numerator by denominator) and
1125 "e" is not set.
1126 Note a very special use of "truncate": when applied to a power series,
1128 it transforms it into a polynomial or a rational function with
1129 denominator a power of "X", by chopping away the "O(X^k)". Similarly,
1130 when applied to a "p"-adic number, it transforms it into an integer or
1131 a rational number by chopping away the "O(p^k)".
1132 The library syntax is gcvtoi"(x,&e)", where "e" is a "long" integer.
1134 Also available is " gtrunc(x)".
1135 valuation"(x,p)"
1137 computes the highest exponent of "p" dividing "x". If "p" is of type
1138 integer, "x" must be an integer, an intmod whose modulus is divisible
1139 by "p", a fraction, a "q"-adic number with "q = p", or a polynomial or
1140 power series in which case the valuation is the minimum of the
1141 valuation of the coefficients.
1142 If "p" is of type polynomial, "x" must be of type polynomial or
1144 rational function, and also a power series if "x" is a monomial.
1145 Finally, the valuation of a vector, complex or quadratic number is the
1146 minimum of the component valuations.
1147 If "x = 0", the result is "VERYBIGINT" ("2^{31}-1" for 32-bit machines
1149 or "2^{63}-1" for 64-bit machines) if "x" is an exact object. If "x" is
1150 a "p"-adic numbers or power series, the result is the exponent of the
1151 zero. Any other type combinations gives an error.
1152 The library syntax is ggval"(x,p)", and the result is a "long".
1154 variable"(x)"
1156 gives the main variable of the object "x", and "p" if "x" is a "p"-adic
1157 number. Gives an error if "x" has no variable associated to it. Note
1158 that this function is useful only in GP, since in library mode the
1159 function "gvar" is more appropriate.
1160 The library syntax is gpolvar"(x)". However, in library mode, this
1162 function should not be used. Instead, test whether "x" is a "p"-adic
1163 (type "t_PADIC"), in which case "p" is in "x[2]", or call the function
1164 " gvar(x)" which returns the variable \emph{number} of "x" if it
1165 exists, "BIGINT" otherwise.
1166
1168 As a general rule, which of course in some cases may have exceptions,
1169 transcendental functions operate in the following way:
1170 \item If the argument is either an integer, a real, a rational, a
1172 complex or a quadratic number, it is, if necessary, first converted to
1173 a real (or complex) number using the current precision held in the
1174 default "realprecision". Note that only exact arguments are converted,
1175 while inexact arguments such as reals are not.
1176 In GP this is transparent to the user, but when programming in library
1178 mode, care must be taken to supply a meaningful parameter prec as the
1179 last argument of the function if the first argument is an exact object.
1180 This parameter is ignored if the argument is inexact.
1181 Note that in library mode the precision argument prec is a word count
1183 including codewords, i.e. represents the length in words of a real
1184 number, while under "gp" the precision (which is changed by the
1185 metacommand "\p" or using "default(realprecision,...)") is the number
1186 of significant decimal digits.
1187 Note that some accuracies attainable on 32-bit machines cannot be
1189 attained on 64-bit machines for parity reasons. For example the default
1190 "gp" accuracy is 28 decimal digits on 32-bit machines, corresponding to
1191 prec having the value 5, but this cannot be attained on 64-bit
1192 machines.
1193 After possible conversion, the function is computed. Note that even if
1195 the argument is real, the result may be complex (e.g. "acos(2.0)" or
1196 "acosh(0.0)"). Note also that the principal branch is always chosen.
1197 \item If the argument is an intmod or a "p"-adic, at present only a few
1199 functions like "sqrt" (square root), "sqr" (square), "log", "exp",
1200 powering, "teichmuller" (Teichmüller character) and "agm" (arithmetic-
1201 geometric mean) are implemented.
1202 Note that in the case of a 2-adic number, sqr(x) may not be identical
1204 to "x*x": for example if "x = 1+O(2^5)" and "y = 1+O(2^5)" then "x*y =
1205 1+O(2^5)" while "sqr(x) = 1+O(2^6)". Here, "x * x" yields the same
1206 result as sqr(x) since the two operands are known to be
1207 \emph{identical}. The same statement holds true for "p"-adics raised to
1208 the power "n", where "v_p(n) > 0".
1209 Remark: note that if we wanted to be strictly consistent with the PARI
1211 philosophy, we should have "x*y = (4 mod 8)" and "sqr(x) = (4 mod 32)"
1212 when both "x" and "y" are congruent to 2 modulo 4. However, since
1213 intmod is an exact object, PARI assumes that the modulus must not
1214 change, and the result is hence "(0 mod 4)" in both cases. On the other
1215 hand, "p"-adics are not exact objects, hence are treated differently.
1216 \item If the argument is a polynomial, power series or rational
1218 function, it is, if necessary, first converted to a power series using
1219 the current precision held in the variable "precdl". Under "gp" this
1220 again is transparent to the user. When programming in library mode,
1221 however, the global variable "precdl" must be set before calling the
1222 function if the argument has an exact type (i.e. not a power series).
1223 Here "precdl" is not an argument of the function, but a global
1224 variable.
1225 Then the Taylor series expansion of the function around "X = 0" (where
1227 "X" is the main variable) is computed to a number of terms depending on
1228 the number of terms of the argument and the function being computed.
1229 \item If the argument is a vector or a matrix, the result is the
1231 componentwise evaluation of the function. In particular, transcendental
1232 functions on square matrices, which are not implemented in the present
1233 version 2.2.0, will have a different name if they are implemented some
1234 day.
1235 ^
1237 If "y" is not of type integer, "x^y" has the same effect as
1238 "exp(y*log(x))". It can be applied to "p"-adic numbers as well as to
1239 the more usual types.
1240 The library syntax is gpow"(x,y,prec)".
1242 Euler
1244 Euler's constant "gamma = 0.57721...". Note that "Euler" is one of the
1245 few special reserved names which cannot be used for variables (the
1246 others are "I" and "Pi", as well as all function names).
1247 The library syntax is mpeuler"(prec)" where "prec" \emph{must} be
1249 given. Note that this creates "gamma" on the PARI stack, but a copy is
1250 also created on the heap for quicker computations next time the
1251 function is called.
1252 I
1254 the complex number " sqrt {-1}".
1255 The library syntax is the global variable "gi" (of type "GEN").
1257 Pi
1259 the constant "Pi" (3.14159...).
1260 The library syntax is mppi"(prec)" where "prec" \emph{must} be given.
1262 Note that this creates "Pi" on the PARI stack, but a copy is also
1263 created on the heap for quicker computations next time the function is
1264 called.
1265 abs"(x)"
1267 absolute value of "x" (modulus if "x" is complex). Rational functions
1268 are not allowed. Contrary to most transcendental functions, an exact
1269 argument is \emph{not} converted to a real number before applying "abs"
1270 and an exact result is returned if possible.
1271 ? abs(-1)
1273 %1 = 1
1274 ? abs(3/7 + 4/7*I)
1275 %2 = 5/7
1276 ? abs(1 + I)
1277 %3 = 1.414213562373095048801688724
1278 If "x" is a polynomial, returns "-x" if the leading coefficient is real
1280 and negative else returns "x". For a power series, the constant
1281 coefficient is considered instead.
1282 The library syntax is gabs"(x,prec)".
1284 acos"(x)"
1286 principal branch of "cos^{-1}(x)", i.e. such that "Re(acos(x)) belongs
1287 to [0,Pi]". If "x belongs to R" and "|x| > 1", then acos(x) is complex.
1288 The library syntax is gacos"(x,prec)".
1290 acosh"(x)"
1292 principal branch of "cosh^{-1}(x)", i.e. such that "Im(acosh(x))
1293 belongs to [0,Pi]". If "x belongs to R" and "x < 1", then acosh(x) is
1294 complex.
1295 The library syntax is gach"(x,prec)".
1297 agm"(x,y)"
1299 arithmetic-geometric mean of "x" and "y". In the case of complex or
1300 negative numbers, the principal square root is always chosen. "p"-adic
1301 or power series arguments are also allowed. Note that a "p"-adic agm
1302 exists only if "x/y" is congruent to 1 modulo "p" (modulo 16 for "p =
1303 2"). "x" and "y" cannot both be vectors or matrices.
1304 The library syntax is agm"(x,y,prec)".
1306 arg"(x)"
1308 argument of the complex number "x", such that "-Pi < arg(x) <= Pi".
1309 The library syntax is garg"(x,prec)".
1311 asin"(x)"
1313 principal branch of "sin^{-1}(x)", i.e. such that "Re(asin(x)) belongs
1314 to [-Pi/2,Pi/2]". If "x belongs to R" and "|x| > 1" then asin(x) is
1315 complex.
1316 The library syntax is gasin"(x,prec)".
1318 asinh"(x)"
1320 principal branch of "sinh^{-1}(x)", i.e. such that "Im(asinh(x))
1321 belongs to [-Pi/2,Pi/2]".
1322 The library syntax is gash"(x,prec)".
1324 atan"(x)"
1326 principal branch of "tan^{-1}(x)", i.e. such that "Re(atan(x)) belongs
1327 to ]-Pi/2,Pi/2[".
1328 The library syntax is gatan"(x,prec)".
1330 atanh"(x)"
1332 principal branch of "tanh^{-1}(x)", i.e. such that "Im(atanh(x))
1333 belongs to ]-Pi/2,Pi/2]". If "x belongs to R" and "|x| > 1" then
1334 atanh(x) is complex.
1335 The library syntax is gath"(x,prec)".
1337 bernfrac"(x)"
1339 Bernoulli number "B_x", where "B_0 = 1", "B_1 = -1/2", "B_2 = 1/6",...,
1340 expressed as a rational number. The argument "x" should be of type
1341 integer.
1342 The library syntax is bernfrac"(x)".
1344 bernreal"(x)"
1346 Bernoulli number "B_x", as "bernfrac", but "B_x" is returned as a real
1347 number (with the current precision).
1348 The library syntax is bernreal"(x,prec)".
1350 bernvec"(x)"
1352 creates a vector containing, as rational numbers, the Bernoulli numbers
1353 "B_0", "B_2",..., "B_{2x}". This routine is obsolete. Use "bernfrac"
1354 instead each time you need a Bernoulli number in exact form.
1355 Note: this routine is implemented using repeated independent calls to
1357 "bernfrac", which is faster than the standard recursion in exact
1358 arithmetic. It is only kept for backward compatibility: it is not
1359 faster than individual calls to "bernfrac", its output uses a lot of
1360 memory space, and coping with the index shift is awkward.
1361 The library syntax is bernvec"(x)".
1363 besselh1"(nu,x)"
1365 "H^1"-Bessel function of index nu and argument "x".
1366 The library syntax is hbessel1"(nu,x,prec)".
1368 besselh2"(nu,x)"
1370 "H^2"-Bessel function of index nu and argument "x".
1371 The library syntax is hbessel2"(nu,x,prec)".
1373 besseli"(nu,x)"
1375 "I"-Bessel function of index nu and argument "x". If "x" converts to a
1376 power series, the initial factor "(x/2)^nu/Gamma(nu+1)" is omitted
1377 (since it cannot be represented in PARI when "nu" is not integral).
1378 The library syntax is ibessel"(nu,x,prec)".
1380 besselj"(nu,x)"
1382 "J"-Bessel function of index nu and argument "x". If "x" converts to a
1383 power series, the initial factor "(x/2)^nu/Gamma(nu+1)" is omitted
1384 (since it cannot be represented in PARI when "nu" is not integral).
1385 The library syntax is jbessel"(nu,x,prec)".
1387 besseljh"(n,x)"
1389 "J"-Bessel function of half integral index. More precisely,
1390 "besseljh(n,x)" computes "J_{n+1/2}(x)" where "n" must be of type
1391 integer, and "x" is any element of C. In the present version 2.2.0,
1392 this function is not very accurate when "x" is small.
1393 The library syntax is jbesselh"(n,x,prec)".
1395 besselk"(nu,x,{flag = 0})"
1397 "K"-Bessel function of index nu (which can be complex) and argument
1398 "x". Only real and positive arguments "x" are allowed in the present
1399 version 2.2.0. If "flag" is equal to 1, uses another implementation of
1400 this function which is faster when "x\gg 1".
1401 The library syntax is kbessel"(nu,x,prec)" and " kbessel2(nu,x,prec)"
1403 respectively.
1404 besseln"(nu,x)"
1406 "N"-Bessel function of index nu and argument "x".
1407 The library syntax is nbessel"(nu,x,prec)".
1409 cos"(x)"
1411 cosine of "x".
1412 The library syntax is gcos"(x,prec)".
1414 cosh"(x)"
1416 hyperbolic cosine of "x".
1417 The library syntax is gch"(x,prec)".
1419 cotan"(x)"
1421 cotangent of "x".
1422 The library syntax is gcotan"(x,prec)".
1424 dilog"(x)"
1426 principal branch of the dilogarithm of "x", i.e. analytic continuation
1427 of the power series " log _2(x) = sum_{n >= 1}x^n/n^2".
1428 The library syntax is dilog"(x,prec)".
1430 eint1"(x,{n})"
1432 exponential integral "int_x^ oo (e^{-t})/(t)dt" ("x belongs to R")
1433 If "n" is present, outputs the "n"-dimensional vector
1435 "[eint1(x),...,eint1(nx)]" ("x >= 0"). This is faster than repeatedly
1436 calling "eint1(i * x)".
1437 The library syntax is veceint1"(x,n,prec)". Also available is "
1439 eint1(x,prec)".
1440 erfc"(x)"
1442 complementary error function "(2/ sqrt Pi)int_x^ oo e^{-t^2}dt" ("x
1443 belongs to R").
1444 The library syntax is erfc"(x,prec)".
1446 eta"(x,{flag = 0})"
1448 Dedekind's "eta" function, without the "q^{1/24}". This means the
1449 following: if "x" is a complex number with positive imaginary part, the
1450 result is "prod_{n = 1}^ oo (1-q^n)", where "q = e^{2iPi x}". If "x" is
1451 a power series (or can be converted to a power series) with positive
1452 valuation, the result is "prod_{n = 1}^ oo (1-x^n)".
1453 If "flag = 1" and "x" can be converted to a complex number (i.e. is not
1455 a power series), computes the true "eta" function, including the
1456 leading "q^{1/24}".
1457 The library syntax is eta"(x,prec)".
1459 exp"(x)"
1461 exponential of "x". "p"-adic arguments with positive valuation are
1462 accepted.
1463 The library syntax is gexp"(x,prec)".
1465 gammah"(x)"
1467 gamma function evaluated at the argument "x+1/2".
1468 The library syntax is ggamd"(x,prec)".
1470 gamma"(x)"
1472 gamma function of "x".
1473 The library syntax is ggamma"(x,prec)".
1475 hyperu"(a,b,x)"
1477 "U"-confluent hypergeometric function with parameters "a" and "b". The
1478 parameters "a" and "b" can be complex but the present implementation
1479 requires "x" to be positive.
1480 The library syntax is hyperu"(a,b,x,prec)".
1482 incgam"(s,x,{y})"
1484 incomplete gamma function. The argument "x" and "s" are complex numbers
1485 ("x" must be a positive real number if "s = 0"). The result returned
1486 is "int_x^ oo e^{-t}t^{s-1}dt". When "y" is given, assume (of course
1487 without checking!) that "y = Gamma(s)". For small "x", this will speed
1488 up the computation.
1489 The library syntax is incgam"(s,x,prec)" and " incgam0(s,x,y,prec)",
1491 respectively (an omitted "y" is coded as "NULL").
1492 incgamc"(s,x)"
1494 complementary incomplete gamma function. The arguments "x" and "s" are
1495 complex numbers such that "s" is not a pole of "Gamma" and
1496 "|x|/(|s|+1)" is not much larger than 1 (otherwise the convergence is
1497 very slow). The result returned is "int_0^x e^{-t}t^{s-1}dt".
1498 The library syntax is incgamc"(s,x,prec)".
1500 log"(x)"
1502 principal branch of the natural logarithm of "x", i.e. such that
1503 "Im(log(x)) belongs to ]-Pi,Pi]". The result is complex (with
1504 imaginary part equal to "Pi") if "x belongs to R" and "x < 0". In
1505 general, the algorithm uses the formula
1506 " log (x) ~ (Pi)/(2agm(1, 4/s)) - m log 2, "
1508 if "s = x 2^m" is large enough. (The result is exact to "B" bits
1510 provided "s > 2^{B/2}".) At low accuracies, the series expansion near 1
1511 is used.
1512 "p"-adic arguments are also accepted for "x", with the convention that
1514 " log (p) = 0". Hence in particular " exp ( log (x))/x" is not in
1515 general equal to 1 but to a "(p-1)"-th root of unity (or "+-1" if "p =
1516 2") times a power of "p".
1517 The library syntax is glog"(x,prec)".
1519 lngamma"(x)"
1521 principal branch of the logarithm of the gamma function of "x". This
1522 function is analytic on the complex plane with non-positive integers
1523 removed. Can have much larger arguments than "gamma" itself. The
1524 "p"-adic "lngamma" function is not implemented.
1525 The library syntax is glngamma"(x,prec)".
1527 polylog"(m,x,{flag = 0})"
1529 one of the different polylogarithms, depending on flag:
1530 If "flag = 0" or is omitted: "m^th" polylogarithm of "x", i.e. analytic
1532 continuation of the power series "Li_m(x) = sum_{n >= 1}x^n/n^m" ("x <
1533 1"). Uses the functional equation linking the values at "x" and "1/x"
1534 to restrict to the case "|x| <= 1", then the power series when "|x|^2
1535 <= 1/2", and the power series expansion in " log (x)" otherwise.
1536 Using "flag", computes a modified "m^th" polylogarithm of "x". We use
1538 Zagier's notations; let " Re _m" denotes " Re " or " Im " depending
1539 whether "m" is odd or even:
1540 If "flag = 1": compute "~ D_m(x)", defined for "|x| <= 1" by
1542 " Re _m(sum_{k = 0}^{m-1} ((- log |x|)^k)/(k!)Li_{m-k}(x) +((- log
1544 |x|)^{m-1})/(m!) log |1-x|)."
1545 If "flag = 2": compute D_m(x), defined for "|x| <= 1" by
1547 " Re _m(sum_{k = 0}^{m-1}((- log |x|)^k)/(k!)Li_{m-k}(x) -(1)/(2)((-
1549 log |x|)^m)/(m!))."
1550 If "flag = 3": compute P_m(x), defined for "|x| <= 1" by
1552 " Re _m(sum_{k = 0}^{m-1}(2^kB_k)/(k!)( log |x|)^kLi_{m-k}(x)
1554 -(2^{m-1}B_m)/(m!)( log |x|)^m)."
1555 These three functions satisfy the functional equation "f_m(1/x) =
1557 (-1)^{m-1}f_m(x)".
1558 The library syntax is polylog0"(m,x,flag,prec)".
1560 psi"(x)"
1562 the "psi"-function of "x", i.e. the logarithmic derivative
1563 "Gamma'(x)/Gamma(x)".
1564 The library syntax is gpsi"(x,prec)".
1566 sin"(x)"
1568 sine of "x".
1569 The library syntax is gsin"(x,prec)".
1571 sinh"(x)"
1573 hyperbolic sine of "x".
1574 The library syntax is gsh"(x,prec)".
1576 sqr"(x)"
1578 square of "x". This operation is not completely straightforward,
1579 i.e. identical to "x * x", since it can usually be computed more
1580 efficiently (roughly one-half of the elementary multiplications can be
1581 saved). Also, squaring a 2-adic number increases its precision. For
1582 example,
1583 ? (1 + O(2^4))^2
1585 %1 = 1 + O(2^5)
1586 ? (1 + O(2^4)) * (1 + O(2^4))
1587 %2 = 1 + O(2^4)
1588 Note that this function is also called whenever one multiplies two
1590 objects which are known to be \emph{identical}, e.g. they are the value
1591 of the same variable, or we are computing a power.
1592 ? x = (1 + O(2^4)); x * x
1594 %3 = 1 + O(2^5)
1595 ? (1 + O(2^4))^4
1596 %4 = 1 + O(2^6)
1597 (note the difference between %2 and %3 above).
1599 The library syntax is gsqr"(x)".
1601 sqrt"(x)"
1603 principal branch of the square root of "x", i.e. such that
1604 "Arg(sqrt(x)) belongs to ]-Pi/2, Pi/2]", or in other words such that "
1605 Re (sqrt(x)) > 0" or " Re (sqrt(x)) = 0" and " Im (sqrt(x)) >= 0". If
1606 "x belongs to R" and "x < 0", then the result is complex with positive
1607 imaginary part.
1608 Intmod a prime and "p"-adics are allowed as arguments. In that case,
1610 the square root (if it exists) which is returned is the one whose first
1611 "p"-adic digit (or its unique "p"-adic digit in the case of intmods) is
1612 in the interval "[0,p/2]". When the argument is an intmod a non-prime
1613 (or a non-prime-adic), the result is undefined.
1614 The library syntax is gsqrt"(x,prec)".
1616 sqrtn"(x,n,{&z})"
1618 principal branch of the "n"th root of "x", i.e. such that "Arg(sqrt(x))
1619 belongs to ]-Pi/n, Pi/n]". Intmod a prime and "p"-adics are allowed as
1620 arguments.
1621 If "z" is present, it is set to a suitable root of unity allowing to
1623 recover all the other roots. If it was not possible, z is set to zero.
1624 In the case this argument is present and no square root exist, 0 is
1625 returned instead or raising an error.
1626 ? sqrtn(Mod(2,7), 2)
1628 %1 = Mod(4, 7)
1629 ? sqrtn(Mod(2,7), 2, &z); z
1630 %2 = Mod(6, 7)
1631 ? sqrtn(Mod(2,7), 3)
1632 *** sqrtn: nth-root does not exist in gsqrtn.
1633 ? sqrtn(Mod(2,7), 3, &z)
1634 %2 = 0
1635 ? z
1636 %3 = 0
1637 The following script computes all roots in all possible cases:
1639 sqrtnall(x,n)=
1641 {
1642 local(V,r,z,r2);
1643 r = sqrtn(x,n, &z);
1644 if (!z, error("Impossible case in sqrtn"));
1645 if (type(x) == "t_INTMOD" || type(x)=="t_PADIC" ,
1646 r2 = r*z; n = 1;
1647 while (r2!=r, r2*=z;n++));
1648 V = vector(n); V[1] = r;
1649 for(i=2, n, V[i] = V[i-1]*z);
1650 V
1651 }
1652 addhelp(sqrtnall,"sqrtnall(x,n):compute the vector of nth-roots of x");
1653 The library syntax is gsqrtn"(x,n,&z,prec)".
1655 tan"(x)"
1657 tangent of "x".
1658 The library syntax is gtan"(x,prec)".
1660 tanh"(x)"
1662 hyperbolic tangent of "x".
1663 The library syntax is gth"(x,prec)".
1665 teichmuller"(x)"
1667 Teichmüller character of the "p"-adic number "x", i.e. the unique
1668 "(p-1)"-th root of unity congruent to "x / p^{v_p(x)}" modulo "p".
1669 The library syntax is teich"(x)".
1671 theta"(q,z)"
1673 Jacobi sine theta-function.
1674 The library syntax is theta"(q,z,prec)".
1676 thetanullk"(q,k)"
1678 "k"-th derivative at "z = 0" of "theta(q,z)".
1679 The library syntax is thetanullk"(q,k,prec)", where "k" is a "long".
1681 weber"(x,{flag = 0})"
1683 one of Weber's three "f" functions. If "flag = 0", returns
1684 "f(x) = exp (-iPi/24).eta((x+1)/2)/eta(x) such that j =
1686 (f^{24}-16)^3/f^{24},"
1687 where "j" is the elliptic "j"-invariant (see the function "ellj"). If
1689 "flag = 1", returns
1690 "f_1(x) = eta(x/2)/eta(x) such that j = (f_1^{24}+16)^3/f_1^{24}."
1692 Finally, if "flag = 2", returns
1694 "f_2(x) = sqrt {2}eta(2x)/eta(x) such that j =
1696 (f_2^{24}+16)^3/f_2^{24}."
1697 Note the identities "f^8 = f_1^8+f_2^8" and "ff_1f_2 = sqrt 2".
1699 The library syntax is weber0"(x,flag,prec)". Associated to the various
1701 values of flag, the following functions are also available: "
1702 werberf(x,prec)", " werberf1(x,prec)" or " werberf2(x,prec)".
1703 zeta"(s)"
1705 For "s" a complex number, Riemann's zeta function "zeta(s) = sum_{n >=
1706 1}n^{-s}", computed using the Euler-Maclaurin summation formula, except
1707 when "s" is of type integer, in which case it is computed using
1708 Bernoulli numbers for "s <= 0" or "s > 0" and even, and using modular
1709 forms for "s > 0" and odd.
1710 For "s" a "p"-adic number, Kubota-Leopoldt zeta function at "s", that
1712 is the unique continuous "p"-adic function on the "p"-adic integers
1713 that interpolates the values of "(1 - p^{-k}) zeta(k)" at negative
1714 integers "k" such that "k = 1 (mod p-1)" (resp. "k" is odd) if "p" is
1715 odd (resp. "p = 2").
1716 The library syntax is gzeta"(s,prec)".
1718
1720 These functions are by definition functions whose natural domain of
1721 definition is either Z (or "Z_{ > 0}"), or sometimes polynomials over a
1722 base ring. Functions which concern polynomials exclusively will be
1723 explained in the next section. The way these functions are used is
1724 completely different from transcendental functions: in general only the
1725 types integer and polynomial are accepted as arguments. If a vector or
1726 matrix type is given, the function will be applied on each coefficient
1727 independently.
1728 In the present version 2.2.0, all arithmetic functions in the narrow
1730 sense of the word --- Euler's totient function, the Moebius function,
1731 the sums over divisors or powers of divisors etc.--- call, after trial
1732 division by small primes, the same versatile factoring machinery
1733 described under "factorint". It includes Shanks SQUFOF, Pollard Rho,
1734 ECM and MPQS stages, and has an early exit option for the functions
1735 moebius and (the integer function underlying) issquarefree. Note that
1736 it relies on a (fairly strong) probabilistic primality test, see
1737 "ispseudoprime".
1738 addprimes"({x = []})"
1740 adds the integers contained in the vector "x" (or the single integer
1741 "x") to a special table of ``user-defined primes'', and returns that
1742 table. Whenever "factor" is subsequently called, it will trial divise
1743 by the elements in this table. If "x" is empty or omitted, just
1744 returns the current list of extra primes.
1745 The entries in "x" are not checked for primality, and in fact they need
1747 only be positive integers. The algorithm makes sure that all elements
1748 in the table are pairwise coprime, so it may end up containing divisors
1749 of the input integers.
1750 It is a useful trick to add known composite numbers, which the function
1752 "factor(x,0)" was not able to factor. In case the message ``impossible
1753 inverse modulo "<"some INTMOD">"'' shows up afterwards, you have just
1754 stumbled over a non-trivial factor. Note that the arithmetic functions
1755 in the narrow sense, like eulerphi, do \emph{not} use this extra table.
1756 To remove primes from the list use "removeprimes".
1758 The library syntax is addprimes"(x)".
1760 bestappr"(x,A,{B})"
1762 if "B" is omitted, finds the best rational approximation to "x belongs
1763 to R" (or "R[X]", or "R^n",...) with denominator at most equal to "A"
1764 using continued fractions.
1765 If "B" is present, "x" is assumed to be of type "t_INTMOD" modulo "M"
1767 (or a recursive combination of those), and the routine returns the
1768 unique fraction "a/b" in coprime integers "a <= A" and "b <= B" which
1769 is congruent to "x" modulo "M". If "M <= 2AB", uniqueness is not
1770 guaranteed and the function fails with an error message. If rational
1771 reconstruction is not possible (no such "a/b" exists for at least one
1772 component of "x"), returns "-1".
1773 The library syntax is bestappr0"(x,A,B)". Also available is "
1775 bestappr(x,A)" corresponding to an omitted "B".
1776 bezout"(x,y)"
1778 finds "u" and "v" minimal in a natural sense such that "x*u+y*v =
1779 gcd(x,y)". The arguments must be both integers or both polynomials, and
1780 the result is a row vector with three components "u", "v", and
1781 "gcd(x,y)".
1782 The library syntax is vecbezout"(x,y)" to get the vector, or "
1784 gbezout(x,y, &u, &v)" which gives as result the address of the created
1785 gcd, and puts the addresses of the corresponding created objects into
1786 "u" and "v".
1787 bezoutres"(x,y)"
1789 as "bezout", with the resultant of "x" and "y" replacing the gcd. The
1790 algorithm uses (subresultant) assumes the base ring is a domain.
1791 The library syntax is vecbezoutres"(x,y)" to get the vector, or "
1793 subresext(x,y, &u, &v)" which gives as result the address of the
1794 created gcd, and puts the addresses of the corresponding created
1795 objects into "u" and "v".
1796 bigomega"(x)"
1798 number of prime divisors of "|x|" counted with multiplicity. "x" must
1799 be an integer.
1800 The library syntax is bigomega"(x)", the result is a "long".
1802 binomial"(x,y)"
1804 binomial coefficient "\binom{x}{y}". Here "y" must be an integer, but
1805 "x" can be any PARI object.
1806 The library syntax is binomial"(x,y)", where "y" must be a "long".
1808 chinese"(x,{y})"
1810 if "x" and "y" are both intmods or both polmods, creates (with the same
1811 type) a "z" in the same residue class as "x" and in the same residue
1812 class as "y", if it is possible.
1813 This function also allows vector and matrix arguments, in which case
1815 the operation is recursively applied to each component of the vector or
1816 matrix. For polynomial arguments, it is applied to each coefficient.
1817 If "y" is omitted, and "x" is a vector, "chinese" is applied
1819 recursively to the components of "x", yielding a residue belonging to
1820 the same class as all components of "x".
1821 Finally "chinese(x,x) = x" regardless of the type of "x"; this allows
1823 vector arguments to contain other data, so long as they are identical
1824 in both vectors.
1825 The library syntax is chinese"(x,y)". Also available is
1827 "chinese1""(x)", corresponding to an ommitted "y".
1828 content"(x)"
1830 computes the gcd of all the coefficients of "x", when this gcd makes
1831 sense. This is the natural definition if "x" is a polynomial (and by
1832 extension a power series) or a vector/matrix. This is in general a
1833 weaker notion than the \emph{ideal} generated by the coefficients:
1834 ? content(2*x+y)
1836 %1 = 1 \\ = gcd(2,y) over Q[y]
1837 If "x" is a scalar, this simply returns the absolute value of "x" if
1839 "x" is rational ("t_INT" or "t_FRAC"), and either 1 (inexact input) or
1840 "x" (exact input) otherwise; the result should be identical to "gcd(x,
1841 0)".
1842 The content of a rational function is the ratio of the contents of the
1844 numerator and the denominator. In recursive structures, if a matrix or
1845 vector \emph{coefficient} "x" appears, the gcd is taken not with "x",
1846 but with its content:
1847 ? content([ [2], 4*matid(3) ])
1849 %1 = 2
1850 The library syntax is content"(x)".
1852 contfrac"(x,{b},{nmax})"
1854 creates the row vector whose components are the partial quotients of
1855 the continued fraction expansion of "x". That is a result
1856 "[a_0,...,a_n]" means that "x ~ a_0+1/(a_1+...+1/a_n)...)". The output
1857 is normalized so that "a_n ! = 1" (unless we also have "n = 0").
1858 The number of partial quotients "n" is limited to "nmax". If "x" is a
1860 real number, the expansion stops at the last significant partial
1861 quotient if "nmax" is omitted. "x" can also be a rational function or a
1862 power series.
1863 If a vector "b" is supplied, the numerators will be equal to the
1865 coefficients of "b" (instead of all equal to 1 as above). The length of
1866 the result is then equal to the length of "b", unless a partial
1867 remainder is encountered which is equal to zero, in which case the
1868 expansion stops. In the case of real numbers, the stopping criterion is
1869 thus different from the one mentioned above since, if "b" is too long,
1870 some partial quotients may not be significant.
1871 If "b" is an integer, the command is understood as "contfrac(x,nmax)".
1873 The library syntax is contfrac0"(x,b,nmax)". Also available are "
1875 gboundcf(x,nmax)", " gcf(x)", or " gcf2(b,x)", where "nmax" is a C
1876 integer.
1877 contfracpnqn"(x)"
1879 when "x" is a vector or a one-row matrix, "x" is considered as the list
1880 of partial quotients "[a_0,a_1,...,a_n]" of a rational number, and the
1881 result is the 2 by 2 matrix "[p_n,p_{n-1};q_n,q_{n-1}]" in the standard
1882 notation of continued fractions, so "p_n/q_n =
1883 a_0+1/(a_1+...+1/a_n)...)". If "x" is a matrix with two rows
1884 "[b_0,b_1,...,b_n]" and "[a_0,a_1,...,a_n]", this is then considered as
1885 a generalized continued fraction and we have similarly "p_n/q_n =
1886 1/b_0(a_0+b_1/(a_1+...+b_n/a_n)...)". Note that in this case one
1887 usually has "b_0 = 1".
1888 The library syntax is pnqn"(x)".
1890 core"(n,{flag = 0})"
1892 if "n" is a non-zero integer written as "n = df^2" with "d" squarefree,
1893 returns "d". If "flag" is non-zero, returns the two-element row vector
1894 "[d,f]".
1895 The library syntax is core0"(n,flag)". Also available are " core(n)" (
1897 = " core0(n,0)") and " core2(n)" ( = " core0(n,1)").
1898 coredisc"(n,{flag})"
1900 if "n" is a non-zero integer written as "n = df^2" with "d" fundamental
1901 discriminant (including 1), returns "d". If "flag" is non-zero, returns
1902 the two-element row vector "[d,f]". Note that if "n" is not congruent
1903 to 0 or 1 modulo 4, "f" will be a half integer and not an integer.
1904 The library syntax is coredisc0"(n,flag)". Also available are "
1906 coredisc(n)" ( = " coredisc(n,0)") and " coredisc2(n)" ( = "
1907 coredisc(n,1)").
1908 dirdiv"(x,y)"
1910 "x" and "y" being vectors of perhaps different lengths but with "y[1] !
1911 = 0" considered as Dirichlet series, computes the quotient of "x" by
1912 "y", again as a vector.
1913 The library syntax is dirdiv"(x,y)".
1915 direuler"(p = a,b,expr,{c})"
1917 computes the Dirichlet series associated to the Euler product of
1918 expression expr as "p" ranges through the primes from "a" to "b". expr
1919 must be a polynomial or rational function in another variable than "p"
1920 (say "X") and "expr(X)" is understood as the local factor
1921 "expr(p^{-s})".
1922 The series is output as a vector of coefficients. If "c" is present,
1924 output only the first "c" coefficients in the series. The following
1925 command computes the sigma function, associated to "zeta(s)zeta(s-1)":
1926 ? direuler(p=2, 10, 1/((1-X)*(1-p*X)))
1928 %1 = [1, 3, 4, 7, 6, 12, 8, 15, 13, 18]
1929 The library syntax is direuler"(void *E, GEN (*eval)(GEN,void*), GEN a,
1931 GEN b)"
1932 dirmul"(x,y)"
1934 "x" and "y" being vectors of perhaps different lengths considered as
1935 Dirichlet series, computes the product of "x" by "y", again as a
1936 vector.
1937 The library syntax is dirmul"(x,y)".
1939 divisors"(x)"
1941 creates a row vector whose components are the divisors of "x". The
1942 factorization of "x" (as output by "factor") can be used instead.
1943 By definition, these divisors are the products of the irreducible
1945 factors of "n", as produced by factor(n), raised to appropriate powers
1946 (no negative exponent may occur in the factorization). If "n" is an
1947 integer, they are the positive divisors, in increasing order.
1948 The library syntax is divisors"(x)".
1950 eulerphi"(x)"
1952 Euler's "phi" (totient) function of "|x|", in other words "|(Z/xZ)^*|".
1953 "x" must be of type integer.
1954 The library syntax is phi"(x)".
1956 factor"(x,{lim = -1})"
1958 general factorization function. If "x" is of type integer, rational,
1959 polynomial or rational function, the result is a two-column matrix, the
1960 first column being the irreducibles dividing "x" (prime numbers or
1961 polynomials), and the second the exponents. If "x" is a vector or a
1962 matrix, the factoring is done componentwise (hence the result is a
1963 vector or matrix of two-column matrices). By definition, 0 is factored
1964 as "0^1".
1965 If "x" is of type integer or rational, the factors are pseudoprimes
1967 (see "ispseudoprime"), and in general not rigorously proven primes. In
1968 fact, any factor which is " <= 10^{13}" is a genuine prime number. Use
1969 "isprime" to prove primality of other factors, as in
1970 fa = factor(2^2^7 +1)
1972 isprime( fa[,1] )
1973 An argument lim can be added, meaning that we look only for prime
1975 factors "p < lim", or up to "primelimit", whichever is lowest (except
1976 when "lim = 0" where the effect is identical to setting "lim =
1977 primelimit"). In this case, the remaining part may actually be a proven
1978 composite! See "factorint" for more information about the algorithms
1979 used.
1980 The polynomials or rational functions to be factored must have scalar
1982 coefficients. In particular PARI does \emph{not} know how to factor
1983 multivariate polynomials. See "factormod" and "factorff" for the
1984 algorithms used over finite fields, "factornf" for the algorithms over
1985 number fields. Over Q, van Hoeij's method is used, which is able to
1986 cope with hundreds of modular factors.
1987 Note that PARI tries to guess in a sensible way over which ring you
1989 want to factor. Note also that factorization of polynomials is done up
1990 to multiplication by a constant. In particular, the factors of rational
1991 polynomials will have integer coefficients, and the content of a
1992 polynomial or rational function is discarded and not included in the
1993 factorization. If needed, you can always ask for the content
1994 explicitly:
1995 ? factor(t^2 + 5/2*t + 1)
1997 %1 =
1998 [2*t + 1 1]
1999 [t + 2 1]
2001 ? content(t^2 + 5/2*t + 1)
2003 %2 = 1/2
2004 See also "factornf" and "nffactor".
2006 The library syntax is factor0"(x,lim)", where lim is a C integer. Also
2008 available are " factor(x)" ( = " factor0(x,-1)"), " smallfact(x)" ( = "
2009 factor0(x,0)").
2010 factorback"(f,{e},{nf})"
2012 gives back the factored object corresponding to a factorization. The
2013 integer 1 corresponds to the empty factorization. If the last argument
2014 is of number field type (e.g. created by "nfinit"), assume we are
2015 dealing with an ideal factorization in the number field. The resulting
2016 ideal product is given in HNF form.
2017 If "e" is present, "e" and "f" must be vectors of the same length ("e"
2019 being integral), and the corresponding factorization is the product of
2020 the "f[i]^{e[i]}".
2021 If not, and "f" is vector, it is understood as in the preceding case
2023 with "e" a vector of 1 (the product of the "f[i]" is returned).
2024 Finally, "f" can be a regular factorization, as produced with any
2025 "factor" command. A few examples:
2026 ? factorback([2,2; 3,1])
2028 %1 = 12
2029 ? factorback([2,2], [3,1])
2030 %2 = 12
2031 ? factorback([5,2,3])
2032 %3 = 30
2033 ? factorback([2,2], [3,1], nfinit(x^3+2))
2034 %4 =
2035 [16 0 0]
2036 [0 16 0]
2038 [0 0 16]
2040 ? nf = nfinit(x^2+1); fa = idealfactor(nf, 10)
2041 %5 =
2042 [[2, [1, 1]~, 2, 1, [1, 1]~] 2]
2043 [[5, [-2, 1]~, 1, 1, [2, 1]~] 1]
2045 [[5, [2, 1]~, 1, 1, [-2, 1]~] 1]
2047 ? factorback(fa)
2048 *** forbidden multiplication t_VEC * t_VEC.
2049 ? factorback(fa, nf)
2050 %6 =
2051 [10 0]
2052 [0 10]
2054 In the fourth example, 2 and 3 are interpreted as principal ideals in a
2056 cubic field. In the fifth one, "factorback(fa)" is meaningless since we
2057 forgot to indicate the number field, and the entries in the first
2058 column of "fa" can't be multiplied.
2059 The library syntax is factorback0"(f,e,nf)", where an omitted "nf" or
2061 "e" is entered as "NULL". Also available is "factorback""(f,nf)" (case
2062 "e = NULL") where an omitted "nf" is entered as "NULL".
2063 factorcantor"(x,p)"
2065 factors the polynomial "x" modulo the prime "p", using distinct degree
2066 plus Cantor-Zassenhaus. The coefficients of "x" must be operation-
2067 compatible with "Z/pZ". The result is a two-column matrix, the first
2068 column being the irreducible polynomials dividing "x", and the second
2069 the exponents. If you want only the \emph{degrees} of the irreducible
2070 polynomials (for example for computing an "L"-function), use
2071 "factormod(x,p,1)". Note that the "factormod" algorithm is usually
2072 faster than "factorcantor".
2073 The library syntax is factcantor"(x,p)".
2075 factorff"(x,p,a)"
2077 factors the polynomial "x" in the field "F_q" defined by the
2078 irreducible polynomial "a" over "F_p". The coefficients of "x" must be
2079 operation-compatible with "Z/pZ". The result is a two-column matrix:
2080 the first column contains the irreducible factors of "x", and the
2081 second their exponents. If all the coefficients of "x" are in "F_p", a
2082 much faster algorithm is applied, using the computation of isomorphisms
2083 between finite fields.
2084 The library syntax is factorff"(x,p,a)".
2086 factorial"(x)" or "x!"
2088 factorial of "x". The expression "x!" gives a result which is an
2089 integer, while factorial(x) gives a real number.
2090 The library syntax is mpfact"(x)" for "x!" and " mpfactr(x,prec)" for
2092 factorial(x). "x" must be a "long" integer and not a PARI integer.
2093 factorint"(n,{flag = 0})"
2095 factors the integer "n" into a product of pseudoprimes (see
2096 "ispseudoprime"), using a combination of the Shanks SQUFOF and Pollard
2097 Rho method (with modifications due to Brent), Lenstra's ECM (with
2098 modifications by Montgomery), and MPQS (the latter adapted from the
2099 LiDIA code with the kind permission of the LiDIA maintainers), as well
2100 as a search for pure powers with exponents" <= 10". The output is a
2101 two-column matrix as for "factor". Use "isprime" on the result if you
2102 want to guarantee primality.
2103 This gives direct access to the integer factoring engine called by most
2105 arithmetical functions. flag is optional; its binary digits mean 1:
2106 avoid MPQS, 2: skip first stage ECM (we may still fall back to it
2107 later), 4: avoid Rho and SQUFOF, 8: don't run final ECM (as a result, a
2108 huge composite may be declared to be prime). Note that a (strong)
2109 probabilistic primality test is used; thus composites might (very
2110 rarely) not be detected.
2111 You are invited to play with the flag settings and watch the internals
2113 at work by using "gp"'s "debuglevel" default parameter (level 3 shows
2114 just the outline, 4 turns on time keeping, 5 and above show an
2115 increasing amount of internal details). If you see anything funny
2116 happening, please let us know.
2117 The library syntax is factorint"(n,flag)".
2119 factormod"(x,p,{flag = 0})"
2121 factors the polynomial "x" modulo the prime integer "p", using
2122 Berlekamp. The coefficients of "x" must be operation-compatible with
2123 "Z/pZ". The result is a two-column matrix, the first column being the
2124 irreducible polynomials dividing "x", and the second the exponents. If
2125 "flag" is non-zero, outputs only the \emph{degrees} of the irreducible
2126 polynomials (for example, for computing an "L"-function). A different
2127 algorithm for computing the mod "p" factorization is "factorcantor"
2128 which is sometimes faster.
2129 The library syntax is factormod"(x,p,flag)". Also available are "
2131 factmod(x,p)" (which is equivalent to " factormod(x,p,0)") and "
2132 simplefactmod(x,p)" ( = " factormod(x,p,1)").
2133 fibonacci"(x)"
2135 "x^{th}" Fibonacci number.
2136 The library syntax is fibo"(x)". "x" must be a "long".
2138 ffinit"(p,n,{v = x})"
2140 computes a monic polynomial of degree "n" which is irreducible over
2141 "F_p". For instance if "P = ffinit(3,2,y)", you can represent elements
2142 in "F_{3^2}" as polmods modulo "P". This function uses a fast variant
2143 of Adleman-Lenstra's algorithm.
2144 The library syntax is ffinit"(p,n,v)", where "v" is a variable number.
2146 gcd"(x,{y})"
2148 creates the greatest common divisor of "x" and "y". "x" and "y" can be
2149 of quite general types, for instance both rational numbers. If "y" is
2150 omitted and "x" is a vector, returns the "gcd" of all components of
2151 "x", i.e. this is equivalent to content(x).
2152 When "x" and "y" are both given and one of them is a vector/matrix
2154 type, the GCD is again taken recursively on each component, but in a
2155 different way. If "y" is a vector, resp. matrix, then the result has
2156 the same type as "y", and components equal to "gcd(x, y[i])",
2157 resp. "gcd(x, y[,i])". Else if "x" is a vector/matrix the result has
2158 the same type as "x" and an analogous definition. Note that for these
2159 types, "gcd" is not commutative.
2160 The algorithm used is a naive Euclid except for the following inputs:
2162 \item integers: use modified right-shift binary (``plus-minus''
2164 variant).
2165 \item univariate polynomials with coeffients in the same number field
2167 (in particular rational): use modular gcd algorithm.
2168 \item general polynomials: use the subresultant algorithm if
2170 coefficient explosion is likely (exact, non modular, coefficients).
2171 The library syntax is ggcd"(x,y)". For general polynomial inputs, "
2173 srgcd(x,y)" is also available. For univariate \emph{rational}
2174 polynomials, one also has " modulargcd(x,y)".
2175 hilbert"(x,y,{p})"
2177 Hilbert symbol of "x" and "y" modulo "p". If "x" and "y" are of type
2178 integer or fraction, an explicit third parameter "p" must be supplied,
2179 "p = 0" meaning the place at infinity. Otherwise, "p" needs not be
2180 given, and "x" and "y" can be of compatible types integer, fraction,
2181 real, intmod a prime (result is undefined if the modulus is not prime),
2182 or "p"-adic.
2183 The library syntax is hil"(x,y,p)".
2185 isfundamental"(x)"
2187 true (1) if "x" is equal to 1 or to the discriminant of a quadratic
2188 field, false (0) otherwise.
2189 The library syntax is gisfundamental"(x)", but the simpler function "
2191 isfundamental(x)" which returns a "long" should be used if "x" is known
2192 to be of type integer.
2193 ispower"(x,{k}, {&n})"
2195 if "k" is given, returns true (1) if "x" is a "k"-th power, false (0)
2196 if not. In this case, "x" may be an integer or polynomial, a rational
2197 number or function, or an intmod a prime or "p"-adic.
2198 If "k" is omitted, only integers and fractions are allowed and the
2200 function returns the maximal "k >= 2" such that "x = n^k" is a perfect
2201 power, or 0 if no such "k" exist; in particular "ispower(-1)",
2202 ispower(0), and ispower(1) all return 0.
2203 If a third argument &n is given and a "k"-th root was computed in the
2205 process, then "n" is set to that root.
2206 The library syntax is ispower"(x, k, &n)", the result is a "long".
2208 Omitted "k" or "n" are coded as "NULL".
2209 isprime"(x,{flag = 0})"
2211 true (1) if "x" is a (proven) prime number, false (0) otherwise. This
2212 can be very slow when "x" is indeed prime and has more than 1000
2213 digits, say. Use "ispseudoprime" to quickly check for pseudo primality.
2214 See also "factor".
2215 If "flag = 0", use a combination of Baillie-PSW pseudo primality test
2217 (see "ispseudoprime"), Selfridge ``"p-1"'' test if "x-1" is smooth
2218 enough, and Adleman-Pomerance-Rumely-Cohen-Lenstra (APRCL) for general
2219 "x".
2220 If "flag = 1", use Selfridge-Pocklington-Lehmer ``"p-1"'' test and
2222 output a primality certificate as follows: return 0 if "x" is
2223 composite, 1 if "x" is small enough that passing Baillie-PSW test
2224 guarantees its primality (currently "x < 10^{13}"), 2 if "x" is a large
2225 prime whose primality could only sensibly be proven (given the
2226 algorithms implemented in PARI) using the APRCL test. Otherwise ("x" is
2227 large and "x-1" is smooth) output a three column matrix as a primality
2228 certificate. The first column contains the prime factors "p" of "x-1",
2229 the second the corresponding elements "a_p" as in Proposition 8.3.1 in
2230 GTM 138, and the third the output of isprime(p,1). The algorithm fails
2231 if one of the pseudo-prime factors is not prime, which is exceedingly
2232 unlikely (and well worth a bug report).
2233 If "flag = 2", use APRCL.
2235 The library syntax is gisprime"(x,flag)", but the simpler function "
2237 isprime(x)" which returns a "long" should be used if "x" is known to be
2238 of type integer.
2239 ispseudoprime"(x,{flag})"
2241 true (1) if "x" is a strong pseudo prime (see below), false (0)
2242 otherwise. If this function returns false, "x" is not prime; if, on the
2243 other hand it returns true, it is only highly likely that "x" is a
2244 prime number. Use "isprime" (which is of course much slower) to prove
2245 that "x" is indeed prime.
2246 If "flag = 0", checks whether "x" is a Baillie-Pomerance-Selfridge-
2248 Wagstaff pseudo prime (strong Rabin-Miller pseudo prime for base 2,
2249 followed by strong Lucas test for the sequence "(P,-1)", "P" smallest
2250 positive integer such that "P^2 - 4" is not a square mod "x").
2251 There are no known composite numbers passing this test (in particular,
2253 all composites " <= 10^{13}" are correctly detected), although it is
2254 expected that infinitely many such numbers exist.
2255 If "flag > 0", checks whether "x" is a strong Miller-Rabin pseudo prime
2257 for "flag" randomly chosen bases (with end-matching to catch square
2258 roots of "-1").
2259 The library syntax is gispseudoprime"(x,flag)", but the simpler
2261 function " ispseudoprime(x)" which returns a "long" should be used if
2262 "x" is known to be of type integer.
2263 issquare"(x,{&n})"
2265 true (1) if "x" is a square, false (0) if not. What ``being a square''
2266 means depends on the type of "x": all "t_COMPLEX" are squares, as well
2267 as all non-negative "t_REAL"; for exact types such as "t_INT", "t_FRAC"
2268 and "t_INTMOD", squares are numbers of the form "s^2" with "s" in Z, Q
2269 and "Z/NZ" respectively.
2270 ? issquare(3) \\ as an integer
2272 %1 = 0
2273 ? issquare(3.) \\ as a real number
2274 %2 = 1
2275 ? issquare(Mod(7, 8)) \\ in Z/8Z
2276 %3 = 0
2277 ? issquare( 5 + O(13^4) ) \\ in Q_13
2278 %4 = 0
2279 If "n" is given and an exact square root had to be computed in the
2281 checking process, puts that square root in "n". This is the case when
2282 "x" is a "t_INT", "t_FRAC", "t_POL" or "t_RFRAC" (or a vector of such
2283 objects):
2284 ? issquare(4, &n)
2286 %1 = 1
2287 ? n
2288 %2 = 2
2289 ? issquare([4, x^2], &n)
2290 %3 = [1, 1] \\ both are squares
2291 ? n
2292 %4 = [2, x] \\ the square roots
2293 This will \emph{not} work for "t_INTMOD" (use quadratic reciprocity) or
2295 "t_SER" (only check the leading coefficient).
2296 The library syntax is gissquarerem"(x,&n)". Also available is "
2298 gissquare(x)".
2299 issquarefree"(x)"
2301 true (1) if "x" is squarefree, false (0) if not. Here "x" can be an
2302 integer or a polynomial.
2303 The library syntax is gissquarefree"(x)", but the simpler function "
2305 issquarefree(x)" which returns a "long" should be used if "x" is known
2306 to be of type integer. This issquarefree is just the square of the
2307 Moebius function, and is computed as a multiplicative arithmetic
2308 function much like the latter.
2309 kronecker"(x,y)"
2311 Kronecker symbol "(x|y)", where "x" and "y" must be of type integer. By
2312 definition, this is the extension of Legendre symbol to "Z x Z" by
2313 total multiplicativity in both arguments with the following special
2314 rules for "y = 0, -1" or 2:
2315 \item "(x|0) = 1" if "|x |= 1" and 0 otherwise.
2317 \item "(x|-1) = 1" if "x >= 0" and "-1" otherwise.
2319 \item "(x|2) = 0" if "x" is even and 1 if "x = 1,-1 mod 8" and "-1" if
2321 "x = 3,-3 mod 8".
2322 The library syntax is kronecker"(x,y)", the result (0 or "+- 1") is a
2324 "long".
2325 lcm"(x,{y})"
2327 least common multiple of "x" and "y", i.e. such that "lcm(x,y)*gcd(x,y)
2328 = abs(x*y)". If "y" is omitted and "x" is a vector, returns the "lcm"
2329 of all components of "x".
2330 When "x" and "y" are both given and one of them is a vector/matrix
2332 type, the LCM is again taken recursively on each component, but in a
2333 different way. If "y" is a vector, resp. matrix, then the result has
2334 the same type as "y", and components equal to "lcm(x, y[i])",
2335 resp. "lcm(x, y[,i])". Else if "x" is a vector/matrix the result has
2336 the same type as "x" and an analogous definition. Note that for these
2337 types, "lcm" is not commutative.
2338 Note that lcm(v) is quite different from
2340 l = v[1]; for (i = 1, #v, l = lcm(l, v[i]))
2342 Indeed, lcm(v) is a scalar, but "l" may not be (if one of the "v[i]" is
2344 a vector/matrix). The computation uses a divide-conquer tree and should
2345 be much more efficient, especially when using the GMP multiprecision
2346 kernel (and more subquadratic algorithms become available):
2347 ? v = vector(10^4, i, random);
2349 ? lcm(v);
2350 time = 323 ms.
2351 ? l = v[1]; for (i = 1, #v, l = lcm(l, v[i]))
2352 time = 833 ms.
2353 The library syntax is glcm"(x,y)".
2355 moebius"(x)"
2357 Moebius "mu"-function of "|x|". "x" must be of type integer.
2358 The library syntax is mu"(x)", the result (0 or "+- 1") is a "long".
2360 nextprime"(x)"
2362 finds the smallest pseudoprime (see "ispseudoprime") greater than or
2363 equal to "x". "x" can be of any real type. Note that if "x" is a
2364 pseudoprime, this function returns "x" and not the smallest pseudoprime
2365 strictly larger than "x". To rigorously prove that the result is prime,
2366 use "isprime".
2367 The library syntax is nextprime"(x)".
2369 numdiv"(x)"
2371 number of divisors of "|x|". "x" must be of type integer.
2372 The library syntax is numbdiv"(x)".
2374 numbpart"(n)"
2376 gives the number of unrestricted partitions of "n", usually called p(n)
2377 in the litterature; in other words the number of nonnegative integer
2378 solutions to "a+2b+3c+.. .= n". "n" must be of type integer and "1 <= n
2379 < 10^{15}". The algorithm uses the Hardy-Ramanujan-Rademacher formula.
2380 The library syntax is numbpart"(n)".
2382 omega"(x)"
2384 number of distinct prime divisors of "|x|". "x" must be of type
2385 integer.
2386 The library syntax is omega"(x)", the result is a "long".
2388 precprime"(x)"
2390 finds the largest pseudoprime (see "ispseudoprime") less than or equal
2391 to "x". "x" can be of any real type. Returns 0 if "x <= 1". Note that
2392 if "x" is a prime, this function returns "x" and not the largest prime
2393 strictly smaller than "x". To rigorously prove that the result is
2394 prime, use "isprime".
2395 The library syntax is precprime"(x)".
2397 prime"(x)"
2399 the "x^{th}" prime number, which must be among the precalculated
2400 primes.
2401 The library syntax is prime"(x)". "x" must be a "long".
2403 primepi"(x)"
2405 the prime counting function. Returns the number of primes "p", "p <=
2406 x". Uses a naive algorithm so that "x" must be less than "primelimit".
2407 The library syntax is primepi"(x)".
2409 primes"(x)"
2411 creates a row vector whose components are the first "x" prime numbers,
2412 which must be among the precalculated primes.
2413 The library syntax is primes"(x)". "x" must be a "long".
2415 qfbclassno"(D,{flag = 0})"
2417 ordinary class number of the quadratic order of discriminant "D". In
2418 the present version 2.2.0, a "O(D^{1/2})" algorithm is used for "D > 0"
2419 (using Euler product and the functional equation) so "D" should not be
2420 too large, say "D < 10^8", for the time to be reasonable. On the other
2421 hand, for "D < 0" one can reasonably compute qfbclassno(D) for "|D| <
2422 10^{25}", since the routine uses Shanks's method which is in
2423 "O(|D|^{1/4})". For larger values of "|D|", see "quadclassunit".
2424 If "flag = 1", compute the class number using Euler products and the
2426 functional equation. However, it is in "O(|D|^{1/2})".
2427 Important warning. For "D < 0", this function may give incorrect
2429 results when the class group has a low exponent (has many cyclic
2430 factors), because implementing Shanks's method in full generality slows
2431 it down immensely. It is therefore strongly recommended to double-check
2432 results using either the version with "flag = 1" or the function
2433 "quadclassunit".
2434 Warning. contrary to what its name implies, this routine does not
2436 compute the number of classes of binary primitive forms of discriminant
2437 "D", which is equal to the \emph{narrow} class number. The two notions
2438 are the same when "D < 0" or the fundamental unit "varepsilon" has
2439 negative norm; when "D > 0" and "Nvarepsilon > 0", the number of
2440 classes of forms is twice the ordinary class number. This is a problem
2441 which we cannot fix for backward compatibility reasons. Use the
2442 following routine if you are only interested in the number of classes
2443 of forms:
2444 QFBclassno(D) =
2446 qfbclassno(D) * if (D < 0 || norm(quadunit(D)) < 0, 1, 2)
2447 Here are a few examples:
2449 %2 = 1
2451 ? qfbclassno(-400000028)
2452 time = 0 ms.
2453 %3 = 7253 \{ much faster}
2454 %2 = 1
2455 ? qfbclassno(-400000028)
2456 time = 0 ms.
2457 %3 = 7253 \{ correct, and fast enough}
2458 ? quadclassunit(-400000028).no
2459 time = 0 ms.
2460 %4 = 7253
2461 The library syntax is qfbclassno0"(D,flag)". Also available: "
2463 classno(D)" ( = " qfbclassno(D)"), " classno2(D)" ( = "
2464 qfbclassno(D,1)"), and finally we have the function " hclassno(D)"
2465 which computes the class number of an imaginary quadratic field by
2466 counting reduced forms, an "O(|D|)" algorithm. See also "qfbhclassno".
2467 qfbcompraw"(x,y)"
2469 composition of the binary quadratic forms "x" and "y", without
2470 reduction of the result. This is useful e.g. to compute a generating
2471 element of an ideal.
2472 The library syntax is compraw"(x,y)".
2474 qfbhclassno"(x)"
2476 Hurwitz class number of "x", where "x" is non-negative and congruent to
2477 0 or 3 modulo 4. For "x > 5. 10^5", we assume the GRH, and use
2478 "quadclassunit" with default parameters.
2479 The library syntax is hclassno"(x)".
2481 qfbnucomp"(x,y,l)"
2483 composition of the primitive positive definite binary quadratic forms
2484 "x" and "y" (type "t_QFI") using the NUCOMP and NUDUPL algorithms of
2485 Shanks, à la Atkin. "l" is any positive constant, but for optimal
2486 speed, one should take "l = |D|^{1/4}", where "D" is the common
2487 discriminant of "x" and "y". When "x" and "y" do not have the same
2488 discriminant, the result is undefined.
2489 The current implementation is straightforward and in general
2491 \emph{slower} than the generic routine (since the latter take
2492 advantadge of asymptotically fast operations and careful
2493 optimizations).
2494 The library syntax is nucomp"(x,y,l)". The auxiliary function "
2496 nudupl(x,l)" can be used when "x = y".
2497 qfbnupow"(x,n)"
2499 "n"-th power of the primitive positive definite binary quadratic form
2500 "x" using Shanks's NUCOMP and NUDUPL algorithms (see "qfbnucomp", in
2501 particular the final warning).
2502 The library syntax is nupow"(x,n)".
2504 qfbpowraw"(x,n)"
2506 "n"-th power of the binary quadratic form "x", computed without doing
2507 any reduction (i.e. using "qfbcompraw"). Here "n" must be non-negative
2508 and "n < 2^{31}".
2509 The library syntax is powraw"(x,n)" where "n" must be a "long" integer.
2511 qfbprimeform"(x,p)"
2513 prime binary quadratic form of discriminant "x" whose first coefficient
2514 is the prime number "p". By abuse of notation, "p = +- 1" is a valid
2515 special case which returns the unit form. Returns an error if "x" is
2516 not a quadratic residue mod "p". In the case where "x > 0", "p < 0" is
2517 allowed, and the ``distance'' component of the form is set equal to
2518 zero according to the current precision. (Note that negative definite
2519 "t_QFI" are not implemented.)
2520 The library syntax is primeform"(x,p,prec)", where the third variable
2522 "prec" is a "long", but is only taken into account when "x > 0".
2523 qfbred"(x,{flag = 0},{D},{isqrtD},{sqrtD})"
2525 reduces the binary quadratic form "x" (updating Shanks's distance
2526 function if "x" is indefinite). The binary digits of "flag" are toggles
2527 meaning
2528 1: perform a single reduction step
2530 2: don't update Shanks's distance
2532 "D", isqrtD, sqrtD, if present, supply the values of the discriminant,
2534 "\floor{ sqrt {D}}", and " sqrt {D}" respectively (no checking is done
2535 of these facts). If "D < 0" these values are useless, and all
2536 references to Shanks's distance are irrelevant.
2537 The library syntax is qfbred0"(x,flag,D,isqrtD,sqrtD)". Use "NULL" to
2539 omit any of "D", isqrtD, sqrtD.
2540 Also available are
2542 " redimag(x)" ( = " qfbred(x)" where "x" is definite),
2544 and for indefinite forms:
2546 " redreal(x)" ( = " qfbred(x)"),
2548 " rhoreal(x)" ( = " qfbred(x,1)"),
2550 " redrealnod(x,sq)" ( = " qfbred(x,2,,isqrtD)"),
2552 " rhorealnod(x,sq)" ( = " qfbred(x,3,,isqrtD)").
2554 qfbsolve"(Q,p)"
2556 Solve the equation "Q(x,y) = p" over the integers, where "Q" is a
2557 binary quadratic form and "p" a prime number.
2558 Return "[x,y]" as a two-components vector, or zero if there is no
2560 solution. Note that this function returns only one solution and not
2561 all the solutions.
2562 Let "D = \disc Q". The algorithm used runs in probabilistic polynomial
2564 time in "p" (through the computation of a square root of "D" modulo
2565 "p"); it is polynomial time in "D" if "Q" is imaginary, but exponential
2566 time if "Q" is real (through the computation of a full cycle of reduced
2567 forms). In the latter case, note that "bnfisprincipal" provides a
2568 solution in heuristic subexponential time in "D" assuming the GRH.
2569 The library syntax is qfbsolve"(Q,n)".
2571 quadclassunit"(D,{flag = 0},{tech = []})"
2573 Buchmann-McCurley's sub-exponential algorithm for computing the class
2574 group of a quadratic order of discriminant "D".
2575 This function should be used instead of "qfbclassno" or "quadregula"
2577 when "D < -10^{25}", "D > 10^{10}", or when the \emph{structure} is
2578 wanted. It is a special case of "bnfinit", which is slower, but more
2579 robust.
2580 If "flag" is non-zero \emph{and} "D > 0", computes the narrow class
2582 group and regulator, instead of the ordinary (or wide) ones. In the
2583 current version 2.2.0, this does not work at all: use the general
2584 function "bnfnarrow".
2585 Optional parameter tech is a row vector of the form "[c_1, c_2]", where
2587 "c_1 <= c_2" are positive real numbers which control the execution time
2588 and the stack size. For a given "c_1", set "c_2 = c_1" to get maximum
2589 speed. To get a rigorous result under GRH, you must take "c_2 >= 6".
2590 Reasonable values for "c_1" are between 0.1 and 2. More precisely, the
2591 algorithm will \emph{assume} that prime ideals of norm less than "c_2 (
2592 log |D|)^2" generate the class group, but the bulk of the work is done
2593 with prime ideals of norm less than "c_1 ( log |D|)^2". A larger "c_1"
2594 means that relations are easier to find, but more relations are needed
2595 and the linear algebra will be harder. The default is "c_1 = c_2 =
2596 0.2", so the result is \emph{not} rigorously proven.
2597 The result is a vector "v" with 3 components if "D < 0", and 4
2599 otherwise. The correspond respectively to
2600 \item "v[1]": the class number
2602 \item "v[2]": a vector giving the structure of the class group as a
2604 product of cyclic groups;
2605 \item "v[3]": a vector giving generators of those cyclic groups (as
2607 binary quadratic forms).
2608 \item "v[4]": (omitted if "D < 0") the regulator, computed to an
2610 accuracy which is the maximum of an internal accuracy determined by the
2611 program and the current default (note that once the regulator is known
2612 to a small accuracy it is trivial to compute it to very high accuracy,
2613 see the tutorial).
2614 The library syntax is quadclassunit0"(D,flag,tech)". Also available are
2616 " buchimag(D,c_1,c_2)" and " buchreal(D,flag,c_1,c_2)".
2617 quaddisc"(x)"
2619 discriminant of the quadratic field "Q( sqrt {x})", where "x belongs to
2620 Q".
2621 The library syntax is quaddisc"(x)".
2623 quadhilbert"(D,{pq})"
2625 relative equation defining the Hilbert class field of the quadratic
2626 field of discriminant "D".
2627 If "D < 0", uses complex multiplication (Schertz's variant). The
2629 technical component "pq", if supplied, is a vector "[p,q]" where "p",
2630 "q" are the prime numbers needed for the Schertz's method. More
2631 precisely, prime ideals above "p" and "q" should be non-principal and
2632 coprime to all reduced representatives of the class group. In addition,
2633 if one of these ideals has order 2 in the class group, they should have
2634 the same class. Finally, for efficiency, "gcd(24,(p-1)(q-1))" should be
2635 as large as possible. The routine returns 0 if "[p,q]" is not
2636 suitable.
2637 If "D > 0" Stark units are used and (in rare cases) a vector of
2639 extensions may be returned whose compositum is the requested class
2640 field. See "bnrstark" for details.
2641 The library syntax is quadhilbert"(D,pq,prec)".
2643 quadgen"(D)"
2645 creates the quadratic number "omega = (a+ sqrt {D})/2" where "a = 0" if
2646 "x = 0 mod 4", "a = 1" if "D = 1 mod 4", so that "(1,omega)" is an
2647 integral basis for the quadratic order of discriminant "D". "D" must be
2648 an integer congruent to 0 or 1 modulo 4, which is not a square.
2649 The library syntax is quadgen"(x)".
2651 quadpoly"(D,{v = x})"
2653 creates the ``canonical'' quadratic polynomial (in the variable "v")
2654 corresponding to the discriminant "D", i.e. the minimal polynomial of
2655 quadgen(D). "D" must be an integer congruent to 0 or 1 modulo 4, which
2656 is not a square.
2657 The library syntax is quadpoly0"(x,v)".
2659 quadray"(D,f,{lambda})"
2661 relative equation for the ray class field of conductor "f" for the
2662 quadratic field of discriminant "D" using analytic methods. A "bnf" for
2663 "x^2 - D" is also accepted in place of "D".
2664 For "D < 0", uses the "sigma" function. If supplied, lambda is is the
2666 technical element "lambda" of "bnf" necessary for Schertz's method. In
2667 that case, returns 0 if "lambda" is not suitable.
2668 For "D > 0", uses Stark's conjecture, and a vector of relative
2670 equations may be returned. See "bnrstark" for more details.
2671 The library syntax is quadray"(D,f,lambda,prec)", where an omitted
2673 "lambda" is coded as "NULL".
2674 quadregulator"(x)"
2676 regulator of the quadratic field of positive discriminant "x". Returns
2677 an error if "x" is not a discriminant (fundamental or not) or if "x" is
2678 a square. See also "quadclassunit" if "x" is large.
2679 The library syntax is regula"(x,prec)".
2681 quadunit"(D)"
2683 fundamental unit of the real quadratic field "Q( sqrt D)" where "D"
2684 is the positive discriminant of the field. If "D" is not a fundamental
2685 discriminant, this probably gives the fundamental unit of the
2686 corresponding order. "D" must be an integer congruent to 0 or 1 modulo
2687 4, which is not a square; the result is a quadratic number (see "Label
2688 se:quadgen").
2689 The library syntax is fundunit"(x)".
2691 removeprimes"({x = []})"
2693 removes the primes listed in "x" from the prime number table. In
2694 particular "removeprimes(addprimes)" empties the extra prime table. "x"
2695 can also be a single integer. List the current extra primes if "x" is
2696 omitted.
2697 The library syntax is removeprimes"(x)".
2699 sigma"(x,{k = 1})"
2701 sum of the "k^{th}" powers of the positive divisors of "|x|". "x" and
2702 "k" must be of type integer.
2703 The library syntax is sumdiv"(x)" ( = " sigma(x)") or " gsumdivk(x,k)"
2705 ( = " sigma(x,k)"), where "k" is a C long integer.
2706 sqrtint"(x)"
2708 integer square root of "x", which must be a non-negative integer. The
2709 result is non-negative and rounded towards zero.
2710 The library syntax is sqrti"(x)". Also available is "sqrtremi""(x,&r)"
2712 which returns "s" such that "s^2 = x+r", with "0 <= r <= 2s".
2713 zncoppersmith"(P, N, X, {B = N})"
2715 finds all integers "x_0" with "|x_0| <= X" such that
2716 "gcd(N, P(x_0)) >= B."
2718 If "N" is prime or a prime power, "polrootsmod" or "polrootspadic" will
2720 be much faster. "X" must be smaller than " exp ( log ^2 B / ( deg (P)
2721 log N))".
2722 The library syntax is zncoppersmith"(P, N, X, B)", where an omitted "B"
2724 is coded as "NULL".
2725 znlog"(x,g)"
2727 "g" must be a primitive root mod a prime "p", and the result is the
2728 discrete log of "x" in the multiplicative group "(Z/pZ)^*". This
2729 function uses a simple-minded combination of Pohlig-Hellman algorithm
2730 and Shanks baby-step/giant-step which requires "O( sqrt {q})" storage,
2731 where "q" is the largest prime factor of "p-1". Hence it cannot be used
2732 when the largest prime divisor of "p-1" is greater than about
2733 "10^{13}".
2734 The library syntax is znlog"(x,g)".
2736 znorder"(x,{o})"
2738 "x" must be an integer mod "n", and the result is the order of "x" in
2739 the multiplicative group "(Z/nZ)^*". Returns an error if "x" is not
2740 invertible. If optional parameter "o" is given it is assumed to be a
2741 multiple of the order (used to limit the search space).
2742 The library syntax is znorder"(x,o)", where an omitted "o" is coded as
2744 "NULL". Also available is " order(x)".
2745 znprimroot"(n)"
2747 returns a primitive root (generator) of "(Z/nZ)^*", whenever this
2748 latter group is cyclic ("n = 4" or "n = 2p^k" or "n = p^k", where "p"
2749 is an odd prime and "k >= 0").
2750 The library syntax is gener"(x)".
2752 znstar"(n)"
2754 gives the structure of the multiplicative group "(Z/nZ)^*" as a
2755 3-component row vector "v", where "v[1] = phi(n)" is the order of that
2756 group, "v[2]" is a "k"-component row-vector "d" of integers "d[i]" such
2757 that "d[i] > 1" and "d[i] | d[i-1]" for "i >= 2" and "(Z/nZ)^* ~
2758 prod_{i = 1}^k(Z/d[i]Z)", and "v[3]" is a "k"-component row vector
2759 giving generators of the image of the cyclic groups "Z/d[i]Z".
2760 The library syntax is znstar"(n)".
2762
2764 We have implemented a number of functions which are useful for number
2765 theorists working on elliptic curves. We always use Tate's notations.
2766 The functions assume that the curve is given by a general Weierstrass
2767 model
2768 " y^2+a_1xy+a_3y = x^3+a_2x^2+a_4x+a_6, "
2770 where a priori the "a_i" can be of any scalar type. This curve can be
2772 considered as a five-component vector "E = [a1,a2,a3,a4,a6]". Points on
2773 "E" are represented as two-component vectors "[x,y]", except for the
2774 point at infinity, i.e. the identity element of the group law,
2775 represented by the one-component vector "[0]".
2776 It is useful to have at one's disposal more information. This is given
2778 by the function "ellinit" (see there), which initalizes and returns an
2779 ell structure by default. If a specific flag is added, a shortened
2780 sell, for small ell, is returned, which is much faster to compute but
2781 contains less information. The following member functions are available
2782 to deal with the output of "ellinit", both ell and sell:
2783 "a1"--"a6", "b2"--"b8", "c4"--"c6" : coefficients of the elliptic
2785 curve.
2786 "area" : volume of the complex lattice defining "E".
2788 "disc" : discriminant of the curve.
2790 "j" : "j"-invariant of the curve.
2792 "omega" : "[omega_1,omega_2]", periods forming a basis of the
2794 complex lattice defining "E" ("omega_1" is the
2795 real period, and "omega_2/omega_1" belongs to
2797 Poincaré's half-plane).
2798 "eta" : quasi-periods "[eta_1, eta_2]", such that
2800 "eta_1omega_2-eta_2omega_1 = iPi".
2801 "roots" : roots of the associated Weierstrass equation.
2803 "tate" : "[u^2,u,v]" in the notation of Tate.
2805 "w" : Mestre's "w" (this is technical).
2807 The member functions "area", "eta" and "omega" are only available for
2809 curves over Q. Conversely, "tate" and "w" are only available for curves
2810 defined over "Q_p". The use of member functions is best described by an
2811 example:
2812 ? E = ellinit([0,0,0,0,1]); \\ The curve y^2 = x^3 + 1
2814 ? E.a6
2815 %2 = 1
2816 ? E.c6
2817 %3 = -864
2818 ? E.disc
2819 %4 = -432
2820 Some functions, in particular those relative to height computations
2822 (see "ellheight") require also that the curve be in minimal Weierstrass
2823 form, which is duly stressed in their description below. This is
2824 achieved by the function "ellminimalmodel". \emph{Using a non-minimal
2825 model in such a routine will yield a wrong result!}
2826 All functions related to elliptic curves share the prefix "ell", and
2828 the precise curve we are interested in is always the first argument, in
2829 either one of the three formats discussed above, unless otherwise
2830 specified. The requirements are given as the \emph{minimal} ones: any
2831 richer structure may replace the ones requested. For instance, in
2832 functions which have no use for the extra information given by an ell
2833 structure, the curve can be given either as a five-component vector, as
2834 an sell, or as an ell; if an sell is requested, an ell may equally be
2835 given.
2836 elladd"(E,z1,z2)"
2838 sum of the points "z1" and "z2" on the elliptic curve corresponding to
2839 "E".
2840 The library syntax is addell"(E,z1,z2)".
2842 ellak"(E,n)"
2844 computes the coefficient "a_n" of the "L"-function of the elliptic
2845 curve "E", i.e. in principle coefficients of a newform of weight 2
2846 assuming Taniyama-Weil conjecture (which is now known to hold in full
2847 generality thanks to the work of Breuil, Conrad, Diamond, Taylor and
2848 Wiles). "E" must be an sell as output by "ellinit". For this function
2849 to work for every "n" and not just those prime to the conductor, "E"
2850 must be a minimal Weierstrass equation. If this is not the case, use
2851 the function "ellminimalmodel" before using "ellak".
2852 The library syntax is akell"(E,n)".
2854 ellan"(E,n)"
2856 computes the vector of the first "n" "a_k" corresponding to the
2857 elliptic curve "E". All comments in "ellak" description remain valid.
2858 The library syntax is anell"(E,n)", where "n" is a C integer.
2860 ellap"(E,p,{flag = 0})"
2862 computes the "a_p" corresponding to the elliptic curve "E" and the
2863 prime number "p". These are defined by the equation "#E(F_p) = p+1 -
2864 a_p", where "#E(F_p)" stands for the number of points of the curve "E"
2865 over the finite field "F_p". When "flag" is 0, this uses the baby-step
2866 giant-step method and a trick due to Mestre. This runs in time
2867 "O(p^{1/4})" and requires "O(p^{1/4})" storage, hence becomes
2868 unreasonable when "p" has about 30 digits.
2869 If "flag" is 1, computes the "a_p" as a sum of Legendre symbols. This
2871 is slower than the previous method as soon as "p" is greater than 100,
2872 say.
2873 No checking is done that "p" is indeed prime. "E" must be an sell as
2875 output by "ellinit", defined over Q, "F_p" or "Q_p". "E" must be given
2876 by a Weierstrass equation minimal at "p".
2877 The library syntax is ellap0"(E,p,flag)". Also available are "
2879 apell(E,p)", corresponding to "flag = 0", and " apell2(E,p)" ("flag =
2880 1").
2881 ellbil"(E,z1,z2)"
2883 if "z1" and "z2" are points on the elliptic curve "E", assumed to be
2884 integral given by a minimal model, this function computes the value of
2885 the canonical bilinear form on "z1", "z2":
2886 " ( h(E,z1+z2) - h(E,z1) - h(E,z2) ) / 2 "
2888 where "+" denotes of course addition on "E". In addition, "z1" or "z2"
2890 (but not both) can be vectors or matrices.
2891 The library syntax is bilhell"(E,z1,z2,prec)".
2893 ellchangecurve"(E,v)"
2895 changes the data for the elliptic curve "E" by changing the coordinates
2896 using the vector "v = [u,r,s,t]", i.e. if "x'" and "y'" are the new
2897 coordinates, then "x = u^2x'+r", "y = u^3y'+su^2x'+t". "E" must be an
2898 sell as output by "ellinit".
2899 The library syntax is coordch"(E,v)".
2901 ellchangepoint"(x,v)"
2903 changes the coordinates of the point or vector of points "x" using the
2904 vector "v = [u,r,s,t]", i.e. if "x'" and "y'" are the new coordinates,
2905 then "x = u^2x'+r", "y = u^3y'+su^2x'+t" (see also "ellchangecurve").
2906 The library syntax is pointch"(x,v)".
2908 ellconvertname"(name)"
2910 converts an elliptic curve name, as found in the "elldata" database,
2911 from a string to a triplet "[conductor, isogeny class, index]". It will
2912 also convert a triplet back to a curve name. Examples:
2913 ? ellconvertname("123b1")
2915 %1 = [123, 1, 1]
2916 ? ellconvertname(%)
2917 %2 = "123b1"
2918 The library syntax is ellconvertname"(name)".
2920 elleisnum"(E,k,{flag = 0})"
2922 "E" being an elliptic curve as output by "ellinit" (or, alternatively,
2923 given by a 2-component vector "[omega_1,omega_2]" representing its
2924 periods), and "k" being an even positive integer, computes the
2925 numerical value of the Eisenstein series of weight "k" at "E", namely
2926 " (2i Pi/omega_2)^k \Big(1 + 2/zeta(1-k) sum_{n >= 0} n^{k-1}q^n /
2928 (1-q^n)\Big), "
2929 where "q = e(omega_1/omega_2)".
2931 When flag is non-zero and "k = 4" or 6, returns the elliptic invariants
2933 "g_2" or "g_3", such that
2934 "y^2 = 4x^3 - g_2 x - g_3"
2936 is a Weierstrass equation for "E".
2938 The library syntax is elleisnum"(E,k,flag)".
2940 elleta"(om)"
2942 returns the two-component row vector "[eta_1,eta_2]" of quasi-periods
2943 associated to "om = [omega_1, omega_2]"
2944 The library syntax is elleta"(om, prec)"
2946 ellgenerators"(E)"
2948 returns a Z-basis of the free part of the Mordell-Weil group associated
2949 to "E". This function depends on the "elldata" database being
2950 installed and referencing the curve, and so is only available for
2951 curves over Z of small conductors.
2952 The library syntax is ellgenerators"(E)".
2954 ellglobalred"(E)"
2956 calculates the arithmetic conductor, the global minimal model of "E"
2957 and the global Tamagawa number "c". "E" must be an sell as output by
2958 "ellinit", \emph{and is supposed to have all its coefficients "a_i" in}
2959 Q. The result is a 3 component vector "[N,v,c]". "N" is the arithmetic
2960 conductor of the curve. "v" gives the coordinate change for "E" over Q
2961 to the minimal integral model (see "ellminimalmodel"). Finally "c" is
2962 the product of the local Tamagawa numbers "c_p", a quantity which
2963 enters in the Birch and Swinnerton-Dyer conjecture.
2964 The library syntax is ellglobalred"(E)".
2966 ellheight"(E,z,{flag = 2})"
2968 global Néron-Tate height of the point "z" on the elliptic curve "E"
2969 (defined over Q), given by a standard minimal integral model. "E" must
2970 be an "ell" as output by "ellinit". flag selects the algorithm used to
2971 compute the archimedean local height. If "flag = 0", this computation
2972 is done using sigma and theta-functions and a trick due to J.
2973 Silverman. If "flag = 1", use Tate's "4^n" algorithm. If "flag = 2",
2974 use Mestre's AGM algorithm. The latter is much faster than the other
2975 two, both in theory (converges quadratically) and in practice.
2976 The library syntax is ellheight0"(E,z,flag,prec)". Also available are "
2978 ghell(E,z,prec)" ("flag = 0") and " ghell2(E,z,prec)" ("flag = 1").
2979 ellheightmatrix"(E,x)"
2981 "x" being a vector of points, this function outputs the Gram matrix of
2982 "x" with respect to the Néron-Tate height, in other words, the "(i,j)"
2983 component of the matrix is equal to "ellbil(E,x[i],x[j])". The rank of
2984 this matrix, at least in some approximate sense, gives the rank of the
2985 set of points, and if "x" is a basis of the Mordell-Weil group of "E",
2986 its determinant is equal to the regulator of "E". Note that this matrix
2987 should be divided by 2 to be in accordance with certain normalizations.
2988 "E" is assumed to be integral, given by a minimal model.
2989 The library syntax is mathell"(E,x,prec)".
2991 ellidentify"(E)"
2993 look up the elliptic curve "E" (over Z) in the "elldata" database and
2994 return "[[N, M, G], C]" where "N" is the name of the curve in J. E.
2995 Cremona database, "M" the minimal model, "G" a Z-basis of the free part
2996 of the Mordell-Weil group of "E" and "C" the coordinates change (see
2997 "ellchangecurve").
2998 The library syntax is ellidentify"(E)".
3000 ellinit"(E,{flag = 0})"
3002 initialize an "ell" structure, associated to the elliptic curve "E".
3003 "E" is a 5-component vector "[a_1,a_2,a_3,a_4,a_6]" defining the
3004 elliptic curve with Weierstrass equation
3005 " Y^2 + a_1 XY + a_3 Y = X^3 + a_2 X^2 + a_4 X + a_6 "
3007 or a string, in this case the coefficients of the curve with matching
3009 name are looked in the "elldata" database if available. For the time
3010 being, only curves over a prime field "F_p" and over the "p"-adic or
3011 real numbers (including rational numbers) are fully supported. Other
3012 domains are only supported for very basic operations such as point
3013 addition.
3014 The result of "ellinit" is a an ell structure by default, and a shorted
3016 sell if "flag = 1". Both contain the following information in their
3017 components:
3018 " a_1,a_2,a_3,a_4,a_6,b_2,b_4,b_6,b_8,c_4,c_6,Delta,j."
3020 All are accessible via member functions. In particular, the
3022 discriminant is "E.disc", and the "j"-invariant is "E.j".
3023 The other six components are only present if "flag" is 0 or omitted.
3025 Their content depends on whether the curve is defined over R or not:
3026 \item When "E" is defined over R, "E.roots" is a vector whose three
3028 components contain the roots of the right hand side of the associated
3029 Weierstrass equation.
3030 " (y + a_1x/2 + a_3/2)^2 = g(x) "
3032 If the roots are all real, then they are ordered by decreasing value.
3034 If only one is real, it is the first component.
3035 Then "omega_1 = ""E.omega[1]" is the real period of "E" (integral of
3037 "dx/(2y+a_1x+a_3)" over the connected component of the identity element
3038 of the real points of the curve), and "omega_2 = ""E.omega[2]" is a
3039 complex period. In other words, "E.omega" forms a basis of the complex
3040 lattice defining "E", with "tau = (omega_2)/(omega_1)" having positive
3041 imaginary part.
3042 "E.eta" is a row vector containing the corresponding values "eta_1" and
3044 "eta_2" such that "eta_1omega_2-eta_2omega_1 = iPi".
3045 Finally, "E.area" is the volume of the complex lattice defining "E".
3047 \item When "E" is defined over "Q_p", the "p"-adic valuation of "j"
3049 must be negative. Then "E.roots" is the vector with a single component
3050 equal to the "p"-adic root of the associated Weierstrass equation
3051 corresponding to "-1" under the Tate parametrization.
3052 "E.tate" yields the three-component vector "[u^2,u,q]", in the
3054 notations of Tate. If the "u"-component does not belong to "Q_p", it is
3055 set to zero.
3056 "E.w" is Mestre's "w" (this is technical).
3058 For all other base fields or rings, the last six components are
3060 arbitrarily set equal to zero. See also the description of member
3061 functions related to elliptic curves at the beginning of this section.
3062 The library syntax is ellinit0"(E,flag,prec)". Also available are "
3064 initell(E,prec)" ("flag = 0") and " smallinitell(E,prec)" ("flag = 1").
3065 ellisoncurve"(E,z)"
3067 gives 1 (i.e. true) if the point "z" is on the elliptic curve "E", 0
3068 otherwise. If "E" or "z" have imprecise coefficients, an attempt is
3069 made to take this into account, i.e. an imprecise equality is checked,
3070 not a precise one. It is allowed for "z" to be a vector of points in
3071 which case a vector (of the same type) is returned.
3072 The library syntax is ellisoncurve"(E,z)". Also available is "
3074 oncurve(E,z)" which returns a "long" but does not accept vector of
3075 points.
3076 ellj"(x)"
3078 elliptic "j"-invariant. "x" must be a complex number with positive
3079 imaginary part, or convertible into a power series or a "p"-adic number
3080 with positive valuation.
3081 The library syntax is jell"(x,prec)".
3083 elllocalred"(E,p)"
3085 calculates the Kodaira type of the local fiber of the elliptic curve
3086 "E" at the prime "p". "E" must be an sell as output by "ellinit", and
3087 is assumed to have all its coefficients "a_i" in Z. The result is a
3088 4-component vector "[f,kod,v,c]". Here "f" is the exponent of "p" in
3089 the arithmetic conductor of "E", and "kod" is the Kodaira type which is
3090 coded as follows:
3091 1 means good reduction (type I"_0"), 2, 3 and 4 mean types II, III and
3093 IV respectively, "4+nu" with "nu > 0" means type I"_nu"; finally the
3094 opposite values "-1", "-2", etc. refer to the starred types I"_0^*",
3095 II"^*", etc. The third component "v" is itself a vector "[u,r,s,t]"
3096 giving the coordinate changes done during the local reduction.
3097 Normally, this has no use if "u" is 1, that is, if the given equation
3098 was already minimal. Finally, the last component "c" is the local
3099 Tamagawa number "c_p".
3100 The library syntax is elllocalred"(E,p)".
3102 elllseries"(E,s,{A = 1})"
3104 "E" being an sell as output by "ellinit", this computes the value of
3105 the L-series of "E" at "s". It is assumed that "E" is defined over Q,
3106 not necessarily minimal. The optional parameter "A" is a cutoff point
3107 for the integral, which must be chosen close to 1 for best speed. The
3108 result must be independent of "A", so this allows some internal
3109 checking of the function.
3110 Note that if the conductor of the curve is large, say greater than
3112 "10^{12}", this function will take an unreasonable amount of time since
3113 it uses an "O(N^{1/2})" algorithm.
3114 The library syntax is elllseries"(E,s,A,prec)" where "prec" is a "long"
3116 and an omitted "A" is coded as "NULL".
3117 ellminimalmodel"(E,{&v})"
3119 return the standard minimal integral model of the rational elliptic
3120 curve "E". If present, sets "v" to the corresponding change of
3121 variables, which is a vector "[u,r,s,t]" with rational components. The
3122 return value is identical to that of "ellchangecurve(E, v)".
3123 The resulting model has integral coefficients, is everywhere minimal,
3125 "a_1" is 0 or 1, "a_2" is 0, 1 or "-1" and "a_3" is 0 or 1. Such a
3126 model is unique, and the vector "v" is unique if we specify that "u" is
3127 positive, which we do.
3128 The library syntax is ellminimalmodel"(E,&v)", where an omitted "v" is
3130 coded as "NULL".
3131 ellorder"(E,z)"
3133 gives the order of the point "z" on the elliptic curve "E" if it is a
3134 torsion point, zero otherwise. In the present version 2.2.0, this is
3135 implemented only for elliptic curves defined over Q.
3136 The library syntax is orderell"(E,z)".
3138 ellordinate"(E,x)"
3140 gives a 0, 1 or 2-component vector containing the "y"-coordinates of
3141 the points of the curve "E" having "x" as "x"-coordinate.
3142 The library syntax is ordell"(E,x)".
3144 ellpointtoz"(E,z)"
3146 if "E" is an elliptic curve with coefficients in R, this computes a
3147 complex number "t" (modulo the lattice defining "E") corresponding to
3148 the point "z", i.e. such that, in the standard Weierstrass model, " wp
3149 (t) = z[1], wp '(t) = z[2]". In other words, this is the inverse
3150 function of "ellztopoint". More precisely, if "(w1,w2)" are the real
3151 and complex periods of "E", "t" is such that "0 <= Re (t) < w1" and "0
3152 <= Im (t) < Im (w2)".
3153 If "E" has coefficients in "Q_p", then either Tate's "u" is in "Q_p",
3155 in which case the output is a "p"-adic number "t" corresponding to the
3156 point "z" under the Tate parametrization, or only its square is, in
3157 which case the output is "t+1/t". "E" must be an ell as output by
3158 "ellinit".
3159 The library syntax is zell"(E,z,prec)".
3161 ellpow"(E,z,n)"
3163 computes "n" times the point "z" for the group law on the elliptic
3164 curve "E". Here, "n" can be in Z, or "n" can be a complex quadratic
3165 integer if the curve "E" has complex multiplication by "n" (if not, an
3166 error message is issued).
3167 The library syntax is powell"(E,z,n)".
3169 ellrootno"(E,{p = 1})"
3171 "E" being an sell as output by "ellinit", this computes the local (if
3172 "p ! = 1") or global (if "p = 1") root number of the L-series of the
3173 elliptic curve "E". Note that the global root number is the sign of the
3174 functional equation and conjecturally is the parity of the rank of the
3175 Mordell-Weil group. The equation for "E" must have coefficients in Q
3176 but need \emph{not} be minimal.
3177 The library syntax is ellrootno"(E,p)" and the result (equal to "+-1")
3179 is a "long".
3180 ellsigma"(E,z,{flag = 0})"
3182 value of the Weierstrass "sigma" function of the lattice associated to
3183 "E" as given by "ellinit" (alternatively, "E" can be given as a lattice
3184 "[omega_1,omega_2]").
3185 If "flag = 1", computes an (arbitrary) determination of " log
3187 (sigma(z))".
3188 If "flag = 2,3", same using the product expansion instead of theta
3190 series. The library syntax is ellsigma"(E,z,flag)"
3191 ellsearch"(N)"
3193 if "N" is an integer, it is taken as a conductor else if "N" is a
3194 string, it can be a curve name ("11a1"), a isogeny class ("11a") or a
3195 conductor "11". This function finds all curves in the "elldata"
3196 database with the given property.
3197 If "N" is a full curve name, the output format is "[N,
3199 [a_1,a_2,a_3,a_4,a_6], G]" where "[a_1,a_2,a_3,a_4,a_6]" are the
3200 coefficients of the Weierstrass equation of the curve and "G" is a
3201 Z-basis of the free part of the Mordell-Weil group associated to the
3202 curve.
3203 If "N" is not a full-curve name, the output is the list (as a vector)
3205 of all matching curves in the above format.
3206 The library syntax is ellsearch"(N)". Also available is "
3208 ellsearchcurve(N)" that only accept complete curve names.
3209 ellsub"(E,z1,z2)"
3211 difference of the points "z1" and "z2" on the elliptic curve
3212 corresponding to "E".
3213 The library syntax is subell"(E,z1,z2)".
3215 elltaniyama"(E)"
3217 computes the modular parametrization of the elliptic curve "E", where
3218 "E" is an sell as output by "ellinit", in the form of a two-component
3219 vector "[u,v]" of power series, given to the current default series
3220 precision. This vector is characterized by the following two
3221 properties. First the point "(x,y) = (u,v)" satisfies the equation of
3222 the elliptic curve. Second, the differential "du/(2v+a_1u+a_3)" is
3223 equal to "f(z)dz", a differential form on "H/Gamma_0(N)" where "N" is
3224 the conductor of the curve. The variable used in the power series for
3225 "u" and "v" is "x", which is implicitly understood to be equal to " exp
3226 (2iPi z)". It is assumed that the curve is a \emph{strong} Weil curve,
3227 and that the Manin constant is equal to 1. The equation of the curve
3228 "E" must be minimal (use "ellminimalmodel" to get a minimal equation).
3229 The library syntax is elltaniyama"(E, prec)", and the precision of the
3231 result is determined by "prec".
3232 elltors"(E,{flag = 0})"
3234 if "E" is an elliptic curve \emph{defined over Q}, outputs the torsion
3235 subgroup of "E" as a 3-component vector "[t,v1,v2]", where "t" is the
3236 order of the torsion group, "v1" gives the structure of the torsion
3237 group as a product of cyclic groups (sorted by decreasing order), and
3238 "v2" gives generators for these cyclic groups. "E" must be an ell as
3239 output by "ellinit".
3240 ? E = ellinit([0,0,0,-1,0]);
3242 ? elltors(E)
3243 %1 = [4, [2, 2], [[0, 0], [1, 0]]]
3244 Here, the torsion subgroup is isomorphic to "Z/2Z x Z/2Z", with
3246 generators "[0,0]" and "[1,0]".
3247 If "flag = 0", use Doud's algorithm: bound torsion by computing
3249 "#E(F_p)" for small primes of good reduction, then look for torsion
3250 points using Weierstrass parametrization (and Mazur's classification).
3251 If "flag = 1", use Lutz-Nagell (\emph{much} slower), "E" is allowed to
3253 be an sell.
3254 The library syntax is elltors0"(E,flag)".
3256 ellwp"(E,{z = x},{flag = 0})"
3258 Computes the value at "z" of the Weierstrass " wp " function attached
3259 to the elliptic curve "E" as given by "ellinit" (alternatively, "E" can
3260 be given as a lattice "[omega_1,omega_2]").
3261 If "z" is omitted or is a simple variable, computes the \emph{power
3263 series} expansion in "z" (starting "z^{-2}+O(z^2)"). The number of
3264 terms to an \emph{even} power in the expansion is the default
3265 serieslength in "gp", and the second argument (C long integer) in
3266 library mode.
3267 Optional flag is (for now) only taken into account when "z" is numeric,
3269 and means 0: compute only " wp (z)", 1: compute "[ wp (z), wp '(z)]".
3270 The library syntax is ellwp0"(E,z,flag,prec,precdl)". Also available is
3272 " weipell(E,precdl)" for the power series.
3273 ellzeta"(E,z)"
3275 value of the Weierstrass "zeta" function of the lattice associated to
3276 "E" as given by "ellinit" (alternatively, "E" can be given as a lattice
3277 "[omega_1,omega_2]").
3278 The library syntax is ellzeta"(E,z)".
3280 ellztopoint"(E,z)"
3282 "E" being an ell as output by "ellinit", computes the coordinates
3283 "[x,y]" on the curve "E" corresponding to the complex number "z". Hence
3284 this is the inverse function of "ellpointtoz". In other words, if the
3285 curve is put in Weierstrass form, "[x,y]" represents the Weierstrass "
3286 wp "-function and its derivative. If "z" is in the lattice defining "E"
3287 over C, the result is the point at infinity "[0]".
3288 The library syntax is pointell"(E,z,prec)".
3290
3292 In this section can be found functions which are used almost
3293 exclusively for working in general number fields. Other less specific
3294 functions can be found in the next section on polynomials. Functions
3295 related to quadratic number fields are found in section "Label
3296 se:arithmetic" (Arithmetic functions).
3297 Number field structures
3299 Let "K = Q[X] / (T)" a number field, "Z_K" its ring of integers, "T
3300 belongs to Z[X]" is monic. Three basic number field structures can be
3301 associated to "K" in GP:
3302 \item "nf" denotes a number field, i.e. a data structure output by
3304 "nfinit". This contains the basic arithmetic data associated to the
3305 number field: signature, maximal order (given by a basis "nf.zk"),
3306 discriminant, defining polynomial "T", etc.
3307 \item "bnf" denotes a ``Buchmann's number field'', i.e. a data
3309 structure output by "bnfinit". This contains "nf" and the deeper
3310 invariants of the field: units U(K), class group "\Cl(K)", as well as
3311 technical data required to solve the two associated discrete logarithm
3312 problems.
3313 \item "bnr" denotes a ``ray number field'', i.e. a data structure
3315 output by "bnrinit", corresponding to the ray class group structure of
3316 the field, for some modulus "f". It contains a bnf, the modulus "f",
3317 the ray class group "\Cl_f(K)" and data associated to the discrete
3318 logarithm problem therein.
3319 Algebraic numbers and ideals
3321 An algebraic number belonging to "K = Q[X]/(T)" is given as
3322 \item a "t_INT", "t_FRAC" or "t_POL" (implicitly modulo "T"), or
3324 \item a "t_POLMOD" (modulo "T"), or
3326 \item a "t_COL" "v" of dimension "N = [K:Q]", representing the element
3328 in terms of the computed integral basis, as "sum(i = 1, N, v[i] *
3329 nf.zk[i])". Note that a "t_VEC" will not be recognized.
3330 An ideal is given in any of the following ways:
3332 \item an algebraic number in one of the above forms, defining a
3334 principal ideal.
3335 \item a prime ideal, i.e. a 5-component vector in the format output by
3337 "idealprimedec".
3338 \item a "t_MAT", square and in Hermite Normal Form (or at least upper
3340 triangular with non-negative coefficients), whose columns represent a
3341 basis of the ideal.
3342 One may use "idealhnf" to convert an ideal to the last (preferred)
3344 format.
3345 Note. Some routines accept non-square matrices, but using this format
3347 is strongly discouraged. Nevertheless, their behaviour is as follows:
3348 If strictly less than "N = [K:Q]" generators are given, it is assumed
3349 they form a "Z_K"-basis. If "N" or more are given, a Z-basis is
3350 assumed. If exactly "N" are given, it is further assumed the matrix is
3351 in HNF. If any of these assumptions is not correct the behaviour of the
3352 routine is undefined.
3353 \item an idele is a 2-component vector, the first being an ideal as
3355 above, the second being a "R_1+R_2"-component row vector giving
3356 Archimedean information, as complex numbers.
3357 Finite abelian groups
3359 A finite abelian group "G" in user-readable format is given by its
3360 Smith Normal Form as a pair "[h,d]" or triple "[h,d,g]". Here "h" is
3361 the cardinality of "G", "(d_i)" is the vector of elementary divisors,
3362 and "(g_i)" is a vector of generators. In short, "G = oplus _{i <= n}
3363 (Z/d_iZ) g_i", with "d_n | ... | d_2 | d_1" and "prod d_i = h". This
3364 information can also be retrieved as "G.no", "G.cyc" and "G.gen".
3365 \item a character on the abelian group " oplus (Z/d_iZ) g_i" is given
3367 by a row vector "chi = [a_1,...,a_n]" such that "chi(prod g_i^{n_i}) =
3368 exp (2iPisum a_i n_i / d_i)".
3369 \item given such a structure, a subgroup "H" is input as a square
3371 matrix, whose column express generators of "H" on the given generators
3372 "g_i". Note that the absolute value of the determinant of that matrix
3373 is equal to the index "(G:H)".
3374 Relative extensions
3376 When defining a relative extension, the base field "nf" must be defined
3377 by a variable having a lower priority (see "Label se:priority") than
3378 the variable defining the extension. For example, you may use the
3379 variable name "y" to define the base field, and "x" to define the
3380 relative extension.
3381 \item "rnf" denotes a relative number field, i.e. a data structure
3383 output by "rnfinit".
3384 \item A \emph{relative matrix} is a matrix whose entries are elements
3386 of a (fixed) number field "nf", always expressed as column vectors on
3387 the integral basis "nf.zk". Hence it is a matrix of vectors.
3388 \item An ideal list is a row vector of (fractional) ideals of the
3390 number field "nf".
3391 \item A pseudo-matrix is a pair "(A,I)" where "A" is a relative matrix
3393 and "I" an ideal list whose length is the same as the number of columns
3394 of "A". This pair is represented by a 2-component row vector.
3395 \item The projective module generated by a pseudo-matrix "(A,I)" is the
3397 sum "sum_i {a}_j A_j" where the "{a}_j" are the ideals of "I" and "A_j"
3398 is the "j"-th column of "A".
3399 \item A pseudo-matrix "(A,I)" is a pseudo-basis of the module it
3401 generates if "A" is a square matrix with non-zero determinant and all
3402 the ideals of "I" are non-zero. We say that it is in Hermite Normal
3403 Form (HNF) if it is upper triangular and all the elements of the
3404 diagonal are equal to 1.
3405 \item The \emph{determinant} of a pseudo-basis "(A,I)" is the ideal
3407 equal to the product of the determinant of "A" by all the ideals of
3408 "I". The determinant of a pseudo-matrix is the determinant of any
3409 pseudo-basis of the module it generates.
3410 Class field theory
3412 A "modulus", in the sense of class field theory, is a divisor supported
3413 on the non-complex places of "K". In PARI terms, this means either an
3414 ordinary ideal "I" as above (no archimedean component), or a pair
3415 "[I,a]", where "a" is a vector with "r_1" "{0,1}"-components,
3416 corresponding to the infinite part of the divisor. More precisely, the
3417 "i"-th component of "a" corresponds to the real embedding associated to
3418 the "i"-th real root of "K.roots". (That ordering is not canonical, but
3419 well defined once a defining polynomial for "K" is chosen.) For
3420 instance, "[1, [1,1]]" is a modulus for a real quadratic field,
3421 allowing ramification at any of the two places at infinity.
3422 A bid or ``big ideal'' is a structure output by "idealstar" needed to
3424 compute in "(Z_K/I)^*", where "I" is a modulus in the above sense. If
3425 is a finite abelian group as described above, supplemented by technical
3426 data needed to solve discrete log problems.
3427 Finally we explain how to input ray number fields (or bnr), using class
3429 field theory. These are defined by a triple "a1", "a2", "a3", where the
3430 defining set "[a1,a2,a3]" can have any of the following forms: "[bnr]",
3431 "[bnr,subgroup]", "[bnf,module]", "[bnf,module,subgroup]".
3432 \item "bnf" is as output by "bnfinit", where units are mandatory unless
3434 the modulus is trivial; bnr is as output by "bnrinit". This is the
3435 ground field "K".
3436 \item \emph{module} is a modulus "\goth{f}", as described above.
3438 \item \emph{subgroup} a subgroup of the ray class group modulo
3440 "\goth{f}" of "K". As described above, this is input as a square matrix
3441 expressing generators of a subgroup of the ray class group "bnr.clgp"
3442 on the given generators.
3443 The corresponding bnr is the subfield of the ray class field of "K"
3445 modulo "\goth{f}", fixed by the given subgroup.
3446 General use
3448 All the functions which are specific to relative extensions, number
3449 fields, Buchmann's number fields, Buchmann's number rays, share the
3450 prefix "rnf", "nf", "bnf", "bnr" respectively. They take as first
3451 argument a number field of that precise type, respectively output by
3452 "rnfinit", "nfinit", "bnfinit", and "bnrinit".
3453 However, and even though it may not be specified in the descriptions of
3455 the functions below, it is permissible, if the function expects a "nf",
3456 to use a "bnf" instead, which contains much more information. On the
3457 other hand, if the function requires a "bnf", it will \emph{not} launch
3458 "bnfinit" for you, which is a costly operation. Instead, it will give
3459 you a specific error message. In short, the types
3460 " nf <= bnf <= bnr"
3462 are ordered, each function requires a minimal type to work properly,
3464 but you may always substitute a larger type.
3465 The data types corresponding to the structures described above are
3467 rather complicated. Thus, as we already have seen it with elliptic
3468 curves, GP provides ``member functions'' to retrieve data from these
3469 structures (once they have been initialized of course). The relevant
3470 types of number fields are indicated between parentheses:
3471 "bid" (bnr, ) : bid ideal structure.
3473 "bnf" (bnr, bnf ) : Buchmann's number field.
3475 "clgp" (bnr, bnf ) : classgroup. This one admits the following
3477 three subclasses:
3478 "cyc" : cyclic decomposition (SNF).
3480 "gen" : generators.
3482 "no" : number of elements.
3484 "diff" (bnr, bnf, nf ) : the different ideal.
3486 "codiff" (bnr, bnf, nf ) : the codifferent (inverse of the
3488 different in the ideal group).
3489 "disc" (bnr, bnf, nf ) : discriminant.
3491 "fu" (bnr, bnf, nf ) : fundamental units.
3493 "index" (bnr, bnf, nf ) : index of the power order in the ring of
3495 integers.
3496 "nf" (bnr, bnf, nf ) : number field.
3498 "r1" (bnr, bnf, nf ) : the number of real embeddings.
3500 "r2" (bnr, bnf, nf ) : the number of pairs of complex embeddings.
3502 "reg" (bnr, bnf, ) : regulator.
3504 "roots" (bnr, bnf, nf ) : roots of the polynomial generating the
3506 field.
3507 "t2" (bnr, bnf, nf ) : the T2 matrix (see "nfinit").
3509 "tu" (bnr, bnf, ) : a generator for the torsion units.
3511 "tufu" (bnr, bnf, ) : "[w,u_1,...,u_r]", "(u_i)" is a vector of
3513 fundamental units, "w" generates the torsion units.
3514 "zk" (bnr, bnf, nf ) : integral basis, i.e. a Z-basis of the
3516 maximal order.
3517 For instance, assume that "bnf = bnfinit(pol)", for some polynomial.
3519 Then "bnf.clgp" retrieves the class group, and "bnf.clgp.no" the class
3520 number. If we had set "bnf = nfinit(pol)", both would have output an
3521 error message. All these functions are completely recursive, thus for
3522 instance "bnr.bnf.nf.zk" will yield the maximal order of bnr, which you
3523 could get directly with a simple "bnr.zk".
3524 Class group, units, and the GRH
3526 Some of the functions starting with "bnf" are implementations of the
3527 sub-exponential algorithms for finding class and unit groups under GRH,
3528 due to Hafner-McCurley, Buchmann and Cohen-Diaz-Olivier. The general
3529 call to the functions concerning class groups of general number fields
3530 (i.e. excluding "quadclassunit") involves a polynomial "P" and a
3531 technical vector
3532 "tech = [c, c2, nrpid ],"
3534 where the parameters are to be understood as follows:
3536 "P" is the defining polynomial for the number field, which must be in
3538 "Z[X]", irreducible and monic. In fact, if you supply a non-monic
3539 polynomial at this point, "gp" issues a warning, then \emph{transforms
3540 your polynomial} so that it becomes monic. The "nfinit" routine will
3541 return a different result in this case: instead of "res", you get a
3542 vector "[res,Mod(a,Q)]", where "Mod(a,Q) = Mod(X,P)" gives the change
3543 of variables. In all other routines, the variable change is simply
3544 lost.
3545 The numbers "c <= c_2" are positive real numbers which control the
3547 execution time and the stack size. For a given "c", set "c_2 = c" to
3548 get maximum speed. To get a rigorous result under GRH you must take "c2
3549 >= 12" (or "c2 >= 6" in "P" is quadratic). Reasonable values for "c"
3550 are between 0.1 and 2. The default is "c = c_2 = 0.3".
3551 "nrpid" is the maximal number of small norm relations associated to
3553 each ideal in the factor base. Set it to 0 to disable the search for
3554 small norm relations. Otherwise, reasonable values are between 4 and
3555 20. The default is 4.
3556 Warning. Make sure you understand the above! By default, most of the
3558 "bnf" routines depend on the correctness of a heuristic assumption
3559 which is stronger than the GRH. In particular, any of the class number,
3560 class group structure, class group generators, regulator and
3561 fundamental units may be wrong, independently of each other. Any result
3562 computed from such a "bnf" may be wrong. The only guarantee is that the
3563 units given generate a subgroup of finite index in the full unit group.
3564 In practice, very few counter-examples are known, requiring unlucky
3565 random seeds. No counter-example has been reported for "c_2 = 0.5"
3566 (which should be almost as fast as "c_2 = 0.3", and shall very probably
3567 become the default). If you use "c_2 = 12", then everything is correct
3568 assuming the GRH holds. You can use "bnfcertify" to certify the
3569 computations unconditionally.
3570 Remarks.
3572 Apart from the polynomial "P", you do not need to supply the technical
3574 parameters (under the library you still need to send at least an empty
3575 vector, coded as "NULL"). However, should you choose to set some of
3576 them, they \emph{must} be given in the requested order. For example, if
3577 you want to specify a given value of nrpid, you must give some values
3578 as well for "c" and "c_2", and provide a vector "[c,c_2,nrpid]".
3579 Note also that you can use an "nf" instead of "P", which avoids
3581 recomputing the integral basis and analogous quantities.
3582 bnfcertify"(bnf)"
3584 "bnf" being as output by "bnfinit", checks whether the result is
3585 correct, i.e. whether it is possible to remove the assumption of the
3586 Generalized Riemann Hypothesis. It is correct if and only if the answer
3587 is 1. If it is incorrect, the program may output some error message, or
3588 loop indefinitely. You can check its progress by increasing the debug
3589 level.
3590 The library syntax is certifybuchall"(bnf)", and the result is a C
3592 long.
3593 bnfclassunit"(P,{flag = 0},{tech = []})"
3595 \emph{this function is DEPRECATED, use "bnfinit"}.
3596 Buchmann's sub-exponential algorithm for computing the class group, the
3598 regulator and a system of fundamental units of the general algebraic
3599 number field "K" defined by the irreducible polynomial "P" with integer
3600 coefficients.
3601 The result of this function is a vector "v" with many components, which
3603 for ease of presentation is in fact output as a one column matrix. It
3604 is \emph{not} a "bnf", you need "bnfinit" for that. First we describe
3605 the default behaviour ("flag = 0"):
3606 "v[1]" is equal to the polynomial "P".
3608 "v[2]" is the 2-component vector "[r1,r2]", where "r1" and "r2" are as
3610 usual the number of real and half the number of complex embeddings of
3611 the number field "K".
3612 "v[3]" is the 2-component vector containing the field discriminant and
3614 the index.
3615 "v[4]" is an integral basis in Hermite normal form.
3617 "v[5]" ("v.clgp") is a 3-component vector containing the class number
3619 ("v.clgp.no"), the structure of the class group as a product of cyclic
3620 groups of order "n_i" ("v.clgp.cyc"), and the corresponding generators
3621 of the class group of respective orders "n_i" ("v.clgp.gen").
3622 "v[6]" ("v.reg") is the regulator computed to an accuracy which is the
3624 maximum of an internally determined accuracy and of the default.
3625 "v[7]" is deprecated, maintained for backward compatibility and always
3627 equal to 1.
3628 "v[8]" ("v.tu") a vector with 2 components, the first being the number
3630 "w" of roots of unity in "K" and the second a primitive "w"-th root of
3631 unity expressed as a polynomial.
3632 "v[9]" ("v.fu") is a system of fundamental units also expressed as
3634 polynomials.
3635 If "flag = 1", and the precision happens to be insufficient for
3637 obtaining the fundamental units, the internal precision is doubled and
3638 the computation redone, until the exact results are obtained. Be warned
3639 that this can take a very long time when the coefficients of the
3640 fundamental units on the integral basis are very large, for example in
3641 large real quadratic fields. For this case, there are alternate
3642 compact representations for algebraic numbers, implemented in PARI but
3643 currently not available in GP.
3644 If "flag = 2", the fundamental units and roots of unity are not
3646 computed. Hence the result has only 7 components, the first seven
3647 ones.
3648 The library syntax is bnfclassunit0"(P,flag,tech,prec)".
3650 bnfclgp"(P,{tech = []})"
3652 as "bnfinit", but only outputs "bnf.clgp", i.e. the class group.
3653 The library syntax is classgrouponly"(P,tech,prec)", where tech is as
3655 described under "bnfinit".
3656 bnfdecodemodule"(nf,m)"
3658 if "m" is a module as output in the first component of an extension
3659 given by "bnrdisclist", outputs the true module.
3660 The library syntax is decodemodule"(nf,m)".
3662 bnfinit"(P,{flag = 0},{tech = []})"
3664 initializes a bnf structure. Used in programs such as "bnfisprincipal",
3665 "bnfisunit" or "bnfnarrow". By default, the results are conditional on
3666 a heuristic strengthening of the GRH, see se:GRHbnf. The result is a
3667 10-component vector bnf.
3668 This implements Buchmann's sub-exponential algorithm for computing the
3670 class group, the regulator and a system of fundamental units of the
3671 general algebraic number field "K" defined by the irreducible
3672 polynomial "P" with integer coefficients.
3673 If the precision becomes insufficient, "gp" outputs a warning
3675 ("fundamental units too large, not given") and does not strive to
3676 compute the units by default ("flag = 0").
3677 When "flag = 1", we insist on finding the fundamental units exactly. Be
3679 warned that this can take a very long time when the coefficients of the
3680 fundamental units on the integral basis are very large. If the
3681 fundamental units are simply too large to be represented in this form,
3682 an error message is issued. They could be obtained using the so-called
3683 compact representation of algebraic numbers as a formal product of
3684 algebraic integers. The latter is implemented internally but not
3685 publicly accessible yet.
3686 When "flag = 2", on the contrary, it is initially agreed that units are
3688 not computed. Note that the resulting bnf will not be suitable for
3689 "bnrinit", and that this flag provides negligible time savings compared
3690 to the default. In short, it is deprecated.
3691 When "flag = 3", computes a very small version of "bnfinit", a ``small
3693 Buchmann's number field'' (or sbnf for short) which contains enough
3694 information to recover the full "bnf" vector very rapidly, but which is
3695 much smaller and hence easy to store and print. It is supposed to be
3696 used in conjunction with "bnfmake".
3697 "tech" is a technical vector (empty by default, see se:GRHbnf).
3699 Careful use of this parameter may speed up your computations
3700 considerably.
3701 The components of a bnf or sbnf are technical and never used by the
3703 casual user. In fact: \emph{never access a component directly, always
3704 use a proper member function.} However, for the sake of completeness
3705 and internal documentation, their description is as follows. We use the
3706 notations explained in the book by H. Cohen, \emph{A Course in
3707 Computational Algebraic Number Theory}, Graduate Texts in Maths 138,
3708 Springer-Verlag, 1993, Section 6.5, and subsection 6.5.5 in particular.
3709 "bnf[1]" contains the matrix "W", i.e. the matrix in Hermite normal
3711 form giving relations for the class group on prime ideal generators "(
3712 wp _i)_{1 <= i <= r}".
3713 "bnf[2]" contains the matrix "B", i.e. the matrix containing the
3715 expressions of the prime ideal factorbase in terms of the " wp _i". It
3716 is an "r x c" matrix.
3717 "bnf[3]" contains the complex logarithmic embeddings of the system of
3719 fundamental units which has been found. It is an "(r_1+r_2) x
3720 (r_1+r_2-1)" matrix.
3721 "bnf[4]" contains the matrix "M''_C" of Archimedean components of the
3723 relations of the matrix "(W|B)".
3724 "bnf[5]" contains the prime factor base, i.e. the list of prime ideals
3726 used in finding the relations.
3727 "bnf[6]" used to contain a permutation of the prime factor base, but
3729 has been obsoleted. It contains a dummy 0.
3730 "bnf[7]" or "bnf.nf" is equal to the number field data "nf" as would be
3732 given by "nfinit".
3733 "bnf[8]" is a vector containing the classgroup "bnf.clgp" as a finite
3735 abelian group, the regulator "bnf.reg", a 1 (used to contain an
3736 obsolete ``check number''), the number of roots of unity and a
3737 generator "bnf.tu", the fundamental units "bnf.fu".
3738 "bnf[9]" is a 3-element row vector used in "bnfisprincipal" only and
3740 obtained as follows. Let "D = U W V" obtained by applying the Smith
3741 normal form algorithm to the matrix "W" ( = "bnf[1]") and let "U_r" be
3742 the reduction of "U" modulo "D". The first elements of the factorbase
3743 are given (in terms of "bnf.gen") by the columns of "U_r", with
3744 Archimedean component "g_a"; let also "GD_a" be the Archimedean
3745 components of the generators of the (principal) ideals defined by the
3746 "bnf.gen[i]^bnf.cyc[i]". Then "bnf[9] = [U_r, g_a, GD_a]".
3747 "bnf[10]" is by default unused and set equal to 0. This field is used
3749 to store further information about the field as it becomes available,
3750 which is rarely needed, hence would be too expensive to compute during
3751 the initial "bnfinit" call. For instance, the generators of the
3752 principal ideals "bnf.gen[i]^bnf.cyc[i]" (during a call to
3753 "bnrisprincipal"), or those corresponding to the relations in "W" and
3754 "B" (when the "bnf" internal precision needs to be increased).
3755 An sbnf is a 12 component vector "v", as follows. Let "bnf" be the
3757 result of a full "bnfinit", complete with units. Then "v[1]" is the
3758 polynomial "P", "v[2]" is the number of real embeddings "r_1", "v[3]"
3759 is the field discriminant, "v[4]" is the integral basis, "v[5]" is the
3760 list of roots as in the sixth component of "nfinit", "v[6]" is the
3761 matrix "MD" of "nfinit" giving a Z-basis of the different, "v[7]" is
3762 the matrix "W = bnf[1]", "v[8]" is the matrix "matalpha = bnf[2]",
3763 "v[9]" is the prime ideal factor base "bnf[5]" coded in a compact way,
3764 and ordered according to the permutation "bnf[6]", "v[10]" is the
3765 2-component vector giving the number of roots of unity and a generator,
3766 expressed on the integral basis, "v[11]" is the list of fundamental
3767 units, expressed on the integral basis, "v[12]" is a vector containing
3768 the algebraic numbers alpha corresponding to the columns of the matrix
3769 "matalpha", expressed on the integral basis.
3770 Note that all the components are exact (integral or rational), except
3772 for the roots in "v[5]". Note also that member functions will
3773 \emph{not} work on sbnf, you have to use "bnfmake" explicitly first.
3774 The library syntax is bnfinit0"(P,flag,tech,prec)".
3776 bnfisintnorm"(bnf,x)"
3778 computes a complete system of solutions (modulo units of positive norm)
3779 of the absolute norm equation "\Norm(a) = x", where "a" is an integer
3780 in "bnf". If "bnf" has not been certified, the correctness of the
3781 result depends on the validity of GRH.
3782 See also "bnfisnorm".
3784 The library syntax is bnfisintnorm"(bnf,x)".
3786 bnfisnorm"(bnf,x,{flag = 1})"
3788 tries to tell whether the rational number "x" is the norm of some
3789 element y in "bnf". Returns a vector "[a,b]" where "x = Norm(a)*b".
3790 Looks for a solution which is an "S"-unit, with "S" a certain set of
3791 prime ideals containing (among others) all primes dividing "x". If
3792 "bnf" is known to be Galois, set "flag = 0" (in this case, "x" is a
3793 norm iff "b = 1"). If "flag" is non zero the program adds to "S" the
3794 following prime ideals, depending on the sign of "flag". If "flag > 0",
3795 the ideals of norm less than "flag". And if "flag < 0" the ideals
3796 dividing "flag".
3797 Assuming GRH, the answer is guaranteed (i.e. "x" is a norm iff "b =
3799 1"), if "S" contains all primes less than "12 log (\disc(Bnf))^2",
3800 where "Bnf" is the Galois closure of "bnf".
3801 See also "bnfisintnorm".
3803 The library syntax is bnfisnorm"(bnf,x,flag,prec)", where "flag" and
3805 "prec" are "long"s.
3806 bnfissunit"(bnf,sfu,x)"
3808 "bnf" being output by "bnfinit", sfu by "bnfsunit", gives the column
3809 vector of exponents of "x" on the fundamental "S"-units and the roots
3810 of unity. If "x" is not a unit, outputs an empty vector.
3811 The library syntax is bnfissunit"(bnf,sfu,x)".
3813 bnfisprincipal"(bnf,x,{flag = 1})"
3815 "bnf" being the number field data output by "bnfinit", and "x" being
3816 either a Z-basis of an ideal in the number field (not necessarily in
3817 HNF) or a prime ideal in the format output by the function
3818 "idealprimedec", this function tests whether the ideal is principal or
3819 not. The result is more complete than a simple true/false answer: it
3820 gives a row vector "[v_1,v_2]", where
3821 "v_1" is the vector of components "c_i" of the class of the ideal "x"
3823 in the class group, expressed on the generators "g_i" given by
3824 "bnfinit" (specifically "bnf.gen"). The "c_i" are chosen so that "0 <=
3825 c_i < n_i" where "n_i" is the order of "g_i" (the vector of "n_i" being
3826 "bnf.cyc").
3827 "v_2" gives on the integral basis the components of "alpha" such that
3829 "x = alphaprod_ig_i^{c_i}". In particular, "x" is principal if and only
3830 if "v_1" is equal to the zero vector. In the latter case, "x =
3831 alphaZ_K" where "alpha" is given by "v_2". Note that if "alpha" is too
3832 large to be given, a warning message will be printed and "v_2" will be
3833 set equal to the empty vector.
3834 If "flag = 0", outputs only "v_1", which is much easier to compute.
3836 If "flag = 2", does as if "flag" were 0, but doubles the precision
3838 until a result is obtained.
3839 If "flag = 3", as in the default behaviour ("flag = 1"), but doubles
3841 the precision until a result is obtained.
3842 The user is warned that these two last setting may induce \emph{very}
3844 lengthy computations.
3845 The library syntax is isprincipalall"(bnf,x,flag)".
3847 bnfisunit"(bnf,x)"
3849 "bnf" being the number field data output by "bnfinit" and "x" being an
3850 algebraic number (type integer, rational or polmod), this outputs the
3851 decomposition of "x" on the fundamental units and the roots of unity if
3852 "x" is a unit, the empty vector otherwise. More precisely, if
3853 "u_1",...,"u_r" are the fundamental units, and "zeta" is the generator
3854 of the group of roots of unity ("bnf.tu"), the output is a vector
3855 "[x_1,...,x_r,x_{r+1}]" such that "x = u_1^{x_1}...
3856 u_r^{x_r}.zeta^{x_{r+1}}". The "x_i" are integers for "i <= r" and is
3857 an integer modulo the order of "zeta" for "i = r+1".
3858 The library syntax is isunit"(bnf,x)".
3860 bnfmake"(sbnf)"
3862 sbnf being a ``small "bnf"'' as output by "bnfinit""(x,3)", computes
3863 the complete "bnfinit" information. The result is \emph{not} identical
3864 to what "bnfinit" would yield, but is functionally identical. The
3865 execution time is very small compared to a complete "bnfinit". Note
3866 that if the default precision in "gp" (or "prec" in library mode) is
3867 greater than the precision of the roots "sbnf[5]", these are recomputed
3868 so as to get a result with greater accuracy.
3869 Note that the member functions are \emph{not} available for sbnf, you
3871 have to use "bnfmake" explicitly first.
3872 The library syntax is makebigbnf"(sbnf,prec)", where "prec" is a C long
3874 integer.
3875 bnfnarrow"(bnf)"
3877 "bnf" being as output by "bnfinit", computes the narrow class group of
3878 "bnf". The output is a 3-component row vector "v" analogous to the
3879 corresponding class group component "bnf.clgp" ("bnf[8][1]"): the first
3880 component is the narrow class number "v.no", the second component is a
3881 vector containing the SNF cyclic components "v.cyc" of the narrow class
3882 group, and the third is a vector giving the generators of the
3883 corresponding "v.gen" cyclic groups. Note that this function is a
3884 special case of "bnrinit".
3885 The library syntax is buchnarrow"(bnf)".
3887 bnfsignunit"(bnf)"
3889 "bnf" being as output by "bnfinit", this computes an "r_1 x
3890 (r_1+r_2-1)" matrix having "+-1" components, giving the signs of the
3891 real embeddings of the fundamental units. The following functions
3892 compute generators for the totally positive units:
3893 /* exponents of totally positive units generators on bnf.tufu */
3895 tpuexpo(bnf)=
3896 { local(S,d,K);
3897 S = bnfsignunit(bnf); d = matsize(S);
3899 S = matrix(d[1],d[2], i,j, if (S[i,j] < 0, 1,0));
3900 S = concat(vectorv(d[1],i,1), S); \\ add sign(-1)
3901 K = lift(matker(S * Mod(1,2)));
3902 if (K, mathnfmodid(K, 2), 2*matid(d[1]))
3903 }
3904 /* totally positive units */
3906 tpu(bnf)=
3907 { local(vu = bnf.tufu, ex = tpuexpo(bnf));
3908 vector(#ex-1, i, factorback(vu, ex[,i+1])) \\ ex[,1] is 1
3910 }
3911 The library syntax is signunits"(bnf)".
3913 bnfreg"(bnf)"
3915 "bnf" being as output by "bnfinit", computes its regulator.
3916 The library syntax is regulator"(bnf,tech,prec)", where tech is as in
3918 "bnfinit".
3919 bnfsunit"(bnf,S)"
3921 computes the fundamental "S"-units of the number field "bnf" (output by
3922 "bnfinit"), where "S" is a list of prime ideals (output by
3923 "idealprimedec"). The output is a vector "v" with 6 components.
3924 "v[1]" gives a minimal system of (integral) generators of the "S"-unit
3926 group modulo the unit group.
3927 "v[2]" contains technical data needed by "bnfissunit".
3929 "v[3]" is an empty vector (used to give the logarithmic embeddings of
3931 the generators in "v[1]" in version 2.0.16).
3932 "v[4]" is the "S"-regulator (this is the product of the regulator, the
3934 determinant of "v[2]" and the natural logarithms of the norms of the
3935 ideals in "S").
3936 "v[5]" gives the "S"-class group structure, in the usual format (a row
3938 vector whose three components give in order the "S"-class number, the
3939 cyclic components and the generators).
3940 "v[6]" is a copy of "S".
3942 The library syntax is bnfsunit"(bnf,S,prec)".
3944 bnfunit"(bnf)"
3946 "bnf" being as output by "bnfinit", outputs the vector of fundamental
3947 units of the number field.
3948 This function is mostly useless, since it will only succeed if bnf
3950 contains the units, in which case "bnf.fu" is recommanded instead, or
3951 bnf was produced with "bnfinit(,,2)", which is itself deprecated.
3952 The library syntax is buchfu"(bnf)".
3954 bnrL1"(bnr,{subgroup},{flag = 0})"
3956 bnr being the number field data which is output by "bnrinit(,,1)" and
3957 subgroup being a square matrix defining a congruence subgroup of the
3958 ray class group corresponding to bnr (the trivial congruence subgroup
3959 if omitted), returns for each character "chi" of the ray class group
3960 which is trivial on this subgroup, the value at "s = 1" (or "s = 0") of
3961 the abelian "L"-function associated to "chi". For the value at "s = 0",
3962 the function returns in fact for each character "chi" a vector "[r_chi
3963 , c_chi]" where "r_chi" is the order of "L(s, chi)" at "s = 0" and
3964 "c_chi" the first non-zero term in the expansion of "L(s, chi)" at "s =
3965 0"; in other words
3966 "L(s, chi) = c_chi.s^{r_chi} + O(s^{r_chi + 1})"
3968 near 0. flag is optional, default value is 0; its binary digits mean 1:
3970 compute at "s = 1" if set to 1 or "s = 0" if set to 0, 2: compute the
3971 primitive "L"-functions associated to "chi" if set to 0 or the
3972 "L"-function with Euler factors at prime ideals dividing the modulus of
3973 bnr removed if set to 1 (this is the so-called "L_S(s, chi)" function
3974 where "S" is the set of infinite places of the number field together
3975 with the finite prime ideals dividing the modulus of bnr, see the
3976 example below), 3: returns also the character. Example:
3977 bnf = bnfinit(x^2 - 229);
3979 bnr = bnrinit(bnf,1,1);
3980 bnrL1(bnr)
3981 returns the order and the first non-zero term of the abelian
3983 "L"-functions "L(s, chi)" at "s = 0" where "chi" runs through the
3984 characters of the class group of "Q( sqrt {229})". Then
3985 bnr2 = bnrinit(bnf,2,1);
3987 bnrL1(bnr2,,2)
3988 returns the order and the first non-zero terms of the abelian
3990 "L"-functions "L_S(s, chi)" at "s = 0" where "chi" runs through the
3991 characters of the class group of "Q( sqrt {229})" and "S" is the set of
3992 infinite places of "Q( sqrt {229})" together with the finite prime 2.
3993 Note that the ray class group modulo 2 is in fact the class group, so
3994 "bnrL1(bnr2,0)" returns exactly the same answer as "bnrL1(bnr,0)".
3995 The library syntax is bnrL1"(bnr,subgroup,flag,prec)", where an omitted
3997 subgroup is coded as "NULL".
3998 bnrclass"(bnf,ideal,{flag = 0})"
4000 \emph{this function is DEPRECATED, use "bnrinit"}.
4001 "bnf" being as output by "bnfinit" (the units are mandatory unless the
4003 ideal is trivial), and ideal being a modulus, computes the ray class
4004 group of the number field for the modulus ideal, as a finite abelian
4005 group.
4006 The library syntax is bnrclass0"(bnf,ideal,flag)".
4008 bnrclassno"(bnf,I)"
4010 "bnf" being as output by "bnfinit" (units are mandatory unless the
4011 ideal is trivial), and "I" being a modulus, computes the ray class
4012 number of the number field for the modulus "I". This is faster than
4013 "bnrinit" and should be used if only the ray class number is desired.
4014 See "bnrclassnolist" if you need ray class numbers for all moduli less
4015 than some bound.
4016 The library syntax is bnrclassno"(bnf,I)".
4018 bnrclassnolist"(bnf,list)"
4020 "bnf" being as output by "bnfinit", and list being a list of moduli
4021 (with units) as output by "ideallist" or "ideallistarch", outputs the
4022 list of the class numbers of the corresponding ray class groups. To
4023 compute a single class number, "bnrclassno" is more efficient.
4024 ? bnf = bnfinit(x^2 - 2);
4026 ? L = ideallist(bnf, 100, 2);
4027 ? H = bnrclassnolist(bnf, L);
4028 ? H[98]
4029 %4 = [1, 3, 1]
4030 ? l = L[1][98]; ids = vector(#l, i, l[i].mod[1])
4031 %5 = [[98, 88; 0, 1], [14, 0; 0, 7], [98, 10; 0, 1]]
4032 The weird "l[i].mod[1]", is the first component of "l[i].mod", i.e.
4034 the finite part of the conductor. (This is cosmetic: since by
4035 construction the archimedean part is trivial, I do not want to see it).
4036 This tells us that the ray class groups modulo the ideals of norm 98
4037 (printed as %5) have respectively order 1, 3 and 1. Indeed, we may
4038 check directly :
4039 ? bnrclassno(bnf, ids[2])
4041 %6 = 3
4042 The library syntax is bnrclassnolist"(bnf,list)".
4044 bnrconductor"(a_1,{a_2},{a_3}, {flag = 0})"
4046 conductor "f" of the subfield of a ray class field as defined by
4047 "[a_1,a_2,a_3]" (see "bnr" at the beginning of this section).
4048 If "flag = 0", returns "f".
4050 If "flag = 1", returns "[f, Cl_f, H]", where "Cl_f" is the ray class
4052 group modulo "f", as a finite abelian group; finally "H" is the
4053 subgroup of "Cl_f" defining the extension.
4054 If "flag = 2", returns "[f, bnr(f), H]", as above except "Cl_f" is
4056 replaced by a "bnr" structure, as output by "bnrinit(,f,1)".
4057 The library syntax is conductor"(bnr, subgroup, flag)", where an
4059 omitted subgroup (trivial subgroup, i.e. ray class field) is input as
4060 "NULL", and "flag" is a C long.
4061 bnrconductorofchar"(bnr,chi)"
4063 bnr being a big ray number field as output by "bnrinit", and chi being
4064 a row vector representing a character as expressed on the generators of
4065 the ray class group, gives the conductor of this character as a
4066 modulus.
4067 The library syntax is bnrconductorofchar"(bnr,chi)".
4069 bnrdisc"(a1,{a2},{a3},{flag = 0})"
4071 "a1", "a2", "a3" defining a big ray number field "L" over a ground
4072 field "K" (see "bnr" at the beginning of this section for the meaning
4073 of "a1", "a2", "a3"), outputs a 3-component row vector "[N,R_1,D]",
4074 where "N" is the (absolute) degree of "L", "R_1" the number of real
4075 places of "L", and "D" the discriminant of "L/Q", including sign (if
4076 "flag = 0").
4077 If "flag = 1", as above but outputs relative data. "N" is now the
4079 degree of "L/K", "R_1" is the number of real places of "K" unramified
4080 in "L" (so that the number of real places of "L" is equal to "R_1"
4081 times the relative degree "N"), and "D" is the relative discriminant
4082 ideal of "L/K".
4083 If "flag = 2", as the default case, except that if the modulus is not
4085 the exact conductor corresponding to the "L", no data is computed and
4086 the result is 0.
4087 If "flag = 3", as case 2, but output relative data.
4089 The library syntax is bnrdisc0"(a1,a2,a3,flag)".
4091 bnrdisclist"(bnf,bound,{arch})"
4093 "bnf" being as output by "bnfinit" (with units), computes a list of
4094 discriminants of Abelian extensions of the number field by increasing
4095 modulus norm up to bound bound. The ramified Archimedean places are
4096 given by arch; all possible values are taken if arch is omitted.
4097 The alternative syntax "bnrdisclist(bnf,list)" is supported, where list
4099 is as output by "ideallist" or "ideallistarch" (with units), in which
4100 case arch is disregarded.
4101 The output "v" is a vector of vectors, where "v[i][j]" is understood to
4103 be in fact "V[2^{15}(i-1)+j]" of a unique big vector "V". (This akward
4104 scheme allows for larger vectors than could be otherwise represented.)
4105 "V[k]" is itself a vector "W", whose length is the number of ideals of
4107 norm "k". We consider first the case where arch was specified. Each
4108 component of "W" corresponds to an ideal "m" of norm "k", and gives
4109 invariants associated to the ray class field "L" of "bnf" of conductor
4110 "[m, arch]". Namely, each contains a vector "[m,d,r,D]" with the
4111 following meaning: "m" is the prime ideal factorization of the modulus,
4112 "d = [L:Q]" is the absolute degree of "L", "r" is the number of real
4113 places of "L", and "D" is the factorization of its absolute
4114 discriminant. We set "d = r = D = 0" if "m" is not the finite part of a
4115 conductor.
4116 If arch was omitted, all "t = 2^{r_1}" possible values are taken and a
4118 component of "W" has the form "[m, [[d_1,r_1,D_1],...,
4119 [d_t,r_t,D_t]]]", where "m" is the finite part of the conductor as
4120 above, and "[d_i,r_i,D_i]" are the invariants of the ray class field of
4121 conductor "[m,v_i]", where "v_i" is the "i"-th archimedean component,
4122 ordered by inverse lexicographic order; so "v_1 = [0,...,0]", "v_2 =
4123 [1,0...,0]", etc. Again, we set "d_i = r_i = D_i = 0" if "[m,v_i]" is
4124 not a conductor.
4125 Finally, each prime ideal "pr = [p,alpha,e,f,beta]" in the prime
4127 factorization "m" is coded as the integer "p.n^2+(f-1).n+(j-1)", where
4128 "n" is the degree of the base field and "j" is such that
4129 "pr = idealprimedec(nf,p)[j]".
4131 "m" can be decoded using "bnfdecodemodule".
4133 Note that to compute such data for a single field, either "bnrclassno"
4135 or "bnrdisc" is more efficient.
4136 The library syntax is bnrdisclist0"(bnf,bound,arch)".
4138 bnrinit"(bnf,f,{flag = 0})"
4140 "bnf" is as output by "bnfinit", "f" is a modulus, initializes data
4141 linked to the ray class group structure corresponding to this module, a
4142 so-called bnr structure. The following member functions are available
4143 on the result: ".bnf" is the underlying bnf, ".mod" the modulus, ".bid"
4144 the bid structure associated to the modulus; finally, ".clgp", ".no",
4145 ".cyc", "clgp" refer to the ray class group (as a finite abelian
4146 group), its cardinality, its elementary divisors, its generators.
4147 The last group of functions are different from the members of the
4149 underlying bnf, which refer to the class group; use "bnr.bnf.xxx" to
4150 access these, e.g. "bnr.bnf.cyc" to get the cyclic decomposition of the
4151 class group.
4152 They are also different from the members of the underlying bid, which
4154 refer to "(\O_K/f)^*"; use "bnr.bid.xxx" to access these,
4155 e.g. "bnr.bid.no" to get "phi(f)".
4156 If "flag = 0" (default), the generators of the ray class group are not
4158 computed, which saves time. Hence "bnr.gen" would produce an error.
4159 If "flag = 1", as the default, except that generators are computed.
4161 The library syntax is bnrinit0"(bnf,f,flag)".
4163 bnrisconductor"(a1,{a2},{a3})"
4165 "a1", "a2", "a3" represent an extension of the base field, given by
4166 class field theory for some modulus encoded in the parameters. Outputs
4167 1 if this modulus is the conductor, and 0 otherwise. This is slightly
4168 faster than "bnrconductor".
4169 The library syntax is bnrisconductor"(a1,a2,a3)" and the result is a
4171 "long".
4172 bnrisprincipal"(bnr,x,{flag = 1})"
4174 bnr being the number field data which is output by "bnrinit""(,,1)" and
4175 "x" being an ideal in any form, outputs the components of "x" on the
4176 ray class group generators in a way similar to "bnfisprincipal". That
4177 is a 2-component vector "v" where "v[1]" is the vector of components of
4178 "x" on the ray class group generators, "v[2]" gives on the integral
4179 basis an element "alpha" such that "x = alphaprod_ig_i^{x_i}".
4180 If "flag = 0", outputs only "v_1". In that case, bnr need not contain
4182 the ray class group generators, i.e. it may be created with
4183 "bnrinit""(,,0)"
4184 The library syntax is bnrisprincipal"(bnr,x,flag)".
4186 bnrrootnumber"(bnr,chi,{flag = 0})"
4188 if "chi = chi" is a (not necessarily primitive) character over bnr, let
4189 "L(s,chi) = sum_{id} chi(id) N(id)^{-s}" be the associated Artin
4190 L-function. Returns the so-called Artin root number, i.e. the complex
4191 number "W(chi)" of modulus 1 such that
4192 "Lambda(1-s,chi) = W(chi) Lambda(s,\overline{chi})"
4194 where "Lambda(s,chi) = A(chi)^{s/2}gamma_chi(s) L(s,chi)" is the
4196 enlarged L-function associated to "L".
4197 The generators of the ray class group are needed, and you can set "flag
4199 = 1" if the character is known to be primitive. Example:
4200 bnf = bnfinit(x^2 - 145);
4202 bnr = bnrinit(bnf,7,1);
4203 bnrrootnumber(bnr, [5])
4204 returns the root number of the character "chi" of "\Cl_7(Q( sqrt
4206 {145}))" such that "chi(g) = zeta^5", where "g" is the generator of the
4207 ray-class field and "zeta = e^{2iPi/N}" where "N" is the order of "g"
4208 ("N = 12" as "bnr.cyc" readily tells us).
4209 The library syntax is bnrrootnumber"(bnf,chi,flag)"
4211 bnrstark"{(bnr,{subgroup})}"
4213 bnr being as output by "bnrinit(,,1)", finds a relative equation for
4214 the class field corresponding to the modulus in bnr and the given
4215 congruence subgroup (as usual, omit "subgroup" if you want the whole
4216 ray class group).
4217 The routine uses Stark units and needs to find a suitable auxilliary
4219 conductor, which may not exist when the class field is not cyclic over
4220 the base. In this case "bnrstark" is allowed to return a vector of
4221 polynomials defining \emph{independent} relative extensions, whose
4222 compositum is the requested class field. It was decided that it was
4223 more useful to keep the extra information thus made available, hence
4224 the user has to take the compositum herself.
4225 The main variable of bnr must not be "x", and the ground field and the
4227 class field must be totally real. When the base field is Q, the vastly
4228 simpler "galoissubcyclo" is used instead. Here is an example:
4229 bnf = bnfinit(y^2 - 3);
4231 bnr = bnrinit(bnf, 5, 1);
4232 pol = bnrstark(bnr)
4233 returns the ray class field of "Q( sqrt {3})" modulo 5. Usually, one
4235 wants to apply to the result one of
4236 rnfpolredabs(bnf, pol, 16 + 2) \\ compute a reduced relative polynomial
4238 rnfpolredabs(bnf, pol, 16 + 2) \\ compute a reduced absolute polynomial
4239 The library syntax is bnrstark"(bnr,subgroup)", where an omitted
4241 subgroup is coded by "NULL".
4242 dirzetak"(nf,b)"
4244 gives as a vector the first "b" coefficients of the Dedekind zeta
4245 function of the number field "nf" considered as a Dirichlet series.
4246 The library syntax is dirzetak"(nf,b)".
4248 factornf"(x,t)"
4250 factorization of the univariate polynomial "x" over the number field
4251 defined by the (univariate) polynomial "t". "x" may have coefficients
4252 in Q or in the number field. The algorithm reduces to factorization
4253 over Q (Trager's trick). The direct approach of "nffactor", which uses
4254 van Hoeij's method in a relative setting, is in general faster.
4255 The main variable of "t" must be of \emph{lower} priority than that of
4257 "x" (see "Label se:priority"). However if non-rational number field
4258 elements occur (as polmods or polynomials) as coefficients of "x", the
4259 variable of these polmods \emph{must} be the same as the main variable
4260 of "t". For example
4261 ? factornf(x^2 + Mod(y, y^2+1), y^2+1);
4263 ? factornf(x^2 + y, y^2+1); \\ these two are OK
4264 ? factornf(x^2 + Mod(z,z^2+1), y^2+1)
4265 *** factornf: inconsistent data in rnf function.
4266 ? factornf(x^2 + z, y^2+1)
4267 *** factornf: incorrect variable in rnf function.
4268 The library syntax is polfnf"(x,t)".
4270 galoisexport"(gal,{flag = 0})"
4272 gal being be a Galois field as output by "galoisinit", export the
4273 underlying permutation group as a string suitable for (no flags or
4274 "flag = 0") GAP or ("flag = 1") Magma. The following example compute
4275 the index of the underlying abstract group in the GAP library:
4276 ? G = galoisinit(x^6+108);
4278 ? s = galoisexport(G)
4279 %2 = "Group((1, 2, 3)(4, 5, 6), (1, 4)(2, 6)(3, 5))"
4280 ? extern("echo \"IdGroup("s");\" | gap -q")
4281 %3 = [6, 1]
4282 ? galoisidentify(G)
4283 %4 = [6, 1]
4284 This command also accepts subgroups returned by "galoissubgroups".
4286 The library syntax is galoisexport"(gal,flag)".
4288 galoisfixedfield"(gal,perm,{flag = 0},{v = y}))"
4290 gal being be a Galois field as output by "galoisinit" and perm an
4291 element of "gal.group" or a vector of such elements, computes the fixed
4292 field of gal by the automorphism defined by the permutations perm of
4293 the roots "gal.roots". "P" is guaranteed to be squarefree modulo
4294 "gal.p".
4295 If no flags or "flag = 0", output format is the same as for
4297 "nfsubfield", returning "[P,x]" such that "P" is a polynomial defining
4298 the fixed field, and "x" is a root of "P" expressed as a polmod in
4299 "gal.pol".
4300 If "flag = 1" return only the polynomial "P".
4302 If "flag = 2" return "[P,x,F]" where "P" and "x" are as above and "F"
4304 is the factorization of "gal.pol" over the field defined by "P", where
4305 variable "v" ("y" by default) stands for a root of "P". The priority of
4306 "v" must be less than the priority of the variable of "gal.pol" (see
4307 "Label se:priority"). Example:
4308 ? G = galoisinit(x^4+1);
4310 ? galoisfixedfield(G,G.group[2],2)
4311 %2 = [x^2 + 2, Mod(x^3 + x, x^4 + 1), [x^2 - y*x - 1, x^2 + y*x - 1]]
4312 computes the factorization "x^4+1 = (x^2- sqrt {-2}x-1)(x^2+ sqrt
4314 {-2}x-1)"
4315 The library syntax is galoisfixedfield"(gal,perm,flag,"v")", where "v"
4317 is a variable number, an omitted "v" being coded by "-1".
4318 galoisidentify"(gal)"
4320 gal being be a Galois field as output by "galoisinit", output the
4321 isomorphism class of the underlying abstract group as a two-components
4322 vector "[o,i]", where "o" is the group order, and "i" is the group
4323 index in the GAP4 Small Group library, by Hans Ulrich Besche, Bettina
4324 Eick and Eamonn O'Brien.
4325 This command also accepts subgroups returned by "galoissubgroups".
4327 The current implementation is limited to degree less or equal to 127.
4329 Some larger ``easy'' orders are also supported.
4330 The output is similar to the output of the function "IdGroup" in GAP4.
4332 Note that GAP4 "IdGroup" handles all groups of order less than 2000
4333 except 1024, so you can use "galoisexport" and GAP4 to identify large
4334 Galois groups.
4335 The library syntax is galoisidentify"(gal)".
4337 galoisinit"(pol,{den})"
4339 computes the Galois group and all necessary information for computing
4340 the fixed fields of the Galois extension "K/Q" where "K" is the number
4341 field defined by "pol" (monic irreducible polynomial in "Z[X]" or a
4342 number field as output by "nfinit"). The extension "K/Q" must be Galois
4343 with Galois group ``weakly'' super-solvable (see "nfgaloisconj")
4344 This is a prerequisite for most of the "galois""xxx" routines. For
4346 instance:
4347 P = x^6 + 108;
4349 G = galoisinit(P);
4350 L = galoissubgroups(G);
4351 vector(#L, i, galoisisabelian(L[i],1))
4352 vector(#L, i, galoisidentify(L[i]))
4353 The output is an 8-component vector gal.
4355 "gal[1]" contains the polynomial pol ("gal.pol").
4357 "gal[2]" is a three-components vector "[p,e,q]" where "p" is a prime
4359 number ("gal.p") such that pol totally split modulo "p" , "e" is an
4360 integer and "q = p^e" ("gal.mod") is the modulus of the roots in
4361 "gal.roots".
4362 "gal[3]" is a vector "L" containing the "p"-adic roots of pol as
4364 integers implicitly modulo "gal.mod". ("gal.roots").
4365 "gal[4]" is the inverse of the Van der Monde matrix of the "p"-adic
4367 roots of pol, multiplied by "gal[5]".
4368 "gal[5]" is a multiple of the least common denominator of the
4370 automorphisms expressed as polynomial in a root of pol.
4371 "gal[6]" is the Galois group "G" expressed as a vector of permutations
4373 of "L" ("gal.group").
4374 "gal[7]" is a generating subset "S = [s_1,...,s_g]" of "G" expressed as
4376 a vector of permutations of "L" ("gal.gen").
4377 "gal[8]" contains the relative orders "[o_1,...,o_g]" of the generators
4379 of "S" ("gal.orders").
4380 Let "H" be the maximal normal supersolvable subgroup of "G", we have
4382 the following properties:
4383 \item if "G/H ~ A_4" then "[o_1,...,o_g]" ends by "[2,2,3]".
4385 \item if "G/H ~ S_4" then "[o_1,...,o_g]" ends by "[2,2,3,2]".
4387 \item else "G" is super-solvable.
4389 \item for "1 <= i <= g" the subgroup of "G" generated by
4391 "[s_1,...,s_g]" is normal, with the exception of "i = g-2" in the
4392 second case and of "i = g-3" in the third.
4393 \item the relative order "o_i" of "s_i" is its order in the quotient
4395 group "G/<s_1,...,s_{i-1}>", with the same exceptions.
4396 \item for any "x belongs to G" there exists a unique family
4398 "[e_1,...,e_g]" such that (no exceptions):
4399 -- for "1 <= i <= g" we have "0 <= e_i < o_i"
4401 -- "x = g_1^{e_1}g_2^{e_2}...g_n^{e_n}"
4403 If present "den" must be a suitable value for "gal[5]".
4405 The library syntax is galoisinit"(gal,den)".
4407 galoisisabelian"(gal,{fl = 0})"
4409 gal being as output by "galoisinit", return 0 if gal is not an abelian
4410 group, and the HNF matrix of gal over "gal.gen" if "fl = 0", 1 if "fl =
4411 1".
4412 This command also accepts subgroups returned by "galoissubgroups".
4414 The library syntax is galoisisabelian"(gal,fl)" where fl is a C long
4416 integer.
4417 galoispermtopol"(gal,perm)"
4419 gal being a Galois field as output by "galoisinit" and perm a element
4420 of "gal.group", return the polynomial defining the Galois automorphism,
4421 as output by "nfgaloisconj", associated with the permutation perm of
4422 the roots "gal.roots". perm can also be a vector or matrix, in this
4423 case, "galoispermtopol" is applied to all components recursively.
4424 Note that
4426 G = galoisinit(pol);
4428 galoispermtopol(G, G[6])~
4429 is equivalent to "nfgaloisconj(pol)", if degree of pol is greater or
4431 equal to 2.
4432 The library syntax is galoispermtopol"(gal,perm)".
4434 galoissubcyclo"(N,H,{fl = 0},{v})"
4436 computes the subextension of "Q(zeta_n)" fixed by the subgroup "H
4437 \subset (Z/nZ)^*". By the Kronecker-Weber theorem, all abelian number
4438 fields can be generated in this way (uniquely if "n" is taken to be
4439 minimal).
4440 The pair "(n, H)" is deduced from the parameters "(N, H)" as follows
4442 \item "N" an integer: then "n = N"; "H" is a generator, i.e. an integer
4444 or an integer modulo "n"; or a vector of generators.
4445 \item "N" the output of znstar(n). "H" as in the first case above, or a
4447 matrix, taken to be a HNF left divisor of the SNF for "(Z/nZ)^*" (of
4448 type "N.cyc"), giving the generators of "H" in terms of "N.gen".
4449 \item "N" the output of "bnrinit(bnfinit(y), m, 1)" where "m" is a
4451 module. "H" as in the first case, or a matrix taken to be a HNF left
4452 divisor of the SNF for the ray class group modulo "m" (of type
4453 "N.cyc"), giving the generators of "H" in terms of "N.gen".
4454 In this last case, beware that "H" is understood relatively to "N"; in
4456 particular, if the infinite place does not divide the module, e.g if
4457 "m" is an integer, then it is not a subgroup of "(Z/nZ)^*", but of its
4458 quotient by "{+- 1}".
4459 If "fl = 0", compute a polynomial (in the variable v) defining the the
4461 subfield of "Q(zeta_n)" fixed by the subgroup H of "(Z/nZ)^*".
4462 If "fl = 1", compute only the conductor of the abelian extension, as a
4464 module.
4465 If "fl = 2", output "[pol, N]", where "pol" is the polynomial as output
4467 when "fl = 0" and "N" the conductor as output when "fl = 1".
4468 The following function can be used to compute all subfields of
4470 "Q(zeta_n)" (of exact degree "d", if "d" is set):
4471 subcyclo(n, d = -1)=
4473 {
4474 local(bnr,L,IndexBound);
4475 IndexBound = if (d < 0, n, [d]);
4476 bnr = bnrinit(bnfinit(y), [n,[1]], 1);
4477 L = subgrouplist(bnr, IndexBound, 1);
4478 vector(#L,i, galoissubcyclo(bnr,L[i]));
4479 }
4480 Setting "L = subgrouplist(bnr, IndexBound)" would produce subfields of
4482 exact conductor "n oo ".
4483 The library syntax is galoissubcyclo"(N,H,fl,v)" where fl is a C long
4485 integer, and v a variable number.
4486 galoissubfields"(G,{fl = 0},{v})"
4488 Output all the subfields of the Galois group G, as a vector. This
4489 works by applying "galoisfixedfield" to all subgroups. The meaning of
4490 the flag fl is the same as for "galoisfixedfield".
4491 The library syntax is galoissubfields"(G,fl,v)", where fl is a long and
4493 v a variable number.
4494 galoissubgroups"(gal)"
4496 Output all the subgroups of the Galois group "gal". A subgroup is a
4497 vector [gen, orders], with the same meaning as for "gal.gen" and
4498 "gal.orders". Hence gen is a vector of permutations generating the
4499 subgroup, and orders is the relatives orders of the generators. The
4500 cardinal of a subgroup is the product of the relative orders. Such
4501 subgroup can be used instead of a Galois group in the following
4502 command: "galoisisabelian", "galoissubgroups", "galoisexport" and
4503 "galoisidentify".
4504 To get the subfield fixed by a subgroup sub of gal, use
4506 galoisfixedfield(gal,sub[1])
4508 The library syntax is galoissubgroups"(gal)".
4510 idealadd"(nf,x,y)"
4512 sum of the two ideals "x" and "y" in the number field "nf". When "x"
4513 and "y" are given by Z-bases, this does not depend on "nf" and can be
4514 used to compute the sum of any two Z-modules. The result is given in
4515 HNF.
4516 The library syntax is idealadd"(nf,x,y)".
4518 idealaddtoone"(nf,x,{y})"
4520 "x" and "y" being two co-prime integral ideals (given in any form),
4521 this gives a two-component row vector "[a,b]" such that "a belongs to
4522 x", "b belongs to y" and "a+b = 1".
4523 The alternative syntax "idealaddtoone(nf,v)", is supported, where "v"
4525 is a "k"-component vector of ideals (given in any form) which sum to
4526 "Z_K". This outputs a "k"-component vector "e" such that "e[i] belongs
4527 to x[i]" for "1 <= i <= k" and "sum_{1 <= i <= k}e[i] = 1".
4528 The library syntax is idealaddtoone0"(nf,x,y)", where an omitted "y" is
4530 coded as "NULL".
4531 idealappr"(nf,x,{flag = 0})"
4533 if "x" is a fractional ideal (given in any form), gives an element
4534 "alpha" in "nf" such that for all prime ideals " wp " such that the
4535 valuation of "x" at " wp " is non-zero, we have "v_{ wp }(alpha) = v_{
4536 wp }(x)", and. "v_{ wp }(alpha) >= 0" for all other "{ wp }".
4537 If "flag" is non-zero, "x" must be given as a prime ideal
4539 factorization, as output by "idealfactor", but possibly with zero or
4540 negative exponents. This yields an element "alpha" such that for all
4541 prime ideals " wp " occurring in "x", "v_{ wp }(alpha)" is equal to the
4542 exponent of " wp " in "x", and for all other prime ideals, "v_{ wp
4543 }(alpha) >= 0". This generalizes "idealappr(nf,x,0)" since zero
4544 exponents are allowed. Note that the algorithm used is slightly
4545 different, so that "idealappr(nf,idealfactor(nf,x))" may not be the
4546 same as "idealappr(nf,x,1)".
4547 The library syntax is idealappr0"(nf,x,flag)".
4549 idealchinese"(nf,x,y)"
4551 "x" being a prime ideal factorization (i.e. a 2 by 2 matrix whose first
4552 column contain prime ideals, and the second column integral exponents),
4553 "y" a vector of elements in "nf" indexed by the ideals in "x", computes
4554 an element "b" such that
4555 "v_ wp (b - y_ wp ) >= v_ wp (x)" for all prime ideals in "x" and "v_
4557 wp (b) >= 0" for all other " wp ".
4558 The library syntax is idealchinese"(nf,x,y)".
4560 idealcoprime"(nf,x,y)"
4562 given two integral ideals "x" and "y" in the number field "nf", finds a
4563 "beta" in the field, expressed on the integral basis "nf[7]", such that
4564 "beta.x" is an integral ideal coprime to "y".
4565 The library syntax is idealcoprime"(nf,x,y)".
4567 idealdiv"(nf,x,y,{flag = 0})"
4569 quotient "x.y^{-1}" of the two ideals "x" and "y" in the number field
4570 "nf". The result is given in HNF.
4571 If "flag" is non-zero, the quotient "x.y^{-1}" is assumed to be an
4573 integral ideal. This can be much faster when the norm of the quotient
4574 is small even though the norms of "x" and "y" are large.
4575 The library syntax is idealdiv0"(nf,x,y,flag)". Also available are "
4577 idealdiv(nf,x,y)" ("flag = 0") and " idealdivexact(nf,x,y)" ("flag =
4578 1").
4579 idealfactor"(nf,x)"
4581 factors into prime ideal powers the ideal "x" in the number field "nf".
4582 The output format is similar to the "factor" function, and the prime
4583 ideals are represented in the form output by the "idealprimedec"
4584 function, i.e. as 5-element vectors.
4585 The library syntax is idealfactor"(nf,x)".
4587 idealhnf"(nf,a,{b})"
4589 gives the Hermite normal form matrix of the ideal "a". The ideal can be
4590 given in any form whatsoever (typically by an algebraic number if it is
4591 principal, by a "Z_K"-system of generators, as a prime ideal as given
4592 by "idealprimedec", or by a Z-basis).
4593 If "b" is not omitted, assume the ideal given was "aZ_K+bZ_K", where
4595 "a" and "b" are elements of "K" given either as vectors on the integral
4596 basis "nf[7]" or as algebraic numbers.
4597 The library syntax is idealhnf0"(nf,a,b)" where an omitted "b" is coded
4599 as "NULL". Also available is " idealhermite(nf,a)" ("b" omitted).
4600 idealintersect"(nf,A,B)"
4602 intersection of the two ideals "A" and "B" in the number field "nf".
4603 The result is given in HNF.
4604 ? nf = nfinit(x^2+1);
4606 ? idealintersect(nf, 2, x+1)
4607 %2 =
4608 [2 0]
4609 [0 2]
4611 This function does not apply to general Z-modules, e.g. orders, since
4613 its arguments are replaced by the ideals they generate. The following
4614 script intersects Z-modules "A" and "B" given by matrices of compatible
4615 dimensions with integer coefficients:
4616 ZM_intersect(A,B) =
4618 { local( Ker = matkerint(concat(A,B)) );
4619 mathnf(A * vecextract(Ker, Str("..", #A), ".."))
4620 }
4621 The library syntax is idealintersect"(nf,A,B)".
4623 idealinv"(nf,x)"
4625 inverse of the ideal "x" in the number field "nf". The result is the
4626 Hermite normal form of the inverse of the ideal, together with the
4627 opposite of the Archimedean information if it is given.
4628 The library syntax is idealinv"(nf,x)".
4630 ideallist"(nf,bound,{flag = 4})"
4632 computes the list of all ideals of norm less or equal to bound in the
4633 number field nf. The result is a row vector with exactly bound
4634 components. Each component is itself a row vector containing the
4635 information about ideals of a given norm, in no specific order,
4636 depending on the value of "flag":
4637 The possible values of "flag" are:
4639 0: give the bid associated to the ideals, without generators.
4641 1: as 0, but include the generators in the bid.
4643 2: in this case, nf must be a bnf with units. Each component is of
4645 the form "[bid,U]", where bid is as case 0 and "U" is a vector of
4646 discrete logarithms of the units. More precisely, it gives the
4647 "ideallog"s with respect to bid of "bnf.tufu". This structure is
4648 technical, and only meant to be used in conjunction with
4649 "bnrclassnolist" or "bnrdisclist".
4650 3: as 2, but include the generators in the bid.
4652 4: give only the HNF of the ideal.
4654 ? #L[65]
4656 %4 = 4 \\ A single ideal of norm 1
4657 ? #L[65]
4658 %4 = 4 \\ There are 4 ideals of norm 4 in Z[i]
4659 If one wants more information, one could do instead:
4661 ? nf = nfinit(x^2+1);
4663 ? L = ideallist(nf, 100, 0);
4664 ? l = L[25]; vector(#l, i, l[i].clgp)
4665 %3 = [[20, [20]], [16, [4, 4]], [20, [20]]]
4666 ? l[1].mod
4667 %4 = [[25, 18; 0, 1], []]
4668 ? l[2].mod
4669 %5 = [[5, 0; 0, 5], []]
4670 ? l[3].mod
4671 %6 = [[25, 7; 0, 1], []]
4672 where we ask for the structures of the "(Z[i]/I)^*" for all three
4674 ideals of norm 25. In fact, for all moduli with finite part of norm 25
4675 and trivial archimedean part, as the last 3 commands show. See
4676 "ideallistarch" to treat general moduli.
4677 The library syntax is ideallist0"(nf,bound,flag)", where bound must be
4679 a C long integer. Also available is " ideallist(nf,bound)",
4680 corresponding to the case "flag = 4".
4681 ideallistarch"(nf,list,arch)"
4683 list is a vector of vectors of bid's, as output by "ideallist" with
4684 flag 0 to 3. Return a vector of vectors with the same number of
4685 components as the original list. The leaves give information about
4686 moduli whose finite part is as in original list, in the same order, and
4687 archimedean part is now arch (it was originally trivial). The
4688 information contained is of the same kind as was present in the input;
4689 see "ideallist", in particular the meaning of flag.
4690 ? L = ideallist(bnf, 100, 0);
4692 ? l = L[98]; vector(#l, i, l[i].clgp)
4693 %4 = [[42, [42]], [36, [6, 6]], [42, [42]]]
4694 ? La = ideallistarch(bnf, L, [1,1]); \\ two places at infinity
4695 ? L = ideallist(bnf, 100, 0);
4696 ? l = L[98]; vector(#l, i, l[i].clgp)
4697 %4 = [[42, [42]], [36, [6, 6]], [42, [42]]]
4698 ? La = ideallistarch(bnf, L, [1,1]); \\ add them to the modulus
4699 ? l = La[98]; vector(#l, i, l[i].clgp)
4700 %6 = [[168, [42, 2, 2]], [144, [6, 6, 2, 2]], [168, [42, 2, 2]]]
4701 Of course, the results above are obvious: adding "t" places at infinity
4703 will add "t" copies of "Z/2Z" to the ray class group. The following
4704 application is more typical:
4705 ? L = ideallist(bnf, 100, 2); \\ units are required now
4707 ? La = ideallistarch(bnf, L, [1,1]);
4708 ? H = bnrclassnolist(bnf, La);
4709 ? H[98];
4710 %6 = [2, 12, 2]
4711 The library syntax is ideallistarch"(nf,list,arch)".
4713 ideallog"(nf,x,bid)"
4715 "nf" is a number field, bid a ``big ideal'' as output by "idealstar"
4716 and "x" a non-necessarily integral element of nf which must have
4717 valuation equal to 0 at all prime ideals dividing "I = bid[1]". This
4718 function computes the ``discrete logarithm'' of "x" on the generators
4719 given in "bid[2]". In other words, if "g_i" are these generators, of
4720 orders "d_i" respectively, the result is a column vector of integers
4721 "(x_i)" such that "0 <= x_i < d_i" and
4722 "x = prod_ig_i^{x_i} (mod ^*I) ."
4724 Note that when "I" is a module, this implies also sign conditions on
4726 the embeddings.
4727 The library syntax is zideallog"(nf,x,bid)".
4729 idealmin"(nf,x,{vdir})"
4731 computes a minimum of the ideal "x" in the direction vdir in the number
4732 field nf.
4733 The library syntax is minideal"(nf,x,vdir,prec)", where an omitted vdir
4735 is coded as "NULL".
4736 idealmul"(nf,x,y,{flag = 0})"
4738 ideal multiplication of the ideals "x" and "y" in the number field nf.
4739 The result is a generating set for the ideal product with at most "n"
4740 elements, and is in Hermite normal form if either "x" or "y" is in HNF
4741 or is a prime ideal as output by "idealprimedec", and this is given
4742 together with the sum of the Archimedean information in "x" and "y" if
4743 both are given.
4744 If "flag" is non-zero, reduce the result using "idealred".
4746 The library syntax is idealmul"(nf,x,y)" ("flag = 0") or "
4748 idealmulred(nf,x,y,prec)" ("flag ! = 0"), where as usual, "prec" is a C
4749 long integer representing the precision.
4750 idealnorm"(nf,x)"
4752 computes the norm of the ideal "x" in the number field "nf".
4753 The library syntax is idealnorm"(nf, x)".
4755 idealpow"(nf,x,k,{flag = 0})"
4757 computes the "k"-th power of the ideal "x" in the number field "nf".
4758 "k" can be positive, negative or zero. The result is NOT reduced, it is
4759 really the "k"-th ideal power, and is given in HNF.
4760 If "flag" is non-zero, reduce the result using "idealred". Note however
4762 that this is NOT the same as as "idealpow(nf,x,k)" followed by
4763 reduction, since the reduction is performed throughout the powering
4764 process.
4765 The library syntax corresponding to "flag = 0" is " idealpow(nf,x,k)".
4767 If "k" is a "long", you can use " idealpows(nf,x,k)". Corresponding to
4768 "flag = 1" is " idealpowred(nf,vp,k,prec)", where "prec" is a "long".
4769 idealprimedec"(nf,p)"
4771 computes the prime ideal decomposition of the prime number "p" in the
4772 number field "nf". "p" must be a (positive) prime number. Note that the
4773 fact that "p" is prime is not checked, so if a non-prime "p" is given
4774 the result is undefined.
4775 The result is a vector of pr structures, each representing one of the
4777 prime ideals above "p" in the number field "nf". The representation "P
4778 = [p,a,e,f,b]" of a prime ideal means the following. The prime ideal is
4779 equal to "pZ_K+alphaZ_K" where "Z_K" is the ring of integers of the
4780 field and "alpha = sum_i a_iomega_i" where the "omega_i" form the
4781 integral basis "nf.zk", "e" is the ramification index, "f" is the
4782 residual index, and "b" represents a "beta belongs to Z_K" such that
4783 "P^{-1} = Z_K+beta/pZ_K" which will be useful for computing valuations,
4784 but which the user can ignore. The number "alpha" is guaranteed to have
4785 a valuation equal to 1 at the prime ideal (this is automatic if "e >
4786 1").
4787 The components of "P" should be accessed by member functions: "P.p",
4789 "P.e", "P.f", and "P.gen" (returns the vector "[p,a]").
4790 The library syntax is primedec"(nf,p)".
4792 idealprincipal"(nf,x)"
4794 creates the principal ideal generated by the algebraic number "x"
4795 (which must be of type integer, rational or polmod) in the number field
4796 "nf". The result is a one-column matrix.
4797 The library syntax is principalideal"(nf,x)".
4799 idealred"(nf,I,{vdir = 0})"
4801 LLL reduction of the ideal "I" in the number field nf, along the
4802 direction vdir. If vdir is present, it must be an "r1+r2"-component
4803 vector ("r1" and "r2" number of real and complex places of nf as
4804 usual).
4805 This function finds a ``small'' "a" in "I" (it is an LLL pseudo-minimum
4807 along direction vdir). The result is the Hermite normal form of the
4808 LLL-reduced ideal "r I/a", where "r" is a rational number such that the
4809 resulting ideal is integral and primitive. This is often, but not
4810 always, a reduced ideal in the sense of Buchmann. If "I" is an idele,
4811 the logarithmic embeddings of "a" are subtracted to the Archimedean
4812 part.
4813 More often than not, a principal ideal will yield the identity matrix.
4815 This is a quick and dirty way to check if ideals are principal without
4816 computing a full "bnf" structure, but it's not a necessary condition;
4817 hence, a non-trivial result doesn't prove the ideal is non-trivial in
4818 the class group.
4819 Note that this is \emph{not} the same as the LLL reduction of the
4821 lattice "I" since ideal operations are involved.
4822 The library syntax is ideallllred"(nf,x,vdir,prec)", where an omitted
4824 vdir is coded as "NULL".
4825 idealstar"(nf,I,{flag = 1})"
4827 outputs a bid structure, necessary for computing in the finite abelian
4828 group "G = (Z_K/I)^*". Here, nf is a number field and "I" is a modulus:
4829 either an ideal in any form, or a row vector whose first component is
4830 an ideal and whose second component is a row vector of "r_1" 0 or 1.
4831 This bid is used in "ideallog" to compute discrete logarithms. It also
4833 contains useful information which can be conveniently retrieved as
4834 "bid.mod" (the modulus), "bid.clgp" ("G" as a finite abelian group),
4835 "bid.no" (the cardinality of "G"), "bid.cyc" (elementary divisors) and
4836 "bid.gen" (generators).
4837 If "flag = 1" (default), the result is a bid structure without
4839 generators.
4840 If "flag = 2", as "flag = 1", but including generators, which wastes
4842 some time.
4843 If "flag = 0", \emph{deprecated}. Only outputs "(Z_K/I)^*" as an
4845 abelian group, i.e as a 3-component vector "[h,d,g]": "h" is the order,
4846 "d" is the vector of SNF cyclic components and "g" the corresponding
4847 generators. This flag is deprecated: it is in fact slightly faster to
4848 compute a true bid structure, which contains much more information.
4849 The library syntax is idealstar0"(nf,I,flag)".
4851 idealtwoelt"(nf,x,{a})"
4853 computes a two-element representation of the ideal "x" in the number
4854 field "nf", using a straightforward (exponential time) search. "x" can
4855 be an ideal in any form, (including perhaps an Archimedean part, which
4856 is ignored) and the result is a row vector "[a,alpha]" with two
4857 components such that "x = aZ_K+alphaZ_K" and "a belongs to Z", where
4858 "a" is the one passed as argument if any. If "x" is given by at least
4859 two generators, "a" is chosen to be the positive generator of "x cap
4860 Z".
4861 Note that when an explicit "a" is given, we use an asymptotically
4863 faster method, however in practice it is usually slower.
4864 The library syntax is ideal_two_elt0"(nf,x,a)", where an omitted "a" is
4866 entered as "NULL".
4867 idealval"(nf,x,vp)"
4869 gives the valuation of the ideal "x" at the prime ideal vp in the
4870 number field "nf", where vp must be a 5-component vector as given by
4871 "idealprimedec".
4872 The library syntax is idealval"(nf,x,vp)", and the result is a "long"
4874 integer.
4875 ideleprincipal"(nf,x)"
4877 creates the principal idele generated by the algebraic number "x"
4878 (which must be of type integer, rational or polmod) in the number field
4879 "nf". The result is a two-component vector, the first being a one-
4880 column matrix representing the corresponding principal ideal, and the
4881 second being the vector with "r_1+r_2" components giving the complex
4882 logarithmic embedding of "x".
4883 The library syntax is principalidele"(nf,x)".
4885 matalgtobasis"(nf,x)"
4887 "nf" being a number field in "nfinit" format, and "x" a matrix whose
4888 coefficients are expressed as polmods in "nf", transforms this matrix
4889 into a matrix whose coefficients are expressed on the integral basis of
4890 "nf". This is the same as applying "nfalgtobasis" to each entry, but it
4891 would be dangerous to use the same name.
4892 The library syntax is matalgtobasis"(nf,x)".
4894 matbasistoalg"(nf,x)"
4896 "nf" being a number field in "nfinit" format, and "x" a matrix whose
4897 coefficients are expressed as column vectors on the integral basis of
4898 "nf", transforms this matrix into a matrix whose coefficients are
4899 algebraic numbers expressed as polmods. This is the same as applying
4900 "nfbasistoalg" to each entry, but it would be dangerous to use the same
4901 name.
4902 The library syntax is matbasistoalg"(nf,x)".
4904 modreverse"(a)"
4906 "a" being a polmod A(X) modulo T(X), finds the ``reverse polmod'' B(X)
4907 modulo Q(X), where "Q" is the minimal polynomial of "a", which must be
4908 equal to the degree of "T", and such that if "theta" is a root of "T"
4909 then "theta = B(alpha)" for a certain root "alpha" of "Q".
4910 This is very useful when one changes the generating element in
4912 algebraic extensions.
4913 The library syntax is polmodrecip"(x)".
4915 newtonpoly"(x,p)"
4917 gives the vector of the slopes of the Newton polygon of the polynomial
4918 "x" with respect to the prime number "p". The "n" components of the
4919 vector are in decreasing order, where "n" is equal to the degree of
4920 "x". Vertical slopes occur iff the constant coefficient of "x" is zero
4921 and are denoted by "VERYBIGINT", the biggest single precision integer
4922 representable on the machine ("2^{31}-1" (resp. "2^{63}-1") on 32-bit
4923 (resp. 64-bit) machines), see "Label se:valuation".
4924 The library syntax is newtonpoly"(x,p)".
4926 nfalgtobasis"(nf,x)"
4928 this is the inverse function of "nfbasistoalg". Given an object "x"
4929 whose entries are expressed as algebraic numbers in the number field
4930 "nf", transforms it so that the entries are expressed as a column
4931 vector on the integral basis "nf.zk".
4932 The library syntax is algtobasis"(nf,x)".
4934 nfbasis"(x,{flag = 0},{fa})"
4936 integral basis of the number field defined by the irreducible,
4937 preferably monic, polynomial "x", using a modified version of the round
4938 4 algorithm by default, due to David Ford, Sebastian Pauli and Xavier
4939 Roblot. The binary digits of "flag" have the following meaning:
4940 1: assume that no square of a prime greater than the default
4942 "primelimit" divides the discriminant of "x", i.e. that the index of
4943 "x" has only small prime divisors.
4944 2: use round 2 algorithm. For small degrees and coefficient size, this
4946 is sometimes a little faster. (This program is the translation into C
4947 of a program written by David Ford in Algeb.)
4948 Thus for instance, if "flag = 3", this uses the round 2 algorithm and
4950 outputs an order which will be maximal at all the small primes.
4951 If fa is present, we assume (without checking!) that it is the two-
4953 column matrix of the factorization of the discriminant of the
4954 polynomial "x". Note that it does \emph{not} have to be a complete
4955 factorization. This is especially useful if only a local integral basis
4956 for some small set of places is desired: only factors with exponents
4957 greater or equal to 2 will be considered.
4958 The library syntax is nfbasis0"(x,flag,fa)". An extended version is "
4960 nfbasis(x,&d,flag,fa)", where "d" receives the discriminant of the
4961 number field (\emph{not} of the polynomial "x"), and an omitted fa is
4962 input as "NULL". Also available are " base(x,&d)" ("flag = 0"), "
4963 base2(x,&d)" ("flag = 2") and " factoredbase(x,fa,&d)".
4964 nfbasistoalg"(nf,x)"
4966 this is the inverse function of "nfalgtobasis". Given an object "x"
4967 whose entries are expressed on the integral basis "nf.zk", transforms
4968 it into an object whose entries are algebraic numbers (i.e. polmods).
4969 The library syntax is basistoalg"(nf,x)".
4971 nfdetint"(nf,x)"
4973 given a pseudo-matrix "x", computes a non-zero ideal contained in
4974 (i.e. multiple of) the determinant of "x". This is particularly useful
4975 in conjunction with "nfhnfmod".
4976 The library syntax is nfdetint"(nf,x)".
4978 nfdisc"(x,{flag = 0},{fa})"
4980 field discriminant of the number field defined by the integral,
4981 preferably monic, irreducible polynomial "x". "flag" and "fa" are
4982 exactly as in "nfbasis". That is, "fa" provides the matrix of a partial
4983 factorization of the discriminant of "x", and binary digits of "flag"
4984 are as follows:
4985 1: assume that no square of a prime greater than "primelimit" divides
4987 the discriminant.
4988 2: use the round 2 algorithm, instead of the default round 4. This
4990 should be slower except maybe for polynomials of small degree and
4991 coefficients.
4992 The library syntax is nfdiscf0"(x,flag,fa)" where an omitted "fa" is
4994 input as "NULL". You can also use " discf(x)" ("flag = 0").
4995 nfeltdiv"(nf,x,y)"
4997 given two elements "x" and "y" in nf, computes their quotient "x/y" in
4998 the number field "nf".
4999 The library syntax is element_div"(nf,x,y)".
5001 nfeltdiveuc"(nf,x,y)"
5003 given two elements "x" and "y" in nf, computes an algebraic integer "q"
5004 in the number field "nf" such that the components of "x-qy" are
5005 reasonably small. In fact, this is functionally identical to
5006 "round(nfeltdiv(nf,x,y))".
5007 The library syntax is nfdiveuc"(nf,x,y)".
5009 nfeltdivmodpr"(nf,x,y,pr)"
5011 given two elements "x" and "y" in nf and pr a prime ideal in "modpr"
5012 format (see "nfmodprinit"), computes their quotient "x / y" modulo the
5013 prime ideal pr.
5014 The library syntax is element_divmodpr"(nf,x,y,pr)".
5016 nfeltdivrem"(nf,x,y)"
5018 given two elements "x" and "y" in nf, gives a two-element row vector
5019 "[q,r]" such that "x = qy+r", "q" is an algebraic integer in "nf", and
5020 the components of "r" are reasonably small.
5021 The library syntax is nfdivrem"(nf,x,y)".
5023 nfeltmod"(nf,x,y)"
5025 given two elements "x" and "y" in nf, computes an element "r" of "nf"
5026 of the form "r = x-qy" with "q" and algebraic integer, and such that
5027 "r" is small. This is functionally identical to
5028 "x - nfeltmul(nf,round(nfeltdiv(nf,x,y)),y)."
5030 The library syntax is nfmod"(nf,x,y)".
5032 nfeltmul"(nf,x,y)"
5034 given two elements "x" and "y" in nf, computes their product "x*y" in
5035 the number field "nf".
5036 The library syntax is element_mul"(nf,x,y)".
5038 nfeltmulmodpr"(nf,x,y,pr)"
5040 given two elements "x" and "y" in nf and pr a prime ideal in "modpr"
5041 format (see "nfmodprinit"), computes their product "x*y" modulo the
5042 prime ideal pr.
5043 The library syntax is element_mulmodpr"(nf,x,y,pr)".
5045 nfeltpow"(nf,x,k)"
5047 given an element "x" in nf, and a positive or negative integer "k",
5048 computes "x^k" in the number field "nf".
5049 The library syntax is element_pow"(nf,x,k)".
5051 nfeltpowmodpr"(nf,x,k,pr)"
5053 given an element "x" in nf, an integer "k" and a prime ideal pr in
5054 "modpr" format (see "nfmodprinit"), computes "x^k" modulo the prime
5055 ideal pr.
5056 The library syntax is element_powmodpr"(nf,x,k,pr)".
5058 nfeltreduce"(nf,x,ideal)"
5060 given an ideal in Hermite normal form and an element "x" of the number
5061 field "nf", finds an element "r" in "nf" such that "x-r" belongs to the
5062 ideal and "r" is small.
5063 The library syntax is element_reduce"(nf,x,ideal)".
5065 nfeltreducemodpr"(nf,x,pr)"
5067 given an element "x" of the number field "nf" and a prime ideal pr in
5068 "modpr" format compute a canonical representative for the class of "x"
5069 modulo pr.
5070 The library syntax is nfreducemodpr"(nf,x,pr)".
5072 nfeltval"(nf,x,pr)"
5074 given an element "x" in nf and a prime ideal pr in the format output by
5075 "idealprimedec", computes their the valuation at pr of the element "x".
5076 The same result could be obtained using "idealval(nf,x,pr)" (since "x"
5077 would then be converted to a principal ideal), but it would be less
5078 efficient.
5079 The library syntax is element_val"(nf,x,pr)", and the result is a
5081 "long".
5082 nffactor"(nf,x)"
5084 factorization of the univariate polynomial "x" over the number field
5085 "nf" given by "nfinit". "x" has coefficients in "nf" (i.e. either
5086 scalar, polmod, polynomial or column vector). The main variable of "nf"
5087 must be of \emph{lower} priority than that of "x" (see "Label
5088 se:priority"). However if the polynomial defining the number field
5089 occurs explicitly in the coefficients of "x" (as modulus of a
5090 "t_POLMOD"), its main variable must be \emph{the same} as the main
5091 variable of "x". For example,
5092 ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ OK
5094 ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ OK
5095 ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ WRONG
5096 The library syntax is nffactor"(nf,x)".
5098 nffactormod"(nf,x,pr)"
5100 factorization of the univariate polynomial "x" modulo the prime ideal
5101 pr in the number field "nf". "x" can have coefficients in the number
5102 field (scalar, polmod, polynomial, column vector) or modulo the prime
5103 ideal (intmod modulo the rational prime under pr, polmod or polynomial
5104 with intmod coefficients, column vector of intmod). The prime ideal pr
5105 \emph{must} be in the format output by "idealprimedec". The main
5106 variable of "nf" must be of lower priority than that of "x" (see "Label
5107 se:priority"). However if the coefficients of the number field occur
5108 explicitly (as polmods) as coefficients of "x", the variable of these
5109 polmods \emph{must} be the same as the main variable of "t" (see
5110 "nffactor").
5111 The library syntax is nffactormod"(nf,x,pr)".
5113 nfgaloisapply"(nf,aut,x)"
5115 "nf" being a number field as output by "nfinit", and aut being a Galois
5116 automorphism of "nf" expressed either as a polynomial or a polmod (such
5117 automorphisms being found using for example one of the variants of
5118 "nfgaloisconj"), computes the action of the automorphism aut on the
5119 object "x" in the number field. "x" can be an element (scalar, polmod,
5120 polynomial or column vector) of the number field, an ideal (either
5121 given by "Z_K"-generators or by a Z-basis), a prime ideal (given as a
5122 5-element row vector) or an idele (given as a 2-element row vector).
5123 Because of possible confusion with elements and ideals, other vector or
5124 matrix arguments are forbidden.
5125 The library syntax is galoisapply"(nf,aut,x)".
5127 nfgaloisconj"(nf,{flag = 0},{d})"
5129 "nf" being a number field as output by "nfinit", computes the
5130 conjugates of a root "r" of the non-constant polynomial "x = nf[1]"
5131 expressed as polynomials in "r". This can be used even if the number
5132 field "nf" is not Galois since some conjugates may lie in the field.
5133 "nf" can simply be a polynomial if "flag ! = 1".
5135 If no flags or "flag = 0", if "nf" is a number field use a combination
5137 of flag 4 and 1 and the result is always complete, else use a
5138 combination of flag 4 and 2 and the result is subject to the
5139 restriction of "flag = 2", but a warning is issued when it is not
5140 proven complete.
5141 If "flag = 1", use "nfroots" (require a number field).
5143 If "flag = 2", use complex approximations to the roots and an integral
5145 LLL. The result is not guaranteed to be complete: some conjugates may
5146 be missing (no warning issued), especially so if the corresponding
5147 polynomial has a huge index. In that case, increasing the default
5148 precision may help.
5149 If "flag = 4", use Allombert's algorithm and permutation testing. If
5151 the field is Galois with ``weakly'' super solvable Galois group, return
5152 the complete list of automorphisms, else only the identity element. If
5153 present, "d" is assumed to be a multiple of the least common
5154 denominator of the conjugates expressed as polynomial in a root of pol.
5155 A group G is ``weakly'' super solvable (WKSS) if it contains a super
5157 solvable normal subgroup "H" such that "G = H" , or "G/H ~ A_4" , or
5158 "G/H ~ S_4". Abelian and nilpotent groups are WKSS. In practice,
5159 almost all groups of small order are WKSS, the exceptions having order
5160 36(1 exception), 48(2), 56(1), 60(1), 72(5), 75(1), 80(1), 96(10) and "
5161 >= 108".
5162 Hence "flag = 4" permits to quickly check whether a polynomial of order
5164 strictly less than 36 is Galois or not. This method is much faster than
5165 "nfroots" and can be applied to polynomials of degree larger than 50.
5166 This routine can only compute Q-automorphisms, but it may be used to
5168 get "K"-automorphism for any base field "K" as follows:
5169 rnfgaloisconj(nfK, R) = \\ K-automorphisms of L = K[X] / (R)
5171 { local(polabs, N, H);
5172 R *= Mod(1, nfK.pol); \\ convert coeffs to polmod elts of K
5173 polabs = rnfequation(nfK, R);
5174 N = nfgaloisconj(polabs) % R; \\ Q-automorphisms of L
5175 H = [];
5176 for(i=1, #N, \\ select the ones that fix K
5177 if (subst(R, variable(R), Mod(N[i],R)) == 0,
5178 H = concat(H,N[i])
5179 )
5180 ); H
5181 }
5182 K = nfinit(y^2 + 7);
5183 polL = x^4 - y*x^3 - 3*x^2 + y*x + 1;
5184 rnfgaloisconj(K, polL) \\ K-automorphisms of L
5185 The library syntax is galoisconj0"(nf,flag,d,prec)". Also available are
5187 " galoisconj(nf)" for "flag = 0", " galoisconj2(nf,n,prec)" for "flag =
5188 2" where "n" is a bound on the number of conjugates, and "
5189 galoisconj4(nf,d)" corresponding to "flag = 4".
5190 nfhilbert"(nf,a,b,{pr})"
5192 if pr is omitted, compute the global Hilbert symbol "(a,b)" in "nf",
5193 that is 1 if "x^2 - a y^2 - b z^2" has a non trivial solution "(x,y,z)"
5194 in "nf", and "-1" otherwise. Otherwise compute the local symbol modulo
5195 the prime ideal pr (as output by "idealprimedec").
5196 The library syntax is nfhilbert"(nf,a,b,pr)", where an omitted pr is
5198 coded as "NULL".
5199 nfhnf"(nf,x)"
5201 given a pseudo-matrix "(A,I)", finds a pseudo-basis in Hermite normal
5202 form of the module it generates.
5203 The library syntax is nfhermite"(nf,x)".
5205 nfhnfmod"(nf,x,detx)"
5207 given a pseudo-matrix "(A,I)" and an ideal detx which is contained in
5208 (read integral multiple of) the determinant of "(A,I)", finds a pseudo-
5209 basis in Hermite normal form of the module generated by "(A,I)". This
5210 avoids coefficient explosion. detx can be computed using the function
5211 "nfdetint".
5212 The library syntax is nfhermitemod"(nf,x,detx)".
5214 nfinit"(pol,{flag = 0})"
5216 pol being a non-constant, preferably monic, irreducible polynomial in
5217 "Z[X]", initializes a \emph{number field} structure ("nf") associated
5218 to the field "K" defined by pol. As such, it's a technical object
5219 passed as the first argument to most "nf"xxx functions, but it contains
5220 some information which may be directly useful. Access to this
5221 information via \emph{member functions} is preferred since the specific
5222 data organization specified below may change in the future. Currently,
5223 "nf" is a row vector with 9 components:
5224 "nf[1]" contains the polynomial pol ("nf.pol").
5226 "nf[2]" contains "[r1,r2]" ("nf.sign", "nf.r1", "nf.r2"), the number of
5228 real and complex places of "K".
5229 "nf[3]" contains the discriminant d(K) ("nf.disc") of "K".
5231 "nf[4]" contains the index of "nf[1]" ("nf.index"), i.e. "[Z_K :
5233 Z[theta]]", where "theta" is any root of "nf[1]".
5234 "nf[5]" is a vector containing 7 matrices "M", "G", "T2", "T", "MD",
5236 "TI", "MDI" useful for certain computations in the number field "K".
5237 \item "M" is the "(r1+r2) x n" matrix whose columns represent the
5239 numerical values of the conjugates of the elements of the integral
5240 basis.
5241 \item "G" is such that "T2 = ^t G G", where "T2" is the quadratic
5243 form "T_2(x) = sum |sigma(x)|^2", "sigma" running over the embeddings
5244 of "K" into C.
5245 \item The "T2" component is deprecated and currently unused.
5247 \item "T" is the "n x n" matrix whose coefficients are
5249 "Tr(omega_iomega_j)" where the "omega_i" are the elements of the
5250 integral basis. Note also that " det (T)" is equal to the discriminant
5251 of the field "K".
5252 \item The columns of "MD" ("nf.diff") express a Z-basis of the
5254 different of "K" on the integral basis.
5255 \item "TI" is equal to "d(K)T^{-1}", which has integral coefficients.
5257 Note that, understood as as ideal, the matrix "T^{-1}" generates the
5258 codifferent ideal.
5259 \item Finally, "MDI" is a two-element representation (for faster
5261 ideal product) of d(K) times the codifferent ideal
5262 ("nf.disc*nf.codiff", which is an integral ideal). "MDI" is only used
5263 in "idealinv".
5264 "nf[6]" is the vector containing the "r1+r2" roots ("nf.roots") of
5266 "nf[1]" corresponding to the "r1+r2" embeddings of the number field
5267 into C (the first "r1" components are real, the next "r2" have positive
5268 imaginary part).
5269 "nf[7]" is an integral basis for "Z_K" ("nf.zk") expressed on the
5271 powers of "theta". Its first element is guaranteed to be 1. This basis
5272 is LLL-reduced with respect to "T_2" (strictly speaking, it is a
5273 permutation of such a basis, due to the condition that the first
5274 element be 1).
5275 "nf[8]" is the "n x n" integral matrix expressing the power basis in
5277 terms of the integral basis, and finally
5278 "nf[9]" is the "n x n^2" matrix giving the multiplication table of the
5280 integral basis.
5281 If a non monic polynomial is input, "nfinit" will transform it into a
5283 monic one, then reduce it (see "flag = 3"). It is allowed, though not
5284 very useful given the existence of "nfnewprec", to input a "nf" or a
5285 "bnf" instead of a polynomial.
5286 ? nf = nfinit(x^3 - 12); \\ initialize number field Q[X] / (X^3 - 12)
5288 ? nf.pol \\ defining polynomial
5289 %2 = x^3 - 12
5290 ? nf.disc \\ field discriminant
5291 %3 = -972
5292 ? nf.index \\ index of power basis order in maximal order
5293 %4 = 2
5294 ? nf.zk \\ integer basis, lifted to Q[X]
5295 %5 = [1, x, 1/2*x^2]
5296 ? nf.sign \\ signature
5297 %6 = [1, 1]
5298 ? factor(abs(nf.disc )) \\ determines ramified primes
5299 %7 =
5300 [2 2]
5301 [3 5]
5303 ? idealfactor(nf, 2)
5304 %8 =
5305 [[2, [0, 0, -1]~, 3, 1, [0, 1, 0]~] 3] \\ \goth{P}_2^3
5306 In case pol has a huge discriminant which is difficult to factor, the
5308 special input format "[pol,B]" is also accepted where pol is a
5309 polynomial as above and "B" is the integer basis, as would be computed
5310 by "nfbasis". This is useful if the integer basis is known in advance,
5311 or was computed conditionnally.
5312 ? pol = polcompositum(x^5 - 101, polcyclo(7))[1];
5314 ? B = nfbasis(pol, 1); \\ faster than nfbasis(pol), but conditional
5315 ? nf = nfinit( [pol, B] );
5316 ? factor( abs(nf.disc) )
5317 [5 18]
5318 [7 25]
5320 [101 24]
5322 "B" is conditional when its discriminant, which is "nf.disc", can't be
5324 factored. In this example, the above factorization proves the
5325 correctness of the computation.
5326 If "flag = 2": pol is changed into another polynomial "P" defining the
5328 same number field, which is as simple as can easily be found using the
5329 "polred" algorithm, and all the subsequent computations are done using
5330 this new polynomial. In particular, the first component of the result
5331 is the modified polynomial.
5332 If "flag = 3", does a "polred" as in case 2, but outputs
5334 "[nf,Mod(a,P)]", where "nf" is as before and "Mod(a,P) = Mod(x,pol)"
5335 gives the change of variables. This is implicit when pol is not monic:
5336 first a linear change of variables is performed, to get a monic
5337 polynomial, then a "polred" reduction.
5338 If "flag = 4", as 2 but uses a partial "polred".
5340 If "flag = 5", as 3 using a partial "polred".
5342 The library syntax is nfinit0"(x,flag,prec)".
5344 nfisideal"(nf,x)"
5346 returns 1 if "x" is an ideal in the number field "nf", 0 otherwise.
5347 The library syntax is isideal"(x)".
5349 nfisincl"(x,y)"
5351 tests whether the number field "K" defined by the polynomial "x" is
5352 conjugate to a subfield of the field "L" defined by "y" (where "x" and
5353 "y" must be in "Q[X]"). If they are not, the output is the number 0. If
5354 they are, the output is a vector of polynomials, each polynomial "a"
5355 representing an embedding of "K" into "L", i.e. being such that "y | x
5356 o a".
5357 If "y" is a number field (nf), a much faster algorithm is used
5359 (factoring "x" over "y" using "nffactor"). Before version 2.0.14, this
5360 wasn't guaranteed to return all the embeddings, hence was triggered by
5361 a special flag. This is no more the case.
5362 The library syntax is nfisincl"(x,y,flag)".
5364 nfisisom"(x,y)"
5366 as "nfisincl", but tests for isomorphism. If either "x" or "y" is a
5367 number field, a much faster algorithm will be used.
5368 The library syntax is nfisisom"(x,y,flag)".
5370 nfnewprec"(nf)"
5372 transforms the number field "nf" into the corresponding data using
5373 current (usually larger) precision. This function works as expected if
5374 "nf" is in fact a "bnf" (update "bnf" to current precision) but may be
5375 quite slow (many generators of principal ideals have to be computed).
5376 The library syntax is nfnewprec"(nf,prec)".
5378 nfkermodpr"(nf,a,pr)"
5380 kernel of the matrix "a" in "Z_K/pr", where pr is in modpr format (see
5381 "nfmodprinit").
5382 The library syntax is nfkermodpr"(nf,a,pr)".
5384 nfmodprinit"(nf,pr)"
5386 transforms the prime ideal pr into "modpr" format necessary for all
5387 operations modulo pr in the number field nf.
5388 The library syntax is nfmodprinit"(nf,pr)".
5390 nfsubfields"(pol,{d = 0})"
5392 finds all subfields of degree "d" of the number field defined by the
5393 (monic, integral) polynomial pol (all subfields if "d" is null or
5394 omitted). The result is a vector of subfields, each being given by
5395 "[g,h]", where "g" is an absolute equation and "h" expresses one of the
5396 roots of "g" in terms of the root "x" of the polynomial defining "nf".
5397 This routine uses J. Klüners's algorithm in the general case, and
5398 B. Allombert's "galoissubfields" when nf is Galois (with weakly
5399 supersolvable Galois group).
5400 The library syntax is subfields"(nf,d)".
5402 nfroots"({nf},x)"
5404 roots of the polynomial "x" in the number field "nf" given by "nfinit"
5405 without multiplicity (in Q if "nf" is omitted). "x" has coefficients in
5406 the number field (scalar, polmod, polynomial, column vector). The main
5407 variable of "nf" must be of lower priority than that of "x" (see "Label
5408 se:priority"). However if the coefficients of the number field occur
5409 explicitly (as polmods) as coefficients of "x", the variable of these
5410 polmods \emph{must} be the same as the main variable of "t" (see
5411 "nffactor").
5412 The library syntax is nfroots"(nf,x)".
5414 nfrootsof1"(nf)"
5416 computes the number of roots of unity "w" and a primitive "w"-th root
5417 of unity (expressed on the integral basis) belonging to the number
5418 field "nf". The result is a two-component vector "[w,z]" where "z" is a
5419 column vector expressing a primitive "w"-th root of unity on the
5420 integral basis "nf.zk".
5421 The library syntax is rootsof1"(nf)".
5423 nfsnf"(nf,x)"
5425 given a torsion module "x" as a 3-component row vector "[A,I,J]" where
5426 "A" is a square invertible "n x n" matrix, "I" and "J" are two ideal
5427 lists, outputs an ideal list "d_1,...,d_n" which is the Smith normal
5428 form of "x". In other words, "x" is isomorphic to "Z_K/d_1 oplus ...
5429 oplus Z_K/d_n" and "d_i" divides "d_{i-1}" for "i >= 2". The link
5430 between "x" and "[A,I,J]" is as follows: if "e_i" is the canonical
5431 basis of "K^n", "I = [b_1,...,b_n]" and "J = [a_1,...,a_n]", then "x"
5432 is isomorphic to
5433 " (b_1e_1 oplus ... oplus b_ne_n) / (a_1A_1 oplus ... oplus a_nA_n)
5435 , "
5436 where the "A_j" are the columns of the matrix "A". Note that every
5438 finitely generated torsion module can be given in this way, and even
5439 with "b_i = Z_K" for all "i".
5440 The library syntax is nfsmith"(nf,x)".
5442 nfsolvemodpr"(nf,a,b,pr)"
5444 solution of "a.x = b" in "Z_K/pr", where "a" is a matrix and "b" a
5445 column vector, and where pr is in modpr format (see "nfmodprinit").
5446 The library syntax is nfsolvemodpr"(nf,a,b,pr)".
5448 polcompositum"(P,Q,{flag = 0})"
5450 "P" and "Q" being squarefree polynomials in "Z[X]" in the same
5451 variable, outputs the simple factors of the étale Q-algebra "A = Q(X,
5452 Y) / (P(X), Q(Y))". The factors are given by a list of polynomials "R"
5453 in "Z[X]", associated to the number field "Q(X)/ (R)", and sorted by
5454 increasing degree (with respect to lexicographic ordering for factors
5455 of equal degrees). Returns an error if one of the polynomials is not
5456 squarefree.
5457 Note that it is more efficient to reduce to the case where "P" and "Q"
5459 are irreducible first. The routine will not perform this for you, since
5460 it may be expensive, and the inputs are irreducible in most
5461 applications anyway. Assuming "P" is irreducible (of smaller degree
5462 than "Q" for efficiency), it is in general \emph{much} faster to
5463 proceed as follows
5464 nf = nfinit(P); L = nffactor(nf, Q)[,1];
5466 vector(#L, i, rnfequation(nf, L[i]))
5467 to obtain the same result. If you are only interested in the degrees of
5469 the simple factors, the "rnfequation" instruction can be replaced by a
5470 trivial "poldegree(P) * poldegree(L[i])".
5471 If "flag = 1", outputs a vector of 4-component vectors "[R,a,b,k]",
5473 where "R" ranges through the list of all possible compositums as above,
5474 and "a" (resp. "b") expresses the root of "P" (resp. "Q") as an element
5475 of "Q(X)/(R)". Finally, "k" is a small integer such that "b + ka = X"
5476 modulo "R".
5477 A compositum is quite often defined by a complicated polynomial, which
5479 it is advisable to reduce before further work. Here is a simple example
5480 involving the field "Q(zeta_5, 5^{1/5})":
5481 ? pol = z[1]
5483 %5 = x^20 + 25*x^10 + 5
5484 ? a = subst(a.pol, x, z[2]) \\ pol defines the compositum
5485 ? pol = z[1]
5486 %5 = x^20 + 25*x^10 + 5
5487 ? a = subst(a.pol, x, z[2]) \\ a is a fifth root of 5
5488 ? pol = z[1]
5489 %5 = x^20 + 25*x^10 + 5
5490 ? a = subst(a.pol, x, z[2]) \\ look for a simpler polynomial
5491 ? pol = z[1]
5492 %5 = x^20 + 25*x^10 + 5
5493 ? a = subst(a.pol, x, z[2]) \\ a in the new coordinates
5494 %6 = Mod(-5/22*x^19 + 1/22*x^14 - 123/22*x^9 + 9/11*x^4, x^20 + 25*x^10 + 5)
5495 The library syntax is polcompositum0"(P,Q,flag)".
5497 polgalois"(x)"
5499 Galois group of the non-constant polynomial "x belongs to Q[X]". In the
5500 present version 2.2.0, "x" must be irreducible and the degree of "x"
5501 must be less than or equal to 7. On certain versions for which the data
5502 file of Galois resolvents has been installed (available in the Unix
5503 distribution as a separate package), degrees 8, 9, 10 and 11 are also
5504 implemented.
5505 The output is a 4-component vector "[n,s,k,name]" with the following
5507 meaning: "n" is the cardinality of the group, "s" is its signature ("s
5508 = 1" if the group is a subgroup of the alternating group "A_n", "s =
5509 -1" otherwise) and name is a character string containing name of the
5510 transitive group according to the GAP 4 transitive groups library by
5511 Alexander Hulpke.
5512 "k" is more arbitrary and the choice made up to version 2.2.3 of PARI
5514 is rather unfortunate: for "n > 7", "k" is the numbering of the group
5515 among all transitive subgroups of "S_n", as given in ``The transitive
5516 groups of degree up to eleven'', G. Butler and J. McKay,
5517 \emph{Communications in Algebra}, vol. 11, 1983, pp. 863--911 (group
5518 "k" is denoted "T_k" there). And for "n <= 7", it was ad hoc, so as to
5519 ensure that a given triple would design a unique group. Specifically,
5520 for polynomials of degree " <= 7", the groups are coded as follows,
5521 using standard notations
5522 In degree 1: "S_1 = [1,1,1]".
5524 In degree 2: "S_2 = [2,-1,1]".
5526 In degree 3: "A_3 = C_3 = [3,1,1]", "S_3 = [6,-1,1]".
5528 In degree 4: "C_4 = [4,-1,1]", "V_4 = [4,1,1]", "D_4 = [8,-1,1]", "A_4
5530 = [12,1,1]", "S_4 = [24,-1,1]".
5531 In degree 5: "C_5 = [5,1,1]", "D_5 = [10,1,1]", "M_{20} = [20,-1,1]",
5533 "A_5 = [60,1,1]", "S_5 = [120,-1,1]".
5534 In degree 6: "C_6 = [6,-1,1]", "S_3 = [6,-1,2]", "D_6 = [12,-1,1]",
5536 "A_4 = [12,1,1]", "G_{18} = [18,-1,1]", "S_4^ -= [24,-1,1]", "A_4 x C_2
5537 = [24,-1,2]", "S_4^ += [24,1,1]", "G_{36}^ -= [36,-1,1]", "G_{36}^ +=
5538 [36,1,1]", "S_4 x C_2 = [48,-1,1]", "A_5 = PSL_2(5) = [60,1,1]",
5539 "G_{72} = [72,-1,1]", "S_5 = PGL_2(5) = [120,-1,1]", "A_6 = [360,1,1]",
5540 "S_6 = [720,-1,1]".
5541 In degree 7: "C_7 = [7,1,1]", "D_7 = [14,-1,1]", "M_{21} = [21,1,1]",
5543 "M_{42} = [42,-1,1]", "PSL_2(7) = PSL_3(2) = [168,1,1]", "A_7 =
5544 [2520,1,1]", "S_7 = [5040,-1,1]".
5545 This is deprecated and obsolete, but for reasons of backward
5547 compatibility, we cannot change this behaviour yet. So you can use the
5548 default "new_galois_format" to switch to a consistent naming scheme,
5549 namely "k" is always the standard numbering of the group among all
5550 transitive subgroups of "S_n". If this default is in effect, the above
5551 groups will be coded as:
5552 In degree 1: "S_1 = [1,1,1]".
5554 In degree 2: "S_2 = [2,-1,1]".
5556 In degree 3: "A_3 = C_3 = [3,1,1]", "S_3 = [6,-1,2]".
5558 In degree 4: "C_4 = [4,-1,1]", "V_4 = [4,1,2]", "D_4 = [8,-1,3]", "A_4
5560 = [12,1,4]", "S_4 = [24,-1,5]".
5561 In degree 5: "C_5 = [5,1,1]", "D_5 = [10,1,2]", "M_{20} = [20,-1,3]",
5563 "A_5 = [60,1,4]", "S_5 = [120,-1,5]".
5564 In degree 6: "C_6 = [6,-1,1]", "S_3 = [6,-1,2]", "D_6 = [12,-1,3]",
5566 "A_4 = [12,1,4]", "G_{18} = [18,-1,5]", "A_4 x C_2 = [24,-1,6]", "S_4^
5567 += [24,1,7]", "S_4^ -= [24,-1,8]", "G_{36}^ -= [36,-1,9]", "G_{36}^ +=
5568 [36,1,10]", "S_4 x C_2 = [48,-1,11]", "A_5 = PSL_2(5) = [60,1,12]",
5569 "G_{72} = [72,-1,13]", "S_5 = PGL_2(5) = [120,-1,14]", "A_6 =
5570 [360,1,15]", "S_6 = [720,-1,16]".
5571 In degree 7: "C_7 = [7,1,1]", "D_7 = [14,-1,2]", "M_{21} = [21,1,3]",
5573 "M_{42} = [42,-1,4]", "PSL_2(7) = PSL_3(2) = [168,1,5]", "A_7 =
5574 [2520,1,6]", "S_7 = [5040,-1,7]".
5575 Warning: The method used is that of resolvent polynomials and is
5577 sensitive to the current precision. The precision is updated internally
5578 but, in very rare cases, a wrong result may be returned if the initial
5579 precision was not sufficient.
5580 The library syntax is polgalois"(x,prec)". To enable the new format in
5582 library mode, set the global variable "new_galois_format" to 1.
5583 polred"(x,{flag = 0},{fa})"
5585 finds polynomials with reasonably small coefficients defining subfields
5586 of the number field defined by "x". One of the polynomials always
5587 defines Q (hence is equal to "x-1"), and another always defines the
5588 same number field as "x" if "x" is irreducible. All "x" accepted by
5589 "nfinit" are also allowed here (e.g. non-monic polynomials, "nf",
5590 "bnf", "[x,Z_K_basis]").
5591 The following binary digits of "flag" are significant:
5593 1: possibly use a suborder of the maximal order. The primes dividing
5595 the index of the order chosen are larger than "primelimit" or divide
5596 integers stored in the "addprimes" table.
5597 2: gives also elements. The result is a two-column matrix, the first
5599 column giving the elements defining these subfields, the second giving
5600 the corresponding minimal polynomials.
5601 If "fa" is given, it is assumed that it is the two-column matrix of the
5603 factorization of the discriminant of the polynomial "x".
5604 The library syntax is polred0"(x,flag,fa)", where an omitted "fa" is
5606 coded by "NULL". Also available are " polred(x)" and "
5607 factoredpolred(x,fa)", both corresponding to "flag = 0".
5608 polredabs"(x,{flag = 0})"
5610 finds one of the polynomial defining the same number field as the one
5611 defined by "x", and such that the sum of the squares of the modulus of
5612 the roots (i.e. the "T_2"-norm) is minimal. All "x" accepted by
5613 "nfinit" are also allowed here (e.g. non-monic polynomials, "nf",
5614 "bnf", "[x,Z_K_basis]").
5615 Warning: this routine uses an exponential-time algorithm to enumerate
5617 all potential generators, and may be exceedingly slow when the number
5618 field has many subfields, hence a lot of elements of small "T_2"-norm.
5619 E.g. do not try it on the compositum of many quadratic fields, use
5620 "polred" instead.
5621 The binary digits of "flag" mean
5623 1: outputs a two-component row vector "[P,a]", where "P" is the default
5625 output and "a" is an element expressed on a root of the polynomial "P",
5626 whose minimal polynomial is equal to "x".
5627 4: gives \emph{all} polynomials of minimal "T_2" norm (of the two
5629 polynomials P(x) and "P(-x)", only one is given).
5630 16: possibly use a suborder of the maximal order. The primes dividing
5632 the index of the order chosen are larger than "primelimit" or divide
5633 integers stored in the "addprimes" table. In that case it may happen
5634 that the output polynomial does not have minimal "T_2" norm.
5635 The library syntax is polredabs0"(x,flag)".
5637 polredord"(x)"
5639 finds polynomials with reasonably small coefficients and of the same
5640 degree as that of "x" defining suborders of the order defined by "x".
5641 One of the polynomials always defines Q (hence is equal to "(x-1)^n",
5642 where "n" is the degree), and another always defines the same order as
5643 "x" if "x" is irreducible.
5644 The library syntax is ordred"(x)".
5646 poltschirnhaus"(x)"
5648 applies a random Tschirnhausen transformation to the polynomial "x",
5649 which is assumed to be non-constant and separable, so as to obtain a
5650 new equation for the étale algebra defined by "x". This is for instance
5651 useful when computing resolvents, hence is used by the "polgalois"
5652 function.
5653 The library syntax is tschirnhaus"(x)".
5655 rnfalgtobasis"(rnf,x)"
5657 expresses "x" on the relative integral basis. Here, "rnf" is a relative
5658 number field extension "L/K" as output by "rnfinit", and "x" an element
5659 of "L" in absolute form, i.e. expressed as a polynomial or polmod with
5660 polmod coefficients, \emph{not} on the relative integral basis.
5661 The library syntax is rnfalgtobasis"(rnf,x)".
5663 rnfbasis"(bnf, M)"
5665 let "K" the field represented by bnf, as output by "bnfinit". "M" is a
5666 projective "Z_K"-module given by a pseudo-basis, as output by
5667 "rnfhnfbasis". The routine returns either a true "Z_K"-basis of "M" if
5668 it exists, or an "n+1"-element generating set of "M" if not, where "n"
5669 is the rank of "M" over "K". (Note that "n" is the size of the pseudo-
5670 basis.)
5671 It is allowed to use a polynomial "P" with coefficients in "K" instead
5673 of "M", in which case, "M" is defined as the ring of integers of
5674 "K[X]/(P)" ("P" is assumed irreducible over "K"), viewed as a
5675 "Z_K"-module.
5676 The library syntax is rnfbasis"(bnf,x)".
5678 rnfbasistoalg"(rnf,x)"
5680 computes the representation of "x" as a polmod with polmods
5681 coefficients. Here, "rnf" is a relative number field extension "L/K" as
5682 output by "rnfinit", and "x" an element of "L" expressed on the
5683 relative integral basis.
5684 The library syntax is rnfbasistoalg"(rnf,x)".
5686 rnfcharpoly"(nf,T,a,{v = x})"
5688 characteristic polynomial of "a" over "nf", where "a" belongs to the
5689 algebra defined by "T" over "nf", i.e. "nf[X]/(T)". Returns a
5690 polynomial in variable "v" ("x" by default).
5691 The library syntax is rnfcharpoly"(nf,T,a,v)", where "v" is a variable
5693 number.
5694 rnfconductor"(bnf,pol,{flag = 0})"
5696 given "bnf" as output by "bnfinit", and pol a relative polynomial
5697 defining an Abelian extension, computes the class field theory
5698 conductor of this Abelian extension. The result is a 3-component vector
5699 "[conductor,rayclgp,subgroup]", where conductor is the conductor of the
5700 extension given as a 2-component row vector "[f_0,f_ oo ]", rayclgp is
5701 the full ray class group corresponding to the conductor given as a
5702 3-component vector [h,cyc,gen] as usual for a group, and subgroup is a
5703 matrix in HNF defining the subgroup of the ray class group on the given
5704 generators gen. If "flag" is non-zero, check that pol indeed defines an
5705 Abelian extension, return 0 if it does not.
5706 The library syntax is rnfconductor"(rnf,pol,flag)".
5708 rnfdedekind"(nf,pol,pr)"
5710 given a number field "nf" as output by "nfinit" and a polynomial pol
5711 with coefficients in "nf" defining a relative extension "L" of "nf",
5712 evaluates the relative Dedekind criterion over the order defined by a
5713 root of pol for the prime ideal pr and outputs a 3-component vector as
5714 the result. The first component is a flag equal to 1 if the enlarged
5715 order could be proven to be pr-maximal and to 0 otherwise (it may be
5716 maximal in the latter case if pr is ramified in "L"), the second
5717 component is a pseudo-basis of the enlarged order and the third
5718 component is the valuation at pr of the order discriminant.
5719 The library syntax is rnfdedekind"(nf,pol,pr)".
5721 rnfdet"(nf,M)"
5723 given a pseudo-matrix "M" over the maximal order of "nf", computes its
5724 determinant.
5725 The library syntax is rnfdet"(nf,M)".
5727 rnfdisc"(nf,pol)"
5729 given a number field "nf" as output by "nfinit" and a polynomial pol
5730 with coefficients in "nf" defining a relative extension "L" of "nf",
5731 computes the relative discriminant of "L". This is a two-element row
5732 vector "[D,d]", where "D" is the relative ideal discriminant and "d" is
5733 the relative discriminant considered as an element of "nf^*/{nf^*}^2".
5734 The main variable of "nf" \emph{must} be of lower priority than that of
5735 pol, see "Label se:priority".
5736 The library syntax is rnfdiscf"(bnf,pol)".
5738 rnfeltabstorel"(rnf,x)"
5740 "rnf" being a relative number field extension "L/K" as output by
5741 "rnfinit" and "x" being an element of "L" expressed as a polynomial
5742 modulo the absolute equation "rnf.pol", computes "x" as an element of
5743 the relative extension "L/K" as a polmod with polmod coefficients.
5744 The library syntax is rnfelementabstorel"(rnf,x)".
5746 rnfeltdown"(rnf,x)"
5748 "rnf" being a relative number field extension "L/K" as output by
5749 "rnfinit" and "x" being an element of "L" expressed as a polynomial or
5750 polmod with polmod coefficients, computes "x" as an element of "K" as a
5751 polmod, assuming "x" is in "K" (otherwise an error will occur). If "x"
5752 is given on the relative integral basis, apply "rnfbasistoalg" first,
5753 otherwise PARI will believe you are dealing with a vector.
5754 The library syntax is rnfelementdown"(rnf,x)".
5756 rnfeltreltoabs"(rnf,x)"
5758 "rnf" being a relative number field extension "L/K" as output by
5759 "rnfinit" and "x" being an element of "L" expressed as a polynomial or
5760 polmod with polmod coefficients, computes "x" as an element of the
5761 absolute extension "L/Q" as a polynomial modulo the absolute equation
5762 "rnf.pol". If "x" is given on the relative integral basis, apply
5763 "rnfbasistoalg" first, otherwise PARI will believe you are dealing with
5764 a vector.
5765 The library syntax is rnfelementreltoabs"(rnf,x)".
5767 rnfeltup"(rnf,x)"
5769 "rnf" being a relative number field extension "L/K" as output by
5770 "rnfinit" and "x" being an element of "K" expressed as a polynomial or
5771 polmod, computes "x" as an element of the absolute extension "L/Q" as a
5772 polynomial modulo the absolute equation "rnf.pol". If "x" is given on
5773 the integral basis of "K", apply "nfbasistoalg" first, otherwise PARI
5774 will believe you are dealing with a vector.
5775 The library syntax is rnfelementup"(rnf,x)".
5777 rnfequation"(nf,pol,{flag = 0})"
5779 given a number field "nf" as output by "nfinit" (or simply a
5780 polynomial) and a polynomial pol with coefficients in "nf" defining a
5781 relative extension "L" of "nf", computes the absolute equation of "L"
5782 over Q.
5783 If "flag" is non-zero, outputs a 3-component row vector "[z,a,k]",
5785 where "z" is the absolute equation of "L" over Q, as in the default
5786 behaviour, "a" expresses as an element of "L" a root "alpha" of the
5787 polynomial defining the base field "nf", and "k" is a small integer
5788 such that "theta = beta+kalpha" where "theta" is a root of "z" and
5789 "beta" a root of "pol".
5790 The main variable of "nf" \emph{must} be of lower priority than that of
5792 pol (see "Label se:priority"). Note that for efficiency, this does not
5793 check whether the relative equation is irreducible over "nf", but only
5794 if it is squarefree. If it is reducible but squarefree, the result will
5795 be the absolute equation of the étale algebra defined by pol. If pol is
5796 not squarefree, an error message will be issued.
5797 The library syntax is rnfequation0"(nf,pol,flag)".
5799 rnfhnfbasis"(bnf,x)"
5801 given "bnf" as output by "bnfinit", and either a polynomial "x" with
5802 coefficients in "bnf" defining a relative extension "L" of "bnf", or a
5803 pseudo-basis "x" of such an extension, gives either a true "bnf"-basis
5804 of "L" in upper triangular Hermite normal form, if it exists, and
5805 returns 0 otherwise.
5806 The library syntax is rnfhnfbasis"(nf,x)".
5808 rnfidealabstorel"(rnf,x)"
5810 let "rnf" be a relative number field extension "L/K" as output by
5811 "rnfinit", and "x" an ideal of the absolute extension "L/Q" given by a
5812 Z-basis of elements of "L". Returns the relative pseudo-matrix in HNF
5813 giving the ideal "x" considered as an ideal of the relative extension
5814 "L/K".
5815 If "x" is an ideal in HNF form, associated to an nf structure, for
5817 instance as output by "idealhnf(nf,...)", use "rnfidealabstorel(rnf,
5818 nf.zk * x)" to convert it to a relative ideal.
5819 The library syntax is rnfidealabstorel"(rnf,x)".
5821 rnfidealdown"(rnf,x)"
5823 let "rnf" be a relative number field extension "L/K" as output by
5824 "rnfinit", and "x" an ideal of "L", given either in relative form or by
5825 a Z-basis of elements of "L" (see "Label se:rnfidealabstorel"), returns
5826 the ideal of "K" below "x", i.e. the intersection of "x" with "K".
5827 The library syntax is rnfidealdown"(rnf,x)".
5829 rnfidealhnf"(rnf,x)"
5831 "rnf" being a relative number field extension "L/K" as output by
5832 "rnfinit" and "x" being a relative ideal (which can be, as in the
5833 absolute case, of many different types, including of course elements),
5834 computes the HNF pseudo-matrix associated to "x", viewed as a
5835 "Z_K"-module.
5836 The library syntax is rnfidealhermite"(rnf,x)".
5838 rnfidealmul"(rnf,x,y)"
5840 "rnf" being a relative number field extension "L/K" as output by
5841 "rnfinit" and "x" and "y" being ideals of the relative extension "L/K"
5842 given by pseudo-matrices, outputs the ideal product, again as a
5843 relative ideal.
5844 The library syntax is rnfidealmul"(rnf,x,y)".
5846 rnfidealnormabs"(rnf,x)"
5848 "rnf" being a relative number field extension "L/K" as output by
5849 "rnfinit" and "x" being a relative ideal (which can be, as in the
5850 absolute case, of many different types, including of course elements),
5851 computes the norm of the ideal "x" considered as an ideal of the
5852 absolute extension "L/Q". This is identical to
5853 "idealnorm(rnfidealnormrel(rnf,x))", but faster.
5854 The library syntax is rnfidealnormabs"(rnf,x)".
5856 rnfidealnormrel"(rnf,x)"
5858 "rnf" being a relative number field extension "L/K" as output by
5859 "rnfinit" and "x" being a relative ideal (which can be, as in the
5860 absolute case, of many different types, including of course elements),
5861 computes the relative norm of "x" as a ideal of "K" in HNF.
5862 The library syntax is rnfidealnormrel"(rnf,x)".
5864 rnfidealreltoabs"(rnf,x)"
5866 "rnf" being a relative number field extension "L/K" as output by
5867 "rnfinit" and "x" being a relative ideal, gives the ideal "xZ_L" as an
5868 absolute ideal of "L/Q", in the form of a Z-basis, given by a vector of
5869 polynomials (modulo "rnf.pol"). The following routine might be useful:
5870 \\ return y = rnfidealreltoabs(rnf,...) as an ideal in HNF form
5872 \\ associated to nf = nfinit( rnf.pol );
5873 idealgentoHNF(nf, y) = mathnf( Mat( nfalgtobasis(nf, y) ) );
5874 The library syntax is rnfidealreltoabs"(rnf,x)".
5876 rnfidealtwoelt"(rnf,x)"
5878 "rnf" being a relative number field extension "L/K" as output by
5879 "rnfinit" and "x" being an ideal of the relative extension "L/K" given
5880 by a pseudo-matrix, gives a vector of two generators of "x" over "Z_L"
5881 expressed as polmods with polmod coefficients.
5882 The library syntax is rnfidealtwoelement"(rnf,x)".
5884 rnfidealup"(rnf,x)"
5886 "rnf" being a relative number field extension "L/K" as output by
5887 "rnfinit" and "x" being an ideal of "K", gives the ideal "xZ_L" as an
5888 absolute ideal of "L/Q", in the form of a Z-basis, given by a vector of
5889 polynomials (modulo "rnf.pol"). The following routine might be useful:
5890 \\ return y = rnfidealup(rnf,...) as an ideal in HNF form
5892 \\ associated to nf = nfinit( rnf.pol );
5893 idealgentoHNF(nf, y) = mathnf( Mat( nfalgtobasis(nf, y) ) );
5894 The library syntax is rnfidealup"(rnf,x)".
5896 rnfinit"(nf,pol)"
5898 "nf" being a number field in "nfinit" format considered as base field,
5899 and pol a polynomial defining a relative extension over "nf", this
5900 computes all the necessary data to work in the relative extension. The
5901 main variable of pol must be of higher priority (see "Label
5902 se:priority") than that of "nf", and the coefficients of pol must be in
5903 "nf".
5904 The result is a row vector, whose components are technical. In the
5906 following description, we let "K" be the base field defined by "nf",
5907 "m" the degree of the base field, "n" the relative degree, "L" the
5908 large field (of relative degree "n" or absolute degree "nm"), "r_1" and
5909 "r_2" the number of real and complex places of "K".
5910 "rnf[1]" contains the relative polynomial pol.
5912 "rnf[2]" is currently unused.
5914 "rnf[3]" is a two-component row vector "[\goth{d}(L/K),s]" where
5916 "\goth{d}(L/K)" is the relative ideal discriminant of "L/K" and "s" is
5917 the discriminant of "L/K" viewed as an element of "K^*/(K^*)^2", in
5918 other words it is the output of "rnfdisc".
5919 "rnf[4]" is the ideal index "\goth{f}", i.e. such that "d(pol)Z_K =
5921 \goth{f}^2\goth{d}(L/K)".
5922 "rnf[5]" is currently unused.
5924 "rnf[6]" is currently unused.
5926 "rnf[7]" is a two-component row vector, where the first component is
5928 the relative integral pseudo basis expressed as polynomials (in the
5929 variable of "pol") with polmod coefficients in "nf", and the second
5930 component is the ideal list of the pseudobasis in HNF.
5931 "rnf[8]" is the inverse matrix of the integral basis matrix, with
5933 coefficients polmods in "nf".
5934 "rnf[9]" is currently unused.
5936 "rnf[10]" is "nf".
5938 "rnf[11]" is the output of "rnfequation(nf, pol, 1)". Namely, a vector
5940 vabs with 3 entries describing the \emph{absolute} extension "L/Q".
5941 "vabs[1]" is an absolute equation, more conveniently obtained as
5942 "rnf.pol". "vabs[2]" expresses the generator "alpha" of the number
5943 field "nf" as a polynomial modulo the absolute equation "vabs[1]".
5944 "vabs[3]" is a small integer "k" such that, if "beta" is an abstract
5945 root of pol and "alpha" the generator of "nf", the generator whose root
5946 is vabs will be "beta + k alpha". Note that one must be very careful if
5947 "k ! = 0" when dealing simultaneously with absolute and relative
5948 quantities since the generator chosen for the absolute extension is not
5949 the same as for the relative one. If this happens, one can of course go
5950 on working, but we strongly advise to change the relative polynomial so
5951 that its root will be "beta + k alpha". Typically, the GP instruction
5952 would be
5953 "pol = subst(pol, x, x - k*Mod(y,nf.pol))"
5955 "rnf[12]" is by default unused and set equal to 0. This field is used
5957 to store further information about the field as it becomes available
5958 (which is rarely needed, hence would be too expensive to compute during
5959 the initial "rnfinit" call).
5960 The library syntax is rnfinitalg"(nf,pol,prec)".
5962 rnfisfree"(bnf,x)"
5964 given "bnf" as output by "bnfinit", and either a polynomial "x" with
5965 coefficients in "bnf" defining a relative extension "L" of "bnf", or a
5966 pseudo-basis "x" of such an extension, returns true (1) if "L/bnf" is
5967 free, false (0) if not.
5968 The library syntax is rnfisfree"(bnf,x)", and the result is a "long".
5970 rnfisnorm"(T,a,{flag = 0})"
5972 similar to "bnfisnorm" but in the relative case. "T" is as output by
5973 "rnfisnorminit" applied to the extension "L/K". This tries to decide
5974 whether the element "a" in "K" is the norm of some "x" in the extension
5975 "L/K".
5976 The output is a vector "[x,q]", where "a = \Norm(x)*q". The algorithm
5978 looks for a solution "x" which is an "S"-integer, with "S" a list of
5979 places of "K" containing at least the ramified primes, the generators
5980 of the class group of "L", as well as those primes dividing "a". If
5981 "L/K" is Galois, then this is enough; otherwise, "flag" is used to add
5982 more primes to "S": all the places above the primes "p <= flag"
5983 (resp. "p|flag") if "flag > 0" (resp. "flag < 0").
5984 The answer is guaranteed (i.e. "a" is a norm iff "q = 1") if the field
5986 is Galois, or, under GRH, if "S" contains all primes less than "12 log
5987 ^2|\disc(M)|", where "M" is the normal closure of "L/K".
5988 If "rnfisnorminit" has determined (or was told) that "L/K" is Galois,
5990 and "flag ! = 0", a Warning is issued (so that you can set "flag = 1"
5991 to check whether "L/K" is known to be Galois, according to "T").
5992 Example:
5993 bnf = bnfinit(y^3 + y^2 - 2*y - 1);
5995 p = x^2 + Mod(y^2 + 2*y + 1, bnf.pol);
5996 T = rnfisnorminit(bnf, p);
5997 rnfisnorm(T, 17)
5998 checks whether 17 is a norm in the Galois extension "Q(beta) /
6000 Q(alpha)", where "alpha^3 + alpha^2 - 2alpha - 1 = 0" and "beta^2 +
6001 alpha^2 + 2alpha + 1 = 0" (it is).
6002 The library syntax is rnfisnorm"(T,x,flag)".
6004 rnfisnorminit"(pol,polrel,{flag = 2})"
6006 let "K" be defined by a root of pol, and "L/K" the extension defined by
6007 the polynomial polrel. As usual, pol can in fact be an nf, or bnf, etc;
6008 if pol has degree 1 (the base field is Q), polrel is also allowed to be
6009 an nf, etc. Computes technical data needed by "rnfisnorm" to solve norm
6010 equations "Nx = a", for "x" in "L", and "a" in "K".
6011 If "flag = 0", do not care whether "L/K" is Galois or not.
6013 If "flag = 1", "L/K" is assumed to be Galois (unchecked), which speeds
6015 up "rnfisnorm".
6016 If "flag = 2", let the routine determine whether "L/K" is Galois.
6018 The library syntax is rnfisnorminit"(pol,polrel,flag)".
6020 rnfkummer"(bnr,{subgroup},{deg = 0})"
6022 bnr being as output by "bnrinit", finds a relative equation for the
6023 class field corresponding to the module in bnr and the given congruence
6024 subgroup (the full ray class field if subgroup is omitted). If deg is
6025 positive, outputs the list of all relative equations of degree deg
6026 contained in the ray class field defined by bnr, with the \emph{same}
6027 conductor as "(bnr, subgroup)".
6028 Warning: this routine only works for subgroups of prime index. It uses
6030 Kummer theory, adjoining necessary roots of unity (it needs to compute
6031 a tough "bnfinit" here), and finds a generator via Hecke's
6032 characterization of ramification in Kummer extensions of prime degree.
6033 If your extension does not have prime degree, for the time being, you
6034 have to split it by hand as a tower / compositum of such extensions.
6035 The library syntax is rnfkummer"(bnr,subgroup,deg,prec)", where deg is
6037 a "long" and an omitted subgroup is coded as "NULL"
6038 rnflllgram"(nf,pol,order)"
6040 given a polynomial pol with coefficients in nf defining a relative
6041 extension "L" and a suborder order of "L" (of maximal rank), as output
6042 by "rnfpseudobasis""(nf,pol)" or similar, gives "[[neworder],U]", where
6043 neworder is a reduced order and "U" is the unimodular transformation
6044 matrix.
6045 The library syntax is rnflllgram"(nf,pol,order,prec)".
6047 rnfnormgroup"(bnr,pol)"
6049 bnr being a big ray class field as output by "bnrinit" and pol a
6050 relative polynomial defining an Abelian extension, computes the norm
6051 group (alias Artin or Takagi group) corresponding to the Abelian
6052 extension of "bnf = bnr[1]" defined by pol, where the module
6053 corresponding to bnr is assumed to be a multiple of the conductor
6054 (i.e. pol defines a subextension of bnr). The result is the HNF
6055 defining the norm group on the given generators of "bnr[5][3]". Note
6056 that neither the fact that pol defines an Abelian extension nor the
6057 fact that the module is a multiple of the conductor is checked. The
6058 result is undefined if the assumption is not correct.
6059 The library syntax is rnfnormgroup"(bnr,pol)".
6061 rnfpolred"(nf,pol)"
6063 relative version of "polred". Given a monic polynomial pol with
6064 coefficients in "nf", finds a list of relative polynomials defining
6065 some subfields, hopefully simpler and containing the original field. In
6066 the present version 2.2.0, this is slower and less efficient than
6067 "rnfpolredabs".
6068 The library syntax is rnfpolred"(nf,pol,prec)".
6070 rnfpolredabs"(nf,pol,{flag = 0})"
6072 relative version of "polredabs". Given a monic polynomial pol with
6073 coefficients in "nf", finds a simpler relative polynomial defining the
6074 same field. The binary digits of "flag" mean
6075 1: returns "[P,a]" where "P" is the default output and "a" is an
6077 element expressed on a root of "P" whose characteristic polynomial is
6078 pol
6079 2: returns an absolute polynomial (same as
6081 "rnfequation(nf,rnfpolredabs(nf,pol))" but faster).
6082 16: possibly use a suborder of the maximal order. This is slower than
6084 the default when the relative discriminant is smooth, and much faster
6085 otherwise. See "Label se:polredabs".
6086 Remark. In the present implementation, this is both faster and much
6088 more efficient than "rnfpolred", the difference being more dramatic
6089 than in the absolute case. This is because the implementation of
6090 "rnfpolred" is based on (a partial implementation of) an incomplete
6091 reduction theory of lattices over number fields, the function
6092 "rnflllgram", which deserves to be improved.
6093 The library syntax is rnfpolredabs"(nf,pol,flag,prec)".
6095 rnfpseudobasis"(nf,pol)"
6097 given a number field "nf" as output by "nfinit" and a polynomial pol
6098 with coefficients in "nf" defining a relative extension "L" of "nf",
6099 computes a pseudo-basis "(A,I)" for the maximal order "Z_L" viewed as a
6100 "Z_K"-module, and the relative discriminant of "L". This is output as a
6101 four-element row vector "[A,I,D,d]", where "D" is the relative ideal
6102 discriminant and "d" is the relative discriminant considered as an
6103 element of "nf^*/{nf^*}^2".
6104 The library syntax is rnfpseudobasis"(nf,pol)".
6106 rnfsteinitz"(nf,x)"
6108 given a number field "nf" as output by "nfinit" and either a polynomial
6109 "x" with coefficients in "nf" defining a relative extension "L" of
6110 "nf", or a pseudo-basis "x" of such an extension as output for example
6111 by "rnfpseudobasis", computes another pseudo-basis "(A,I)" (not in HNF
6112 in general) such that all the ideals of "I" except perhaps the last one
6113 are equal to the ring of integers of "nf", and outputs the four-
6114 component row vector "[A,I,D,d]" as in "rnfpseudobasis". The name of
6115 this function comes from the fact that the ideal class of the last
6116 ideal of "I", which is well defined, is the Steinitz class of the
6117 "Z_K"-module "Z_L" (its image in "SK_0(Z_K)").
6118 The library syntax is rnfsteinitz"(nf,x)".
6120 subgrouplist"(bnr,{bound},{flag = 0})"
6122 bnr being as output by "bnrinit" or a list of cyclic components of a
6123 finite Abelian group "G", outputs the list of subgroups of "G".
6124 Subgroups are given as HNF left divisors of the SNF matrix
6125 corresponding to "G".
6126 Warning: the present implementation cannot treat a group "G" where any
6128 cyclic factor has more than "2^{31}", resp. "2^{63}" elements on a
6129 32-bit, resp. 64-bit architecture. "forsubgroup" is a bit more general
6130 and can handle "G" if all "p"-Sylow subgroups of "G" satisfy the
6131 condition above.
6132 If "flag = 0" (default) and bnr is as output by "bnrinit", gives only
6134 the subgroups whose modulus is the conductor. Otherwise, the modulus is
6135 not taken into account.
6136 If bound is present, and is a positive integer, restrict the output to
6138 subgroups of index less than bound. If bound is a vector containing a
6139 single positive integer "B", then only subgroups of index exactly equal
6140 to "B" are computed. For instance
6141 %2 = [[2, 1; 0, 1], [1, 0; 0, 2], [2, 0; 0, 1], [3, 0; 0, 1], [1, 0; 0, 1]]
6143 ? subgrouplist([6,2],[3]) \\ index less than 3
6144 %2 = [[2, 1; 0, 1], [1, 0; 0, 2], [2, 0; 0, 1], [3, 0; 0, 1], [1, 0; 0, 1]]
6145 ? subgrouplist([6,2],[3]) \\ index 3
6146 %3 = [[3, 0; 0, 1]]
6147 ? bnr = bnrinit(bnfinit(x), [120,[1]], 1);
6148 ? L = subgrouplist(bnr, [8]);
6149 In the last example, "L" corresponds to the 24 subfields of
6151 "Q(zeta_{120})", of degree 8 and conductor "120 oo " (by setting flag,
6152 we see there are a total of 43 subgroups of degree 8).
6153 ? vector(#L, i, galoissubcyclo(bnr, L[i]))
6155 will produce their equations. (For a general base field, you would have
6157 to rely on "bnrstark", or "rnfkummer".)
6158 The library syntax is subgrouplist0"(bnr,bound,flag)", where "flag" is
6160 a long integer, and an omitted bound is coded by "NULL".
6161 zetak"(znf,x,{flag = 0})"
6163 znf being a number field initialized by "zetakinit" (\emph{not} by
6164 "nfinit"), computes the value of the Dedekind zeta function of the
6165 number field at the complex number "x". If "flag = 1" computes Dedekind
6166 "Lambda" function instead (i.e. the product of the Dedekind zeta
6167 function by its gamma and exponential factors).
6168 CAVEAT. This implementation is not satisfactory and must be rewritten.
6170 In particular
6171 "*" The accuracy of the result depends in an essential way on the
6173 accuracy of both the "zetakinit" program and the current accuracy. Be
6174 wary in particular that "x" of large imaginary part or, on the
6175 contrary, very close to an ordinary integer will suffer from precision
6176 loss, yielding fewer significant digits than expected. Computing with
6177 28 eight digits of relative accuracy, we have
6178 ? zeta(3)
6180 %1 = 1.202056903159594285399738161
6181 ? zeta(3-1e-20)
6182 %2 = 1.202056903159594285401719424
6183 ? zetak(zetakinit(x), 3-1e-20)
6184 %3 = 1.2020569031595952919 \\ 5 digits are wrong
6185 ? zetak(zetakinit(x), 3-1e-28)
6186 %4 = -25.33411749 \\ junk
6187 "*" As the precision increases, results become unexpectedly completely
6189 wrong:
6190 ? \p100
6192 ? zetak(zetakinit(x^2-5), -1) - 1/30
6193 %1 = 7.26691813 E-108 \\ perfect
6194 ? \p150
6195 ? zetak(zetakinit(x^2-5), -1) - 1/30
6196 %2 = -2.486113578 E-156 \\ perfect
6197 ? \p200
6198 ? zetak(zetakinit(x^2-5), -1) - 1/30
6199 %3 = 4.47... E-75 \\ more than half of the digits are wrong
6200 ? \p250
6201 ? zetak(zetakinit(x^2-5), -1) - 1/30
6202 %4 = 1.6 E43 \\ junk
6203 The library syntax is glambdak"(znf,x,prec)" or " gzetak(znf,x,prec)".
6205 zetakinit"(x)"
6207 computes a number of initialization data concerning the number field
6208 defined by the polynomial "x" so as to be able to compute the Dedekind
6209 zeta and lambda functions (respectively zetak(x) and "zetak(x,1)").
6210 This function calls in particular the "bnfinit" program. The result is
6211 a 9-component vector "v" whose components are very technical and cannot
6212 really be used by the user except through the "zetak" function. The
6213 only component which can be used if it has not been computed already is
6214 "v[1][4]" which is the result of the "bnfinit" call.
6215 This function is very inefficient and should be rewritten. It needs to
6217 computes millions of coefficients of the corresponding Dirichlet series
6218 if the precision is big. Unless the discriminant is small it will not
6219 be able to handle more than 9 digits of relative precision. For
6220 instance, "zetakinit(x^8 - 2)" needs 440MB of memory at default
6221 precision.
6222 The library syntax is initzeta"(x)".
6224
6226 We group here all functions which are specific to polynomials or power
6227 series. Many other functions which can be applied on these objects are
6228 described in the other sections. Also, some of the functions described
6229 here can be applied to other types.
6230 O"(p^e)"
6232 if "p" is an integer greater than 2, returns a "p"-adic 0 of precision
6233 "e". In all other cases, returns a power series zero with precision
6234 given by "e v", where "v" is the "X"-adic valuation of "p" with respect
6235 to its main variable.
6236 The library syntax is zeropadic"(p,e)" for a "p"-adic and "
6238 zeroser(v,e)" for a power series zero in variable "v", which is a
6239 "long". The precision "e" is a "long".
6240 deriv"(x,{v})"
6242 derivative of "x" with respect to the main variable if "v" is omitted,
6243 and with respect to "v" otherwise. The derivative of a scalar type is
6244 zero, and the derivative of a vector or matrix is done componentwise.
6245 One can use "x'" as a shortcut if the derivative is with respect to the
6246 main variable of "x".
6247 By definition, the main variable of a "t_POLMOD" is the main variable
6249 among the coefficients from its two polynomial components
6250 (representative and modulus); in other words, assuming a polmod
6251 represents an element of "R[X]/(T(X))", the variable "X" is a mute
6252 variable and the derivative is taken with respect to the main variable
6253 used in the base ring "R".
6254 The library syntax is deriv"(x,v)", where "v" is a "long", and an
6256 omitted "v" is coded as "-1". When "x" is a "t_POL", derivpol(x) is a
6257 shortcut for "deriv(x, -1)".
6258 eval"(x)"
6260 replaces in "x" the formal variables by the values that have been
6261 assigned to them after the creation of "x". This is mainly useful in
6262 GP, and not in library mode. Do not confuse this with substitution (see
6263 "subst").
6264 If "x" is a character string, eval(x) executes "x" as a GP command, as
6266 if directly input from the keyboard, and returns its output. For
6267 convenience, "x" is evaluated as if "strictmatch" was off. In
6268 particular, unused characters at the end of "x" do not prevent its
6269 evaluation:
6270 ? eval("1a")
6272 % 1 = 1
6273 The library syntax is geval"(x)". The more basic functions "
6275 poleval(q,x)", " qfeval(q,x)", and " hqfeval(q,x)" evaluate "q" at "x",
6276 where "q" is respectively assumed to be a polynomial, a quadratic form
6277 (a symmetric matrix), or an Hermitian form (an Hermitian complex
6278 matrix).
6279 factorpadic"(pol,p,r,{flag = 0})"
6281 "p"-adic factorization of the polynomial pol to precision "r", the
6282 result being a two-column matrix as in "factor". The factors are
6283 normalized so that their leading coefficient is a power of "p". "r"
6284 must be strictly larger than the "p"-adic valuation of the discriminant
6285 of pol for the result to make any sense. The method used is a modified
6286 version of the round 4 algorithm of Zassenhaus.
6287 If "flag = 1", use an algorithm due to Buchmann and Lenstra, which is
6289 usually less efficient.
6290 The library syntax is factorpadic4"(pol,p,r)", where "r" is a "long"
6292 integer.
6293 intformal"(x,{v})"
6295 formal integration of "x" with respect to the main variable if "v" is
6296 omitted, with respect to the variable "v" otherwise. Since PARI does
6297 not know about ``abstract'' logarithms (they are immediately evaluated,
6298 if only to a power series), logarithmic terms in the result will yield
6299 an error. "x" can be of any type. When "x" is a rational function, it
6300 is assumed that the base ring is an integral domain of characteristic
6301 zero.
6302 The library syntax is integ"(x,v)", where "v" is a "long" and an
6304 omitted "v" is coded as "-1".
6305 padicappr"(pol,a)"
6307 vector of "p"-adic roots of the polynomial "pol" congruent to the
6308 "p"-adic number "a" modulo "p", and with the same "p"-adic precision as
6309 "a". The number "a" can be an ordinary "p"-adic number (type "t_PADIC",
6310 i.e. an element of "Z_p") or can be an integral element of a finite
6311 extension of "Q_p", given as a "t_POLMOD" at least one of whose
6312 coefficients is a "t_PADIC". In this case, the result is the vector of
6313 roots belonging to the same extension of "Q_p" as "a".
6314 The library syntax is padicappr"(pol,a)".
6316 polcoeff"(x,s,{v})"
6318 coefficient of degree "s" of the polynomial "x", with respect to the
6319 main variable if "v" is omitted, with respect to "v" otherwise. Also
6320 applies to power series, scalars (polynomial of degree 0), and to
6321 rational functions provided the denominator is a monomial.
6322 The library syntax is polcoeff0"(x,s,v)", where "v" is a "long" and an
6324 omitted "v" is coded as "-1". Also available is " truecoeff(x,v)".
6325 poldegree"(x,{v})"
6327 degree of the polynomial "x" in the main variable if "v" is omitted, in
6328 the variable "v" otherwise.
6329 The degree of 0 is a fixed negative number, whose exact value should
6331 not be used. The degree of a non-zero scalar is 0. Finally, when "x" is
6332 a non-zero polynomial or rational function, returns the ordinary degree
6333 of "x". Raise an error otherwise.
6334 The library syntax is poldegree"(x,v)", where "v" and the result are
6336 "long"s (and an omitted "v" is coded as "-1"). Also available is "
6337 degree(x)", which is equivalent to "poldegree(x,-1)".
6338 polcyclo"(n,{v = x})"
6340 "n"-th cyclotomic polynomial, in variable "v" ("x" by default). The
6341 integer "n" must be positive.
6342 The library syntax is cyclo"(n,v)", where "n" and "v" are "long"
6344 integers ("v" is a variable number, usually obtained through "varn").
6345 poldisc"(pol,{v})"
6347 discriminant of the polynomial pol in the main variable is "v" is
6348 omitted, in "v" otherwise. The algorithm used is the subresultant
6349 algorithm.
6350 The library syntax is poldisc0"(x,v)". Also available is " discsr(x)",
6352 equivalent to "poldisc0(x,-1)".
6353 poldiscreduced"(f)"
6355 reduced discriminant vector of the (integral, monic) polynomial "f".
6356 This is the vector of elementary divisors of
6357 "Z[alpha]/f'(alpha)Z[alpha]", where "alpha" is a root of the polynomial
6358 "f". The components of the result are all positive, and their product
6359 is equal to the absolute value of the discriminant of "f".
6360 The library syntax is reduceddiscsmith"(x)".
6362 polhensellift"(x, y, p, e)"
6364 given a prime "p", an integral polynomial "x" whose leading coefficient
6365 is a "p"-unit, a vector "y" of integral polynomials that are pairwise
6366 relatively prime modulo "p", and whose product is congruent to "x"
6367 modulo "p", lift the elements of "y" to polynomials whose product is
6368 congruent to "x" modulo "p^e".
6369 The library syntax is polhensellift"(x,y,p,e)" where "e" must be a
6371 "long".
6372 polinterpolate"(xa,{ya},{v = x},{&e})"
6374 given the data vectors "xa" and "ya" of the same length "n" ("xa"
6375 containing the "x"-coordinates, and "ya" the corresponding
6376 "y"-coordinates), this function finds the interpolating polynomial
6377 passing through these points and evaluates it at "v". If "ya" is
6378 omitted, return the polynomial interpolating the "(i,xa[i])". If
6379 present, "e" will contain an error estimate on the returned value.
6380 The library syntax is polint"(xa,ya,v,&e)", where "e" will contain an
6382 error estimate on the returned value.
6383 polisirreducible"(pol)"
6385 pol being a polynomial (univariate in the present version 2.2.0),
6386 returns 1 if pol is non-constant and irreducible, 0 otherwise.
6387 Irreducibility is checked over the smallest base field over which pol
6388 seems to be defined.
6389 The library syntax is gisirreducible"(pol)".
6391 pollead"(x,{v})"
6393 leading coefficient of the polynomial or power series "x". This is
6394 computed with respect to the main variable of "x" if "v" is omitted,
6395 with respect to the variable "v" otherwise.
6396 The library syntax is pollead"(x,v)", where "v" is a "long" and an
6398 omitted "v" is coded as "-1". Also available is " leading_term(x)".
6399 pollegendre"(n,{v = x})"
6401 creates the "n^{th}" Legendre polynomial, in variable "v".
6402 The library syntax is legendre"(n)", where "x" is a "long".
6404 polrecip"(pol)"
6406 reciprocal polynomial of pol, i.e. the coefficients are in reverse
6407 order. pol must be a polynomial.
6408 The library syntax is polrecip"(x)".
6410 polresultant"(x,y,{v},{flag = 0})"
6412 resultant of the two polynomials "x" and "y" with exact entries, with
6413 respect to the main variables of "x" and "y" if "v" is omitted, with
6414 respect to the variable "v" otherwise. The algorithm assumes the base
6415 ring is a domain.
6416 If "flag = 0", uses the subresultant algorithm.
6418 If "flag = 1", uses the determinant of Sylvester's matrix instead (here
6420 "x" and "y" may have non-exact coefficients).
6421 If "flag = 2", uses Ducos's modified subresultant algorithm. It should
6423 be much faster than the default if the coefficient ring is complicated
6424 (e.g multivariate polynomials or huge coefficients), and slightly
6425 slower otherwise.
6426 The library syntax is polresultant0"(x,y,v,flag)", where "v" is a
6428 "long" and an omitted "v" is coded as "-1". Also available are "
6429 subres(x,y)" ("flag = 0") and " resultant2(x,y)" ("flag = 1").
6430 polroots"(pol,{flag = 0})"
6432 complex roots of the polynomial pol, given as a column vector where
6433 each root is repeated according to its multiplicity. The precision is
6434 given as for transcendental functions: in GP it is kept in the variable
6435 "realprecision" and is transparent to the user, but it must be
6436 explicitly given as a second argument in library mode.
6437 The algorithm used is a modification of A. Schönhage's root-finding
6439 algorithm, due to and implemented by X. Gourdon. Barring bugs, it is
6440 guaranteed to converge and to give the roots to the required accuracy.
6441 If "flag = 1", use a variant of the Newton-Raphson method, which is
6443 \emph{not} guaranteed to converge, but is rather fast. If you get the
6444 messages ``too many iterations in roots'' or ``INTERNAL ERROR:
6445 incorrect result in roots'', use the default algorithm. This used to be
6446 the default root-finding function in PARI until version 1.39.06.
6447 The library syntax is roots"(pol,prec)" or " rootsold(pol,prec)".
6449 polrootsmod"(pol,p,{flag = 0})"
6451 row vector of roots modulo "p" of the polynomial pol. The particular
6452 non-prime value "p = 4" is accepted, mainly for 2-adic computations.
6453 Multiple roots are \emph{not} repeated.
6454 If "p" is very small, you may try setting "flag = 1", which uses a
6456 naive search.
6457 The library syntax is rootmod"(pol,p)" ("flag = 0") or "
6459 rootmod2(pol,p)" ("flag = 1").
6460 polrootspadic"(pol,p,r)"
6462 row vector of "p"-adic roots of the polynomial pol, given to "p"-adic
6463 precision "r". Multiple roots are \emph{not} repeated. "p" is assumed
6464 to be a prime, and pol to be non-zero modulo "p". Note that this is not
6465 the same as the roots in "Z/p^rZ", rather it gives approximations in
6466 "Z/p^rZ" of the true roots living in "Q_p".
6467 If pol has inexact "t_PADIC" coefficients, this is not always well-
6469 defined; in this case, the equation is first made integral, then lifted
6470 to Z. Hence the roots given are approximations of the roots of a
6471 polynomial which is "p"-adically close to the input.
6472 The library syntax is rootpadic"(pol,p,r)", where "r" is a "long".
6474 polsturm"(pol,{a},{b})"
6476 number of real roots of the real polynomial pol in the interval
6477 "]a,b]", using Sturm's algorithm. "a" (resp. "b") is taken to be "- oo
6478 " (resp. "+ oo ") if omitted.
6479 The library syntax is sturmpart"(pol,a,b)". Use "NULL" to omit an
6481 argument. " sturm(pol)" is equivalent to " sturmpart(pol,NULL,NULL)".
6482 The result is a "long".
6483 polsubcyclo"(n,d,{v = x})"
6485 gives polynomials (in variable "v") defining the sub-Abelian extensions
6486 of degree "d" of the cyclotomic field "Q(zeta_n)", where "d | phi(n)".
6487 If there is exactly one such extension the output is a polynomial, else
6489 it is a vector of polynomials, eventually empty.
6490 To be sure to get a vector, you can use "concat([],polsubcyclo(n,d))"
6492 The function "galoissubcyclo" allows to specify more closely which sub-
6494 Abelian extension should be computed.
6495 The library syntax is polsubcyclo"(n,d,v)", where "n", "d" and "v" are
6497 "long" and "v" is a variable number. When "(Z/nZ)^*" is cyclic, you can
6498 use " subcyclo(n,d,v)", where "n", "d" and "v" are "long" and "v" is a
6499 variable number.
6500 polsylvestermatrix"(x,y)"
6502 forms the Sylvester matrix corresponding to the two polynomials "x" and
6503 "y", where the coefficients of the polynomials are put in the columns
6504 of the matrix (which is the natural direction for solving equations
6505 afterwards). The use of this matrix can be essential when dealing with
6506 polynomials with inexact entries, since polynomial Euclidean division
6507 doesn't make much sense in this case.
6508 The library syntax is sylvestermatrix"(x,y)".
6510 polsym"(x,n)"
6512 creates the vector of the symmetric powers of the roots of the
6513 polynomial "x" up to power "n", using Newton's formula.
6514 The library syntax is polsym"(x)".
6516 poltchebi"(n,{v = x})"
6518 creates the "n^{th}" Chebyshev polynomial "T_n" of the first kind in
6519 variable "v".
6520 The library syntax is tchebi"(n,v)", where "n" and "v" are "long"
6522 integers ("v" is a variable number).
6523 polzagier"(n,m)"
6525 creates Zagier's polynomial "P_n^{(m)}" used in the functions "sumalt"
6526 and "sumpos" (with "flag = 1"). One must have "m <= n". The exact
6527 definition can be found in ``Convergence acceleration of alternating
6528 series'', Cohen et al., Experiment. Math., vol. 9, 2000, pp. 3--12.
6529 The library syntax is polzagreel"(n,m,prec)" if the result is only
6531 wanted as a polynomial with real coefficients to the precision "prec",
6532 or " polzag(n,m)" if the result is wanted exactly, where "n" and "m"
6533 are "long"s.
6534 serconvol"(x,y)"
6536 convolution (or Hadamard product) of the two power series "x" and "y";
6537 in other words if "x = sum a_k*X^k" and "y = sum b_k*X^k" then
6538 "serconvol(x,y) = sum a_k*b_k*X^k".
6539 The library syntax is convol"(x,y)".
6541 serlaplace"(x)"
6543 "x" must be a power series with non-negative exponents. If "x = sum
6544 (a_k/k!)*X^k" then the result is "sum a_k*X^k".
6545 The library syntax is laplace"(x)".
6547 serreverse"(x)"
6549 reverse power series (i.e. "x^{-1}", not "1/x") of "x". "x" must be a
6550 power series whose valuation is exactly equal to one.
6551 The library syntax is recip"(x)".
6553 subst"(x,y,z)"
6555 replace the simple variable "y" by the argument "z" in the
6556 ``polynomial'' expression "x". Every type is allowed for "x", but if it
6557 is not a genuine polynomial (or power series, or rational function),
6558 the substitution will be done as if the scalar components were
6559 polynomials of degree zero. In particular, beware that:
6560 ? subst(1, x, [1,2; 3,4])
6562 %1 =
6563 [1 0]
6564 [0 1]
6566 ? subst(1, x, Mat([0,1]))
6568 *** forbidden substitution by a non square matrix
6569 If "x" is a power series, "z" must be either a polynomial, a power
6571 series, or a rational function.
6572 The library syntax is gsubst"(x,y,z)", where "y" is the variable
6574 number.
6575 substpol"(x,y,z)"
6577 replace the ``variable'' "y" by the argument "z" in the ``polynomial''
6578 expression "x". Every type is allowed for "x", but the same behaviour
6579 as "subst" above apply.
6580 The difference with "subst" is that "y" is allowed to be any polynomial
6582 here. The substitution is done as per the following script:
6583 subst_poly(pol, from, to) =
6585 { local(t = 'subst_poly_t, M = from - t);
6586 subst(lift(Mod(pol,M), variable(M)), t, to)
6588 }
6589 For instance
6591 ? substpol(x^4 + x^2 + 1, x^2, y)
6593 %1 = y^2 + y + 1
6594 ? substpol(x^4 + x^2 + 1, x^3, y)
6595 %2 = x^2 + y*x + 1
6596 ? substpol(x^4 + x^2 + 1, (x+1)^2, y)
6597 %3 = (-4*y - 6)*x + (y^2 + 3*y - 3)
6598 The library syntax is gsubstpol"(x,y,z)".
6600 substvec"(x,v,w)"
6602 "v" being a vector of monomials (variables), "w" a vector of
6603 expressions of the same length, replace in the expression "x" all
6604 occurences of "v_i" by "w_i". The substitutions are done
6605 simultaneously; more precisely, the "v_i" are first replaced by new
6606 variables in "x", then these are replaced by the "w_i":
6607 ? substvec([x,y], [x,y], [y,x])
6609 %1 = [y, x]
6610 ? substvec([x,y], [x,y], [y,x+y])
6611 %2 = [y, x + y] \\ not [y, 2*y]
6612 The library syntax is gsubstvec"(x,v,w)".
6614 taylor"(x,y)"
6616 Taylor expansion around 0 of "x" with respect to the simple variable
6617 "y". "x" can be of any reasonable type, for example a rational
6618 function. The number of terms of the expansion is transparent to the
6619 user in GP, but must be given as a second argument in library mode.
6620 The library syntax is tayl"(x,y,n)", where the "long" integer "n" is
6622 the desired number of terms in the expansion.
6623 thue"(tnf,a,{sol})"
6625 solves the equation "P(x,y) = a" in integers "x" and "y", where tnf was
6626 created with thueinit(P). sol, if present, contains the solutions of
6627 "\Norm(x) = a" modulo units of positive norm in the number field
6628 defined by "P" (as computed by "bnfisintnorm"). If the result is
6629 conditional (on the GRH or some heuristic strenghtening), a Warning is
6630 printed. Otherwise, the result is unconditional, barring bugs. For
6631 instance, here's how to solve the Thue equation "x^{13} - 5y^{13} = -
6632 4":
6633 ? tnf = thueinit(x^13 - 5);
6635 ? thue(tnf, -4)
6636 %1 = [[1, 1]]
6637 Hence, the only solution is "x = 1", "y = 1" and the result is
6639 unconditional. On the other hand:
6640 ? tnf = thueinit(x^3-2*x^2+3*x-17);
6642 ? thue(tnf, -15)
6643 *** thue: Warning: Non trivial conditional class group.
6644 *** May miss solutions of the norm equation.
6645 %2 = [[1, 1]]
6646 This time the result is conditional. All results computed using this
6648 tnf are likewise conditional, \emph{except} for a right-hand side of
6649 "+- 1".
6650 The library syntax is thue"(tnf,a,sol)", where an omitted sol is coded
6652 as "NULL".
6653 thueinit"(P,{flag = 0})"
6655 initializes the tnf corresponding to "P". It is meant to be used in
6656 conjunction with "thue" to solve Thue equations "P(x,y) = a", where "a"
6657 is an integer. If "flag" is non-zero, certify the result
6658 unconditionnally. Otherwise, assume GRH, this being much faster of
6659 course.
6660 \emph{If} the conditional computed class group is trivial \emph{or} you
6662 are only interested in the case "a = +-1", then results are
6663 unconditional anyway. So one should only use the flag is "thue" prints
6664 a Warning (see the example there).
6665 The library syntax is thueinit"(P,flag,prec)".
6667
6669 Note that most linear algebra functions operating on subspaces defined
6670 by generating sets (such as "mathnf", "qflll", etc.) take matrices as
6671 arguments. As usual, the generating vectors are taken to be the
6672 \emph{columns} of the given matrix.
6673 Since PARI does not have a strong typing system, scalars live in
6675 unspecified commutative base rings. It is very difficult to write
6676 robust linear algebra routines in such a general setting. The
6677 developpers's choice has been to assume the base ring is a domain and
6678 work over its field of fractions. If the base ring is \emph{not} a
6679 domain, one gets an error as soon as a non-zero pivot turns out to be
6680 non-invertible. Some functions, e.g. "mathnf" or "mathnfmod",
6681 specifically assume the base ring is Z.
6682 algdep"(x,k,{flag = 0})"
6684 "x" being real/complex, or "p"-adic, finds a polynomial of degree at
6685 most "k" with integer coefficients having "x" as approximate root.
6686 Note that the polynomial which is obtained is not necessarily the
6687 ``correct'' one. In fact it is not even guaranteed to be irreducible.
6688 One can check the closeness either by a polynomial evaluation (use
6689 "subst"), or by computing the roots of the polynomial given by "algdep"
6690 (use "polroots").
6691 Internally, "lindep""([1,x,...,x^k], flag)" is used. If "lindep" is not
6693 able to find a relation and returns a lower bound for the sup norm of
6694 the smallest relation, "algdep" returns that bound instead. A suitable
6695 non-zero value of "flag" may improve on the default behaviour:
6696 \\\\\\\\\ LLL
6698 ? \p200
6699 ? algdep(2^(1/6)+3^(1/5), 30); \\ wrong in 3.8s
6700 ? algdep(2^(1/6)+3^(1/5), 30, 100); \\ wrong in 1s
6701 ? algdep(2^(1/6)+3^(1/5), 30, 170); \\ right in 3.3s
6702 ? algdep(2^(1/6)+3^(1/5), 30, 200); \\ wrong in 2.9s
6703 ? \p250
6704 ? algdep(2^(1/6)+3^(1/5), 30); \\ right in 2.8s
6705 ? algdep(2^(1/6)+3^(1/5), 30, 200); \\ right in 3.4s
6706 \\\\\\\\\ PSLQ
6707 ? \p200
6708 ? algdep(2^(1/6)+3^(1/5), 30, -3); \\ failure in 14s.
6709 ? \p250
6710 ? algdep(2^(1/6)+3^(1/5), 30, -3); \\ right in 18s
6711 Proceeding by increments of 5 digits of accuracy, "algdep" with default
6713 flag produces its first correct result at 205 digits, and from then on
6714 a steady stream of correct results. Interestingly enough, our PSLQ also
6715 reliably succeeds from 205 digits on (and is 5 times slower at that
6716 accuracy).
6717 The above example is the testcase studied in a 2000 paper by Borwein
6719 and Lisonek, Applications of integer relation algorithms,
6720 \emph{Discrete Math.}, 217, p. 65--82. The paper conludes in the
6721 superiority of the PSLQ algorithm, which either shows that PARI's
6722 implementation of PSLQ is lacking, or that its LLL is extremely good.
6723 The version of PARI tested there was 1.39, which succeeded reliably
6724 from precision 265 on, in about 60 as much time as the current version.
6725 The library syntax is algdep0"(x,k,flag,prec)", where "k" and "flag"
6727 are "long"s. Also available is " algdep(x,k,prec)" ("flag = 0").
6728 charpoly"(A,{v = x},{flag = 0})"
6730 characteristic polynomial of "A" with respect to the variable "v",
6731 i.e. determinant of "v*I-A" if "A" is a square matrix. If "A" is not a
6732 square matrix, it returns the characteristic polynomial of the map
6733 ``multiplication by "A"'' if "A" is a scalar, in particular a polmod.
6734 E.g. "charpoly(I) = x^2+1".
6735 The value of "flag" is only significant for matrices.
6737 If "flag = 0", the method used is essentially the same as for computing
6739 the adjoint matrix, i.e. computing the traces of the powers of "A".
6740 If "flag = 1", uses Lagrange interpolation which is almost always
6742 slower.
6743 If "flag = 2", uses the Hessenberg form. This is faster than the
6745 default when the coefficients are intmod a prime or real numbers, but
6746 is usually slower in other base rings.
6747 The library syntax is charpoly0"(A,v,flag)", where "v" is the variable
6749 number. Also available are the functions " caract(A,v)" ("flag = 1"), "
6750 carhess(A,v)" ("flag = 2"), and " caradj(A,v,pt)" where, in this last
6751 case, pt is a "GEN*" which, if not equal to "NULL", will receive the
6752 address of the adjoint matrix of "A" (see "matadjoint"), so both can be
6753 obtained at once.
6754 concat"(x,{y})"
6756 concatenation of "x" and "y". If "x" or "y" is not a vector or matrix,
6757 it is considered as a one-dimensional vector. All types are allowed for
6758 "x" and "y", but the sizes must be compatible. Note that matrices are
6759 concatenated horizontally, i.e. the number of rows stays the same.
6760 Using transpositions, it is easy to concatenate them vertically.
6761 To concatenate vectors sideways (i.e. to obtain a two-row or two-column
6763 matrix), use "Mat" instead (see the example there). Concatenating a row
6764 vector to a matrix having the same number of columns will add the row
6765 to the matrix (top row if the vector is "x", i.e. comes first, and
6766 bottom row otherwise).
6767 The empty matrix "[;]" is considered to have a number of rows
6769 compatible with any operation, in particular concatenation. (Note that
6770 this is definitely \emph{not} the case for empty vectors "[ ]" or
6771 "[ ]~".)
6772 If "y" is omitted, "x" has to be a row vector or a list, in which case
6774 its elements are concatenated, from left to right, using the above
6775 rules.
6776 ? concat([1,2], [3,4])
6778 %1 = [1, 2, 3, 4]
6779 ? a = [[1,2]~, [3,4]~]; concat(a)
6780 %2 =
6781 [1 3]
6782 [2 4]
6784 ? concat([1,2; 3,4], [5,6]~)
6786 %3 =
6787 [1 2 5]
6788 [3 4 6]
6790 ? concat([%, [7,8]~, [1,2,3,4]])
6791 %5 =
6792 [1 2 5 7]
6793 [3 4 6 8]
6795 [1 2 3 4]
6797 The library syntax is concat"(x,y)".
6799 lindep"(x,{flag = 0})"
6801 "x" being a vector with "p"-adic or real/complex coefficients, finds a
6802 small integral linear combination among these coefficients.
6803 If "x" is "p"-adic, "flag" is meaningless and the algorithm LLL-reduces
6805 a suitable (dual) lattice.
6806 Otherwise, the value of "flag" determines the algorithm used; in the
6808 current version of PARI, we suggest to use \emph{non-negative} values,
6809 since it is by far the fastest and most robust implementation. See the
6810 detailed example in "Label se:algdep" ("algdep").
6811 If "flag >= 0", uses a floating point (variable precision) LLL
6813 algorithm. This is in general much faster than the other variants. If
6814 "flag = 0" the accuracy is chosen internally using a crude heuristic.
6815 If "flag > 0" the computation is done with an accuracy of "flag"
6816 decimal digits. In that case, the parameter "flag" should be between
6817 0.6 and 0.9 times the number of correct decimal digits in the input.
6818 If "flag = -1", uses a variant of the LLL algorithm due to Hastad,
6820 Lagarias and Schnorr (STACS 1986). If the precision is too low, the
6821 routine may enter an infinite loop.
6822 If "flag = -2", "x" is allowed to be (and in any case interpreted as) a
6824 matrix. Returns a non trivial element of the kernel of "x", or 0 if
6825 "x" has trivial kernel. The element is defined over the field of
6826 coefficients of "x", and is in general not integral.
6827 If "flag = -3", uses the PSLQ algorithm. This may return a real number
6829 "B", indicating that the input accuracy was exhausted and that no
6830 relation exist whose sup norm is less than "B".
6831 If "flag = -4", uses an experimental 2-level PSLQ, which does not work
6833 at all. (Should be rewritten.)
6834 The library syntax is lindep0"(x,flag,prec)". Also available is "
6836 lindep(x,prec)" ("flag = 0").
6837 listcreate"(n)"
6839 creates an empty list of maximal length "n".
6840 This function is useless in library mode.
6842 listinsert"(list,x,n)"
6844 inserts the object "x" at position "n" in list (which must be of type
6845 "t_LIST"). All the remaining elements of list (from position "n+1"
6846 onwards) are shifted to the right. This and "listput" are the only
6847 commands which enable you to increase a list's effective length (as
6848 long as it remains under the maximal length specified at the time of
6849 the "listcreate").
6850 This function is useless in library mode.
6852 listkill"(list)"
6854 kill list. This deletes all elements from list and sets its effective
6855 length to 0. The maximal length is not affected.
6856 This function is useless in library mode.
6858 listput"(list,x,{n})"
6860 sets the "n"-th element of the list list (which must be of type
6861 "t_LIST") equal to "x". If "n" is omitted, or greater than the list
6862 current effective length, just appends "x". This and "listinsert" are
6863 the only commands which enable you to increase a list's effective
6864 length (as long as it remains under the maximal length specified at the
6865 time of the "listcreate").
6866 If you want to put an element into an occupied cell, i.e. if you don't
6868 want to change the effective length, you can consider the list as a
6869 vector and use the usual "list[n] = x" construct.
6870 This function is useless in library mode.
6872 listsort"(list,{flag = 0})"
6874 sorts list (which must be of type "t_LIST") in place. If "flag" is non-
6875 zero, suppresses all repeated coefficients. This is much faster than
6876 the "vecsort" command since no copy has to be made.
6877 This function is useless in library mode.
6879 matadjoint"(x)"
6881 adjoint matrix of "x", i.e. the matrix "y" of cofactors of "x",
6882 satisfying "x*y = det (x)*\Id". "x" must be a (non-necessarily
6883 invertible) square matrix.
6884 The library syntax is adj"(x)".
6886 matcompanion"(x)"
6888 the left companion matrix to the polynomial "x".
6889 The library syntax is assmat"(x)".
6891 matdet"(x,{flag = 0})"
6893 determinant of "x". "x" must be a square matrix.
6894 If "flag = 0", uses Gauss-Bareiss.
6896 If "flag = 1", uses classical Gaussian elimination, which is better
6898 when the entries of the matrix are reals or integers for example, but
6899 usually much worse for more complicated entries like multivariate
6900 polynomials.
6901 The library syntax is det"(x)" ("flag = 0") and " det2(x)" ("flag =
6903 1").
6904 matdetint"(x)"
6906 "x" being an "m x n" matrix with integer coefficients, this function
6907 computes a \emph{multiple} of the determinant of the lattice generated
6908 by the columns of "x" if it is of rank "m", and returns zero otherwise.
6909 This function can be useful in conjunction with the function
6910 "mathnfmod" which needs to know such a multiple. To obtain the exact
6911 determinant (assuming the rank is maximal), you can compute
6912 "matdet(mathnfmod(x, matdetint(x)))".
6913 Note that as soon as one of the dimensions gets large ("m" or "n" is
6915 larger than 20, say), it will often be much faster to use "mathnf(x,
6916 1)" or "mathnf(x, 4)" directly.
6917 The library syntax is detint"(x)".
6919 matdiagonal"(x)"
6921 "x" being a vector, creates the diagonal matrix whose diagonal entries
6922 are those of "x".
6923 The library syntax is diagonal"(x)".
6925 mateigen"(x)"
6927 gives the eigenvectors of "x" as columns of a matrix.
6928 The library syntax is eigen"(x)".
6930 matfrobenius"(M,{flag = 0},{v = x})"
6932 returns the Frobenius form of the square matrix "M". If "flag = 1",
6933 returns only the elementary divisors as a vectr of polynomials in the
6934 variable "v". If "flag = 2", returns a two-components vector [F,B]
6935 where "F" is the Frobenius form and "B" is the basis change so that "M
6936 = B^{-1}FB".
6937 The library syntax is matfrobenius"(M,flag,v)", where "v" is the
6939 variable number.
6940 mathess"(x)"
6942 Hessenberg form of the square matrix "x".
6943 The library syntax is hess"(x)".
6945 mathilbert"(x)"
6947 "x" being a "long", creates the Hilbert matrixof order "x", i.e. the
6948 matrix whose coefficient ("i","j") is "1/ (i+j-1)".
6949 The library syntax is mathilbert"(x)".
6951 mathnf"(x,{flag = 0})"
6953 if "x" is a (not necessarily square) matrix with integer entries, finds
6954 the \emph{upper triangular} Hermite normal form of "x". If the rank of
6955 "x" is equal to its number of rows, the result is a square matrix. In
6956 general, the columns of the result form a basis of the lattice spanned
6957 by the columns of "x".
6958 If "flag = 0", uses the naive algorithm. This should never be used if
6960 the dimension is at all large (larger than 10, say). It is recommanded
6961 to use either "mathnfmod(x, matdetint(x))" (when "x" has maximal rank)
6962 or "mathnf(x, 1)". Note that the latter is in general faster than
6963 "mathnfmod", and also provides a base change matrix.
6964 If "flag = 1", uses Batut's algorithm, which is much faster than the
6966 default. Outputs a two-component row vector "[H,U]", where "H" is the
6967 \emph{upper triangular} Hermite normal form of "x" defined as above,
6968 and "U" is the unimodular transformation matrix such that "xU = [0|H]".
6969 "U" has in general huge coefficients, in particular when the kernel is
6970 large.
6971 If "flag = 3", uses Batut's algorithm, but outputs "[H,U,P]", such that
6973 "H" and "U" are as before and "P" is a permutation of the rows such
6974 that "P" applied to "xU" gives "H". The matrix "U" is smaller than with
6975 "flag = 1", but may still be large.
6976 If "flag = 4", as in case 1 above, but uses a heuristic variant of LLL
6978 reduction along the way. The matrix "U" is in general close to optimal
6979 (in terms of smallest "L_2" norm), but the reduction is slower than in
6980 case 1.
6981 The library syntax is mathnf0"(x,flag)". Also available are " hnf(x)"
6983 ("flag = 0") and " hnfall(x)" ("flag = 1"). To reduce \emph{huge} (say
6984 "400 x 400" and more) relation matrices (sparse with small entries),
6985 you can use the pair "hnfspec" / "hnfadd". Since this is rather
6986 technical and the calling interface may change, they are not documented
6987 yet. Look at the code in "basemath/alglin1.c".
6988 mathnfmod"(x,d)"
6990 if "x" is a (not necessarily square) matrix of maximal rank with
6991 integer entries, and "d" is a multiple of the (non-zero) determinant of
6992 the lattice spanned by the columns of "x", finds the \emph{upper
6993 triangular} Hermite normal form of "x".
6994 If the rank of "x" is equal to its number of rows, the result is a
6996 square matrix. In general, the columns of the result form a basis of
6997 the lattice spanned by the columns of "x". This is much faster than
6998 "mathnf" when "d" is known.
6999 The library syntax is hnfmod"(x,d)".
7001 mathnfmodid"(x,d)"
7003 outputs the (upper triangular) Hermite normal form of "x" concatenated
7004 with "d" times the identity matrix. Assumes that "x" has integer
7005 entries.
7006 The library syntax is hnfmodid"(x,d)".
7008 matid"(n)"
7010 creates the "n x n" identity matrix.
7011 The library syntax is matid"(n)" where "n" is a "long".
7013 Related functions are " gscalmat(x,n)", which creates "x" times the
7015 identity matrix ("x" being a "GEN" and "n" a "long"), and "
7016 gscalsmat(x,n)" which is the same when "x" is a "long".
7017 matimage"(x,{flag = 0})"
7019 gives a basis for the image of the matrix "x" as columns of a matrix. A
7020 priori the matrix can have entries of any type. If "flag = 0", use
7021 standard Gauss pivot. If "flag = 1", use "matsupplement".
7022 The library syntax is matimage0"(x,flag)". Also available is "
7024 image(x)" ("flag = 0").
7025 matimagecompl"(x)"
7027 gives the vector of the column indices which are not extracted by the
7028 function "matimage". Hence the number of components of matimagecompl(x)
7029 plus the number of columns of matimage(x) is equal to the number of
7030 columns of the matrix "x".
7031 The library syntax is imagecompl"(x)".
7033 matindexrank"(x)"
7035 "x" being a matrix of rank "r", gives two vectors "y" and "z" of length
7036 "r" giving a list of rows and columns respectively (starting from 1)
7037 such that the extracted matrix obtained from these two vectors using
7038 "vecextract(x,y,z)" is invertible.
7039 The library syntax is indexrank"(x)".
7041 matintersect"(x,y)"
7043 "x" and "y" being two matrices with the same number of rows each of
7044 whose columns are independent, finds a basis of the Q-vector space
7045 equal to the intersection of the spaces spanned by the columns of "x"
7046 and "y" respectively. See also the function "idealintersect", which
7047 does the same for free Z-modules.
7048 The library syntax is intersect"(x,y)".
7050 matinverseimage"(M,y)"
7052 gives a column vector belonging to the inverse image "z" of the column
7053 vector or matrix "y" by the matrix "M" if one exists (i.e such that "Mz
7054 = y"), the empty vector otherwise. To get the complete inverse image,
7055 it suffices to add to the result any element of the kernel of "x"
7056 obtained for example by "matker".
7057 The library syntax is inverseimage"(x,y)".
7059 matisdiagonal"(x)"
7061 returns true (1) if "x" is a diagonal matrix, false (0) if not.
7062 The library syntax is isdiagonal"(x)", and this returns a "long"
7064 integer.
7065 matker"(x,{flag = 0})"
7067 gives a basis for the kernel of the matrix "x" as columns of a matrix.
7068 A priori the matrix can have entries of any type.
7069 If "x" is known to have integral entries, set "flag = 1".
7071 Note: The library function "FpM_ker(x, p)", where "x" has integer
7073 entries \emph{reduced mod p} and "p" is prime, is equivalent to, but
7074 orders of magnitude faster than, "matker(x*Mod(1,p))" and needs much
7075 less stack space. To use it under "gp", type "install(FpM_ker, GG)"
7076 first.
7077 The library syntax is matker0"(x,flag)". Also available are " ker(x)"
7079 ("flag = 0"), " keri(x)" ("flag = 1").
7080 matkerint"(x,{flag = 0})"
7082 gives an LLL-reduced Z-basis for the lattice equal to the kernel of the
7083 matrix "x" as columns of the matrix "x" with integer entries (rational
7084 entries are not permitted).
7085 If "flag = 0", uses a modified integer LLL algorithm.
7087 If "flag = 1", uses "matrixqz(x,-2)". If LLL reduction of the final
7089 result is not desired, you can save time using "matrixqz(matker(x),-2)"
7090 instead.
7091 The library syntax is matkerint0"(x,flag)". Also available is "
7093 kerint(x)" ("flag = 0").
7094 matmuldiagonal"(x,d)"
7096 product of the matrix "x" by the diagonal matrix whose diagonal entries
7097 are those of the vector "d". Equivalent to, but much faster than
7098 "x*matdiagonal(d)".
7099 The library syntax is matmuldiagonal"(x,d)".
7101 matmultodiagonal"(x,y)"
7103 product of the matrices "x" and "y" assuming that the result is a
7104 diagonal matrix. Much faster than "x*y" in that case. The result is
7105 undefined if "x*y" is not diagonal.
7106 The library syntax is matmultodiagonal"(x,y)".
7108 matpascal"(x,{q})"
7110 creates as a matrix the lower triangular Pascal triangle of order "x+1"
7111 (i.e. with binomial coefficients up to "x"). If "q" is given, compute
7112 the "q"-Pascal triangle (i.e. using "q"-binomial coefficients).
7113 The library syntax is matqpascal"(x,q)", where "x" is a "long" and "q =
7115 NULL" is used to omit "q". Also available is " matpascal(x)".
7116 matrank"(x)"
7118 rank of the matrix "x".
7119 The library syntax is rank"(x)", and the result is a "long".
7121 matrix"(m,n,{X},{Y},{expr = 0})"
7123 creation of the "m x n" matrix whose coefficients are given by the
7124 expression expr. There are two formal parameters in expr, the first one
7125 ("X") corresponding to the rows, the second ("Y") to the columns, and
7126 "X" goes from 1 to "m", "Y" goes from 1 to "n". If one of the last 3
7127 parameters is omitted, fill the matrix with zeroes.
7128 The library syntax is matrice"(GEN nlig,GEN ncol,entree *e1,entree
7130 *e2,char *expr)".
7131 matrixqz"(x,p)"
7133 "x" being an "m x n" matrix with "m >= n" with rational or integer
7134 entries, this function has varying behaviour depending on the sign of
7135 "p":
7136 If "p >= 0", "x" is assumed to be of maximal rank. This function
7138 returns a matrix having only integral entries, having the same image as
7139 "x", such that the GCD of all its "n x n" subdeterminants is equal to 1
7140 when "p" is equal to 0, or not divisible by "p" otherwise. Here "p"
7141 must be a prime number (when it is non-zero). However, if the function
7142 is used when "p" has no small prime factors, it will either work or
7143 give the message ``impossible inverse modulo'' and a non-trivial
7144 divisor of "p".
7145 If "p = -1", this function returns a matrix whose columns form a basis
7147 of the lattice equal to "Z^n" intersected with the lattice generated by
7148 the columns of "x".
7149 If "p = -2", returns a matrix whose columns form a basis of the lattice
7151 equal to "Z^n" intersected with the Q-vector space generated by the
7152 columns of "x".
7153 The library syntax is matrixqz0"(x,p)".
7155 matsize"(x)"
7157 "x" being a vector or matrix, returns a row vector with two components,
7158 the first being the number of rows (1 for a row vector), the second the
7159 number of columns (1 for a column vector).
7160 The library syntax is matsize"(x)".
7162 matsnf"(X,{flag = 0})"
7164 if "X" is a (singular or non-singular) matrix outputs the vector of
7165 elementary divisors of "X" (i.e. the diagonal of the Smith normal form
7166 of "X").
7167 The binary digits of flag mean:
7169 1 (complete output): if set, outputs "[U,V,D]", where "U" and "V" are
7171 two unimodular matrices such that "UXV" is the diagonal matrix "D".
7172 Otherwise output only the diagonal of "D".
7173 2 (generic input): if set, allows polynomial entries, in which case the
7175 input matrix must be square. Otherwise, assume that "X" has integer
7176 coefficients with arbitrary shape.
7177 4 (cleanup): if set, cleans up the output. This means that elementary
7179 divisors equal to 1 will be deleted, i.e. outputs a shortened vector
7180 "D'" instead of "D". If complete output was required, returns
7181 "[U',V',D']" so that "U'XV' = D'" holds. If this flag is set, "X" is
7182 allowed to be of the form "D" or "[U,V,D]" as would normally be output
7183 with the cleanup flag unset.
7184 The library syntax is matsnf0"(X,flag)". Also available is " smith(X)"
7186 ("flag = 0").
7187 matsolve"(x,y)"
7189 "x" being an invertible matrix and "y" a column vector, finds the
7190 solution "u" of "x*u = y", using Gaussian elimination. This has the
7191 same effect as, but is a bit faster, than "x^{-1}*y".
7192 The library syntax is gauss"(x,y)".
7194 matsolvemod"(m,d,y,{flag = 0})"
7196 "m" being any integral matrix, "d" a vector of positive integer moduli,
7197 and "y" an integral column vector, gives a small integer solution to
7198 the system of congruences "sum_i m_{i,j}x_j = y_i (mod d_i)" if one
7199 exists, otherwise returns zero. Shorthand notation: "y" (resp. "d") can
7200 be given as a single integer, in which case all the "y_i" (resp. "d_i")
7201 above are taken to be equal to "y" (resp. "d").
7202 ? m = [1,2;3,4];
7204 ? matsolvemod(m, [3,4], [1,2]~)
7205 %2 = [-2, 0]~
7206 ? matsolvemod(m, 3, 1) \\ m X = [1,1]~ over F_3
7207 %3 = [-1, 1]~
7208 If "flag = 1", all solutions are returned in the form of a two-
7210 component row vector "[x,u]", where "x" is a small integer solution to
7211 the system of congruences and "u" is a matrix whose columns give a
7212 basis of the homogeneous system (so that all solutions can be obtained
7213 by adding "x" to any linear combination of columns of "u"). If no
7214 solution exists, returns zero.
7215 The library syntax is matsolvemod0"(m,d,y,flag)". Also available are "
7217 gaussmodulo(m,d,y)" ("flag = 0") and " gaussmodulo2(m,d,y)" ("flag =
7218 1").
7219 matsupplement"(x)"
7221 assuming that the columns of the matrix "x" are linearly independent
7222 (if they are not, an error message is issued), finds a square
7223 invertible matrix whose first columns are the columns of "x",
7224 i.e. supplement the columns of "x" to a basis of the whole space.
7225 The library syntax is suppl"(x)".
7227 mattranspose"(x)" or "x~"
7229 transpose of "x". This has an effect only on vectors and matrices.
7230 The library syntax is gtrans"(x)".
7232 minpoly"(A,{v = x},{flag = 0})"
7234 minimal polynomial of "A" with respect to the variable "v"., i.e. the
7235 monic polynomial "P" of minimal degree (in the variable "v") such that
7236 "P(A) = 0".
7237 The library syntax is minpoly"(A,v)", where "v" is the variable number.
7239 qfgaussred"(q)"
7241 decomposition into squares of the quadratic form represented by the
7242 symmetric matrix "q". The result is a matrix whose diagonal entries are
7243 the coefficients of the squares, and the non-diagonal entries represent
7244 the bilinear forms. More precisely, if "(a_{ij})" denotes the output,
7245 one has
7246 " q(x) = sum_i a_{ii} (x_i + sum_{j > i} a_{ij} x_j)^2 "
7248 The library syntax is sqred"(x)".
7250 qfjacobi"(x)"
7252 "x" being a real symmetric matrix, this gives a vector having two
7253 components: the first one is the vector of eigenvalues of "x", the
7254 second is the corresponding orthogonal matrix of eigenvectors of "x".
7255 The method used is Jacobi's method for symmetric matrices.
7256 The library syntax is jacobi"(x)".
7258 qflll"(x,{flag = 0})"
7260 LLL algorithm applied to the \emph{columns} of the matrix "x". The
7261 columns of "x" must be linearly independent, unless specified otherwise
7262 below. The result is a unimodular transformation matrix "T" such that
7263 "x.T" is an LLL-reduced basis of the lattice generated by the column
7264 vectors of "x".
7265 If "flag = 0" (default), the computations are done with floating point
7267 numbers, using Householder matrices for orthogonalization. If "x" has
7268 integral entries, then computations are nonetheless approximate, with
7269 precision varying as needed (Lehmer's trick, as generalized by
7270 Schnorr).
7271 If "flag = 1", it is assumed that "x" is integral. The computation is
7273 done entirely with integers. In this case, "x" needs not be of maximal
7274 rank, but if it is not, "T" will not be square. This is slower and no
7275 more accurate than "flag = 0" above if "x" has small dimension (say 100
7276 or less).
7277 If "flag = 2", "x" should be an integer matrix whose columns are
7279 linearly independent. Returns a partially reduced basis for "x", using
7280 an unpublished algorithm by Peter Montgomery: a basis is said to be
7281 \emph{partially reduced} if "|v_i +- v_j| >= |v_i|" for any two
7282 distinct basis vectors "v_i, v_j".
7283 This is significantly faster than "flag = 1", esp. when one row is huge
7285 compared to the other rows. Note that the resulting basis is \emph{not}
7286 LLL-reduced in general.
7287 If "flag = 4", "x" is assumed to have integral entries, but needs not
7289 be of maximal rank. The result is a two-component vector of matrices:
7290 the columns of the first matrix represent a basis of the integer kernel
7291 of "x" (not necessarily LLL-reduced) and the second matrix is the
7292 transformation matrix "T" such that "x.T" is an LLL-reduced Z-basis of
7293 the image of the matrix "x".
7294 If "flag = 5", case as case 4, but "x" may have polynomial
7296 coefficients.
7297 If "flag = 8", same as case 0, but "x" may have polynomial
7299 coefficients.
7300 The library syntax is qflll0"(x,flag,prec)". Also available are "
7302 lll(x,prec)" ("flag = 0"), " lllint(x)" ("flag = 1"), and "
7303 lllkerim(x)" ("flag = 4").
7304 qflllgram"(G,{flag = 0})"
7306 same as "qflll", except that the matrix "G = x~ * x" is the Gram matrix
7307 of some lattice vectors "x", and not the coordinates of the vectors
7308 themselves. In particular, "G" must now be a square symmetric real
7309 matrix, corresponding to a positive definite quadratic form. The result
7310 is a unimodular transformation matrix "T" such that "x.T" is an LLL-
7311 reduced basis of the lattice generated by the column vectors of "x".
7312 If "flag = 0" (default): the computations are done with floating point
7314 numbers, using Householder matrices for orthogonalization. If "G" has
7315 integral entries, then computations are nonetheless approximate, with
7316 precision varying as needed (Lehmer's trick, as generalized by
7317 Schnorr).
7318 If "flag = 1": "G" has integer entries, still positive but not
7320 necessarily definite (i.e "x" needs not have maximal rank). The
7321 computations are all done in integers and should be slower than the
7322 default, unless the latter triggers accuracy problems.
7323 "flag = 4": "G" has integer entries, gives the kernel and reduced image
7325 of "x".
7326 "flag = 5": same as case 4, but "G" may have polynomial coefficients.
7328 The library syntax is qflllgram0"(G,flag,prec)". Also available are "
7330 lllgram(G,prec)" ("flag = 0"), " lllgramint(G)" ("flag = 1"), and "
7331 lllgramkerim(G)" ("flag = 4").
7332 qfminim"(x,{b},{m},{flag = 0})"
7334 "x" being a square and symmetric matrix representing a positive
7335 definite quadratic form, this function deals with the vectors of "x"
7336 whose norm is less than or equal to "b", enumerated using the Fincke-
7337 Pohst algorithm. The function searches for the minimal non-zero vectors
7338 if "b" is omitted. The precise behaviour depends on "flag".
7339 If "flag = 0" (default), seeks at most "2m" vectors. The result is a
7341 three-component vector, the first component being the number of vectors
7342 found, the second being the maximum norm found, and the last vector is
7343 a matrix whose columns are the vectors found, only one being given for
7344 each pair "+- v" (at most "m" such pairs). The vectors are returned in
7345 no particular order. In this variant, an explicit "m" must be provided.
7346 If "flag = 1", ignores "m" and returns the first vector whose norm is
7348 less than "b". In this variant, an explicit "b" must be provided.
7349 In both these cases, "x" is assumed to have integral entries. The
7351 implementation uses low precision floating point computations for
7352 maximal speed, which gives incorrect result when "x" has large entries.
7353 (The condition is checked in the code and the routine will raise an
7354 error if large rounding errors occur.) A more robust, but much slower,
7355 implementation is chosen if the following flag is used:
7356 If "flag = 2", "x" can have non integral real entries. In this case, if
7358 "b" is omitted, the ``minimal'' vectors only have approximately the
7359 same norm. If "b" is omitted, "m" is an upper bound for the number of
7360 vectors that will be stored and returned, but all minimal vectors are
7361 nevertheless enumerated. If "m" is omitted, all vectors found are
7362 stored and returned; note that this may be a huge vector!
7363 The library syntax is qfminim0"(x,b,m,flag,prec)", also available are "
7365 minim(x,b,m)" ("flag = 0"), " minim2(x,b,m)" ("flag = 1"). In all
7366 cases, an omitted "b" or "m" is coded as "NULL".
7367 qfperfection"(x)"
7369 "x" being a square and symmetric matrix with integer entries
7370 representing a positive definite quadratic form, outputs the perfection
7371 rank of the form. That is, gives the rank of the family of the "s"
7372 symmetric matrices "v_iv_i^t", where "s" is half the number of minimal
7373 vectors and the "v_i" ("1 <= i <= s") are the minimal vectors.
7374 As a side note to old-timers, this used to fail bluntly when "x" had
7376 more than 5000 minimal vectors. Beware that the computations can now be
7377 very lengthy when "x" has many minimal vectors.
7378 The library syntax is perf"(x)".
7380 qfrep"(q, B, {flag = 0})"
7382 "q" being a square and symmetric matrix with integer entries
7383 representing a positive definite quadratic form, outputs the vector
7384 whose "i"-th entry, "1 <= i <= B" is half the number of vectors "v"
7385 such that "q(v) = i". This routine uses a naive algorithm based on
7386 "qfminim", and will fail if any entry becomes larger than "2^{31}".
7387 The binary digits of flag mean:
7389 \item 1: count vectors of even norm from 1 to "2B".
7391 \item 2: return a "t_VECSMALL" instead of a "t_GEN"
7393 The library syntax is qfrep0"(q, B, flag)".
7395 qfsign"(x)"
7397 signature of the quadratic form represented by the symmetric matrix
7398 "x". The result is a two-component vector.
7399 The library syntax is signat"(x)".
7401 setintersect"(x,y)"
7403 intersection of the two sets "x" and "y".
7404 The library syntax is setintersect"(x,y)".
7406 setisset"(x)"
7408 returns true (1) if "x" is a set, false (0) if not. In PARI, a set is
7409 simply a row vector whose entries are strictly increasing. To convert
7410 any vector (and other objects) into a set, use the function "Set".
7411 The library syntax is setisset"(x)", and this returns a "long".
7413 setminus"(x,y)"
7415 difference of the two sets "x" and "y", i.e. set of elements of "x"
7416 which do not belong to "y".
7417 The library syntax is setminus"(x,y)".
7419 setsearch"(x,y,{flag = 0})"
7421 searches if "y" belongs to the set "x". If it does and "flag" is zero
7422 or omitted, returns the index "j" such that "x[j] = y", otherwise
7423 returns 0. If "flag" is non-zero returns the index "j" where "y" should
7424 be inserted, and 0 if it already belongs to "x" (this is meant to be
7425 used in conjunction with "listinsert").
7426 This function works also if "x" is a \emph{sorted} list (see
7428 "listsort").
7429 The library syntax is setsearch"(x,y,flag)" which returns a "long"
7431 integer.
7432 setunion"(x,y)"
7434 union of the two sets "x" and "y".
7435 The library syntax is setunion"(x,y)".
7437 trace"(x)"
7439 this applies to quite general "x". If "x" is not a matrix, it is equal
7440 to the sum of "x" and its conjugate, except for polmods where it is the
7441 trace as an algebraic number.
7442 For "x" a square matrix, it is the ordinary trace. If "x" is a non-
7444 square matrix (but not a vector), an error occurs.
7445 The library syntax is gtrace"(x)".
7447 vecextract"(x,y,{z})"
7449 extraction of components of the vector or matrix "x" according to "y".
7450 In case "x" is a matrix, its components are as usual the \emph{columns}
7451 of "x". The parameter "y" is a component specifier, which is either an
7452 integer, a string describing a range, or a vector.
7453 If "y" is an integer, it is considered as a mask: the binary bits of
7455 "y" are read from right to left, but correspond to taking the
7456 components from left to right. For example, if "y = 13 = (1101)_2" then
7457 the components 1,3 and 4 are extracted.
7458 If "y" is a vector, which must have integer entries, these entries
7460 correspond to the component numbers to be extracted, in the order
7461 specified.
7462 If "y" is a string, it can be
7464 \item a single (non-zero) index giving a component number (a negative
7466 index means we start counting from the end).
7467 \item a range of the form "a..b", where "a" and "b" are indexes as
7469 above. Any of "a" and "b" can be omitted; in this case, we take as
7470 default values "a = 1" and "b = -1", i.e. the first and last components
7471 respectively. We then extract all components in the interval "[a,b]",
7472 in reverse order if "b < a".
7473 In addition, if the first character in the string is "^", the
7475 complement of the given set of indices is taken.
7476 If "z" is not omitted, "x" must be a matrix. "y" is then the
7478 \emph{line} specifier, and "z" the \emph{column} specifier, where the
7479 component specifier is as explained above.
7480 %4 = [e, d, c]
7482 ? vecextract(v, "^2") \\ mask
7483 %4 = [e, d, c]
7484 ? vecextract(v, "^2") \\ component list
7485 %4 = [e, d, c]
7486 ? vecextract(v, "^2") \\ interval
7487 %4 = [e, d, c]
7488 ? vecextract(v, "^2") \\ interval + reverse order
7489 %4 = [e, d, c]
7490 ? vecextract(v, "^2") \\ complement
7491 %5 = [a, c, d, e]
7492 ? vecextract(matid(3), "2..", "..")
7493 %6 =
7494 [0 1 0]
7495 [0 0 1]
7497 The library syntax is extract"(x,y)" or " matextract(x,y,z)".
7499 vecsort"(x,{k},{flag = 0})"
7501 sorts the vector "x" in ascending order, using a mergesort method. "x"
7502 must be a vector, and its components integers, reals, or fractions.
7503 If "k" is present and is an integer, sorts according to the value of
7505 the "k"-th subcomponents of the components of "x". Note that mergesort
7506 is stable, hence is the initial ordering of "equal" entries (with
7507 respect to the sorting criterion) is not changed.
7508 "k" can also be a vector, in which case the sorting is done
7510 lexicographically according to the components listed in the vector "k".
7511 For example, if "k = [2,1,3]", sorting will be done with respect to the
7512 second component, and when these are equal, with respect to the first,
7513 and when these are equal, with respect to the third.
7514 The binary digits of flag mean:
7516 \item 1: indirect sorting of the vector "x", i.e. if "x" is an
7518 "n"-component vector, returns a permutation of "[1,2,...,n]" which
7519 applied to the components of "x" sorts "x" in increasing order. For
7520 example, "vecextract(x, vecsort(x,,1))" is equivalent to vecsort(x).
7521 \item 2: sorts "x" by ascending lexicographic order (as per the "lex"
7523 comparison function).
7524 \item 4: use descending instead of ascending order.
7526 The library syntax is vecsort0"(x,k,flag)". To omit "k", use "NULL"
7528 instead. You can also use the simpler functions
7529 " sort(x)" ( = " vecsort0(x,NULL,0)").
7531 " indexsort(x)" ( = " vecsort0(x,NULL,1)").
7533 " lexsort(x)" ( = " vecsort0(x,NULL,2)").
7535 Also available are " sindexsort(x)" and " sindexlexsort(x)" which
7537 return a "t_VECSMALL" "v", where "v[1]...v[n]" contain the indices.
7538 vector"(n,{X},{expr = 0})"
7540 creates a row vector (type "t_VEC") with "n" components whose
7541 components are the expression expr evaluated at the integer points
7542 between 1 and "n". If one of the last two arguments is omitted, fill
7543 the vector with zeroes.
7544 Avoid modifying "X" within expr; if you do, the formal variable still
7546 runs from 1 to "n". In particular, "vector(n,i,expr)" is not equivalent
7547 to
7548 v = vector(n)
7550 for (i = 1, n, v[i] = expr)
7551 as the following example shows:
7553 n = 3
7555 v = vector(n); vector(n, i, i++) ----> [2, 3, 4]
7556 v = vector(n); for (i = 1, n, v[i] = i++) ----> [2, 0, 4]
7557 The library syntax is vecteur"(GEN nmax, entree *ep, char *expr)".
7559 vectorsmall"(n,{X},{expr = 0})"
7561 creates a row vector of small integers (type "t_VECSMALL") with "n"
7562 components whose components are the expression expr evaluated at the
7563 integer points between 1 and "n". If one of the last two arguments is
7564 omitted, fill the vector with zeroes.
7565 The library syntax is vecteursmall"(GEN nmax, entree *ep, char *expr)".
7567 vectorv"(n,X,expr)"
7569 as "vector", but returns a column vector (type "t_COL").
7570 The library syntax is vvecteur"(GEN nmax, entree *ep, char *expr)".
7572
7574 Although the "gp" calculator is programmable, it is useful to have
7575 preprogrammed a number of loops, including sums, products, and a
7576 certain number of recursions. Also, a number of functions from
7577 numerical analysis like numerical integration and summation of series
7578 will be described here.
7579 One of the parameters in these loops must be the control variable,
7581 hence a simple variable name. In the descriptions, the letter "X" will
7582 always denote any simple variable name, and represents the formal
7583 parameter used in the function. The expression to be summed,
7584 integrated, etc. is any legal PARI expression, including of course
7585 expressions using loops.
7586 Library mode. Since it is easier to program directly the loops in
7588 library mode, these functions are mainly useful for GP programming.
7589 Using them in library mode is tricky and we will not give any details,
7590 although the reader can try and figure it out by himself by checking
7591 the example given for "sum".
7592 On the other hand, numerical routines code a function (to be
7594 integrated, summed, etc.) with two parameters named
7595 GEN (*eval)(GEN,void*)
7597 void *E;
7598 The second is meant to contain all auxilliary data needed by your
7600 function. The first is such that "eval(x, E)" returns your function
7601 evaluated at "x". For instance, one may code the family of functions
7602 "f_t: x \to (x+t)^2" via
7603 GEN f(GEN x, void *t) { return gsqr(gadd(x, (GEN)t)); }
7605 One can then integrate "f_1" between "a" and "b" with the call
7607 intnum((void*)stoi(1), &fun, a, b, NULL, prec);
7609 Since you can set "E" to a pointer to any "struct" (typecast to
7611 "void*") the above mechanism handles arbitrary functions. For simple
7612 functions without extra parameters, you may set "E = NULL" and ignore
7613 that argument in your function definition.
7614 Numerical integration. Starting with version 2.2.9 the powerful
7616 ``double exponential'' univariate integration method is implemented in
7617 "intnum" and its variants. Romberg integration is still available under
7618 the name "intnumromb", but superseded. It is possible to compute
7619 numerically integrals to thousands of decimal places in reasonable
7620 time, as long as the integrand is regular. It is also reasonable to
7621 compute numerically integrals in several variables, although more than
7622 two becomes lengthy. The integration domain may be non-compact, and the
7623 integrand may have reasonable singularities at endpoints. To use
7624 "intnum", the user must split the integral into a sum of subintegrals
7625 where the function has (possible) singularities only at the endpoints.
7626 Polynomials in logarithms are not considered singular, and neglecting
7627 these logs, singularities are assumed to be algebraic (in other words
7628 asymptotic to "C(x-a)^{-alpha}" for some "alpha" such that "alpha > -1"
7629 when "x" is close to "a"), or to correspond to simple discontinuities
7630 of some (higher) derivative of the function. For instance, the point 0
7631 is a singularity of abs(x).
7632 See also the discrete summation methods below (sharing the prefix
7634 "sum").
7635 intcirc"(X = a,R,expr, {tab})"
7637 numerical integration of expr with respect to "X" on the circle "|X-a
7638 |= R", divided by "2iPi". In other words, when expr is a meromorphic
7639 function, sum of the residues in the corresponding disk. tab is as in
7640 "intnum", except that if computed with "intnuminit" it should be with
7641 the endpoints "[-1, 1]".
7642 ? \p105
7644 ? intcirc(s=1, 0.5, zeta(s)) - 1
7645 time = 3,460 ms.
7646 %1 = -2.40... E-104 - 2.7... E-106*I
7647 The library syntax is intcirc"(void *E, GEN (*eval)(GEN,void*), GEN
7649 a,GEN R,GEN tab, long prec)".
7650 intfouriercos"(X = a,b,z,expr,{tab})"
7652 numerical integration of "expr(X) cos (2Pi zX)" from "a" to "b", in
7653 other words Fourier cosine transform (from "a" to "b") of the function
7654 represented by expr. "a" and "b" are coded as in "intnum", and are not
7655 necessarily at infinity, but if they are, oscillations (i.e.
7656 "[[+-1],alpha I]") are forbidden.
7657 The library syntax is intfouriercos"(void *E, GEN (*eval)(GEN,void*),
7659 GEN a, GEN b, GEN z, GEN tab, long prec)".
7660 intfourierexp"(X = a,b,z,expr,{tab})"
7662 numerical integration of "expr(X) exp (-2Pi zX)" from "a" to "b", in
7663 other words Fourier transform (from "a" to "b") of the function
7664 represented by expr. Note the minus sign. "a" and "b" are coded as in
7665 "intnum", and are not necessarily at infinity but if they are,
7666 oscillations (i.e. "[[+-1],alpha I]") are forbidden.
7667 The library syntax is intfourierexp"(void *E, GEN (*eval)(GEN,void*),
7669 GEN a, GEN b, GEN z, GEN tab, long prec)".
7670 intfouriersin"(X = a,b,z,expr,{tab})"
7672 numerical integration of "expr(X) sin (2Pi zX)" from "a" to "b", in
7673 other words Fourier sine transform (from "a" to "b") of the function
7674 represented by expr. "a" and "b" are coded as in "intnum", and are not
7675 necessarily at infinity but if they are, oscillations (i.e.
7676 "[[+-1],alpha I]") are forbidden.
7677 The library syntax is intfouriersin"(void *E, GEN (*eval)(GEN,void*),
7679 GEN a, GEN b, GEN z, GEN tab, long prec)".
7680 intfuncinit"(X = a,b,expr,{flag = 0},{m = 0})"
7682 initalize tables for use with integral transforms such as
7683 "intmellininv", etc., where "a" and "b" are coded as in "intnum",
7684 "expr" is the function s(X) to which the integral transform is to be
7685 applied (which will multiply the weights of integration) and "m" is as
7686 in "intnuminit". If "flag" is nonzero, assumes that "s(-X) =
7687 \overline{s(X)}", which makes the computation twice as fast. See
7688 "intmellininvshort" for examples of the use of this function, which is
7689 particularly useful when the function s(X) is lengthy to compute, such
7690 as a gamma product.
7691 The library syntax is intfuncinit"(void *E, GEN (*eval)(GEN,void*), GEN
7693 a,GEN b,long m, long flag, long prec)". Note that the order of "m" and
7694 "flag" are reversed compared to the "GP" syntax.
7695 intlaplaceinv"(X = sig,z,expr,{tab})"
7697 numerical integration of "expr(X)e^{Xz}" with respect to "X" on the
7698 line " Re (X) = sig", divided by "2iPi", in other words, inverse
7699 Laplace transform of the function corresponding to expr at the value
7700 "z".
7701 "sig" is coded as follows. Either it is a real number "sigma", equal to
7703 the abcissa of integration, and then the function to be integrated is
7704 assumed to be slowly decreasing when the imaginary part of the variable
7705 tends to "+- oo ". Or it is a two component vector "[sigma,alpha]",
7706 where "sigma" is as before, and either "alpha = 0" for slowly
7707 decreasing functions, or "alpha > 0" for functions decreasing like "
7708 exp (-alpha t)". Note that it is not necessary to choose the exact
7709 value of "alpha". tab is as in "intnum".
7710 It is often a good idea to use this function with a value of "m" one or
7712 two higher than the one chosen by default (which can be viewed thanks
7713 to the function "intnumstep"), or to increase the abcissa of
7714 integration "sigma". For example:
7715 ? intlaplaceinv(x=100, 1, 1/x) - 1
7717 time = 330 ms.
7718 %7 = 1.07... E-72 + 3.2... E-72*I \\ not so good
7719 ? intlaplaceinv(x=100, 1, 1/x) - 1
7720 time = 330 ms.
7721 %7 = 1.07... E-72 + 3.2... E-72*I \\ better
7722 ? intlaplaceinv(x=100, 1, 1/x) - 1
7723 time = 330 ms.
7724 %7 = 1.07... E-72 + 3.2... E-72*I \\ perfect but slow.
7725 ? intlaplaceinv(x=100, 1, 1/x) - 1
7726 time = 330 ms.
7727 %7 = 1.07... E-72 + 3.2... E-72*I \\ better than %1
7728 ? intlaplaceinv(x=100, 1, 1/x) - 1
7729 time = 330 ms.
7730 %7 = 1.07... E-72 + 3.2... E-72*I \\ perfect, fast.
7731 ? intlaplaceinv(x=100, 1, 1/x) - 1
7732 time = 330 ms.
7733 %7 = 1.07... E-72 + 3.2... E-72*I \\ perfect, fastest, but why sig = 10?
7734 ? intlaplaceinv(x=100, 1, 1/x) - 1
7735 time = 330 ms.
7736 %7 = 1.07... E-72 + 3.2... E-72*I \\ too far now...
7737 The library syntax is intlaplaceinv"(void *E, GEN (*eval)(GEN,void*),
7739 GEN sig,GEN z, GEN tab, long prec)".
7740 intmellininv"(X = sig,z,expr,{tab})"
7742 numerical integration of "expr(X)z^{-X}" with respect to "X" on the
7743 line " Re (X) = sig", divided by "2iPi", in other words, inverse Mellin
7744 transform of the function corresponding to expr at the value "z".
7745 "sig" is coded as follows. Either it is a real number "sigma", equal to
7747 the abcissa of integration, and then the function to be integrated is
7748 assumed to decrease exponentially fast, of the order of " exp (-t)"
7749 when the imaginary part of the variable tends to "+- oo ". Or it is a
7750 two component vector "[sigma,alpha]", where "sigma" is as before, and
7751 either "alpha = 0" for slowly decreasing functions, or "alpha > 0" for
7752 functions decreasing like " exp (-alpha t)", such as gamma products.
7753 Note that it is not necessary to choose the exact value of "alpha", and
7754 that "alpha = 1" (equivalent to "sig" alone) is usually sufficient. tab
7755 is as in "intnum".
7756 As all similar functions, this function is provided for the convenience
7758 of the user, who could use "intnum" directly. However it is in general
7759 better to use "intmellininvshort".
7760 ? \p 308
7762 ? intmellininv(s=2,4, gamma(s)^3);
7763 time = 51,300 ms. \\ reasonable.
7764 ? \p 308
7765 ? intmellininv(s=2,4, gamma(s)^3);
7766 time = 51,300 ms. \\ slow because of Gamma(s)^3.
7767 The library syntax is intmellininv"(void *E, GEN (*eval)(GEN,void*),
7769 GEN sig, GEN z, GEN tab, long prec)".
7770 intmellininvshort"(sig,z,tab)"
7772 numerical integration of "s(X)z^{-X}" with respect to "X" on the line "
7773 Re (X) = sig", divided by "2iPi", in other words, inverse Mellin
7774 transform of s(X) at the value "z". Here s(X) is implicitly contained
7775 in tab in "intfuncinit" format, typically
7776 tab = intfuncinit(T = [-1], [1], s(sig + I*T))
7778 or similar commands. Take the example of the inverse Mellin transform
7780 of "Gamma(s)^3" given in "intmellininv":
7781 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7783 ? intmellininvshort(2,4, tab2)
7784 %6 = -1.2...E-42 - 3.2...E-109*I \\ for clarity
7785 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7786 ? intmellininvshort(2,4, tab2)
7787 %6 = -1.2...E-42 - 3.2...E-109*I \\ not too fast because of Gamma(s)^3.
7788 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7789 ? intmellininvshort(2,4, tab2)
7790 %6 = -1.2...E-42 - 3.2...E-109*I \\ function of real type, decreasing as exp(-3Pi/2.|t|)
7791 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7792 ? intmellininvshort(2,4, tab2)
7793 %6 = -1.2...E-42 - 3.2...E-109*I \\ 50 times faster than A and perfect.
7794 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7795 ? intmellininvshort(2,4, tab2)
7796 %6 = -1.2...E-42 - 3.2...E-109*I \\ 63 digits lost
7797 In the computation of tab, it was not essential to include the
7799 \emph{exact} exponential decrease of "Gamma(2+it)^3". But as the last
7800 example shows, a rough indication \emph{must} be given, otherwise slow
7801 decrease is assumed, resulting in catastrophic loss of accuracy.
7802 The library syntax is intmellininvshort"(GEN sig, GEN z, GEN tab, long
7804 prec)".
7805 intnum"(X = a,b,expr,{tab})"
7807 numerical integration of expr on "[a,b]" (possibly infinite interval)
7808 with respect to "X", where "a" and "b" are coded as explained below.
7809 The integrand may have values belonging to a vector space over the real
7810 numbers; in particular, it can be complex-valued or vector-valued.
7811 If tab is omitted, necessary integration tables are computed using
7813 "intnuminit" according to the current precision. It may be a positive
7814 integer "m", and tables are computed assuming the integration step is
7815 "1/2^m". Finally tab can be a table output by "intnuminit", in which
7816 case it is used directly. This is important if several integrations of
7817 the same type are performed (on the same kind of interval and
7818 functions, and the same accuracy), since it saves expensive
7819 precomputations.
7820 If tab is omitted the algorithm guesses a reasonable value for "m"
7822 depending on the current precision. That value may be obtained as
7823 intnumstep()
7825 However this value may be off from the optimal one, and this is
7827 important since the integration time is roughly proportional to "2^m".
7828 One may try consecutive values of "m" until they give the same value up
7829 to an accepted error.
7830 The endpoints "a" and "b" are coded as follows. If "a" is not at "+- oo
7832 ", it is either coded as a scalar (real or complex), or as a two
7833 component vector "[a,alpha]", where the function is assumed to have a
7834 singularity of the form "(x-a)^{alpha+\epsilon}" at "a", where
7835 "\epsilon" indicates that powers of logarithms are neglected. In
7836 particular, "[a,alpha]" with "alpha >= 0" is equivalent to "a". If a
7837 wrong singularity exponent is used, the result will lose a catastrophic
7838 number of decimals, for instance approximately half the number of
7839 digits will be correct if "alpha = -1/2" is omitted.
7840 The endpoints of integration can be "+- oo ", which is coded as "[+-
7842 1]" or as "[[+-1],alpha]". Here "alpha" codes the behaviour of the
7843 function at "+- oo " as follows.
7844 \item "alpha = 0" (or no "alpha" at all, i.e. simply "[+-1]") assumes
7846 that the function to be integrated tends to zero, but not exponentially
7847 fast, and not oscillating such as " sin (x)/x".
7848 \item "alpha > 0" assumes that the function tends to zero exponentially
7850 fast approximately as " exp (-alpha x)", including reasonably
7851 oscillating functions such as " exp (-x) sin (x)". The precise choice
7852 of "alpha", while useful in extreme cases, is not critical, and may be
7853 off by a \emph{factor} of 10 or more from the correct value.
7854 \item "alpha < -1" assumes that the function tends to 0 slowly, like
7856 "x^{alpha}". Here it is essential to give the correct "alpha", if
7857 possible, but on the other hand "alpha <= -2" is equivalent to "alpha =
7858 0", in other words to no "alpha" at all.
7859 The last two codes are reserved for oscillating functions. Let "k > 0"
7861 real, and g(x) a nonoscillating function tending to 0, then
7862 \item "alpha = k I" assumes that the function behaves like " cos
7864 (kx)g(x)".
7865 \item "alpha = -kI" assumes that the function behaves like " sin
7867 (kx)g(x)".
7868 Here it is critical to give the exact value of "k". If the oscillating
7870 part is not a pure sine or cosine, one must expand it into a Fourier
7871 series, use the above codings, and sum the resulting contributions.
7872 Otherwise you will get nonsense. Note that " cos (kx)" (and similarly "
7873 sin (kx)") means that very function, and not a translated version such
7874 as " cos (kx+a)".
7875 If for instance "f(x) = cos (kx)g(x)" where g(x) tends to zero
7877 exponentially fast as " exp (-alpha x)", it is up to the user to choose
7878 between "[[+-1],alpha]" and "[[+-1],kI]", but a good rule of thumb is
7879 that if the oscillations are much weaker than the exponential decrease,
7880 choose "[[+-1],alpha]", otherwise choose "[[+-1],kI]", although the
7881 latter can reasonably be used in all cases, while the former cannot. To
7882 take a specific example, in the inverse Mellin transform, the function
7883 to be integrated is almost always exponentially decreasing times
7884 oscillating. If we choose the oscillating type of integral we perhaps
7885 obtain the best results, at the expense of having to recompute our
7886 functions for a different value of the variable "z" giving the
7887 transform, preventing us to use a function such as "intmellininvshort".
7888 On the other hand using the exponential type of integral, we obtain
7889 less accurate results, but we skip expensive recomputations. See
7890 "intmellininvshort" and "intfuncinit" for more explanations.
7891 Note. If you do not like the code "[+-1]" for "+- oo ", you are welcome
7893 to set, e.g "oo = [1]" or "INFINITY = [1]", then using "+oo", "-oo",
7894 "-INFINITY", etc. will have the expected behaviour.
7895 We shall now see many examples to get a feeling for what the various
7897 parameters achieve. All examples below assume precision is set to 105
7898 decimal digits. We first type
7899 ? \p 105
7901 ? oo = [1] \\ for clarity
7902 Apparent singularities. Even if the function f(x) represented by expr
7904 has no singularities, it may be important to define the function
7905 differently near special points. For instance, if "f(x) = 1 /( exp
7906 (x)-1) - exp (-x)/x", then "int_0^ oo f(x)dx = gamma", Euler's
7907 constant "Euler". But
7908 ? f(x) = 1/(exp(x)-1) - exp(-x)/x
7910 ? intnum(x = 0, [oo,1], f(x)) - Euler
7911 %1 = 6.00... E-67
7912 thus only correct to 76 decimal digits. This is because close to 0 the
7914 function "f" is computed with an enormous loss of accuracy. A better
7915 solution is
7916 ? intnum(x = 0, [oo,1], g(x)) - Euler
7918 %2 = 0.E-106 \\ expansion around t = 0
7919 ? intnum(x = 0, [oo,1], g(x)) - Euler
7920 %2 = 0.E-106 \\ note that 6.18 > 105
7921 ? intnum(x = 0, [oo,1], g(x)) - Euler
7922 %2 = 0.E-106 \\ perfect
7923 It is up to the user to determine constants such as the "10^{-18}" and
7925 7 used above.
7926 True singularities. With true singularities the result is much worse.
7928 For instance
7929 ? intnum(x = [0,-1/2], 1, 1/sqrt(x)) - 2
7931 %2 = 0.E-105 \\ only 59 correct decimals
7932 ? intnum(x = [0,-1/2], 1, 1/sqrt(x)) - 2
7934 %2 = 0.E-105 \\ better
7935 Oscillating functions.
7937 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7939 %6 = 0.0092... \\ nonsense
7940 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7942 %6 = 0.0092... \\ bad
7943 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7945 %6 = 0.0092... \\ perfect
7946 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7948 %6 = 0.0092... \\ oops, wrong k
7949 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7951 %6 = 0.0092... \\ perfect
7952 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7954 %6 = 0.0092... \\ bad
7955 ? sin(x)^3 - (3*sin(x)-sin(3*x))/4
7956 %7 = O(x^17)
7957 We may use the above linearization and compute two oscillating
7959 integrals with ``infinite endpoints'' "[oo, -I]" and "[oo, -3*I]"
7960 respectively, or notice the obvious change of variable, and reduce to
7961 the single integral "(1/2)int_0^ oo sin (x)/xdx". We finish with some
7962 more complicated examples:
7963 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7965 %6 = 5.45... E-107 \\ bad
7966 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7967 %6 = 5.45... E-107 \\ OK
7968 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7969 %6 = 5.45... E-107 \\ OK
7970 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7971 %6 = 5.45... E-107 \\ lost 16 decimals. Try higher m:
7972 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7973 %6 = 5.45... E-107 \\ the value of m actually used above.
7974 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7975 %6 = 5.45... E-107 \\ try m one higher.
7976 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7977 %6 = 5.45... E-107 \\ OK this time.
7978 Warning. Like "sumalt", "intnum" often assigns a reasonable value to
7980 diverging integrals. Use these values at your own risk! For example:
7981 ? intnum(x = 0, [oo, -I], x^2*sin(x))
7983 %1 = -2.0000000000...
7984 Note the formula
7986 " int_0^ oo sin (x)/x^sdx = cos (Pi s/2) Gamma(1-s) , "
7988 a priori valid only for "0 < Re (s) < 2", but the right hand side
7990 provides an analytic continuation which may be evaluated at "s = -2"...
7991 Multivariate integration. Using successive univariate integration with
7993 respect to different formal parameters, it is immediate to do naive
7994 multivariate integration. But it is important to use a suitable
7995 "intnuminit" to precompute data for the \emph{internal} integrations at
7996 least!
7997 For example, to compute the double integral on the unit disc "x^2+y^2
7999 <= 1" of the function "x^2+y^2", we can write
8000 ? tab = intnuminit(-1,1);
8002 ? intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2, tab), tab)
8003 The first tab is essential, the second optional. Compare:
8005 ? intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2, tab), tab);
8007 time = 7,210 ms. \\ slow
8008 ? intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2, tab), tab);
8009 time = 7,210 ms. \\ faster
8010 However, the "intnuminit" program is usually pessimistic when it comes
8012 to choosing the integration step "2^{-m}". It is often possible to
8013 improve the speed by trial and error. Continuing the above example:
8014 ? test(m - 3)
8016 time = 120 ms.
8017 %3 = -7.23... E-60 \\ what value of m did it take ?
8018 ? test(m - 3)
8019 time = 120 ms.
8020 %3 = -7.23... E-60 \\ 4 = 2^2 times faster and still OK.
8021 ? test(m - 3)
8022 time = 120 ms.
8023 %3 = -7.23... E-60 \\ 16 = 2^4 times faster and still OK.
8024 ? test(m - 3)
8025 time = 120 ms.
8026 %3 = -7.23... E-60 \\ 64 = 2^6 times faster, lost 45 decimals.
8027 The library syntax is intnum"(void *E, GEN (*eval)(GEN,void*), GEN
8029 a,GEN b,GEN tab, long prec)", where an omitted tab is coded as "NULL".
8030 intnuminit"(a,b,{m = 0})"
8032 initialize tables for integration from "a" to "b", where "a" and "b"
8033 are coded as in "intnum". Only the compactness, the possible existence
8034 of singularities, the speed of decrease or the oscillations at infinity
8035 are taken into account, and not the values. For instance
8036 "intnuminit(-1,1)" is equivalent to "intnuminit(0,Pi)", and
8037 "intnuminit([0,-1/2],[1])" is equivalent to "
8038 intnuminit([-1],[-1,-1/2])". If "m" is not given, it is computed
8039 according to the current precision. Otherwise the integration step is
8040 "1/2^m". Reasonable values of "m" are "m = 6" or "m = 7" for 100
8041 decimal digits, and "m = 9" for 1000 decimal digits.
8042 The result is technical, but in some cases it is useful to know the
8044 output. Let "x = phi(t)" be the change of variable which is used.
8045 tab[1] contains the integer "m" as above, either given by the user or
8046 computed from the default precision, and can be recomputed directly
8047 using the function "intnumstep". tab[2] and tab[3] contain
8048 respectively the abcissa and weight corresponding to "t = 0" ("phi(0)"
8049 and "phi'(0)"). tab[4] and tab[5] contain the abcissas and weights
8050 corresponding to positive "t = nh" for "1 <= n <= N" and "h = 1/2^m"
8051 ("phi(nh)" and "phi'(nh)"). Finally tab[6] and tab[7] contain either
8052 the abcissas and weights corresponding to negative "t = nh" for "-N <=
8053 n <= -1", or may be empty (but not always) if "phi(t)" is an odd
8054 function (implicitly we would have "tab[6] = -tab[4]" and "tab[7] =
8055 tab[5]").
8056 The library syntax is intnuminit"(GEN a, GEN b, long m, long prec)".
8058 intnumromb"(X = a,b,expr,{flag = 0})"
8060 numerical integration of expr (smooth in "]a,b["), with respect to "X".
8061 This function is deprecated, use "intnum" instead.
8062 Set "flag = 0" (or omit it altogether) when "a" and "b" are not too
8064 large, the function is smooth, and can be evaluated exactly everywhere
8065 on the interval "[a,b]".
8066 If "flag = 1", uses a general driver routine for doing numerical
8068 integration, making no particular assumption (slow).
8069 "flag = 2" is tailored for being used when "a" or "b" are infinite. One
8071 \emph{must} have "ab > 0", and in fact if for example "b = + oo ", then
8072 it is preferable to have "a" as large as possible, at least "a >= 1".
8073 If "flag = 3", the function is allowed to be undefined (but continuous)
8075 at "a" or "b", for example the function " sin (x)/x" at "x = 0".
8076 The user should not require too much accuracy: 18 or 28 decimal digits
8078 is OK, but not much more. In addition, analytical cleanup of the
8079 integral must have been done: there must be no singularities in the
8080 interval or at the boundaries. In practice this can be accomplished
8081 with a simple change of variable. Furthermore, for improper integrals,
8082 where one or both of the limits of integration are plus or minus
8083 infinity, the function must decrease sufficiently rapidly at infinity.
8084 This can often be accomplished through integration by parts. Finally,
8085 the function to be integrated should not be very small (compared to the
8086 current precision) on the entire interval. This can of course be
8087 accomplished by just multiplying by an appropriate constant.
8088 Note that infinity can be represented with essentially no loss of
8090 accuracy by 1e1000. However beware of real underflow when dealing with
8091 rapidly decreasing functions. For example, if one wants to compute the
8092 "int_0^ oo e^{-x^2}dx" to 28 decimal digits, then one should set
8093 infinity equal to 10 for example, and certainly not to 1e1000.
8094 The library syntax is intnumromb"(void *E, GEN (*eval)(GEN,void*), GEN
8096 a, GEN b, long flag, long prec)", where "eval(x, E)" returns the value
8097 of the function at "x". You may store any additional information
8098 required by "eval" in "E", or set it to "NULL".
8099 intnumstep"()"
8101 give the value of "m" used in all the "intnum" and "sumnum" programs,
8102 hence such that the integration step is equal to "1/2^m".
8103 The library syntax is intnumstep"(long prec)".
8105 prod"(X = a,b,expr,{x = 1})"
8107 product of expression expr, initialized at "x", the formal parameter
8108 "X" going from "a" to "b". As for "sum", the main purpose of the
8109 initialization parameter "x" is to force the type of the operations
8110 being performed. For example if it is set equal to the integer 1,
8111 operations will start being done exactly. If it is set equal to the
8112 real 1., they will be done using real numbers having the default
8113 precision. If it is set equal to the power series "1+O(X^k)" for a
8114 certain "k", they will be done using power series of precision at most
8115 "k". These are the three most common initializations.
8116 As an extreme example, compare
8118 ? prod(i=1, 100, 1 - X^i); \\ this has degree 5050 !!
8120 time = 3,335 ms.
8121 ? prod(i=1, 100, 1 - X^i, 1 + O(X^101))
8122 time = 43 ms.
8123 %2 = 1 - X - X^2 + X^5 + X^7 - X^12 - X^15 + X^22 + X^26 - X^35 - X^40 + \
8124 X^51 + X^57 - X^70 - X^77 + X^92 + X^100 + O(X^101)
8125 The library syntax is produit"(entree *ep, GEN a, GEN b, char *expr,
8127 GEN x)".
8128 prodeuler"(X = a,b,expr)"
8130 product of expression expr, initialized at 1. (i.e. to a \emph{real}
8131 number equal to 1 to the current "realprecision"), the formal parameter
8132 "X" ranging over the prime numbers between "a" and "b".
8133 The library syntax is prodeuler"(void *E, GEN (*eval)(GEN,void*), GEN
8135 a,GEN b, long prec)".
8136 prodinf"(X = a,expr,{flag = 0})"
8138 infinite product of expression expr, the formal parameter "X" starting
8139 at "a". The evaluation stops when the relative error of the expression
8140 minus 1 is less than the default precision. The expressions must always
8141 evaluate to an element of C.
8142 If "flag = 1", do the product of the ("1+expr") instead.
8144 The library syntax is prodinf"(void *E, GEN (*eval)(GEN, void*), GEN a,
8146 long prec)" ("flag = 0"), or prodinf1 with the same arguments ("flag =
8147 1").
8148 solve"(X = a,b,expr)"
8150 find a real root of expression expr between "a" and "b", under the
8151 condition "expr(X = a) * expr(X = b) <= 0". This routine uses Brent's
8152 method and can fail miserably if expr is not defined in the whole of
8153 "[a,b]" (try "solve(x = 1, 2, tan(x)").
8154 The library syntax is zbrent"(void *E,GEN (*eval)(GEN,void*),GEN a,GEN
8156 b,long prec)".
8157 sum"(X = a,b,expr,{x = 0})"
8159 sum of expression expr, initialized at "x", the formal parameter going
8160 from "a" to "b". As for "prod", the initialization parameter "x" may be
8161 given to force the type of the operations being performed.
8162 As an extreme example, compare
8164 ? sum(i=1, 5000, 1/i); \\ rational number: denominator has 2166 digits.
8166 time = 1,241 ms.
8167 ? sum(i=1, 5000, 1/i, 0.)
8168 time = 158 ms.
8169 %2 = 9.094508852984436967261245533
8170 The library syntax is somme"(entree *ep, GEN a, GEN b, char *expr, GEN
8172 x)". This is to be used as follows: "ep" represents the dummy variable
8173 used in the expression "expr"
8174 /* compute a^2 + ... + b^2 */
8176 {
8177 /* define the dummy variable "i" */
8178 entree *ep = is_entry("i");
8179 /* sum for a <= i <= b */
8180 return somme(ep, a, b, "i^2", gen_0);
8181 }
8182 sumalt"(X = a,expr,{flag = 0})"
8184 numerical summation of the series expr, which should be an alternating
8185 series, the formal variable "X" starting at "a". Use an algorithm of
8186 F. Villegas as modified by D. Zagier (improves on Euler-Van Wijngaarden
8187 method).
8188 If "flag = 1", use a variant with slightly different polynomials.
8190 Sometimes faster.
8191 Divergent alternating series can sometimes be summed by this method, as
8193 well as series which are not exactly alternating (see for example
8194 "Label se:user_defined"). If the series already converges
8195 geometrically, "suminf" is often a better choice:
8196 ? \p28
8198 ? sumalt(i = 1, -(-1)^i / i) - log(2)
8199 time = 0 ms.
8200 %1 = -2.524354897 E-29
8201 ? suminf(i = 1, -(-1)^i / i)
8202 *** suminf: user interrupt after 10min, 20,100 ms.
8203 ? \p1000
8204 ? sumalt(i = 1, -(-1)^i / i) - log(2)
8205 time = 90 ms.
8206 %2 = 4.459597722 E-1002
8207 ? sumalt(i = 0, (-1)^i / i!) - exp(-1)
8209 time = 670 ms.
8210 %3 = -4.03698781490633483156497361352190615794353338591897830587 E-944
8211 ? suminf(i = 0, (-1)^i / i!) - exp(-1)
8212 time = 110 ms.
8213 %4 = -8.39147638 E-1000 \\ faster and more accurate
8214 The library syntax is sumalt"(void *E, GEN (*eval)(GEN,void*),GEN
8216 a,long prec)". Also available is "sumalt2" with the same arguments
8217 ("flag = 1").
8218 sumdiv"(n,X,expr)"
8220 sum of expression expr over the positive divisors of "n".
8221 Arithmetic functions like "sigma" use the multiplicativity of the
8223 underlying expression to speed up the computation. In the present
8224 version 2.2.0, there is no way to indicate that expr is multiplicative
8225 in "n", hence specialized functions should be preferred whenever
8226 possible.
8227 The library syntax is divsum"(entree *ep, GEN num, char *expr)".
8229 suminf"(X = a,expr)"
8231 infinite sum of expression expr, the formal parameter "X" starting at
8232 "a". The evaluation stops when the relative error of the expression is
8233 less than the default precision for 3 consecutive evaluations. The
8234 expressions must always evaluate to a complex number.
8235 If the series converges slowly, make sure "realprecision" is low (even
8237 28 digits may be too much). In this case, if the series is alternating
8238 or the terms have a constant sign, "sumalt" and "sumpos" should be used
8239 instead.
8240 ? \p28
8242 ? suminf(i = 1, -(-1)^i / i)
8243 *** suminf: user interrupt after 10min, 20,100 ms.
8244 ? sumalt(i = 1, -(-1)^i / i) - log(2)
8245 time = 0 ms.
8246 %1 = -2.524354897 E-29
8247 The library syntax is suminf"(void *E, GEN (*eval)(GEN,void*), GEN a,
8249 long prec)".
8250 sumnum"(X = a,sig,expr,{tab}),{flag = 0}"
8252 numerical summation of expr, the variable "X" taking integer values
8253 from ceiling of "a" to "+ oo ", where expr is assumed to be a
8254 holomorphic function f(X) for " Re (X) >= sigma".
8255 The parameter "sigma belongs to R" is coded in the argument "sig" as
8257 follows: it is either
8258 \item a real number "sigma". Then the function "f" is assumed to
8260 decrease at least as "1/X^2" at infinity, but not exponentially;
8261 \item a two-component vector "[sigma,alpha]", where "sigma" is as
8263 before, "alpha < -1". The function "f" is assumed to decrease like
8264 "X^{alpha}". In particular, "alpha <= -2" is equivalent to no "alpha"
8265 at all.
8266 \item a two-component vector "[sigma,alpha]", where "sigma" is as
8268 before, "alpha > 0". The function "f" is assumed to decrease like " exp
8269 (-alpha X)". In this case it is essential that "alpha" be exactly the
8270 rate of exponential decrease, and it is usually a good idea to increase
8271 the default value of "m" used for the integration step. In practice, if
8272 the function is exponentially decreasing "sumnum" is slower and less
8273 accurate than "sumpos" or "suminf", so should not be used.
8274 The function uses the "intnum" routines and integration on the line "
8276 Re (s) = sigma". The optional argument tab is as in intnum, except it
8277 must be initialized with "sumnuminit" instead of "intnuminit".
8278 When tab is not precomputed, "sumnum" can be slower than "sumpos", when
8280 the latter is applicable. It is in general faster for slowly decreasing
8281 functions.
8282 Finally, if "flag" is nonzero, we assume that the function "f" to be
8284 summed is of real type, i.e. satisfies "\overline{f(z)} =
8285 f(\overline{z})", which speeds up the computation.
8286 ? d - c
8288 time = 0 ms.
8289 %5 = 1.97... E-306 \\ slower but done once and for all.
8290 ? d - c
8291 time = 0 ms.
8292 %5 = 1.97... E-306 \\ 3 times as fast as sumpos
8293 ? d - c
8294 time = 0 ms.
8295 %5 = 1.97... E-306 \\ perfect.
8296 ? d - c
8297 time = 0 ms.
8298 %5 = 1.97... E-306 \\ function of real type
8299 ? d - c
8300 time = 0 ms.
8301 %5 = 1.97... E-306 \\ twice as fast, no imaginary part.
8302 ? d - c
8303 time = 0 ms.
8304 %5 = 1.97... E-306 \\ fast
8305 ? d - c
8306 time = 0 ms.
8307 %5 = 1.97... E-306 \\ slow.
8308 ? d - c
8309 time = 0 ms.
8310 %5 = 1.97... E-306 \\ perfect.
8311 For slowly decreasing function, we must indicate singularities:
8313 time = 12,210 ms.
8315 ? b - zeta(4/3)
8316 %3 = 1.05... E-300 \\ slow because of the computation of n^{-4/3}.
8317 time = 12,210 ms.
8318 ? b - zeta(4/3)
8319 %3 = 1.05... E-300 \\ lost 200 decimals because of singularity at oo
8320 time = 12,210 ms.
8321 ? b - zeta(4/3)
8322 %3 = 1.05... E-300 \\ of real type
8323 time = 12,210 ms.
8324 ? b - zeta(4/3)
8325 %3 = 1.05... E-300 \\ better
8326 Since the \emph{complex} values of the function are used, beware of
8328 determination problems. For instance:
8329 ? sumnum(n=1,[2,-3/2], 1/n^(3/2), tab,1) - zeta(3/2)
8331 time = 8,990 ms.
8332 %3 = -1.19... E-305 \\ fast and correct
8333 ? sumnum(n=1,[2,-3/2], 1/n^(3/2), tab,1) - zeta(3/2)
8334 time = 8,990 ms.
8335 %3 = -1.19... E-305 \\ nonsense. However
8336 ? sumnum(n=1,[2,-3/2], 1/n^(3/2), tab,1) - zeta(3/2)
8337 time = 8,990 ms.
8338 %3 = -1.19... E-305 \\ perfect, as 1/(n*sqrt{n}) above but much slower
8339 For exponentially decreasing functions, "sumnum" is given for
8341 completeness, but one of "suminf" or "sumpos" should always be
8342 preferred. If you experiment with such functions and "sumnum" anyway,
8343 indicate the exact rate of decrease and increase "m" by 1 or 2:
8344 ? m = intnumstep()
8346 %4 = 9
8347 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8348 time = 11,770 ms.
8349 %5 = -1.9... E-305 \\ fast and perfect
8350 ? m = intnumstep()
8351 %4 = 9
8352 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8353 time = 11,770 ms.
8354 %5 = -1.9... E-305 \\ also fast and perfect
8355 ? m = intnumstep()
8356 %4 = 9
8357 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8358 time = 11,770 ms.
8359 %5 = -1.9... E-305 \\ nonsense
8360 ? m = intnumstep()
8361 %4 = 9
8362 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8363 time = 11,770 ms.
8364 %5 = -1.9... E-305 \\ of real type
8365 ? m = intnumstep()
8366 %4 = 9
8367 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8368 time = 11,770 ms.
8369 %5 = -1.9... E-305 \\ slow and lost 70 decimals
8370 ? m = intnumstep()
8371 %4 = 9
8372 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8373 time = 11,770 ms.
8374 %5 = -1.9... E-305 \\ now perfect, but slow.
8375 The library syntax is sumnum"(void *E, GEN (*eval)(GEN,void*), GEN
8377 a,GEN sig,GEN tab,long flag, long prec)".
8378 sumnumalt"(X = a,sig,expr,{tab},{flag = 0})"
8380 numerical summation of "(-1)^Xexpr(X)", the variable "X" taking integer
8381 values from ceiling of "a" to "+ oo ", where expr is assumed to be a
8382 holomorphic function for " Re (X) >= sig" (or "sig[1]").
8383 Warning. This function uses the "intnum" routines and is orders of
8385 magnitude slower than "sumalt". It is only given for completeness and
8386 should not be used in practice.
8387 Warning2. The expression expr must \emph{not} include the "(-1)^X"
8389 coefficient. Thus "sumalt(n = a,(-1)^nf(n))" is (approximately) equal
8390 to "sumnumalt(n = a,sig,f(n))".
8391 "sig" is coded as in "sumnum". However for slowly decreasing functions
8393 (where "sig" is coded as "[sigma,alpha]" with "alpha < -1"), it is not
8394 really important to indicate "alpha". In fact, as for "sumalt", the
8395 program will often give meaningful results (usually analytic
8396 continuations) even for divergent series. On the other hand the
8397 exponential decrease must be indicated.
8398 tab is as in "intnum", but if used must be initialized with
8400 "sumnuminit". If "flag" is nonzero, assumes that the function "f" to be
8401 summed is of real type, i.e. satisfies "\overline{f(z)} =
8402 f(\overline{z})", and then twice faster when tab is precomputed.
8403 ? a - b
8405 time = 0 ms.
8406 %1 = -1.66... E-308 \\ abcissa sigma = 2, alternating sums.
8407 ? a - b
8408 time = 0 ms.
8409 %1 = -1.66... E-308 \\ slow, but done once and for all.
8410 ? a - b
8411 time = 0 ms.
8412 %1 = -1.66... E-308 \\ similar speed to sumnum
8413 ? a - b
8414 time = 0 ms.
8415 %1 = -1.66... E-308 \\ infinitely faster!
8416 ? a - b
8417 time = 0 ms.
8418 %1 = -1.66... E-308 \\ perfect
8419 The library syntax is sumnumalt"(void *E, GEN (*eval)(GEN,void*), GEN
8421 a, GEN sig, GEN tab, long flag, long prec)".
8422 sumnuminit"(sig,{m = 0},{sgn = 1})"
8424 initialize tables for numerical summation using "sumnum" (with "sgn =
8425 1") or "sumnumalt" (with "sgn = -1"), "sig" is the abcissa of
8426 integration coded as in "sumnum", and "m" is as in "intnuminit".
8427 The library syntax is sumnuminit"(GEN sig, long m, long sgn, long
8429 prec)".
8430 sumpos"(X = a,expr,{flag = 0})"
8432 numerical summation of the series expr, which must be a series of terms
8433 having the same sign, the formal variable "X" starting at "a". The
8434 algorithm used is Van Wijngaarden's trick for converting such a series
8435 into an alternating one, and is quite slow. For regular functions, the
8436 function "sumnum" is in general much faster once the initializations
8437 have been made using "sumnuminit".
8438 If "flag = 1", use slightly different polynomials. Sometimes faster.
8440 The library syntax is sumpos"(void *E, GEN (*eval)(GEN,void*),GEN
8442 a,long prec)". Also available is "sumpos2" with the same arguments
8443 ("flag = 1").
8444
8446 Although plotting is not even a side purpose of PARI, a number of
8447 plotting functions are provided. Moreover, a lot of people suggested
8448 ideas or submitted patches for this section of the code. Among these,
8449 special thanks go to Klaus-Peter Nischke who suggested the recursive
8450 plotting and the forking/resizing stuff under X11, and Ilya Zakharevich
8451 who undertook a complete rewrite of the graphic code, so that most of
8452 it is now platform-independent and should be easy to port or expand.
8453 There are three types of graphic functions.
8454 High-level plotting functions
8456 (all the functions starting with "ploth") in which the user has little
8457 to do but explain what type of plot he wants, and whose syntax is
8458 similar to the one used in the preceding section.
8459 Low-level plotting functions
8461 (called rectplot functions, sharing the prefix "plot"), where every
8462 drawing primitive (point, line, box, etc.) is specified by the user.
8463 These low-level functions work as follows. You have at your disposal 16
8464 virtual windows which are filled independently, and can then be
8465 physically ORed on a single window at user-defined positions. These
8466 windows are numbered from 0 to 15, and must be initialized before being
8467 used by the function "plotinit", which specifies the height and width
8468 of the virtual window (called a rectwindow in the sequel). At all
8469 times, a virtual cursor (initialized at "[0,0]") is associated to the
8470 window, and its current value can be obtained using the function
8471 "plotcursor".
8472 A number of primitive graphic objects (called rect objects) can then be
8474 drawn in these windows, using a default color associated to that window
8475 (which can be changed under X11, using the "plotcolor" function, black
8476 otherwise) and only the part of the object which is inside the window
8477 will be drawn, with the exception of polygons and strings which are
8478 drawn entirely. The ones sharing the prefix "plotr" draw relatively to
8479 the current position of the virtual cursor, the others use absolute
8480 coordinates. Those having the prefix "plotrecth" put in the rectwindow
8481 a large batch of rect objects corresponding to the output of the
8482 related "ploth" function.
8483 Finally, the actual physical drawing is done using the function
8485 "plotdraw". The rectwindows are preserved so that further drawings
8486 using the same windows at different positions or different windows can
8487 be done without extra work. To erase a window (and free the
8488 corresponding memory), use the function "plotkill". It is not possible
8489 to partially erase a window. Erase it completely, initialize it again
8490 and then fill it with the graphic objects that you want to keep.
8491 In addition to initializing the window, you may use a scaled window to
8493 avoid unnecessary conversions. For this, use the function "plotscale"
8494 below. As long as this function is not called, the scaling is simply
8495 the number of pixels, the origin being at the upper left and the
8496 "y"-coordinates going downwards.
8497 Note that in the present version 2.2.0 all plotting functions (both low
8499 and high level) are written for the X11-window system (hence also for
8500 GUI's based on X11 such as Openwindows and Motif) only, though little
8501 code remains which is actually platform-dependent. It is also possible
8502 to compile "gp" with either of the Qt or FLTK graphical libraries. A
8503 Suntools/Sunview, Macintosh, and an Atari/Gem port were provided for
8504 previous versions, but are now obsolete.
8505 Under X11, the physical window (opened by "plotdraw" or any of the
8507 "ploth*" functions) is completely separated from "gp" (technically, a
8508 "fork" is done, and the non-graphical memory is immediately freed in
8509 the child process), which means you can go on working in the current
8510 "gp" session, without having to kill the window first. Under X11, this
8511 window can be closed, enlarged or reduced using the standard window
8512 manager functions. No zooming procedure is implemented though (yet).
8513 Functions for PostScript output:
8515 in the same way that "printtex" allows you to have a TeX output
8516 corresponding to printed results, the functions starting with "ps"
8517 allow you to have "PostScript" output of the plots. This will not be
8518 absolutely identical with the screen output, but will be sufficiently
8519 close. Note that you can use PostScript output even if you do not have
8520 the plotting routines enabled. The PostScript output is written in a
8521 file whose name is derived from the "psfile" default ("./pari.ps" if
8522 you did not tamper with it). Each time a new PostScript output is asked
8523 for, the PostScript output is appended to that file. Hence you probably
8524 want to remove this file, or change the value of "psfile", in between
8525 plots. On the other hand, in this manner, as many plots as desired can
8526 be kept in a single file.
8527 And library mode ?
8529 \emph{None of the graphic functions are available within the PARI
8530 library, you must be under "gp" to use them}. The reason for that is
8531 that you really should not use PARI for heavy-duty graphical work,
8532 there are better specialized alternatives around. This whole set of
8533 routines was only meant as a convenient, but simple-minded, visual aid.
8534 If you really insist on using these in your program (we warned you),
8535 the source ("plot*.c") should be readable enough for you to achieve
8536 something.
8537 plot"(X = a,b,expr,{Ymin},{Ymax})"
8539 crude ASCII plot of the function represented by expression expr from
8540 "a" to "b", with Y ranging from Ymin to Ymax. If Ymin (resp. Ymax) is
8541 not given, the minima (resp. the maxima) of the computed values of the
8542 expression is used instead.
8543 plotbox"(w,x2,y2)"
8545 let "(x1,y1)" be the current position of the virtual cursor. Draw in
8546 the rectwindow "w" the outline of the rectangle which is such that the
8547 points "(x1,y1)" and "(x2,y2)" are opposite corners. Only the part of
8548 the rectangle which is in "w" is drawn. The virtual cursor does
8549 \emph{not} move.
8550 plotclip"(w)"
8552 `clips' the content of rectwindow "w", i.e remove all parts of the
8553 drawing that would not be visible on the screen. Together with
8554 "plotcopy" this function enables you to draw on a scratchpad before
8555 commiting the part you're interested in to the final picture.
8556 plotcolor"(w,c)"
8558 set default color to "c" in rectwindow "w". In present version 2.2.0,
8559 this is only implemented for the X11 window system, and you only have
8560 the following palette to choose from:
8561 1 = black, 2 = blue, 3 = sienna, 4 = red, 5 = green, 6 = grey, 7 =
8563 gainsborough.
8564 Note that it should be fairly easy for you to hardwire some more colors
8566 by tweaking the files "rect.h" and "plotX.c". User-defined colormaps
8567 would be nice, and \emph{may} be available in future versions.
8568 plotcopy"(w1,w2,dx,dy)"
8570 copy the contents of rectwindow "w1" to rectwindow "w2", with offset
8571 "(dx,dy)".
8572 plotcursor"(w)"
8574 give as a 2-component vector the current (scaled) position of the
8575 virtual cursor corresponding to the rectwindow "w".
8576 plotdraw"(list)"
8578 physically draw the rectwindows given in "list" which must be a vector
8579 whose number of components is divisible by 3. If "list =
8580 [w1,x1,y1,w2,x2,y2,...]", the windows "w1", "w2", etc. are physically
8581 placed with their upper left corner at physical position "(x1,y1)",
8582 "(x2,y2)",...respectively, and are then drawn together. Overlapping
8583 regions will thus be drawn twice, and the windows are considered
8584 transparent. Then display the whole drawing in a special window on your
8585 screen.
8586 ploth"(X = a,b,expr,{flag = 0},{n = 0})"
8588 high precision plot of the function "y = f(x)" represented by the
8589 expression expr, "x" going from "a" to "b". This opens a specific
8590 window (which is killed whenever you click on it), and returns a four-
8591 component vector giving the coordinates of the bounding box in the form
8592 "[xmin,xmax,ymin,ymax]".
8593 Important note: Since this may involve a lot of function calls, it is
8595 advised to keep the current precision to a minimum (e.g. 9) before
8596 calling this function.
8597 "n" specifies the number of reference point on the graph (0 means use
8599 the hardwired default values, that is: 1000 for general plot, 1500 for
8600 parametric plot, and 15 for recursive plot).
8601 If no "flag" is given, expr is either a scalar expression f(X), in
8603 which case the plane curve "y = f(X)" will be drawn, or a vector
8604 "[f_1(X),...,f_k(X)]", and then all the curves "y = f_i(X)" will be
8605 drawn in the same window.
8606 The binary digits of "flag" mean:
8608 \item "1 = Parametric": parametric plot. Here expr must be a vector
8610 with an even number of components. Successive pairs are then understood
8611 as the parametric coordinates of a plane curve. Each of these are then
8612 drawn.
8613 For instance:
8615 "ploth(X = 0,2*Pi,[sin(X),cos(X)],1)" will draw a circle.
8617 "ploth(X = 0,2*Pi,[sin(X),cos(X)])" will draw two entwined sinusoidal
8619 curves.
8620 "ploth(X = 0,2*Pi,[X,X,sin(X),cos(X)],1)" will draw a circle and the
8622 line "y = x".
8623 \item "2 = Recursive": recursive plot. If this flag is set, only
8625 \emph{one} curve can be drawn at a time, i.e. expr must be either a
8626 two-component vector (for a single parametric curve, and the parametric
8627 flag \emph{has} to be set), or a scalar function. The idea is to choose
8628 pairs of successive reference points, and if their middle point is not
8629 too far away from the segment joining them, draw this as a local
8630 approximation to the curve. Otherwise, add the middle point to the
8631 reference points. This is fast, and usually more precise than usual
8632 plot. Compare the results of
8633 "ploth(X = -1,1,sin(1/X),2) and ploth(X = -1,1,sin(1/X))"
8635 for instance. But beware that if you are extremely unlucky, or choose
8637 too few reference points, you may draw some nice polygon bearing little
8638 resemblance to the original curve. For instance you should \emph{never}
8639 plot recursively an odd function in a symmetric interval around 0. Try
8640 ploth(x = -20, 20, sin(x), 2)
8642 to see why. Hence, it's usually a good idea to try and plot the same
8644 curve with slightly different parameters.
8645 The other values toggle various display options:
8647 \item "4 = no_Rescale": do not rescale plot according to the computed
8649 extrema. This is meant to be used when graphing multiple functions on a
8650 rectwindow (as a "plotrecth" call), in conjunction with "plotscale".
8651 \item "8 = no_X_axis": do not print the "x"-axis.
8653 \item "16 = no_Y_axis": do not print the "y"-axis.
8655 \item "32 = no_Frame": do not print frame.
8657 \item "64 = no_Lines": only plot reference points, do not join them.
8659 \item "128 = Points_too": plot both lines and points.
8661 \item "256 = Splines": use splines to interpolate the points.
8663 \item "512 = no_X_ticks": plot no "x"-ticks.
8665 \item "1024 = no_Y_ticks": plot no "y"-ticks.
8667 \item "2048 = Same_ticks": plot all ticks with the same length.
8669 plothraw"(listx,listy,{flag = 0})"
8671 given listx and listy two vectors of equal length, plots (in high
8672 precision) the points whose "(x,y)"-coordinates are given in listx and
8673 listy. Automatic positioning and scaling is done, but with the same
8674 scaling factor on "x" and "y". If "flag" is 1, join points, other non-0
8675 flags toggle display options and should be combinations of bits "2^k",
8676 "k
8677 >= 3" as in "ploth".
8678 plothsizes"()"
8680 return data corresponding to the output window in the form of a
8681 6-component vector: window width and height, sizes for ticks in
8682 horizontal and vertical directions (this is intended for the "gnuplot"
8683 interface and is currently not significant), width and height of
8684 characters.
8685 plotinit"(w,x,y,{flag})"
8687 initialize the rectwindow "w", destroying any rect objects you may have
8688 already drawn in "w". The virtual cursor is set to "(0,0)". The
8689 rectwindow size is set to width "x" and height "y". If "flag = 0", "x"
8690 and "y" represent pixel units. Otherwise, "x" and "y" are understood as
8691 fractions of the size of the current output device (hence must be
8692 between 0 and 1) and internally converted to pixels.
8693 The plotting device imposes an upper bound for "x" and "y", for
8695 instance the number of pixels for screen output. These bounds are
8696 available through the "plothsizes" function. The following sequence
8697 initializes in a portable way (i.e independent of the output device) a
8698 window of maximal size, accessed through coordinates in the "[0,1000]
8699 x [0,1000]" range:
8700 s = plothsizes();
8702 plotinit(0, s[1]-1, s[2]-1);
8703 plotscale(0, 0,1000, 0,1000);
8704 plotkill"(w)"
8706 erase rectwindow "w" and free the corresponding memory. Note that if
8707 you want to use the rectwindow "w" again, you have to use "plotinit"
8708 first to specify the new size. So it's better in this case to use
8709 "plotinit" directly as this throws away any previous work in the given
8710 rectwindow.
8711 plotlines"(w,X,Y,{flag = 0})"
8713 draw on the rectwindow "w" the polygon such that the (x,y)-coordinates
8714 of the vertices are in the vectors of equal length "X" and "Y". For
8715 simplicity, the whole polygon is drawn, not only the part of the
8716 polygon which is inside the rectwindow. If "flag" is non-zero, close
8717 the polygon. In any case, the virtual cursor does not move.
8718 "X" and "Y" are allowed to be scalars (in this case, both have to).
8720 There, a single segment will be drawn, between the virtual cursor
8721 current position and the point "(X,Y)". And only the part thereof which
8722 actually lies within the boundary of "w". Then \emph{move} the virtual
8723 cursor to "(X,Y)", even if it is outside the window. If you want to
8724 draw a line from "(x1,y1)" to "(x2,y2)" where "(x1,y1)" is not
8725 necessarily the position of the virtual cursor, use "plotmove(w,x1,y1)"
8726 before using this function.
8727 plotlinetype"(w,type)"
8729 change the type of lines subsequently plotted in rectwindow "w". type
8730 "-2" corresponds to frames, "-1" to axes, larger values may correspond
8731 to something else. "w = -1" changes highlevel plotting. This is only
8732 taken into account by the "gnuplot" interface.
8733 plotmove"(w,x,y)"
8735 move the virtual cursor of the rectwindow "w" to position "(x,y)".
8736 plotpoints"(w,X,Y)"
8738 draw on the rectwindow "w" the points whose "(x,y)"-coordinates are in
8739 the vectors of equal length "X" and "Y" and which are inside "w". The
8740 virtual cursor does \emph{not} move. This is basically the same
8741 function as "plothraw", but either with no scaling factor or with a
8742 scale chosen using the function "plotscale".
8743 As was the case with the "plotlines" function, "X" and "Y" are allowed
8745 to be (simultaneously) scalar. In this case, draw the single point
8746 "(X,Y)" on the rectwindow "w" (if it is actually inside "w"), and in
8747 any case \emph{move} the virtual cursor to position "(x,y)".
8748 plotpointsize"(w,size)"
8750 changes the ``size'' of following points in rectwindow "w". If "w =
8751 -1", change it in all rectwindows. This only works in the "gnuplot"
8752 interface.
8753 plotpointtype"(w,type)"
8755 change the type of points subsequently plotted in rectwindow "w". "type
8756 = -1" corresponds to a dot, larger values may correspond to something
8757 else. "w = -1" changes highlevel plotting. This is only taken into
8758 account by the "gnuplot" interface.
8759 plotrbox"(w,dx,dy)"
8761 draw in the rectwindow "w" the outline of the rectangle which is such
8762 that the points "(x1,y1)" and "(x1+dx,y1+dy)" are opposite corners,
8763 where "(x1,y1)" is the current position of the cursor. Only the part
8764 of the rectangle which is in "w" is drawn. The virtual cursor does
8765 \emph{not} move.
8766 plotrecth"(w,X = a,b,expr,{flag = 0},{n = 0})"
8768 writes to rectwindow "w" the curve output of "ploth""(w,X =
8769 a,b,expr,flag,n)".
8770 plotrecthraw"(w,data,{flag = 0})"
8772 plot graph(s) for data in rectwindow "w". "flag" has the same
8773 significance here as in "ploth", though recursive plot is no more
8774 significant.
8775 data is a vector of vectors, each corresponding to a list a
8777 coordinates. If parametric plot is set, there must be an even number
8778 of vectors, each successive pair corresponding to a curve. Otherwise,
8779 the first one contains the "x" coordinates, and the other ones contain
8780 the "y"-coordinates of curves to plot.
8781 plotrline"(w,dx,dy)"
8783 draw in the rectwindow "w" the part of the segment
8784 "(x1,y1)-(x1+dx,y1+dy)" which is inside "w", where "(x1,y1)" is the
8785 current position of the virtual cursor, and move the virtual cursor to
8786 "(x1+dx,y1+dy)" (even if it is outside the window).
8787 plotrmove"(w,dx,dy)"
8789 move the virtual cursor of the rectwindow "w" to position
8790 "(x1+dx,y1+dy)", where "(x1,y1)" is the initial position of the cursor
8791 (i.e. to position "(dx,dy)" relative to the initial cursor).
8792 plotrpoint"(w,dx,dy)"
8794 draw the point "(x1+dx,y1+dy)" on the rectwindow "w" (if it is inside
8795 "w"), where "(x1,y1)" is the current position of the cursor, and in any
8796 case move the virtual cursor to position "(x1+dx,y1+dy)".
8797 plotscale"(w,x1,x2,y1,y2)"
8799 scale the local coordinates of the rectwindow "w" so that "x" goes from
8800 "x1" to "x2" and "y" goes from "y1" to "y2" ("x2 < x1" and "y2 < y1"
8801 being allowed). Initially, after the initialization of the rectwindow
8802 "w" using the function "plotinit", the default scaling is the graphic
8803 pixel count, and in particular the "y" axis is oriented downwards since
8804 the origin is at the upper left. The function "plotscale" allows to
8805 change all these defaults and should be used whenever functions are
8806 graphed.
8807 plotstring"(w,x,{flag = 0})"
8809 draw on the rectwindow "w" the String "x" (see "Label se:strings"), at
8810 the current position of the cursor.
8811 flag is used for justification: bits 1 and 2 regulate horizontal
8813 alignment: left if 0, right if 2, center if 1. Bits 4 and 8 regulate
8814 vertical alignment: bottom if 0, top if 8, v-center if 4. Can insert
8815 additional small gap between point and string: horizontal if bit 16 is
8816 set, vertical if bit 32 is set (see the tutorial for an example).
8817 psdraw"(list)"
8819 same as "plotdraw", except that the output is a PostScript program
8820 appended to the "psfile".
8821 psploth"(X = a,b,expr)"
8823 same as "ploth", except that the output is a PostScript program
8824 appended to the "psfile".
8825 psplothraw"(listx,listy)"
8827 same as "plothraw", except that the output is a PostScript program
8828 appended to the "psfile".
8829
8831 =head2 Control statements.
8832 A number of control statements are available in GP. They are simpler
8834 and have a syntax slightly different from their C counterparts, but are
8835 quite powerful enough to write any kind of program. Some of them are
8836 specific to GP, since they are made for number theorists. As usual, "X"
8837 will denote any simple variable name, and seq will always denote a
8838 sequence of expressions, including the empty sequence.
8839 Caveat: in constructs like
8841 for (X = a,b, seq)
8843 the variable "X" is considered local to the loop, leading to possibly
8845 unexpected behaviour:
8846 n = 5;
8848 for (n = 1, 10,
8849 if (something_nice(), break);
8850 );
8851 \\ at this point n is 5 !
8852 If the sequence "seq" modifies the loop index, then the loop is
8854 modified accordingly:
8855 ? for (n = 1, 10, n += 2; print(n))
8857 3
8858 6
8859 9
8860 12
8861 break"({n = 1})"
8863 interrupts execution of current seq, and immediately exits from the
8864 "n" innermost enclosing loops, within the current function call (or
8865 the top level loop). "n" must be bigger than 1. If "n" is greater
8866 than the number of enclosing loops, all enclosing loops are exited.
8867 for"(X = a,b,seq)"
8869 evaluates seq, where the formal variable "X" goes from "a" to "b".
8870 Nothing is done if "a > b". "a" and "b" must be in R.
8871 fordiv"(n,X,seq)"
8873 evaluates seq, where the formal variable "X" ranges through the
8874 divisors of "n" (see "divisors", which is used as a subroutine). It
8875 is assumed that "factor" can handle "n", without negative
8876 exponents. Instead of "n", it is possible to input a factorization
8877 matrix, i.e. the output of factor(n).
8878 This routine uses "divisors" as a subroutine, then loops over the
8880 divisors. In particular, if "n" is an integer, divisors are sorted
8881 by increasing size.
8882 To avoid storing all divisors, possibly using a lot of memory, the
8884 following (much slower) routine loops over the divisors using
8885 essentially constant space:
8886 FORDIV(N)=
8888 { local(P, E);
8889 P = factor(N); E = P[,2]; P = P[,1];
8891 forvec( v = vector(#E, i, [0,E[i]]),
8892 X = factorback(P, v)
8893 \\ ...
8894 );
8895 }
8896 ? for(i=1,10^5, FORDIV(i))
8897 time = 3,445 ms.
8898 ? for(i=1,10^5, fordiv(i, d, ))
8899 time = 490 ms.
8900 forell"(E,a,b,seq)"
8902 evaluates seq, where the formal variable "E" ranges through all
8903 elliptic curves of conductors from "a" to "b". Th "elldata"
8904 database must be installed and contain data for the specified
8905 conductors.
8906 forprime"(X = a,b,seq)"
8908 evaluates seq, where the formal variable "X" ranges over the prime
8909 numbers between "a" to "b" (including "a" and "b" if they are
8910 prime). More precisely, the value of "X" is incremented to the
8911 smallest prime strictly larger than "X" at the end of each
8912 iteration. Nothing is done if "a > b". Note that "a" and "b" must
8913 be in R.
8914 ? { forprime(p = 2, 12,
8916 print(p);
8917 if (p == 3, p = 6);
8918 )
8919 }
8920 2
8921 3
8922 7
8923 11
8924 forstep"(X = a,b,s,seq)"
8926 evaluates seq, where the formal variable "X" goes from "a" to "b",
8927 in increments of "s". Nothing is done if "s > 0" and "a > b" or if
8928 "s < 0" and "a < b". "s" must be in "R^*" or a vector of steps
8929 "[s_1,...,s_n]". In the latter case, the successive steps are used
8930 in the order they appear in "s".
8931 ? forstep(x=5, 20, [2,4], print(x))
8933 5
8934 7
8935 11
8936 13
8937 17
8938 19
8939 forsubgroup"(H = G,{B},seq)"
8941 evaluates seq for each subgroup "H" of the \emph{abelian} group "G"
8942 (given in SNF form or as a vector of elementary divisors), whose
8943 index is bounded by "B". The subgroups are not ordered in any
8944 obvious way, unless "G" is a "p"-group in which case Birkhoff's
8945 algorithm produces them by decreasing index. A subgroup is given as
8946 a matrix whose columns give its generators on the implicit
8947 generators of "G". For example, the following prints all subgroups
8948 of index less than 2 in "G = Z/2Z g_1 x Z/2Z g_2":
8949 ? G = [2,2]; forsubgroup(H=G, 2, print(H))
8951 [1; 1]
8952 [1; 2]
8953 [2; 1]
8954 [1, 0; 1, 1]
8955 The last one, for instance is generated by "(g_1, g_1 + g_2)". This
8957 routine is intended to treat huge groups, when "subgrouplist" is
8958 not an option due to the sheer size of the output.
8959 For maximal speed the subgroups have been left as produced by the
8961 algorithm. To print them in canonical form (as left divisors of
8962 "G" in HNF form), one can for instance use
8963 ? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H))))
8965 [2, 1; 0, 1]
8966 [1, 0; 0, 2]
8967 [2, 0; 0, 1]
8968 [1, 0; 0, 1]
8969 Note that in this last representation, the index "[G:H]" is given
8971 by the determinant. See "galoissubcyclo" and "galoisfixedfield" for
8972 "nfsubfields" applications to Galois theory.
8973 Warning: the present implementation cannot treat a group "G", if
8975 one of its "p"-Sylow subgroups has a cyclic factor with more than
8976 "2^{31}", resp. "2^{63}" elements on a 32-bit, resp. 64-bit
8977 architecture.
8978 forvec"(X = v,seq,{flag = 0})"
8980 Let "v" be an "n"-component vector (where "n" is arbitrary) of two-
8981 component vectors "[a_i,b_i]" for "1 <= i <= n". This routine
8982 evaluates seq, where the formal variables "X[1],..., X[n]" go from
8983 "a_1" to "b_1",..., from "a_n" to "b_n", i.e. "X" goes from
8984 "[a_1,...,a_n]" to "[b_1,...,b_n]" with respect to the
8985 lexicographic ordering. (The formal variable with the highest index
8986 moves the fastest.) If "flag = 1", generate only nondecreasing
8987 vectors "X", and if "flag = 2", generate only strictly increasing
8988 vectors "X".
8989 if"(a,{seq1},{seq2})"
8991 evaluates the expression sequence seq1 if "a" is non-zero,
8992 otherwise the expression seq2. Of course, seq1 or seq2 may be
8993 empty:
8994 "if (a,seq)" evaluates seq if "a" is not equal to zero (you don't
8996 have to write the second comma), and does nothing otherwise,
8997 "if (a,,seq)" evaluates seq if "a" is equal to zero, and does
8999 nothing otherwise. You could get the same result using the "!"
9000 ("not") operator: "if (!a,seq)".
9001 Note that the boolean operators "&&" and "||" are evaluated
9003 according to operator precedence as explained in "Label
9004 se:operators", but that, contrary to other operators, the
9005 evaluation of the arguments is stopped as soon as the final truth
9006 value has been determined. For instance
9007 if (reallydoit && longcomplicatedfunction(), ...)%
9009 is a perfectly safe statement.
9011 Recall that functions such as "break" and "next" operate on
9013 \emph{loops} (such as "forxxx", "while", "until"). The "if"
9014 statement is \emph{not} a loop (obviously!).
9015 next"({n = 1})"
9017 interrupts execution of current "seq", resume the next iteration of
9018 the innermost enclosing loop, within the current function call (or
9019 top level loop). If "n" is specified, resume at the "n"-th
9020 enclosing loop. If "n" is bigger than the number of enclosing
9021 loops, all enclosing loops are exited.
9022 return"({x = 0})"
9024 returns from current subroutine, with result "x". If "x" is
9025 omitted, return the "(void)" value (return no result, like
9026 "print").
9027 until"(a,seq)"
9029 evaluates seq until "a" is not equal to 0 (i.e. until "a" is true).
9030 If "a" is initially not equal to 0, seq is evaluated once (more
9031 generally, the condition on "a" is tested \emph{after} execution of
9032 the seq, not before as in "while").
9033 while"(a,seq)"
9035 while "a" is non-zero, evaluates the expression sequence seq. The
9036 test is made \emph{before} evaluating the "seq", hence in
9037 particular if "a" is initially equal to zero the seq will not be
9038 evaluated at all.
9039 Specific functions used in GP programming
9041 In addition to the general PARI functions, it is necessary to have some
9042 functions which will be of use specifically for "gp", though a few of
9043 these can be accessed under library mode. Before we start describing
9044 these, we recall the difference between \emph{strings} and
9045 \emph{keywords} (see "Label se:strings"): the latter don't get expanded
9046 at all, and you can type them without any enclosing quotes. The former
9047 are dynamic objects, where everything outside quotes gets immediately
9048 expanded.
9049 addhelp"(S,str)"
9051 changes the help message for the symbol "S". The string str is
9052 expanded on the spot and stored as the online help for "S". If "S"
9053 is a function \emph{you} have defined, its definition will still be
9054 printed before the message str. It is recommended that you
9055 document global variables and user functions in this way. Of course
9056 "gp" will not protest if you skip this.
9057 Nothing prevents you from modifying the help of built-in PARI
9059 functions. (But if you do, we would like to hear why you needed to
9060 do it!)
9061 alias"(newkey,key)"
9063 defines the keyword newkey as an alias for keyword key. key must
9064 correspond to an existing \emph{function} name. This is different
9065 from the general user macros in that alias expansion takes place
9066 immediately upon execution, without having to look up any function
9067 code, and is thus much faster. A sample alias file "misc/gpalias"
9068 is provided with the standard distribution. Alias commands are
9069 meant to be read upon startup from the ".gprc" file, to cope with
9070 function names you are dissatisfied with, and should be useless in
9071 interactive usage.
9072 allocatemem"({x = 0})"
9074 this is a very special operation which allows the user to change
9075 the stack size \emph{after} initialization. "x" must be a non-
9076 negative integer. If "x ! = 0", a new stack of size
9077 "16*\ceil{x/16}" bytes is allocated, all the PARI data on the old
9078 stack is moved to the new one, and the old stack is discarded. If
9079 "x = 0", the size of the new stack is twice the size of the old
9080 one.
9081 Although it is a function, "allocatemem" cannot be used in loop-
9083 like constructs, or as part of a larger expression, e.g "2 +
9084 allocatemem()". Such an attempt will raise an error. The technical
9085 reason is that this routine usually moves the stack, so objects
9086 from the current expression may not be correct anymore, e.g. loop
9087 indexes.
9088 The library syntax is allocatemoremem"(x)", where "x" is an
9090 unsigned long, and the return type is void. "gp" uses a variant
9091 which makes sure it was not called within a loop.
9092 default"({key},{val})"
9094 returns the default corresponding to keyword key. If val is
9095 present, sets the default to val first (which is subject to string
9096 expansion first). Typing "default()" (or "\d") yields the complete
9097 default list as well as their current values. See "Label
9098 se:defaults" for a list of available defaults, and "Label se:meta"
9099 for some shortcut alternatives. Note that the shortcut are meant
9100 for interactive use and usually display more information than
9101 "default".
9102 The library syntax is gp_default"(key, val)", where key and val are
9104 "char *".
9105 error"({str}*)"
9107 outputs its argument list (each of them interpreted as a string),
9108 then interrupts the running "gp" program, returning to the input
9109 prompt. For instance
9110 error("n = ", n, " is not squarefree !")
9112 extern"(str)"
9114 the string str is the name of an external command (i.e. one you
9115 would type from your UNIX shell prompt). This command is
9116 immediately run and its input fed into "gp", just as if read from a
9117 file.
9118 The library syntax is extern0"(str)", where str is a "char *".
9120 getheap"()"
9122 returns a two-component row vector giving the number of objects on
9123 the heap and the amount of memory they occupy in long words. Useful
9124 mainly for debugging purposes.
9125 The library syntax is getheap"()".
9127 getrand"()"
9129 returns the current value of the random number seed. Useful mainly
9130 for debugging purposes.
9131 The library syntax is getrand"()", returns a C long.
9133 getstack"()"
9135 returns the current value of "top-avma", i.e. the number of bytes
9136 used up to now on the stack. Should be equal to 0 in between
9137 commands. Useful mainly for debugging purposes.
9138 The library syntax is getstack"()", returns a C long.
9140 gettime"()"
9142 returns the time (in milliseconds) elapsed since either the last
9143 call to "gettime", or to the beginning of the containing GP
9144 instruction (if inside "gp"), whichever came last.
9145 The library syntax is gettime"()", returns a C long.
9147 global"(list of variables)"
9149 declares the corresponding variables to be global. From now on, you
9151 will be forbidden to use them as formal parameters for function
9152 definitions or as loop indexes. This is especially useful when
9153 patching together various scripts, possibly written with different
9154 naming conventions. For instance the following situation is
9155 dangerous:
9156 p = 3 \\ fix characteristic
9158 ...
9159 forprime(p = 2, N, ...)
9160 f(p) = ...
9161 since within the loop or within the function's body (even worse: in
9163 the subroutines called in that scope), the true global value of "p"
9164 will be hidden. If the statement "global(p = 3)" appears at the
9165 beginning of the script, then both expressions will trigger syntax
9166 errors.
9167 Calling "global" without arguments prints the list of global
9169 variables in use. In particular, "eval(global)" will output the
9170 values of all global variables.
9171 input"()"
9173 reads a string, interpreted as a GP expression, from the input
9174 file, usually standard input (i.e. the keyboard). If a sequence of
9175 expressions is given, the result is the result of the last
9176 expression of the sequence. When using this instruction, it is
9177 useful to prompt for the string by using the "print1" function.
9178 Note that in the present version 2.19 of "pari.el", when using "gp"
9179 under GNU Emacs (see "Label se:emacs") one \emph{must} prompt for
9180 the string, with a string which ends with the same prompt as any of
9181 the previous ones (a "? " will do for instance).
9182 install"(name,code,{gpname},{lib})"
9184 loads from dynamic library lib the function name. Assigns to it the
9185 name gpname in this "gp" session, with argument code code (see the
9186 Libpari Manual for an explanation of those). If lib is omitted,
9187 uses "libpari.so". If gpname is omitted, uses name.
9188 This function is useful for adding custom functions to the "gp"
9190 interpreter, or picking useful functions from unrelated libraries.
9191 For instance, it makes the function "system" obsolete:
9192 ? install(system, vs, sys, "libc.so")
9194 ? sys("ls gp*")
9195 gp.c gp.h gp_rl.c
9196 But it also gives you access to all (non static) functions defined
9198 in the PARI library. For instance, the function "GEN addii(GEN x,
9199 GEN y)" adds two PARI integers, and is not directly accessible
9200 under "gp" (it's eventually called by the "+" operator of course):
9201 ? install("addii", "GG")
9203 ? addii(1, 2)
9204 %1 = 3
9205 Re-installing a function will print a Warning, and update the
9207 prototype code if needed, but will reload a symbol from the
9208 library, even it the latter has been recompiled.
9209 Caution: This function may not work on all systems, especially when
9211 "gp" has been compiled statically. In that case, the first use of
9212 an installed function will provoke a Segmentation Fault, i.e. a
9213 major internal blunder (this should never happen with a dynamically
9214 linked executable). Hence, if you intend to use this function,
9215 please check first on some harmless example such as the ones above
9216 that it works properly on your machine.
9217 kill"(s)"
9219 kills the present value of the variable, alias or user-defined
9220 function "s". The corresponding identifier can now be used to name
9221 any GP object (variable or function). This is the only way to
9222 replace a variable by a function having the same name (or the other
9223 way round), as in the following example:
9224 ? f = 1
9226 %1 = 1
9227 ? f(x) = 0
9228 *** unused characters: f(x)=0
9229 ^----
9230 ? kill(f)
9231 ? f(x) = 0
9232 ? f()
9233 %2 = 0
9234 When you kill a variable, all objects that used it become invalid.
9236 You can still display them, even though the killed variable will be
9237 printed in a funny way. For example:
9238 ? a^2 + 1
9240 %1 = a^2 + 1
9241 ? kill(a)
9242 ? %1
9243 %2 = #<1>^2 + 1
9244 If you simply want to restore a variable to its ``undefined'' value
9246 (monomial of degree one), use the quote operator: "a = 'a".
9247 Predefined symbols ("x" and GP function names) cannot be killed.
9248 print"({str}*)"
9250 outputs its (string) arguments in raw format, ending with a
9251 newline.
9252 print1"({str}*)"
9254 outputs its (string) arguments in raw format, without ending with a
9255 newline (note that you can still embed newlines within your
9256 strings, using the "\n" notation !).
9257 printp"({str}*)"
9259 outputs its (string) arguments in prettyprint (beautified) format,
9260 ending with a newline.
9261 printp1"({str}*)"
9263 outputs its (string) arguments in prettyprint (beautified) format,
9264 without ending with a newline.
9265 printtex"({str}*)"
9267 outputs its (string) arguments in TeX format. This output can then
9268 be used in a TeX manuscript. The printing is done on the standard
9269 output. If you want to print it to a file you should use "writetex"
9270 (see there).
9271 Another possibility is to enable the "log" default (see "Label
9273 se:defaults"). You could for instance do:
9274 default(logfile, "new.tex");
9276 default(log, 1);
9277 printtex(result);
9278 quit"()"
9280 exits "gp".
9281 read"({filename})"
9283 reads in the file filename (subject to string expansion). If
9284 filename is omitted, re-reads the last file that was fed into "gp".
9285 The return value is the result of the last expression evaluated.
9286 If a GP "binary file" is read using this command (see "Label
9288 se:writebin"), the file is loaded and the last object in the file
9289 is returned.
9290 readvec"({str})"
9292 reads in the file filename (subject to string expansion). If
9293 filename is omitted, re-reads the last file that was fed into "gp".
9294 The return value is a vector whose components are the evaluation of
9295 all sequences of instructions contained in the file. For instance,
9296 if file contains
9297 1
9299 2
9300 3
9301 then we will get:
9303 ? \r a
9305 %1 = 1
9306 %2 = 2
9307 %3 = 3
9308 ? read(a)
9309 %4 = 3
9310 ? readvec(a)
9311 %5 = [1, 2, 3]
9312 In general a sequence is just a single line, but as usual braces
9314 and "\\" may be used to enter multiline sequences.
9315 reorder"({x = []})"
9317 "x" must be a vector. If "x" is the empty vector, this gives the
9318 vector whose components are the existing variables in increasing
9319 order (i.e. in decreasing importance). Killed variables (see
9320 "kill") will be shown as 0. If "x" is non-empty, it must be a
9321 permutation of variable names, and this permutation gives a new
9322 order of importance of the variables, \emph{for output only}. For
9323 example, if the existing order is "[x,y,z]", then after
9324 "reorder([z,x])" the order of importance of the variables, with
9325 respect to output, will be "[z,y,x]". The internal representation
9326 is unaffected.
9327 setrand"(n)"
9329 reseeds the random number generator to the value "n". The initial
9330 seed is "n = 1".
9331 The library syntax is setrand"(n)", where "n" is a "long". Returns
9333 "n".
9334 system"(str)"
9336 str is a string representing a system command. This command is
9337 executed, its output written to the standard output (this won't get
9338 into your logfile), and control returns to the PARI system. This
9339 simply calls the C "system" command.
9340 trap"({e}, {rec}, {seq})"
9342 tries to evaluate seq, trapping error "e", that is effectively
9343 preventing it from aborting computations in the usual way; the
9344 recovery sequence rec is executed if the error occurs and the
9345 evaluation of rec becomes the result of the command. If "e" is
9346 omitted, all exceptions are trapped. Note in particular that
9347 hitting "^C" (Control-C) raises an exception. See "Label
9348 se:errorrec" for an introduction to error recovery under "gp".
9349 ? \\ trap division by 0
9351 ? inv(x) = trap (gdiver, INFINITY, 1/x)
9352 ? inv(2)
9353 %1 = 1/2
9354 ? inv(0)
9355 %2 = INFINITY
9356 If seq is omitted, defines rec as a default action when catching
9358 exception "e", provided no other trap as above intercepts it first.
9359 The error message is printed, as well as the result of the
9360 evaluation of rec, and control is given back to the "gp" prompt. In
9361 particular, current computation is then lost.
9362 The following error handler prints the list of all user variables,
9364 then stores in a file their name and their values:
9365 ? { trap( ,
9367 print(reorder);
9368 writebin("crash")) }
9369 If no recovery code is given (rec is omitted) a break loop will be
9371 started (see "Label se:breakloop"). In particular
9372 ? trap()
9374 by itself installs a default error handler, that will start a break
9376 loop whenever an exception is raised.
9377 If rec is the empty string "" the default handler (for that error
9379 if "e" is present) is disabled.
9380 Note: The interface is currently not adequate for trapping
9382 individual exceptions. In the current version 2.2.0, the following
9383 keywords are recognized, but the name list will be expanded and
9384 changed in the future (all library mode errors can be trapped: it's
9385 a matter of defining the keywords to "gp", and there are currently
9386 far too many useless ones):
9387 "accurer": accuracy problem
9389 "archer": not available on this architecture or operating system
9391 "errpile": the PARI stack overflows
9393 "gdiver": division by 0
9395 "invmoder": impossible inverse modulo
9397 "siginter": SIGINT received (usually from Control-C)
9399 "talker": miscellaneous error
9401 "typeer": wrong type
9403 "user": user error (from the "error" function)
9405 type"(x)"
9407 this is useful only under "gp". Returns the internal type name of
9408 the PARI object "x" as a string. Check out existing type names
9409 with the metacommand "\t". For example type(1) will return
9410 ""t_INT"".
9411 The library syntax is type0"(x)", though the macro "typ" is usually
9413 simpler to use since it return an integer that can easily be
9414 matched with the symbols "t_*". The name "type" was avoided due to
9415 the fact that "type" is a reserved identifier for some C(++)
9416 compilers.
9417 version"()"
9419 Returns the current version number as a "t_VEC" with three integer
9420 components: major version number, minor version number and
9421 patchlevel. To check against a particular version number, you can
9422 use:
9423 if (lex(version(), [2,2,0]) >= 0,
9425 \\ code to be executed if we are running 2.2.0 or more recent.
9426 ,
9427 \\ compatibility code
9428 );
9429 whatnow"(key)"
9431 if keyword key is the name of a function that was present in GP
9432 version 1.39.15 or lower, outputs the new function name and syntax,
9433 if it changed at all (387 out of 560 did).
9434 write"(filename,{str}*)"
9436 writes (appends) to filename the remaining arguments, and appends a
9437 newline (same output as "print").
9438 write1"(filename,{str}*)"
9440 writes (appends) to filename the remaining arguments without a
9441 trailing newline (same output as "print1").
9442 writebin"(filename,{x})"
9444 writes (appends) to filename the object "x" in binary format. This
9445 format is not human readable, but contains the exact internal
9446 structure of "x", and is much faster to save/load than a string
9447 expression, as would be produced by "write". The binary file format
9448 includes a magic number, so that such a file can be recognized and
9449 correctly input by the regular "read" or "\r" function. If saved
9450 objects refer to (polynomial) variables that are not defined in the
9451 new session, they will be displayed in a funny way (see "Label
9452 se:kill").
9453 If "x" is omitted, saves all user variables from the session,
9455 together with their names. Reading such a ``named object'' back in
9456 a "gp" session will set the corresponding user variable to the
9457 saved value. E.g after
9458 x = 1; writebin("log")
9460 reading "log" into a clean session will set "x" to 1. The relative
9462 variables priorities (see "Label se:priority") of new variables set
9463 in this way remain the same (preset variables retain their former
9464 priority, but are set to the new value). In particular, reading
9465 such a session log into a clean session will restore all variables
9466 exactly as they were in the original one.
9467 User functions, installed functions and history objects can not be
9469 saved via this function. Just as a regular input file, a binary
9470 file can be compressed using "gzip", provided the file name has the
9471 standard ".gz" extension.
9472 In the present implementation, the binary files are architecture
9474 dependent and compatibility with future versions of "gp" is not
9475 guaranteed. Hence binary files should not be used for long term
9476 storage (also, they are larger and harder to compress than text
9477 files).
9478 writetex"(filename,{str}*)"
9480 as "write", in TeX format.
9481
9483 Hey! The above document had some coding errors, which are explained
9484 below:
9485 Around line 9529:
9487 '=item' outside of any '=over'
9488 Around line 9720:
9490 You forgot a '=back' before '=head2'
9491 Around line 9731:
9493 '=item' outside of any '=over'
9494 =over without closing =back
9496perl v5.28.1 2019-03-24 libPARI(3)